### Subversion checkout URL

You can clone with HTTPS or Subversion.

# Add Github flavored Markdown syntax for .wiki files#5

Closed
wants to merge 2 commits into from
 +337 0

### 4 participants

commented

Should we keep files for li3_docs or rather update it to parse .md files ?

 mehlah Add Github flavored readme files 55c397f mehlah Minor formatting clean up 40993de
Owner

I actually don't see much purpose in this. The root readme file was converted for the repository main page, but the rest were written for li3_docs. Updating those would probably mean changing the documentation standard, and converting the API docs for the entire core, which is just not worth it. Thanks anyway for the efforts.

closed this
Owner

As simple as transitioning all namespace documents and READMEs (by changing the suffix from wiki to md) seems, changes like this lead to an inconsistent state across projects where some inevitably still use wiki while others are already at md.

The original need for changing the suffix comes from the way GitHub deals with such documents. This seems to be a little silly at first.

However I'd see there's something to win here as changing the suffix to .md would lead to:

• Enabling rendering of namespace documents within github and the repo browser.
• Standardization of the suffix. md would be the suffix I personally would use for markdown files. How much there is a standard for this is still debatable.

Potential solutions for transitioning include:

• Modifying li3_docs to look for wiki and md or make the suffix configurable.
• While we're moving projects over to gh change the suffix of the documents.
• Have a tool doing that for you:
for FILE in $(find . -name '*.wiki'); do git mv$FILE ${FILE/.wiki/.md}; done  All in all I would vote for finding out what we would deem official/standard, changing the suffix. In the same spirit we should discuss standard project files casing suffix i.e. LICENSE.txt README.txt. Owner Unfortunately, the issue isn't as simple as changing a file extension. If it was, I would be all for it. GitHub seems to use a fundamentally different Markdown format than we do, and changing that in all API docblocks in the core and across all applications is not my idea of a good time. :-) Besides, I think the format we have now reads better within the context of source code. That said, I'm more than happy to be proven wrong. If we can find some middle ground between our format and theirs, great. @mehlah: I know GitHub actually does support multiple markup formats (https://github.com/github/markup). Could you do some investigating and see if they actually do support our flavor and I just overlooked it or didn't do it right? If so, please reopen the issue and let us know whatever you find. Thanks! commented @nateabele I'll check on that referenced this pull request Closed ### Issue #336: Case Sensitive URLs referenced this pull request Merged ### Pull Request #658: add a contributing file @mehlah any information on the github/markup project? I see Nates points as valid, but also would like to see the benefit of what we would have if .md would be the suffix. Owner If all we have to do is change a file extension, awesome. :-) Well, i would go for that solution, even if github does not render everything as intended or done by li3_docs. At least, it is more readible than the standard .wiki files. referenced this pull request Merged ### Pull Request #708: renamed .wiki to .md referenced this pull request in UnionOfRAD/li3_docs Merged ### Pull Request #26: renamed .wiki to .md referenced this pull request in UnionOfRAD/manual Merged ### Pull Request #41: renamed .wiki to .md referenced this pull request in UnionOfRAD/manual Merged ### Pull Request #45: resubmit previous PR into restructure branch to join this conversation on GitHub. Already have an account? Sign in to comment Showing 2 unique commits by 1 author. Jun 13, 2011 Add Github flavored readme files 55c397f Minor formatting clean up 40993de This page is out of date. Refresh to see the latest. Showing 3 changed files with 337 additions and 0 deletions. 1. action/README.md 2. console/README.md 3. template/README.md 1  action/README.md  ... ... @@ -0,0 +1 @@ 1 +The action namespace relies on lithium\http, and includes classes required to route and dispatch HTTP requests. 181  console/README.md  ... ... @@ -0,0 +1,181 @@ 1 +**The console package contains a set of classes required to route and dispatch 2 +incoming console requests.** Moreover it contains the console front-controller 3 +file (lithium.php) as well as wrappers for both *nix and Windows environments 4 +(li3 and li3.bat respectively), allowing to easily invoke the 5 +console front-controller from the command line. 6 + 7 +A command is to the command line what an action controller is to the HTTP 8 +request/response flow. In that commands are quite similar to controllers. 9 +Commands don't leverage the the full MVC as they don't utilize views, but 10 +directly interact with the user through in() and out(). 11 + 12 +Lithium itself provides amongst others commands for creating new applications 13 +or parts thereof. However commands can also be provided through other libraries 14 +or by your application. Commands running in the application context will have 15 +complete access to your application. This is especially useful to reuse 16 +existing logic in an application's model when creating a command to be run as 17 +i.e. a cron-job. 18 + 19 + 20 +## Invoking the front-controller ## 21 + 22 +You right away invoke the console front-controller through one of the wrappers 23 +provided. From the root directory of a standard Lithium distribution call one 24 +of the follwing commands. The first is for users on a *nix command line the 25 +second for users on a Windows system. Please note that the preceding $ in 26 +examples always indicates things that you entere on the command line. 27 + 28 + $libraries/lithium/console/li3 29 +$ libraries/lithium/console/li3.bat 30 + 31 + 32 +However it is recommended you add the path containing the wrapper to the paths 33 +searched by your system. This is $PATH for *nix and %PATH% for Windows. 34 + 35 + 36 +### A: Configuring your$PATH on *nix ### 37 + 38 +This is almost always achievable on a per-user basis through the user's 39 +.profile (Users running Bash may prefer .bash_profile). The file is located 40 +in your home directory. Open the file and add the following line, assuming the 41 +li3 wrapper exists in /path/to/libraries/lithium/console. 42 + 43 + export PATH+=:/path/to/libraries/lithium/console 44 + 45 + 46 +Once you've followed these steps, save your modified the file and reload your environment settings 47 +by sourcing the modified profile through the following command. 48 + 49 + $source ~/.profile 50 + 51 + 52 +If you can't or don't want to modify your $PATH you use two other techniques 53 +to make the wrapper available as just li3. You can either symlink the 54 +wrapper into one of the paths found in the $PATH environment variable 55 + 56 +$ cd /path/to/a/directory/in/your/path 57 + $ln -s /path/to/libraries/lithium/console 58 + 59 +or create a permanent alias by adding an alias to i.e. the .bashrc file in your home directory. 60 + 61 + alias li3='/path/to/lithium/libraries/lithium/console/li3' 62 + 63 + 64 +### B: Configuring your %PATH% on Windows ### 65 + 66 +**Note**: Please note that if you're on Windows you've additionally got to add the PHP directory to 67 + the %PATH% environment variable. As we are going to edit that variable for adding 68 + the location of where the li3.bat wrapper is anyway, we can kill two birds with one stone. 69 + 70 + * Open _System_ from within the _Control Panel_. 71 + * Open the _Advanced_ tab. 72 + * Clicking the _Environment Variables_ button open a dialog where you can edit the variables. 73 + * Double click the _PATH_ entry in order to edit it. 74 + * Add C:\path\to\php;C:\path\to\libraries\lithium\console to the end of the value. 75 + 76 +### Finishing up ### 77 + 78 +Now that you've made the wrapper available as li3 or li3.bat respectively, 79 +you should be able to use it from the command-line just by executing li3 and 80 +li3.bat. Invoking the wrapper like that (without arguments) should give you a 81 +list of available commands. 82 + 83 +$ li3 84 + $li3.bat 85 + 86 + 87 +## Built-in commands ## 88 + 89 +Using the commands which come with lithium is easy. Invoke the wrapper without 90 +any arguments to get a list of all available commands. Get a description about 91 +each command and the options and arguments it accept or may require by using 92 +the help command. 93 + 94 +$ li3 help 95 + $li3 help create 96 +$ li3 help g11n 97 + 98 + 99 +## Creating custom commands ## 100 + 101 +Creating your own commands is very easy. A few fundamentals: 102 + 103 +* All commands inherit from lithium\console\Command. 104 +* Commands are normally placed in your application or library's extensions/commands directory. 105 + 106 +Here's an example command: 107 + 108 + 109 + header('Welcome to the Hello World command!'); 117 + $this->out('Hello, World!'); 118 + } 119 + } 120 + 121 + ?> 122 + 123 + 124 +If you would like to try this command, create an application or use an existing 125 +application, and place the command into the application's extensions/commands 126 +directory and save it as HelloWorld.php. After doing so, open a shell and 127 +change directory to your application's directory and run the following command: 128 + 129 + 130 +$ li3 hello_world 131 + 132 + 133 +Although it's probably obvious, when this command runs it will output a nice 134 +header with the text Welcome to the Hello World command! and some regular 135 +text Hello, World! after it. 136 + 137 +The public method run() is called on your command instance every time your 138 +command has been requested to run. From this method you can add your own command 139 +logic. 140 + 141 +### Parsing options and arguments ### 142 + 143 +Parsing options and arguments to commands should be simple. In fact, the 144 +parsing is already done for you. 145 + 146 +Short and long (GNU-style) options in the form of -f, --foo and --foo=bar 147 +are automatically parsed and exposed to your command instance through its 148 +properties. XF68-style long options (i.e. -foo) are not supported by default 149 +but support can be added by extending the console router. 150 + 151 +Arguments are passed directly to the invoked method. 152 + 153 +Let's look at an example, going back to the hello_world command from earlier: 154 + 155 + header('Welcome to the Hello World command!'); 165 + $this->out('Hello, ' . ($this->recipient ?: 'World') . '!'); 166 + } 167 + } 168 + 169 + ?> 170 + 171 + 172 +Notice the additional property $recipient? Great! Now when --recipient is 173 +passed to the hello_world command, the recipient property on your command 174 +instance will be set to whatever was passed into the command at runtime. 175 + 176 +Try it out with the following command: 177 + 178 +$ li3 hello_world --recipient=AwesomeGuy 179 + 180 + 181 +You should get a special greeting from our good old hello_world command.
 ... ... @@ -0,0 +1,155 @@ 1 +## Special syntax ## 2 + 3 +Views have a special syntax for outputting escaped text. The standard way to 4 +output escaped text in your views from Lithium is as follows: 5 + 6 +  7 + 8 + 9 +This is where a lot of confusion comes in, because it is commonly misunderstood 10 +that Lithium depends on short_open_tags, however, that's not the case. The 11 +contents of a view are processed through a tokenizer (template/view/Compiler) before 12 +it is included by PHP. The file is then compiled into the final PHP+HTML (or whatever 13 +other content type that is requsted), which is then passed off to be fully rendered 14 +by the two-step view to its final form. 15 + 16 +See the PHP [manual](http://php.net/manual/en/book.tokenizer.php) to learn more about tokens. 17 + 18 +The stream wrapper reads the file and searches for anything that looks like 19 + and replaces it with . 20 + 21 +The design decision behind using PHP's short echo syntax is because it's a 22 +familiar syntax and it helps developers focus more on what data _should not_ be 23 +escaped vs. what data _needs_ to be escaped. 24 + 25 +One special case situation to take _important_ note of, is the use of foo()?>. 26 +In this scenario, the code is translated to foo(); ?> 27 +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. 28 +This is to make it easier to work with helpers that return markup. 29 + 30 +An example would be something like: 31 + 32 + form->create();?> 33 + ... my form here ... 34 + form->end();?> 35 + 36 +**Note:** $h() is the HTML escape function used in views. 37 + 38 +**Note:** To output regular, unescaped text, use plain old . 39 + 40 +**Other useful information:** 41 + 42 + * [Introduction to PHP streams](http://www.php.net/intro.stream) 43 + * [Stream examples](http://www.php.net/stream.examples) 44 + 45 + 46 +## Using helpers ## 47 + 48 +Helpers are lazy-loaded by the current renderer. To use a helper, you can 49 +reference it by its name like this: 50 + 51 + echo$this->html->link('Google', 'http://www.google.com'); 52 + 53 +In a template, $this refers to the Renderer object. By using $this->html 54 +for the first time, the renderer will create an instance of the helper and store 55 +it so that the next time the helper is invoked the renderer will not have to 56 +re-instantiate the helper. 57 + 58 +Using such an approach, helpers can easily be loaded as needed without any 59 +performance impact. 60 + 61 +**More info** 62 + 63 + * [HTML helper](template/helper/Html) 64 + * [Form helper](template/helper/Form) 65 + * [Helper base class](template/Helper) 66 + 67 + 68 +## Creating custom helpers ## 69 + 70 +You can also create your own custom helper very easily by extending the Helper base class, and 71 +placing your helper in the correct namespace. By default, helpers belong in the 72 +\extensions\helper namespace, but this can be changed through configuration (see the 73 +the Libraries class (core/Libraries)). 74 +For example, consider the following class, saved as app/extensions/helper/Custom.php: 75 + 76 +  88 + 89 + 90 +You can then use your helper in templates as follows: 91 + 92 + custom->greeting("World"); ?> 93 + 94 + 95 +Your custom helper will then be auto-loaded into the templating engine from your application or a 96 +plugin. 97 + 98 + 99 +## Extending core helpers ## 100 + 101 +Because your application and plugins have a higher order-of-precedence than the Lithium core, 102 +classes like helpers can be extended and replaced seamlessly, without any changes to your templates. 103 + 104 +For example, to add or replace methods in the Form helper, you can add the following to 105 +app/extensions/helper/Form.php: 106 + 107 + 108 +  118 + 119 + 120 +Your custom Form helper will now be invoked in all instances where $this->form is called in a 121 +template. For more information on the load order of classes, see 122 +the locate() method of the Libraries class (core/Libraries::locate) 123 + 124 + 125 +## Rendering elements ## 126 + 127 +Elements are reusable view snippets that you can use in several views and layouts. 128 +You can reference it like so: 129 + 130 + echo$this->_render('element', 'menu'); 131 + 132 + 133 +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. 134 +You can pass variables declared in the view or additional static content using the third parameter to $this->_render(): 135 + 136 + $var1 = 'something'; 137 + echo$this->_render('element', 'menu', array( 138 + 'var1' => $var1, 139 + 'var2' => 'something else' 140 + )); 141 + 142 + 143 +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: 144 + 145 + echo$this->view()->render( 146 + array('element' => 'menu'), 147 + array('var1' => $var1, 'var2' =>$var2) 148 + ); 149 + 150 + 151 +**More info** 152 + 153 + * [View](template/View) 154 + * [Renderer](template/view/Renderer) 155 + * [File adapter](template/view/adapter/File)