Creating the Page
Function documentation pages should have a URL that starts with Functions/.
To add new documentation for the function foo(), add this to a page:
[[Functions/foo|foo()]]
This will create a link that points to the new documentation page for the foo() function. Following the link will allow you to add content to the new page.
Page Structure
Function documentation pages should follow the following structure:
- Summary - A prose description of the purpose and usage of the function
- Since - The version of Omeka in which the function was introduced, and the version deprecated if applicable
- Usage - A code snippet showing the usage (see below)
- Arguments - A list of the arguments passed (see below)
- Options - A description of any options arrays passed (see below)
- Return Value - The value type returned by the function
- See Also - A list of related functions, linked to their documentation
Use, for example,
== Usage ==
to set off the sections. Do not include a heading for the summary.
Make sure that each page is categorized as a Function by adding
{{ApiCategory|Functions}}
at the bottom of each page you write.
The documentation for item() provides a full example.
Templates and Wiki Snippets
Usage Template
The usage section gives a complete example of how to call the function, with all arguments given descriptive names, and showing default values.
Use <source lang="php">...</source> markup.
Example
item($elementSetName, $elementName, $options = array(), $item = null);
Is produced by:
<source lang="php"> item($elementSetName, $elementName, $options = array(), $item = null); </source>
Arguments Template
The arguments section describes all arguments that can be passed to the function, giving name, type, description, and default value.
Use the Template:Parameter template.
Example
- string
$elementSetName - The element set to use. Additionally, the item() helper accepts 'special values' here that do not correspond to an Element Set or Element. Those values are: 'id', 'item type name', 'date added', 'collection name'. 'featured', 'public', and 'permalink'.
- string
$elementName(optional) - The name of the element to display.
- Default:
null - array
$options(optional) - Options that affect the output of the function. See the Options section below for details on valid options.
- Default:
array() - Item
$item(optional) - The Item object to work on. The default (
null) is to use the current item. - Default:
null
Wiki code
{{Parameter
| name = elementSetName
| type = string
| description = The element set to use. Additionally, the item() helper accepts 'special values' here that do not correspond to an Element Set or Element. Those values are: 'id', 'item type name', 'date added', 'collection name'. 'featured', 'public', and 'permalink'.
}}
{{Parameter
| name = elementName
| type = string
| description = The name of the element to display.
| default = null
}}
{{Parameter
| name = options
| type = array
| description = Options that affect the output of the function. See the [[#Options|Options]] section below for details on valid options.
| default = array()
}}
{{Parameter
| name = item
| type = Item
| description = The Item object to work on. The default (<code>null</code>) is to use the current item.
| default = null
}}
Options Template
When an $options argument is available, give a complete description of valid keys and values, and behaviors associated with different values where applicable. If a new valid key/value pair has been added since the first implementation of the function, signal that with, e.g., Since 1.X as the first element of the description.
Use a definition list.
Example
'delimiter'- String
- Return the entire set of metadata as a string, where each entry is separated by the string delimiter.
'index'- Integer
- Return the metadata entry at the specific integer index, starting at 0.
'no_escape'- Boolean
- If set to true, return the text without HTML-escaping.
'no_filter'- Boolean
- Return the set of metadata without running any of the filters.
'snippet'- Integer
- Trim the length of each piece of text to the given integer length.
'all'- Boolean
- If set to true, this will retrieve an array containing all values for a single element rather than a specific value. If set to false, an array is still returned containing only a single value. If set to null, no array is returned.
Wiki Code
;<code>'delimiter'</code> :''String'' :Return the entire set of metadata as a string, where each entry is separated by the string delimiter. ;<code>'index'</code> :''Integer'' :Return the metadata entry at the specific integer index, starting at 0. ;<code>'no_escape'</code> :''Boolean'' :If set to true, return the text without HTML-escaping. ;<code>'no_filter'</code> :''Boolean'' :Return the set of metadata without running any of the filters. ;<code>'snippet'</code> :''Integer'' :Trim the length of each piece of text to the given integer length. ;<code>'all'</code> :''Boolean'' :If set to true, this will retrieve an array containing all values for a single element rather than a specific value. If set to false, an array is still returned containing only a single value. If set to null, no array is returned.
Return Value
The type of data returned by the function, possibly with short guidance of how to use the returned data.
Example
- mixed
- A string or an array suitable for
echoing to the screen, or looping toechoeach value.
Wiki Code
;mixed :A string or an array suitable for <code>echo</code>ing to the screen, or looping to <code>echo</code> each value.
See Also
A list of related functions
Example
Wiki Code
* [[Functions/set_current_item|set_current_item()]] * [[Functions/set_items_for_loop|set_items_for_loop()]] * [[Functions/loop_items|loop_items()]]
Empty Template
{{UnderscoreTitle}}
== Summary ==
== Since ==
== Usage ==
<source lang="php">
foo($arg1, $arg2);
</source>
== Arguments ==
{{Parameter
| name =
| type =
| description =
| default =
}}
{{Parameter
| name =
| type =
| description =
| default =
}}
== Options ==
;<code>' '</code>
:'' ''
:
;<code>' '</code>
:''Since ''
:'' ''
:
== Return Value ==
<pre>
;
:
</pre>
== See Also ==
* [[Functions/foo|foo()]]
* [[Function/bar|bar()]]
{{ApiCategory|Functions}}
