README.txt

   1 Introduction.
   2 ---------------------------------------
   3
   4 The Akelos Framework is an open-source port of Ruby on Rails to the
   5 PHP programming language.
   6
   7 The main goal of the Akelos Framework its to help programmers to build
   8 multilingual database-backed web applications according to the
   9 Model-View-Control pattern. It lets you write less code by favoring
  10 conventions over configuration.
  11
  12 You can find more information at the Akelos Framework website at
  13 http://www.akelos.org
  14
  15
  16 The tutorial
  17 ---------------------------------------
  18 Perhaps the easiest way to lear about Akelos is to get your hands on the tutorials
  19 you can find on the docs folder.
  20
  21
  22 Setting up the framework.
  23 ---------------------------------------
  24 Once you checkout the code you'll need to make available the folder ./public
  25 to your webserver with a command like:
  26
  27     ln -s  /home/bermi/akelos_framework/public /usr/htdocs/akelos
  28
  29 Then just point your browser to that url and follow the steps.
  30
  31 You will also need to make sure that mod_rewrite is loaded into Apache,
  32 and that it can be controlled from .htaccess files, to do this make sure that
  33 the Apache configuration directive AllowOverride is set to 'All' (you may allow only the specific directives for mod_rewrite),
  34 for the directory your project will be accessed from.
  35
  36
  37 If you have problems with the web setup you can copy and edit
  38 config/DEFAULT-config.php and config/DEFAULT-routes.php. You might also need
  39 to edit the  .htaccess files in ./ and ./public/  and un-comment/edit the
  40 "# RewriteBase" directive so it matches to your url path.
  41
  42 All the configuration params are on /config/boot.php If you define any of them
  43 in your /config/config.php, /config/development.php, /config/production.php
  44 or /config/testing.php the default setting will be overwritten.
  45
  46
  47 Accessing the Command Line interface
  48 ---------------------------------------
  49 In order to access the command line interface run
  50
  51     ./script/console
  52
  53 Then you can run any PHP code interactively.
  54
  55 Example:
  56
  57         >>> generate
  58
  59         // Will show a list of available generators
  60
  61         >>> test app/models/post.php
  62
  63         // Will run the unit tests for the framework the Post model
  64
  65 You can also use the commands generate, migrate, setup ... by calling directly
  66
  67      ./script/generate
  68
  69
  70 Differences from Ruby on Rails.
  71 ---------------------------------------
  72 I've tried to adhere as much as I could to the original interfaces, but some
  73 general changes apply:
  74
  75 - PHP doesn't have name spaces so on the controller you must access to
  76 $this->params, $this->ModelName, $this->Request, $this->Response
  77
  78 - Templates are ended in .tpl (there is only one render on the framework, but
  79 more can be added)
  80
  81 - Views work using PHP, but some like file functions, static method calls,
  82 object instantiation.... will be disallowed for helping in keeping in the
  83 view just presentation logic. If you need extra logic for your views you can
  84 always create a helper "./app/helpers" so your views will be easier to
  85 maintain.
  86
  87 - Helpers are made available automatically for your views under the naming
  88 convention $name_helper were "name" is the name of the desired helper.
  89
  90     $url_helper->url_for(array('action'=>'add'));
  91
  92 - All the methods (but helpers) use PEAR like naming conventions so instead of
  93 AkActionController::url_for() you need to call AkActionController::urlFor()
  94
  95 - Helpers are located at /lib/AkActionView/helpers (it's worth having a look
  96 at them)
  97
  98 - In order to expose data from your controllers to the views, you'll simply
  99 need to assign them as attributes of the controller that is handling the
 100 action so:
 101
 102     class PostController extends ApplicationController
 103     {
 104           function index()
 105           {
 106                $this->message = 'Hello World';
 107           }
 108     }
 109
 110 Will expose  into ./app/views/post/index.tpl $message variable so you can use
 111 it like:
 112
 113     <?php echo $message; ?>
 114
 115 or the same using SinTags
 116
 117     {message}
 118
 119
 120 i18n and l10n the Akelos way
 121 ---------------------------------------
 122
 123 Locale files are located at:
 124
 125     ./config/locales/  # Akelos Framework locales
 126     ./app/locales/NAMESPACE/ # Your application locales where NAMESPACE is
 127      replaced by your model/controller/view name
 128
 129 In order to change the language of your application can prefix your request
 130 with the locale name so:
 131
 132     http://example.com/es/post/add # will load ./config/locales/es.php
 133 and
 134     http://example.com/en/post/add # will load ./config/locales/en.php
 135
 136
 137 All the functions for writing multilingual code rely on the Ak::t() method.
 138 Based on the Ak::t() function you can find:
 139
 140     $PostController->t() # controller
 141     $Post->t() # model
 142     $text_helper->translate() # for the view
 143     _{ hello world }  # for the view (SinTags)
 144
 145 All these four will save new locales onto their corresponding namespace in
 146 the example above "./app/locales/post/en.php"
 147
 148 If you want to use your own namespace for storing locales you can do it like:
 149
 150     translate('Hello world', null, 'shared_posts');
 151
 152 In this case it will store it at "./app/locales/shared_posts/en.php"
 153
 154
 155 Deal with Compound Messages
 156
 157 As you can see the Framework has been designed with l10n and i18n in mind. One
 158 nice and flexible feature common to all these functions but the sintags one is
 159 the ability to add compounded messages, you might already realized this but
 160 here is a small example:
 161
 162 Ak::t('Hello %title %last_name,',
 163 array('%title'=>$title,'%last_name'=>$last_name,'%first_name'=>$first_name));
 164
 165     Ak::t('Today is %date', array('%date'=>Ak::getDate()));
 166     // You can use Ak::t or any of its derived methods
 167
 168 The SinTags way to deal with compounded messages is
 169
 170     _{Today is %date}
 171     // which will be converted to
 172     // <?=$text_helper->translate('Today is %date', array('%date'=>$date));?>
 173     // note that $date is selected by replacing the % from the needle
 174
 175 Internationalizing Models.
 176
 177 You can have multilingual database columns by adding the locale prefix plus
 178 and underscore to the column name. This way when you do
 179
 180     $Article->get('title')
 181
 182 you'll get the information on the "en_title" column if "en" is your current
 183 locale.
 184
 185 The same way you can set posted attributes like
 186
 187     $_POST = array('title'=>array('en'=>'Tech details',
 188      'es'=>'Detalles técnicos'));
 189     $Article->setAttributes($_POST);
 190
 191 and the attributes will be mapped to their corresponding columns.
 192
 193 In order to make this work you need to add to your config/config.php
 194
 195     define('AK_ACTIVE_RECORD_DEFAULT_LOCALES', 'en,es');
 196
 197
 198 In order to convert between charsets you can use Ak::recode() and
 199 Ak::utf8('My  ISO Text', 'ISO-8859-1').