Add Github flavored Markdown syntax for .wiki files #5

Closed
wants to merge 2 commits into
from
View
1 action/README.md
@@ -0,0 +1 @@
+The `action` namespace relies on `lithium\http`, and includes classes required to route and dispatch HTTP requests.
View
181 console/README.md
@@ -0,0 +1,181 @@
+**The console package contains a set of classes required to route and dispatch
+incoming console requests.** Moreover it contains the console front-controller
+file (`lithium.php`) as well as wrappers for both *nix and Windows environments
+(`li3` and `li3.bat` respectively), allowing to easily invoke the
+console front-controller from the command line.
+
+A command is to the command line what an action controller is to the HTTP
+request/response flow. In that commands are quite similar to controllers.
+Commands don't leverage the the full MVC as they don't utilize views, but
+directly interact with the user through `in()` and `out()`.
+
+Lithium itself provides amongst others commands for creating new applications
+or parts thereof. However commands can also be provided through other libraries
+or by your application. Commands running in the application context will have
+complete access to your application. This is especially useful to reuse
+existing logic in an application's model when creating a command to be run as
+i.e. a cron-job.
+
+
+## Invoking the front-controller ##
+
+You right away invoke the console front-controller through one of the wrappers
+provided. From the root directory of a standard Lithium distribution call one
+of the follwing commands. The first is for users on a *nix command line the
+second for users on a Windows system. Please note that the preceding `$` in
+examples always indicates things that you entere on the command line.
+
+ $ libraries/lithium/console/li3
+ $ libraries/lithium/console/li3.bat
+
+
+However it is recommended you add the path containing the wrapper to the paths
+searched by your system. This is `$PATH` for *nix and `%PATH%` for Windows.
+
+
+### A: Configuring your $PATH on *nix ###
+
+This is almost always achievable on a per-user basis through the user's
+`.profile` (Users running Bash may prefer `.bash_profile`). The file is located
+in your home directory. Open the file and add the following line, assuming the
+`li3` wrapper exists in `/path/to/libraries/lithium/console`.
+
+ export PATH+=:/path/to/libraries/lithium/console
+
+
+Once you've followed these steps, save your modified the file and reload your environment settings
+by sourcing the modified profile through the following command.
+
+ $ source ~/.profile
+
+
+If you can't or don't want to modify your `$PATH` you use two other techniques
+to make the wrapper available as just `li3`. You can either symlink the
+wrapper into one of the paths found in the `$PATH` environment variable
+
+ $ cd /path/to/a/directory/in/your/path
+ $ ln -s /path/to/libraries/lithium/console
+
+or create a permanent alias by adding an alias to i.e. the `.bashrc` file in your home directory.
+
+ alias li3='/path/to/lithium/libraries/lithium/console/li3'
+
+
+### B: Configuring your %PATH% on Windows ###
+
+**Note**: Please note that if you're on Windows you've additionally got to add the PHP directory to
+ the `%PATH%` environment variable. As we are going to edit that variable for adding
+ the location of where the `li3.bat` wrapper is anyway, we can kill two birds with one stone.
+
+ * Open _System_ from within the _Control Panel_.
+ * Open the _Advanced_ tab.
+ * Clicking the _Environment Variables_ button open a dialog where you can edit the variables.
+ * Double click the _PATH_ entry in order to edit it.
+ * Add `C:\path\to\php;C:\path\to\libraries\lithium\console` to the end of the value.
+
+### Finishing up ###
+
+Now that you've made the wrapper available as `li3` or `li3.bat` respectively,
+you should be able to use it from the command-line just by executing `li3` and
+`li3.bat`. Invoking the wrapper like that (without arguments) should give you a
+list of available commands.
+
+ $ li3
+ $ li3.bat
+
+
+## Built-in commands ##
+
+Using the commands which come with lithium is easy. Invoke the wrapper without
+any arguments to get a list of all available commands. Get a description about
+each command and the options and arguments it accept or may require by using
+the `help` command.
+
+ $ li3 help
+ $ li3 help create
+ $ li3 help g11n
+
+
+## Creating custom commands ##
+
+Creating your own commands is very easy. A few fundamentals:
+
+* All commands inherit from `lithium\console\Command`.
+* Commands are normally placed in your application or library's `extensions/commands` directory.
+
+Here's an example command:
+
+
+ <?php
+
+ namespace app\extensions\command;
+
+ class HelloWorld extends \lithium\console\Command {
+
+ public function run() {
+ $this->header('Welcome to the Hello World command!');
+ $this->out('Hello, World!');
+ }
+ }
+
+ ?>
+
+
+If you would like to try this command, create an application or use an existing
+application, and place the command into the application's `extensions/commands`
+directory and save it as `HelloWorld.php`. After doing so, open a shell and
+change directory to your application's directory and run the following command:
+
+
+ $ li3 hello_world
+
+
+Although it's probably obvious, when this command runs it will output a nice
+header with the text `Welcome to the Hello World command!` and some regular
+text `Hello, World!` after it.
+
+The public method `run()` is called on your command instance every time your
+command has been requested to run. From this method you can add your own command
+logic.
+
+### Parsing options and arguments ###
+
+Parsing options and arguments to commands should be simple. In fact, the
+parsing is already done for you.
+
+Short and long (GNU-style) options in the form of `-f`, `--foo` and `--foo=bar`
+are automatically parsed and exposed to your command instance through its
+properties. XF68-style long options (i.e. `-foo`) are not supported by default
+but support can be added by extending the console router.
+
+Arguments are passed directly to the invoked method.
+
+Let's look at an example, going back to the `hello_world` command from earlier:
+
+ <?php
+
+ namespace app\extensions\command;
+
+ class HelloWorld extends \lithium\console\Command {
+
+ public $recipient;
+
+ public function run() {
+ $this->header('Welcome to the Hello World command!');
+ $this->out('Hello, ' . ($this->recipient ?: 'World') . '!');
+ }
+ }
+
+ ?>
+
+
+Notice the additional property `$recipient`? Great! Now when `--recipient` is
+passed to the `hello_world` command, the recipient property on your command
+instance will be set to whatever was passed into the command at runtime.
+
+Try it out with the following command:
+
+ $ li3 hello_world --recipient=AwesomeGuy
+
+
+You should get a special greeting from our good old `hello_world` command.
View
155 template/README.md
@@ -0,0 +1,155 @@
+## Special syntax ##
+
+Views have a special syntax for outputting escaped text. The standard way to
+output escaped text in your views from Lithium is as follows:
+
+ <?= $variable; ?>
+
+
+This is where a lot of confusion comes in, because it is commonly misunderstood
+that Lithium depends on `short_open_tags`, however, that's not the case. The
+contents of a view are processed through a tokenizer (`template/view/Compiler`) before
+it is included by PHP. The file is then `compiled` into the final PHP+HTML (or whatever
+other content type that is requsted), which is then passed off to be fully rendered
+by the two-step view to its final form.
+
+See the PHP [manual](http://php.net/manual/en/book.tokenizer.php) to learn more about tokens.
+
+The stream wrapper reads the file and searches for anything that looks like
+`<?=...?>` and replaces it with `<?php echo $h(...); ?>`.
+
+The design decision behind using PHP's short echo syntax is because it's a
+familiar syntax and it helps developers focus more on what data _should not_ be
+escaped vs. what data _needs_ to be escaped.
+
+One special case situation to take _important_ note of, is the use of `<?=$this->foo()?>`.
+In this scenario, the code is translated to `<?php echo $this->foo(); ?>`
+rather than being filtered through `$h()` as with the former explanation. When direct access to a method or property on `$this` is contained in the shorthands syntax, it will be output as normal without being filtered.
+This is to make it easier to work with helpers that return markup.
+
+An example would be something like:
+
+ <?=$this->form->create();?>
+ ... my form here ...
+ <?=$this->form->end();?>
+
+**Note:** `$h()` is the HTML escape function used in views.
+
+**Note:** To output regular, unescaped text, use plain old `<?php echo ...; ?>`.
+
+**Other useful information:**
+
+ * [Introduction to PHP streams](http://www.php.net/intro.stream)
+ * [Stream examples](http://www.php.net/stream.examples)
+
+
+## Using helpers ##
+
+Helpers are lazy-loaded by the current renderer. To use a helper, you can
+reference it by its name like this:
+
+ echo $this->html->link('Google', 'http://www.google.com');
+
+In a template, `$this` refers to the `Renderer` object. By using `$this->html`
+for the first time, the renderer will create an instance of the helper and store
+it so that the next time the helper is invoked the renderer will not have to
+re-instantiate the helper.
+
+Using such an approach, helpers can easily be loaded as needed without any
+performance impact.
+
+**More info**
+
+ * [HTML helper](template/helper/Html)
+ * [Form helper](template/helper/Form)
+ * [Helper base class](template/Helper)
+
+
+## Creating custom helpers ##
+
+You can also create your own custom helper very easily by extending the `Helper` base class, and
+placing your helper in the correct namespace. By default, helpers belong in the
+`<library>\extensions\helper` namespace, but this can be changed through configuration (see the
+the `Libraries` class (`core/Libraries`)).
+For example, consider the following class, saved as `app/extensions/helper/Custom.php`:
+
+ <?php
+
+ namespace app\extensions\helper;
+
+ class Custom extends \lithium\template\Helper {
+
+ public function greeting($name) {
+ return "Hello {$name}!";
+ }
+ }
+
+ ?>
+
+
+You can then use your helper in templates as follows:
+
+ <?=$this->custom->greeting("World"); ?>
+
+
+Your custom helper will then be auto-loaded into the templating engine from your application or a
+plugin.
+
+
+## Extending core helpers ##
+
+Because your application and plugins have a higher order-of-precedence than the Lithium core,
+classes like helpers can be extended and replaced seamlessly, without any changes to your templates.
+
+For example, to add or replace methods in the `Form` helper, you can add the following to
+`app/extensions/helper/Form.php`:
+
+
+ <?php
+
+ namespace app\extensions\helper;
+
+ class Form extends \lithium\template\helper\Form {
+
+ // Add or override Form helper methods
+ }
+
+ ?>
+
+
+Your custom `Form` helper will now be invoked in all instances where `$this->form` is called in a
+template. For more information on the load order of classes, see
+the `locate()` method of the `Libraries` class (`core/Libraries::locate`)
+
+
+## Rendering elements ##
+
+Elements are reusable view snippets that you can use in several views and layouts.
+You can reference it like so:
+
+ echo $this->_render('element', 'menu');
+
+
+Where `menu` is the name of your element file, in this example `app/views/elements/menu.html.php`. When using `$this->_render()`, all of the variables set in the controller are available to the element template.
+You can pass variables declared in the view or additional static content using the third parameter to `$this->_render()`:
+
+ $var1 = 'something';
+ echo $this->_render('element', 'menu', array(
+ 'var1' => $var1,
+ 'var2' => 'something else'
+ ));
+
+
+If you need the element template to not have access to existing data passed to the parent template, use the alternate syntax that calls the `View` render method directly:
+
+ echo $this->view()->render(
+ array('element' => 'menu'),
+ array('var1' => $var1, 'var2' => $var2)
+ );
+
+
+**More info**
+
+ * [View](template/View)
+ * [Renderer](template/view/Renderer)
+ * [File adapter](template/view/adapter/File)