^Status|Draft|
^Todo|Pretty much everything|

====== Guidelines ======

Anyone is free to create an account and start editing this user guide. These are the guidelines you should follow to keep it consistent and tidy. If you have ideas for these guidelines then please start a [[:userguide:discussion|discussion]]. Documentation is always for the latest release, currently 2.3 

===== Page Status =====

At the top of most pages you will find a status box. This should be kept up to date while you are editing the pages.

^Status|Draft|
^Todo|Complete this_function(), add example to that_function()|

There are 5 different values status can be:
  * **Stub:** The page has been created and there is no real information yet, maybe a few headers.
  * **Draft:** This should be used when the page is "in progress" and not feature or style complete.
  * **Proof:** When the page is considered complete and needs to be proof read for factualness and spelling/grammar mistakes.
  * **Final:** After it has been proof read and all information is complete and correct. The page may be edited after this to be expanded or reworded, but the status must be changed back to Draft or Proof.
  * **Out of date:** When there is a major code change for the subject of the page making the documentation invalid. The Todo line should also be filled in with what has changed.

There is also an optional Todo line. Any information you think will be helpful to other documenters should be added here, such as functions to be completed or sections that are out of date. Once something is completed it should be removed.

===== Versions =====

The user guide should always be written for the release version of the framework. If there are changes made in the SVN version then these should be highlighted in the user guide using a box, e.g.

<code|h Code:>
<box red>
This method only exists in version x.x
</box>
</code>

Gives:

<box red>
This method only exists in version x.x
</box>

===== Plugins =====

There are a few extra plugins installed in this wiki for use in the user guide.

  * [[doku>plugin:boxes|Boxes]]
  * [[doku>plugin:code2|Code2]]

==== Boxes ====

These should be used to note something important. The default blue colour should be used for normal notes and red should be used when it's critical. Rounded corners should not be used.

==== Code2 ====

===== Styling Conventions =====

==== Code examples ====

All code examples should follow the Kohana coding standards found at [[http://dev.kohanaphp.com/wiki/kohana2/CodingStyle]]

==== Files and Directories ====

Files and directory paths should be styled as follows:
''application/config/config.php''
Note: there is no leading slash.


==== Variable names ====

Variable names, files, class and method names used in the text should be styled as follows:

''$variable'' is used by ''Kohana::log'' when writing to ''application/logs/log.php'' 

==== Methods ====

The following style / layout should be used to document Methods:

Specify only the method name in descriptions. Code examples must provide the full notation, ''Class->method'' or ''Class::method''

''method($arg1, $arg2 = NULL, $arg3 = 'default_value')'' returns the number of items in ''XYZ'' given ''arg1''
  * **[string]** ''$arg1'' The name of the field for ''XYZ''
  * **[mixed]** ''$arg2'' An optional array of attributes.
  * **[string]** ''$arg3'' The value of ''ABC'', default is description of default
  * returns **[integer]** A count of items in ''XYZ''

Code Example:
<code php>
// Preferred notation using $this->
$this->class->method($arg1); 
// OR, if the class can be accessed via an instance
Class::instance()->method($arg1) 
// OR, for static methods and helpers
Kohana::log('type', 'message');
</code>


==== Example:  Retrieve a session item ====

''get($key = FALSE, $default = FALSE)'' retrieves a named value from the session data.
  * **[mixed]** ''$key'' specifies the name of the data to retrieve from the session. 
  * **[mixed]** ''$default'' specifies a default value to be returned if the named data does not exist in the session.
  * returns **[mixed]** The value of the session item specified by ''$key''  If ''$key'' is ''FALSE'', ''get()'' returns an array containing all of the data in the current session.

Code Example:
<code php>
$item_name = $this->session->get('item_name');
</code>


==== Page layout ====

An example of how a page should be structured [[userguide:guidelines:sample|Page layout sample]]