Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 265 lines (173 sloc) 8.172 kB
1fdd2a4 @bermi Akelos Initial Import
bermi authored
1 Introduction.
2 ---------------------------------------
3
35ab663 @bermi Adding release generation makelos task
bermi authored
4 The Akelos Framework is an open-source port of Ruby on Rails to the
1fdd2a4 @bermi Akelos Initial Import
bermi authored
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
35ab663 @bermi Adding release generation makelos task
bermi authored
13 http://www.akelos.org
1fdd2a4 @bermi Akelos Initial Import
bermi authored
14
15
16 The tutorial
17 ---------------------------------------
35ab663 @bermi Adding release generation makelos task
bermi authored
18 Perhaps the easiest way to lear about Akelos is to get your hands on the tutorials
1fdd2a4 @bermi Akelos Initial Import
bermi authored
19 you can find on the docs folder.
20
21
22 Setting up the framework.
23 ---------------------------------------
35ab663 @bermi Adding release generation makelos task
bermi authored
24 Once you checkout the code you'll need to make available the folder ./public
1fdd2a4 @bermi Akelos Initial Import
bermi authored
25 to your webserver with a command like:
26
35ab663 @bermi Adding release generation makelos task
bermi authored
27 ln -s /home/bermi/akelos_framework/public /usr/htdocs/akelos
1fdd2a4 @bermi Akelos Initial Import
bermi authored
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
35ab663 @bermi Adding release generation makelos task
bermi authored
37 If you have problems with the web setup you can copy and edit
1fdd2a4 @bermi Akelos Initial Import
bermi authored
38 config/DEFAULT-config.php and config/DEFAULT-routes.php. You might also need
35ab663 @bermi Adding release generation makelos task
bermi authored
39 to edit the .htaccess files in ./ and ./public/ and un-comment/edit the
1fdd2a4 @bermi Akelos Initial Import
bermi authored
40 "# RewriteBase" directive so it matches to your url path.
41
42 All the configuration params are on /lib/constants.php If you define any of them
35ab663 @bermi Adding release generation makelos task
bermi authored
43 in your /config/config.php, /config/development.php, /config/production.php
1fdd2a4 @bermi Akelos Initial Import
bermi authored
44 or /config/testing.php the default setting will be overwritten.
45
46
47 Accessing the Command Line interface
48 ---------------------------------------
35ab663 @bermi Adding release generation makelos task
bermi authored
49 In order to access the command line interface run
50
1fdd2a4 @bermi Akelos Initial Import
bermi authored
51 ./script/console
52
53 Then you can run any PHP code interactively.
54
55 Example:
56
57 >>> generate
35ab663 @bermi Adding release generation makelos task
bermi authored
58
1fdd2a4 @bermi Akelos Initial Import
bermi authored
59 // Will show a list of available generators
35ab663 @bermi Adding release generation makelos task
bermi authored
60
1fdd2a4 @bermi Akelos Initial Import
bermi authored
61 >>> test app/models/post.php
35ab663 @bermi Adding release generation makelos task
bermi authored
62
1fdd2a4 @bermi Akelos Initial Import
bermi authored
63 // Will run the unit tests for the framework the Post model
35ab663 @bermi Adding release generation makelos task
bermi authored
64
1fdd2a4 @bermi Akelos Initial Import
bermi authored
65 You can also use the commands generate, migrate, setup ... by calling directly
35ab663 @bermi Adding release generation makelos task
bermi authored
66
1fdd2a4 @bermi Akelos Initial Import
bermi authored
67 ./script/generate
68
69
70 Differences from Ruby on Rails.
71 ---------------------------------------
35ab663 @bermi Adding release generation makelos task
bermi authored
72 I've tried to adhere as much as I could to the original interfaces, but some
1fdd2a4 @bermi Akelos Initial Import
bermi authored
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
35ab663 @bermi Adding release generation makelos task
bermi authored
81 - Views work using PHP, but some like file functions, static method calls,
1fdd2a4 @bermi Akelos Initial Import
bermi authored
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
35ab663 @bermi Adding release generation makelos task
bermi authored
87 - Helpers are made available automatically for your views under the naming
1fdd2a4 @bermi Akelos Initial Import
bermi authored
88 convention $name_helper were "name" is the name of the desired helper.
89
90 $url_helper->url_for(array('action'=>'add'));
91
35ab663 @bermi Adding release generation makelos task
bermi authored
92 - All the methods (but helpers) use PEAR like naming conventions so instead of
1fdd2a4 @bermi Akelos Initial Import
bermi authored
93 AkActionController::url_for() you need to call AkActionController::urlFor()
94
35ab663 @bermi Adding release generation makelos task
bermi authored
95 - Helpers are located at /lib/AkActionView/helpers (it's worth having a look
1fdd2a4 @bermi Akelos Initial Import
bermi authored
96 at them)
97
35ab663 @bermi Adding release generation makelos task
bermi authored
98 - In order to expose data from your controllers to the views, you'll simply
1fdd2a4 @bermi Akelos Initial Import
bermi authored
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
35ab663 @bermi Adding release generation makelos task
bermi authored
110 Will expose into ./app/views/post/index.tpl $message variable so you can use
1fdd2a4 @bermi Akelos Initial Import
bermi authored
111 it like:
35ab663 @bermi Adding release generation makelos task
bermi authored
112
113 <?php echo $message; ?>
114
1fdd2a4 @bermi Akelos Initial Import
bermi authored
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
35ab663 @bermi Adding release generation makelos task
bermi authored
129 In order to change the language of your application can prefix your request
1fdd2a4 @bermi Akelos Initial Import
bermi authored
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
35ab663 @bermi Adding release generation makelos task
bermi authored
145 All these four will save new locales onto their corresponding namespace in
1fdd2a4 @bermi Akelos Initial Import
bermi authored
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:
35ab663 @bermi Adding release generation makelos task
bermi authored
149
1fdd2a4 @bermi Akelos Initial Import
bermi authored
150 translate('Hello world', null, 'shared_posts');
35ab663 @bermi Adding release generation makelos task
bermi authored
151
1fdd2a4 @bermi Akelos Initial Import
bermi authored
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
35ab663 @bermi Adding release generation makelos task
bermi authored
169
1fdd2a4 @bermi Akelos Initial Import
bermi authored
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
35ab663 @bermi Adding release generation makelos task
bermi authored
175 Internationalizing Models.
1fdd2a4 @bermi Akelos Initial Import
bermi authored
176
177 You can have multilingual database columns by adding the locale prefix plus
35ab663 @bermi Adding release generation makelos task
bermi authored
178 and underscore to the column name. This way when you do
1fdd2a4 @bermi Akelos Initial Import
bermi authored
179
180 $Article->get('title')
181
182 you'll get the information on the "en_title" column if "en" is your current
35ab663 @bermi Adding release generation makelos task
bermi authored
183 locale.
1fdd2a4 @bermi Akelos Initial Import
bermi authored
184
35ab663 @bermi Adding release generation makelos task
bermi authored
185 The same way you can set posted attributes like
1fdd2a4 @bermi Akelos Initial Import
bermi authored
186
187 $_POST = array('title'=>array('en'=>'Tech details',
35ab663 @bermi Adding release generation makelos task
bermi authored
188 'es'=>'Detalles técnicos'));
189 $Article->setAttributes($_POST);
1fdd2a4 @bermi Akelos Initial Import
bermi authored
190
35ab663 @bermi Adding release generation makelos task
bermi authored
191 and the attributes will be mapped to their corresponding columns.
1fdd2a4 @bermi Akelos Initial Import
bermi authored
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
35ab663 @bermi Adding release generation makelos task
bermi authored
198 In order to convert between charsets you can use Ak::recode() and
1fdd2a4 @bermi Akelos Initial Import
bermi authored
199 Ak::utf8('My ISO Text', 'ISO-8859-1').
35ab663 @bermi Adding release generation makelos task
bermi authored
200
201
202
203
204 Autocompletion on bash prompts
205 --------------------------------
206
207 You can add bash autocompletion support to Makelos
208
209 First you'll need to have installed bash-completion
210
211 Mac OS: sudo port install bash-completion
212 Debian: apt-get install bash-completion
213
214 Add to the very bottom of your bash profile (Nice post by
215 Todd Werth http://blog.infinitered.com/entries/show/4 on
216 the subject)
217
218 Mac OS ~/.profile:
219
220
221 if [ -f /opt/local/etc/bash_completion ]; then
222 . /opt/local/etc/bash_completion
223 fi
224
225 Debian ~/.bashrc:
226
227
228 if [ -f /etc/bash_completion ]; then
229 . /etc/bash_completion
230 fi
231
232
233 Create the file
234
235 Mac OS: /opt/local/etc/bash_completion.d/makelos
236 Debian: /etc/bash_completion.d/makelos
237
238 with the following code
239
7ed392c @bermi Indenting markdown properly
bermi authored
240 _makelos()
241 {
242 local cur colonprefixes arguments
243 COMPREPLY=()
244 cur=${COMP_WORDS[COMP_CWORD]}
245 # Work-around bash_completion issue where bash
246 # interprets a colon
247 # as a separator.
248 # Work-around borrowed from the darcs/Maven2
249 # work-around for the same issue.
250 colonprefixes=${cur%"${cur##*:}"}
251 arguments=("${COMP_WORDS[@]:1}")
252 COMPREPLY=( $(compgen -W '$(./makelos makelos:autocomplete \
253 ${arguments[@]})' -- $cur))
254 local i=${#COMPREPLY[*]}
255 while [ $((--i)) -ge 0 ]; do
256 COMPREPLY[$i]=${COMPREPLY[$i]#"$colonprefixes"}
257 done
258 return 0
259 } &&
35ab663 @bermi Adding release generation makelos task
bermi authored
260
261 complete -o bashdefault -o default -F _makelos ./makelos 2>/dev/null \
262 || complete -o default -F _makelos ./makelos
263
264
265 cd to your app dir in a new prompt and enjoy makelos autocompletion.
Something went wrong with that request. Please try again.