Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 751 lines (507 sloc) 26.037 kb
0873fa0 Upadte readme files titles
Fabrice Luraine authored
1 # Limonade: README
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
2
7538deb README file is now written in english
Fabrice Luraine authored
3 Limonade is a PHP micro framework for rapid web development and prototyping.
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
4
ece681b Updating camping url in readme files
Fabrice Luraine authored
5 It's inspired by frameworks like [Sinatra](http://www.sinatrarb.com/) or [Camping](http://github.com/camping/camping) in Ruby, or [Orbit](http://orbit.luaforge.net/) in Lua. It aims to be simple, lightweight and extremly flexible.
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
6
4f37e74 Small correction
Fabrice Luraine authored
7 Limonade provides functions that complete the PHP basic set, while keeping consistency with native functions and sitting up on them.
7538deb README file is now written in english
Fabrice Luraine authored
8
9 Limonade is easy to learn and provides everything that you can expect from a modern framework (MVC, REST, ...)
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
10
11
12
bc6df0f Fixes Hello world code example
Fabrice Luraine authored
13 require_once 'lib/limonade.php';
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
14 dispatch('/', 'hello');
15 function hello()
16 {
17 return 'Hello world!';
18 }
19 run();
c75e9da Adding a "about this file" section in readme files
Fabrice Luraine authored
20
21 ## About this document ##
22
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
23 This document provides a quick, but comprehensive, guide of Limonade features.
c75e9da Adding a "about this file" section in readme files
Fabrice Luraine authored
24
cc33788 Update links in README.mkd
Fabrice Luraine authored
25 For more informations, you can see the [website](http://limonade-php.github.com/), [examples](https://github.com/sofadesign/limonade/wiki/Examples-and-tutorials), and of course the [source code](http://github.com/sofadesign/limonade/blob/master/lib/limonade.php) which is still the best documentation.
c75e9da Adding a "about this file" section in readme files
Fabrice Luraine authored
26
27 A [discussion group](http://groups.google.fr/group/limonade) is also available for more exchanges.
28
0906634 Add requirements in README [#50 state:resolved]
Fabrice Luraine authored
29 ## Requirements ##
30
31 * PHP 5.1.6 > (successfully tested with PHP 5.1.6 but it might work with older versions)
32
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
33 ## Routes ##
34
269903d Use explicitly 'callback' pseudo-type instead of 'function'.
Fabrice Luraine authored
35 Routes combine
36
37 * an HTTP method
38 * with an URL matching pattern
39 * and a callback parameter
40
41 So they make the glue between an URL + a HTTP method, and the code provided in a callback controller.
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
42
43 dispatch('/', 'my_get_function');
7538deb README file is now written in english
Fabrice Luraine authored
44 # same as dispatch_get('my_get_function');
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
45 function my_get_function()
46 {
47 // Show something
269903d Use explicitly 'callback' pseudo-type instead of 'function'.
Fabrice Luraine authored
48 // with the code of this callback controller
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
49 }
50
51 dispatch_post('/', 'my_post_function');
52 function my_post_function()
53 {
54 // Create something
55 }
56
744a4da Fixing README dispatch_put example
Fabrice Luraine authored
57 dispatch_put('/', 'my_update_function');
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
58 function my_update_function()
59 {
60 // Update something
61 }
62
63 dispatch_delete('/', 'my_delete_function');
64 function my_delete_function()
65 {
66 // Delete something
67 }
7538deb README file is now written in english
Fabrice Luraine authored
68
334fa42 Sergii Pravdzivyi Add HTTP PATCH support
iStyx authored
69 dispatch_patch('/', 'my_patch_function');
70 function my_patch_function()
71 {
72 // Patch something
73 }
74
7538deb README file is now written in english
Fabrice Luraine authored
75
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
76 Routes are matched in the order they are declared.
7538deb README file is now written in english
Fabrice Luraine authored
77 The search is performed with a path given through browser URL:
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
78
79 http://localhost/my_app/?u=/my/path
80 http://localhost/my_app/?uri=/my/path
81 http://localhost/my_app/index.php?/my/path
82 http://localhost/my_app/?/my/path
bfd97ef Adding a note about the _method parameter.
Fabrice Luraine authored
83
334fa42 Sergii Pravdzivyi Add HTTP PATCH support
iStyx authored
84 When `PUT`,`DELETE` or `PATCH` methods are not supported (like in HTML form submision), you can use the `_method` parameter in `POST` requests: it will override the `POST` method.
bfd97ef Adding a note about the _method parameter.
Fabrice Luraine authored
85
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
86 <form action="<?php echo url_for('profile_update'); ?>" method="post">
bfd97ef Adding a note about the _method parameter.
Fabrice Luraine authored
87 <p><input type="hidden" name="_method" value="PUT" id="_method"></p>
88 <p>... your form fields</p>
89 <p><input type="submit" value="Update"></p>
90 </form>
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
91
b987095 Add documentation and tests about route optional default parameters.
Fabrice Luraine authored
92 ### Routing patterns and parameters ###
269903d Use explicitly 'callback' pseudo-type instead of 'function'.
Fabrice Luraine authored
93
7538deb README file is now written in english
Fabrice Luraine authored
94 Patterns may include named parameters. Associated values of those parameters are available with the `params()` function.
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
95
96 dispatch('/hello/:name', 'hello');
b987095 Add documentation and tests about route optional default parameters.
Fabrice Luraine authored
97 function hello()
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
98 {
99 $name = params('name');
100 return 'Hello $name';
101 }
102
7538deb README file is now written in english
Fabrice Luraine authored
103 Patterns may also include wildcard parameters. Associated values are available through numeric indexes, in the same order as in the pattern.
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
104
105 dispatch('/writing/*/to/*', 'my_letter');
106 function my_letter()
107 {
108 # Matches /writing/an_email/to/joe
109 $type = params(0); # "an_email"
110 $name = params(1); # "joe"
111 # ...
112 }
113
114 dispatch('/files/*.*', 'share_files');
115 function share_files()
116 {
117 # matches /files/readme.txt
118 $ext = params(1);
119 $filename = params(0).".".$ext;
120 # ...
121 }
7538deb README file is now written in english
Fabrice Luraine authored
122
123 Unlike the simple wildcard character `*`, the double wildcard character `**` specifies a string that may contain a `/`
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
124
125 dispatch('/files/**', 'share_files')
126 function share_files()
127 {
128 # Matches /files/my/own/file.txt
129 $filename = params(0); # my/own/file.txt
130 }
131
7538deb README file is now written in english
Fabrice Luraine authored
132 Pattern may also be a regular expression if it begins with a `^`
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
133
134 dispatch('^/my/own/(\d+)/regexp', 'my_func');
135 function my_func()
136 {
137 # matches /my/own/12/regexp
138 $num = params(0);
139 }
140
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
141 Wildcard parameters and regular expressions may be named, too.
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
142
143 dispatch(array('/say/*/to/**', array("what", "name")), 'my_func');
144 function my_func()
145 {
146 # Matches /say/hello/to/joe
147 $what = params('what');
148 $name = params('name');
149 }
7538deb README file is now written in english
Fabrice Luraine authored
150
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
151 You can also provide default parameter values that are merged with and overriden by the pattern parameters.
b987095 Add documentation and tests about route optional default parameters.
Fabrice Luraine authored
152
153 $options = array('params' => array('firstname'=>'bob'));
154 dispatch('/hello/:name', 'hello', $options);
155 function hello($firstname, $name) # default parameters first
156 {
157 return 'Hello $firstname $name';
158 }
159
160
269903d Use explicitly 'callback' pseudo-type instead of 'function'.
Fabrice Luraine authored
161 ### Callback controllers ###
162
163 The callback can be a function, an object method, a static method or a closure.
164 See [php documentation](http://php.net/manual/en/language.pseudo-types.php#language.types.callback) to learn more about the callback pseudo-type.
165
166 # will call my_hello_function() function
167 dispatch('/hello', 'my_hello_function');
168
169 # Static class method call, MyClass::hello();
170 dispatch('/hello', array('MyClass', 'hello'));
171
172 # Object method call, $obj->hello();
173 dispatch('/hello', array($obj, 'hello'));
174
175 # Static class method call (As of PHP 5.2.3), MyClass::hello();
176 dispatch('/hello', 'MyClass::hello');
177
178 # Using lambda function (As of PHP 5.3.0)
179 dispatch('/hello', function(){
180 return 'Hello World!';
181 });
182
183 Callback controllers return the rendered view output (see _Views and templates_).
184
b987095 Add documentation and tests about route optional default parameters.
Fabrice Luraine authored
185 They can take the pattern parameters as arguments
186
187 dispatch('/hello/:firstname/:name', 'hello');
188 function hello($firstname, $name)
189 {
190 # $firstname parameter equals params('firstname');
191 # and $name parameter equals params('name');
192 return 'Hello $firstname $name';
193 }
194
195
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
196 Callbacks called by routes can be written anywhere before the execution of the `run()` function. They can also be grouped in controller files stored in a `controllers/` folder.
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
197
198 / # site root
199 - index.php # file with routes declarations and run()
200 + controllers/
82c0951 Refactoring error function
Fabrice Luraine authored
201 - blog.php # functions for blog: blog_index(), blog_show(),
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
202 # blog_post()...
203 - comments.php # comments_for_a_post(), comment_add()...
204
205
206
7538deb README file is now written in english
Fabrice Luraine authored
207 This folder location can be set with the `controllers_dir` option.
208
209 option('controllers_dir', dirname(__FILE__).'/other/dir/for/controllers');
d7a66f1 Explain autoload_controller user defined function in README
Fabrice Luraine authored
210
211
212 You can also define `autoload_controller` function to load controllers in your own way:
213
214 function autoload_controller($callback)
215 {
216 # If $callback, the callback function defined in matching route,
217 # begins with 'admin_', then we load controllers from
218 # the admin sub-directory in the controllers directory.
219 # Else we load controllers the normal way from 'controllers_dir'.
220
221 $path = option('controllers_dir');
222 if(strpos($callback, "admin_") === 0) $path = file_path($path, 'admin');
223 require_once_dir($path);
224 }
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
225
a25bd2f Update CHANGES and README files
Fabrice Luraine authored
226 ### Url rewriting ###
227
228 Since version 0.4.1, Limonade supports url rewriting.
229
056f7d2 Fabrice Luraine Add Nginx rewriting rules in the README
16 authored
230 If you use Apache, with a `.htaccess` in your app folder
a25bd2f Update CHANGES and README files
Fabrice Luraine authored
231
232 <IfModule mod_rewrite.c>
233 Options +FollowSymlinks
234 Options +Indexes
235 RewriteEngine on
ee119cf Fix htaccess in README: comments may not be included on a line after a c...
Fabrice Luraine authored
236
237 # if your app is in a subfolder
238 # RewriteBase /my_app/
a25bd2f Update CHANGES and README files
Fabrice Luraine authored
239
240 # test string is a valid files
241 RewriteCond %{SCRIPT_FILENAME} !-f
242 # test string is a valid directory
243 RewriteCond %{SCRIPT_FILENAME} !-d
244
a256b36 Improving htaccess rules to support clean urls with query string like
Fabrice Luraine authored
245 RewriteRule ^(.*)$ index.php?uri=/$1 [NC,L,QSA]
246 # with QSA flag (query string append),
247 # forces the rewrite engine to append a query string part of the
248 # substitution string to the existing string, instead of replacing it.
a25bd2f Update CHANGES and README files
Fabrice Luraine authored
249 </IfModule>
056f7d2 Fabrice Luraine Add Nginx rewriting rules in the README
16 authored
250
251 If you use Nginx, add the following to your server declaration
252
253 server {
254 location / {
255
256 try_files $uri $uri/ @rewrite;
257 }
258 location @rewrite {
259 rewrite ^/(.*)$ /index.php?u=$1&$args;
260 }
261 }
a25bd2f Update CHANGES and README files
Fabrice Luraine authored
262
9ceb065 Fabrice Luraine Update README.mkd
16 authored
263 then remember to set explicitly the `option('base_uri')` in your configure() function:
a25bd2f Update CHANGES and README files
Fabrice Luraine authored
264
265 option('base_uri', '/my_app'); # '/' or same as the RewriteBase in your .htaccess
266
267 You can access your site with urls like `http://your.new-website.com/my/limonade/path` instead of `http://your.new-website.com/?/my/limonade/path`.
268
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
269
7538deb README file is now written in english
Fabrice Luraine authored
270 ## Views and templates ##
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
271
7538deb README file is now written in english
Fabrice Luraine authored
272 Template files are located by default in `views/` folder.
273 Views folder location can be set with the `views_dir` option.
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
274
82c0951 Refactoring error function
Fabrice Luraine authored
275 option('views_dir', dirname(__FILE__).'/other/dir/for/views');
276
7538deb README file is now written in english
Fabrice Luraine authored
277 To pass variables to templates, we use the function `set ()`
82c0951 Refactoring error function
Fabrice Luraine authored
278
279 set('name', 'John Doe');
280 render('index.html.php');
281
7538deb README file is now written in english
Fabrice Luraine authored
282 Variables may also be passed directly:
82c0951 Refactoring error function
Fabrice Luraine authored
283
284 render('index.html.php', null, array('name' => 'John Doe' ));
285
7538deb README file is now written in english
Fabrice Luraine authored
286
287
288 `set_or_default` function allows passing a variable, and if it's empty, a default value. It is really useful for the assignment of optional parameters extracted from the url using the `params()` function.
82c0951 Refactoring error function
Fabrice Luraine authored
289
290 dispatch('/hello/:name', 'hello');
291 function hello()
292 {
293 # matching /hello/
294 set_or_default('name', params('name'),'John');
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
295 return render('Hello %s!'); // returns 'Hello John!' because params('name') was empty. Else it would have returned params('name') value.
82c0951 Refactoring error function
Fabrice Luraine authored
296 }
297
68ee608 Adding a note about controller output
Fabrice Luraine authored
298 As you can notice, final output is returned by your controller. So remember to explicitly return your view in your controller with the `return` keyword! *(This remark will be particularly helpful for rubyists ;-) )*
82c0951 Refactoring error function
Fabrice Luraine authored
299
300
301
302 ### Layouts ###
303
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
304 Templates may be rendered inside another template: a layout.
82c0951 Refactoring error function
Fabrice Luraine authored
305
7538deb README file is now written in english
Fabrice Luraine authored
306 Layout may be set with the `layout` function:
82c0951 Refactoring error function
Fabrice Luraine authored
307
308 layout('default_layout.php');
7538deb README file is now written in english
Fabrice Luraine authored
309
310 or directly with the template rendering function
82c0951 Refactoring error function
Fabrice Luraine authored
311
312 render('index.html.php', 'default_layout.php');
7538deb README file is now written in english
Fabrice Luraine authored
313
314
315 If layout value is `null`, rendering will be done without any layout.
82c0951 Refactoring error function
Fabrice Luraine authored
316
317 render('index.html.php', null);
318
7538deb README file is now written in english
Fabrice Luraine authored
319 ### Formatted strings and inline templates ###
82c0951 Refactoring error function
Fabrice Luraine authored
320
7538deb README file is now written in english
Fabrice Luraine authored
321 Formatted string can be used like with [`sprintf`](http://php.net/manual/function.sprintf.php):
82c0951 Refactoring error function
Fabrice Luraine authored
322
323 set('num', 5);
269903d Use explicitly 'callback' pseudo-type instead of 'function'.
Fabrice Luraine authored
324 set('where', 'tree');
68ee608 Adding a note about controller output
Fabrice Luraine authored
325 return render('There are %d monkeys in the %s') // returns 'There are 5 monkeys in the tree'
82c0951 Refactoring error function
Fabrice Luraine authored
326
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
327 It's also possible to provide a function name as a template. By this way, for example, we can produce a single file application.
82c0951 Refactoring error function
Fabrice Luraine authored
328
329 function html_message($vars){ extract($vars);?>
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
330 <h1>Title: <?php echo h($title); ?></h1>
82c0951 Refactoring error function
Fabrice Luraine authored
331 <p>Message:<br>
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
332 <?php echo h($msg); ?></p>
82c0951 Refactoring error function
Fabrice Luraine authored
333 <?}
334
7538deb README file is now written in english
Fabrice Luraine authored
335 // in a request handling function
82c0951 Refactoring error function
Fabrice Luraine authored
336 set('title', 'Hello!');
337 set('msg', 'There are 100 monkeys in the Chennai and bangalore');
68ee608 Adding a note about controller output
Fabrice Luraine authored
338 return render('html_message');
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
339
7538deb README file is now written in english
Fabrice Luraine authored
340 ### HTML Templates ###
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
341
7538deb README file is now written in english
Fabrice Luraine authored
342 `html` function is used in the same way as `render`.
343 A header specifies the proper HTTP `Content-type` (`text/html`) and encoding setting defined through options (utf8 by default).
82c0951 Refactoring error function
Fabrice Luraine authored
344
345 html('my_template.html.php');
346
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
347 ### Templates XML ###
348
7538deb README file is now written in english
Fabrice Luraine authored
349 `xml` function is used in the same way as `render`.
350 A header specifies the proper HTTP `Content-type` (`text/xml`) and encoding setting defined through options (utf8 by default).
351
e4c8ee2 Fix wrong example for xml() section in the README [#54 state:resolved]
Fabrice Luraine authored
352 xml('my_template.xml.php');
82c0951 Refactoring error function
Fabrice Luraine authored
353
354 ### Templates CSS ###
355
7538deb README file is now written in english
Fabrice Luraine authored
356 `css` function is used in the same way as `render`.
357 A header specifies the proper HTTP `Content-type` (`text/css`) and encoding setting defined through options (utf8 by default).
82c0951 Refactoring error function
Fabrice Luraine authored
358
359 css('screen.css.php');
360
7794b5f Kematzy Added support for js() output.
kematzy authored
361 ### Templates JS ###
362
363 `js` function is used in the same way as `render`.
364 A header specifies the proper HTTP `Content-type` (`application/javascript`) and encoding setting defined through options (utf8 by default).
365
366 js('app.js.php');
367
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
368 ### Templates TXT ###
369
7538deb README file is now written in english
Fabrice Luraine authored
370 `txt` function is used in the same way as `render`.
371 A header specifies the proper HTTP `Content-type` (`text/plain`) and encoding setting defined through options (utf8 by default).
82c0951 Refactoring error function
Fabrice Luraine authored
372
373 txt('index.txt.php');
374
375 ### Templates JSON ###
376
7538deb README file is now written in english
Fabrice Luraine authored
377 `json` is used the same way as
378 [`json_encode`](http://php.net/manual/function.json-encode.php) function, and returns a string containing the JSON representation of a value.
379 A header specifies the proper HTTP `Content-type` (`application/x-javascript`) and encoding setting defined through options (utf8 by default).
82c0951 Refactoring error function
Fabrice Luraine authored
380
381 json($my_data);
382
7538deb README file is now written in english
Fabrice Luraine authored
383 ### Serving files ###
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
384
7538deb README file is now written in english
Fabrice Luraine authored
385 The `render_file` function can render a file directly to the ouptut buffer.
cb74ce2 Complete README file
Fabrice Luraine authored
386
387 render_file(option('public_dir').'foo.jpg');
388
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
389 A header specifies the proper HTTP `Content-type` depending on the file extension, and for text files, encoding setting defined through options (utf8 by default) .
cb74ce2 Complete README file
Fabrice Luraine authored
390
7538deb README file is now written in english
Fabrice Luraine authored
391 Output is temporized so that it can easily handle large files.
82c0951 Refactoring error function
Fabrice Luraine authored
392
92734d3 Add tests and documentation for `partial` function
Fabrice Luraine authored
393 ### Partials ###
394
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
395 The `partial` function is a shortcut to render with no layout. Useful for managing reusable blocks and keeping them in separate files.
92734d3 Add tests and documentation for `partial` function
Fabrice Luraine authored
396
397 This code
398
399 partial('my_posts.php', array('posts'=>$posts));
400
401 is the same as
402
403 render('my_posts.php', null, array('posts'=>$posts));
404
1f03acf Adding error handling and cleaning files
Fabrice Luraine authored
405 ### Captures ###
406
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
407 The `content_for` function allows you to capture a block of text in a view. Then the captured block will be available for the layout. This is useful for management of layout regions like a sidebar or to set javascript or stylesheet files that are specific to a view.
1b93974 Add tests and documentation for captures in views
Fabrice Luraine authored
408
409
410 For example with this layout:
411
412 <div id="content">
413 <div id="main">
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
414 <?php echo $content; ?>
1b93974 Add tests and documentation for captures in views
Fabrice Luraine authored
415 </div>
416 <div id="side">
417 <?php if (isset($side)) echo $side; ?>
418 </div>
419 </div>
420
421 And in your view:
422
423 <p>My main content</p>
424
425 <?php content_for('side'); ?>
426 <ul>
427 <li><a href="<?php echo url_for('/pages/item1')?>">Item 1</a></li>
428 <li><a href="<?php echo url_for('/pages/item2')?>">Item 2</a></li>
429 </ul>
430 <?php end_content_for(); ?>
431
432 Rendered result is:
433
434 <div id="content">
435 <div id="main">
436 <p>My main content</p>
437 </div>
438 <div id="side">
439 <ul>
440 <li><a href="?/pages/item1">Item 1</a></li>
441 <li><a href="?/pages/item1">Item 2</a></li>
442 </ul>
443 </div>
444 </div>
445
446
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
447 The above example is detailed in [this tutorial](http://blog.limonade-php.net/post/438674987/how-to-use-content-for-and-partial).
cb74ce2 Complete README file
Fabrice Luraine authored
448
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
449 Use captures with partials, it will help you to organize your views and will keep you from having to copy/paste the same code many times.
92734d3 Add tests and documentation for `partial` function
Fabrice Luraine authored
450
8c01314 Initiate a "Hooks and filters" section in documentation.
Fabrice Luraine authored
451 ## Hooks and filters ##
452
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
453 Limonade allows the user to define some functions to enhance the Limonade behaviour with its own needs.
8c01314 Initiate a "Hooks and filters" section in documentation.
Fabrice Luraine authored
454
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
455 Some of those, like the `before` hook and the `after` filter are commonly used, and others are only for advanced usage that might require a good comprehension of Limonade internals.
8c01314 Initiate a "Hooks and filters" section in documentation.
Fabrice Luraine authored
456
cb74ce2 Complete README file
Fabrice Luraine authored
457
57d7632 Better autorender feature (option('autorender') is no longer required) +...
Fabrice Luraine authored
458 ### Before ###
459
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
460 You can define a `before` function that will be executed before each request. This is very useful to define a default layout or for passing common variables to the templates.
cb74ce2 Complete README file
Fabrice Luraine authored
461
3a6534a Passing $route to the after($output, $route) abstract function. Adding ...
Fabrice Luraine authored
462 function before($route)
cb74ce2 Complete README file
Fabrice Luraine authored
463 {
464 layout('default_layout.php');
465 set('site_title', 'My Website');
466 }
467
57d7632 Better autorender feature (option('autorender') is no longer required) +...
Fabrice Luraine authored
468
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
469 The current matching route is also passed to the before function, so you can test it. It's an array as returned by the internal `route_find` function, with these values:
3a6534a Passing $route to the after($output, $route) abstract function. Adding ...
Fabrice Luraine authored
470
471 * `method` (HTTP method)
472 * `pattern` (regexp pattern)
473 * `names` (params names)
269903d Use explicitly 'callback' pseudo-type instead of 'function'.
Fabrice Luraine authored
474 * `callback` (callback)
3a6534a Passing $route to the after($output, $route) abstract function. Adding ...
Fabrice Luraine authored
475 * `options` (route options)
476 * `params` (current params)
7538deb README file is now written in english
Fabrice Luraine authored
477
57d7632 Better autorender feature (option('autorender') is no longer required) +...
Fabrice Luraine authored
478 ### After ###
479
7538deb README file is now written in english
Fabrice Luraine authored
480 An `after` output filter is also available. It's executed after each request and can apply a transformation to the output (except for `render_file` outputs which are sent directly to the output buffer).
cb74ce2 Complete README file
Fabrice Luraine authored
481
8202fee Fix after($output) example in README [#42 state:resolved]
Fabrice Luraine authored
482 function after($output){
483 $config = array('indent' => TRUE,
484 'output-xhtml' => TRUE,
485 'wrap' => 200);
486
487 $encoding = strtoupper(str_replace('-','', option('encoding')));
488 $tidy = tidy_parse_string($output, $config, $encoding);
489 $tidy->cleanRepair();
490 return $tidy;
cb74ce2 Complete README file
Fabrice Luraine authored
491 }
3a6534a Passing $route to the after($output, $route) abstract function. Adding ...
Fabrice Luraine authored
492
493 The current executed route is also available for `after` function.
cb74ce2 Complete README file
Fabrice Luraine authored
494
8c01314 Initiate a "Hooks and filters" section in documentation.
Fabrice Luraine authored
495 ### Before render ###
496
497 You can define a `before_render` function that will filter your view before rendering it.
498
499 The first three parameters are the same as those passed to the `render` function:
500
501 * `$content_or_func`: the view string
502 * `$layout`: current layout path
503 * `$locals`: variables passed directly to the `render` function
504
505 Last parameter, `$view_path` is by default `file_path(option('views_dir'), $content_or_func);`
506
64ec67e Merge branch 'master' of github.com:sofadesign/limonade
Fabrice Luraine authored
507 function before_render($content_or_func, $layout, $locals, $view_path)
508 {
509 # Transform $content_or_func, $layout, $locals or $view_path.
510 # Then return there new values
511 return array($content_or_func, $layout, $locals, $view_path);
512 }
513
514 ### Autorender ###
515
516 You can define your own `autorender` function to make automatic rendering depending on current matching route. It will be executed if your controller returns a null output.
517
518 dispatch('/', 'hello');
519 function hello()
520 {
521 # process some stuff...
522 set('name', 'Bob');
523
524 # but don't return anything
525 # ( like if you were ending this function with return null; )
526 }
527
528 function autorender($route)
529 {
530 $view = $route['callback'] . ".html.php";
531 return html($view);
532 }
533
534 In this example, when url `/` is called, `hello()` is executed and then `autorender()` renders the matching `hello.html.php` view.
535
536 ### Before exit ###
537
538 If you define a `before_exit`, it is called at the begining of the stop/exit process (`stop_and_exit` function called automatically at Limonade application termination).
539
540 function before_exit($exit)
541 {
542 # $exit is the same parameter as the one passed to `stop_and_exit`.
543 # If it's false, the exit process will not be executed,
544 # only the stop instructions
545 # by default it is true
546 }
547
eafcb90 Claus Beerta Rename _lim_header to send_header. Rename inspect_header to before_sendi...
CBeerta authored
548 ### Before sending a header ###
039e699 Claus Beerta Add `inspect_header`to allow inspection of headers beeing sent.
CBeerta authored
549
eafcb90 Claus Beerta Rename _lim_header to send_header. Rename inspect_header to before_sendi...
CBeerta authored
550 You can define a `before_sending_header` function that will be called before Limonade emits a header() call. This way you can add additional headers:
039e699 Claus Beerta Add `inspect_header`to allow inspection of headers beeing sent.
CBeerta authored
551
552 dispatch('/style.css', 'css');
553 function css()
554 {
555 # Generate css file and output
556 return css('style.css.php');
557 }
558
eafcb90 Claus Beerta Rename _lim_header to send_header. Rename inspect_header to before_sendi...
CBeerta authored
559 function before_sending_header($header)
039e699 Claus Beerta Add `inspect_header`to allow inspection of headers beeing sent.
CBeerta authored
560 {
561 if (strpos($header, 'text/css') !== false)
562 {
563 # intercept text/css content-type and add caching to the headers
eafcb90 Claus Beerta Rename _lim_header to send_header. Rename inspect_header to before_sendi...
CBeerta authored
564 send_header("Cache-Control: max-age=600, public");
039e699 Claus Beerta Add `inspect_header`to allow inspection of headers beeing sent.
CBeerta authored
565 }
566 }
64ec67e Merge branch 'master' of github.com:sofadesign/limonade
Fabrice Luraine authored
567
eafcb90 Claus Beerta Rename _lim_header to send_header. Rename inspect_header to before_sendi...
CBeerta authored
568 __Caution__: Take care not to cause a loop by repeatedly calling `send_header()` from the `before_sending_header()` function!
569
570
64ec67e Merge branch 'master' of github.com:sofadesign/limonade
Fabrice Luraine authored
571 ## Configuration ##
572
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
573 You can define a `configure` that will be executed when application is launched (at the begining of the `run` execution).
64ec67e Merge branch 'master' of github.com:sofadesign/limonade
Fabrice Luraine authored
574 You can define options inside it, a connection to a database ...
575
576 function configure()
577 {
578 $env = $_SERVER['HTTP_HOST'] == "localhost" ? ENV_DEVELOPMENT : ENV_PRODUCTION;
579 option('env', $env);
580 if(option('env') > ENV_PRODUCTION)
581 {
582 options('dsn', 'sqlite:db/development.db'));
583 }
584 else
585 {
586 options('dsn', 'sqlite:db/production.db'));
587 }
588 $GLOBALS['my_db_connexion'] = new PDO(option('dsn'));
589 }
590
0d357db Fabrice Luraine In configuration section of the README, describe the proper behaviour ab...
authored
591 PHP files contained in the `option('lib_dir')` folder (`lib/` by default) are loaded with [`require_once`](http://php.net/manual/function.require-once.php) just after executing `configure`. So you can place in this folder all your PHP libraries and functions so that they will be loaded and available at application launch.
64ec67e Merge branch 'master' of github.com:sofadesign/limonade
Fabrice Luraine authored
592
593 ## Options ##
594
595 The `option` function allows you to define and access the options of the application.
596
597 option('env', ENV_PRODUCTION);
598 option('env'); // return ENV_PRODUCTION value
599
600 If the name of option is not specified, it returns an array of all the options set.
601
602 You can use it to manage Limonade options and your own custom options in your application.
603
604 Default Limonade options have the following values:
605
606 option('root_dir', $root_dir); // this folder contains your main application file
607 option('base_path', $base_path);
608 option('base_uri', $base_uri); // set it manually if you use url_rewriting
609 option('limonade_dir', dirname(__FILE__).'/'); // this fiolder contains the limonade.php main file
610 option('limonade_views_dir', dirname(__FILE__).'/limonade/views/');
611 option('limonade_public_dir',dirname(__FILE__).'/limonade/public/');
612 option('public_dir', $root_dir.'/public/');
613 option('views_dir', $root_dir.'/views/');
614 option('controllers_dir', $root_dir.'/controllers/');
615 option('lib_dir', $root_dir.'/lib/');
616 option('error_views_dir', option('limonade_views_dir'));
617 option('env', ENV_PRODUCTION);
618 option('debug', true);
619 option('session', LIM_SESSION_NAME); // true, false or the name of your session
620 option('encoding', 'utf-8');
621 option('x-sendfile', 0); // 0: disabled,
622 // X-SENDFILE: for Apache and Lighttpd v. >= 1.5,
623 // X-LIGHTTPD-SEND-FILE: for Apache and Lighttpd v. < 1.5
624
625 ## Sessions ##
626
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
627 Session starts automatically by default. Then you can access session variables like you used to do, with `$_SESSION` array.
64ec67e Merge branch 'master' of github.com:sofadesign/limonade
Fabrice Luraine authored
628
629 You can disable sessions with the `session` option.
630
631 ⌘ [see snippet example](http://gist.github.com/159327)
632
633 ### Flash ###
634
635 Flash is a special use of sessions. A flash value will be available only on next request and will be deleted after. It's very useful to raise errors on a form or to notice a successful action.
636
637 * `flash($name, $value...)` defines a flash for the next request
638 * in views, you can get current flash values with the `$flash` array or `flash_now($name)` function.
639
640 ⌘ [see snippet example](http://gist.github.com/162680)
641
642 ## Helpers ##
643
644 See sources or api for more about all available helpers.
645
646 ### url_for ###
647
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
648 You can use the `url_for` function for rendering limonade urls. They will be well formed from whatever folder in the document root your application is installed on your web server.
64ec67e Merge branch 'master' of github.com:sofadesign/limonade
Fabrice Luraine authored
649
650 # with option('base_uri', '?')
651 url_for('one', 'two', 'three'); # returns ?/one/two/three
652 url_for('one', 'two', array('page' => 1)); # returns ?/one/two&amp;page=2
653
654
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
655 If you want to use url rewriting, you need to explicitly set the `base_uri` option ( default is `/your_file_path/?`)
64ec67e Merge branch 'master' of github.com:sofadesign/limonade
Fabrice Luraine authored
656
657
658 ## Halting and error handling ##
659
660 ### Halt ###
661
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
662 You can stop immediately the execution of the application with the `halt` function. Errors will be handled by default Limonade error handlers or those you have defined.
64ec67e Merge branch 'master' of github.com:sofadesign/limonade
Fabrice Luraine authored
663
664 halt(NOT_FOUND);
665 halt("En error occured in my app...");
666
667 ### Not Found ###
668
669 By default, displays the `not_found` error output function and sends a _`404 NOT FOUND`_ HTTP header.
670
671 halt(NOT_FOUND);
672 halt(NOT_FOUND, "This product doesn't exists.");
673
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
674 To define a new view for this error, you can simply declare a `not_found` function.
64ec67e Merge branch 'master' of github.com:sofadesign/limonade
Fabrice Luraine authored
675
676 function not_found($errno, $errstr, $errfile=null, $errline=null)
677 {
678 set('errno', $errno);
679 set('errstr', $errstr);
680 set('errfile', $errfile);
681 set('errline', $errline);
682 return html("show_not_found_errors.html.php");
683 }
684
685 ### Server Error ###
686
687 By default, displays the `server_error` error output function and sends a _`500 INTERNAL SERVER ERROR`_ HTTP header.
688
689 halt();
690 halt('Breaking bad!');
691 halt(SERVER_ERROR, "Not good...");
692 trigger_error("Wrong parameter", E_USER_ERROR);
693
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
694 PHP errors are also caught and sent to this error handler output.
64ec67e Merge branch 'master' of github.com:sofadesign/limonade
Fabrice Luraine authored
695
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
696 To define a new view for this error, you can simply declare a `server_error` function.
64ec67e Merge branch 'master' of github.com:sofadesign/limonade
Fabrice Luraine authored
697
698 function server_error($errno, $errstr, $errfile=null, $errline=null)
699 {
700 $args = compact('errno', 'errstr', 'errfile', 'errline');
701 return html("show_server_errors.html.php", error_layout(), $args);
702 }
703
704 ### Error layout ###
705
706 Allows you to define and access a layout dedicated to errors.
707
708 error_layout('error_layout.php');
709 error_layout(); // return 'error_layout.php'
710
711 ### Error handling ###
712
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
713 In addition to the common `NOT_FOUND` and `SERVER_ERROR` error displays, Limonade can redirect precise errors to your own functions.
64ec67e Merge branch 'master' of github.com:sofadesign/limonade
Fabrice Luraine authored
714
715 error(E_USER_WARNING, 'my_notices')
716 function my_notices($errno, $errstr, $errfile, $errline)
717 {
718 // storing php warnings in a log file
719 // ...
720 status(SERVER_ERROR);
721 return html('<h1>Server Error</h1>');
722 }
723
724 `E_LIM_HTTP` means all HTTP errors
725
726 error(E_LIM_HTTP, 'my_http_errors')
727 function my_http_errors($errno, $errstr, $errfile, $errline)
728 {
729 status($errno);
730 return html('<h1>'.http_response_status_code($errno).'</h1>');
731 }
732
9b3cb4a Updated document to fix spelling/grammar errors, and to enhance readabil...
Adam T. Diehm authored
733 `E_LIM_PHP` means all PHP errors (sent by PHP or raised by the user through [`trigger_error`](http://php.net/manual/function.trigger-error.php) function).
64ec67e Merge branch 'master' of github.com:sofadesign/limonade
Fabrice Luraine authored
734
735 ## Other useful functions ##
736
737 Limonade also provides a useful set of functions that can help you managing files, HTTP… For more about those utilities, see the [source code](http://github.com/sofadesign/limonade/blob/master/lib/limonade.php) at section **7. UTILS**.
738
739 ## Testing ##
740
741 [TODO]
742
743 ## More ##
744
cc33788 Update links in README.mkd
Fabrice Luraine authored
745 * [Limonade web site](http://limonade-php.github.com/)
746 * [Limonade blog](http://limonade.tumblr.com/)
64ec67e Merge branch 'master' of github.com:sofadesign/limonade
Fabrice Luraine authored
747 * [Issue tracking / release planning](http://sofadesign.lighthouseapp.com/projects/29612-limonade/overview)
748 * [Support / Discussions](http://groups.google.fr/group/limonade)
749
2fd4138 Remove from the README file the link to the public API because it's no l...
Fabrice Luraine authored
750
Something went wrong with that request. Please try again.