$pico
$pico : \Pico
Current instance of Pico
Pico's Twig extension to implement additional filters
$pico : \Pico
Current instance of Pico
__construct(\Pico $pico)
Constructs a new instance of this Twig extension
| \Pico | $pico | current instance of Pico |
getPico() : \Pico
Returns the extensions instance of Pico
the extension's instance of Pico
markdownFilter(string $markdown, array $meta = array(), boolean $singleLine = false) : string
Parses a markdown string to HTML
This method is registered as the Twig markdown filter. You can use it
to e.g. parse a meta variable ({{ meta.description|markdown }}).
Don't use it to parse the contents of a page, use the content filter
instead, what ensures the proper preparation of the contents.
| string | $markdown | markdown to parse |
| array | $meta | meta data to use for %meta.*% replacement |
| boolean | $singleLine | whether to parse just a single line of markup |
parsed HTML
mapFilter(array|\Traversable $var, mixed $mapKeyPath) : array
Returns a array with the values of the given key or key path
This method is registered as the Twig map filter. You can use this
filter to e.g. get all page titles ({{ pages|map("title") }}).
| array|\Traversable | $var | variable to map |
| mixed | $mapKeyPath | key to map; either a scalar or a array interpreted as key path (i.e. ['foo', 'bar'] will return all $item['foo']['bar'] values) |
mapped values
sortByFilter(array|\Traversable $var, mixed $sortKeyPath, string $fallback = 'bottom') : array
Sorts an array by one of its keys or a arbitrary deep sub-key
This method is registered as the Twig sort_by filter. You can use this
filter to e.g. sort the pages array by a arbitrary meta value. Calling
{{ pages|sort_by([ "meta", "nav" ]) }} returns all pages sorted by the
meta value nav. The sorting algorithm will never assume equality of
two values, it will then fall back to the original order. The result is
always sorted in ascending order, apply Twigs reverse filter to
achieve a descending order.
| array|\Traversable | $var | variable to sort |
| mixed | $sortKeyPath | key to use for sorting; either a scalar or a array interpreted as key path (i.e. ['foo', 'bar'] will sort $var by $item['foo']['bar']) |
| string | $fallback | specify what to do with items which don't contain the specified sort key; use "bottom" (default) to move these items to the end of the sorted array, "top" to rank them first, "keep" to keep the original order, or "remove" to remove these items |
sorted array
getKeyOfVar(array|\Traversable|\ArrayAccess|object $var, mixed $keyPath) : mixed
Returns the value of a variable item specified by a scalar key or a arbitrary deep sub-key using a key path
| array|\Traversable|\ArrayAccess|object | $var | base variable |
| mixed | $keyPath | scalar key or a array interpreted as key path (when passing e.g. ['foo', 'bar'], the method will return $var['foo']['bar']) specifying the value |
the requested value or NULL when the given key or key path didn't match
urlParamFunction(string $name, integer|string $filter = '', mixed|array $options = null, integer|string|array<mixed,integer>|array<mixed,string> $flags = null) : mixed
Filters a URL GET parameter with a specified filter
The Twig function disallows the use of the callback filter.
| string | $name | name of the URL GET parameter to filter |
| integer|string | $filter | the filter to apply |
| mixed|array | $options | either a associative options array to be used by the filter or a scalar default value |
| integer|string|array<mixed,integer>|array<mixed,string> | $flags | flags and flag strings to be used by the filter |
either the filtered data, FALSE if the filter fails, or NULL if the URL GET parameter doesn't exist and no default value is given
formParamFunction(string $name, integer|string $filter = '', mixed|array $options = null, integer|string|array<mixed,integer>|array<mixed,string> $flags = null) : mixed
Filters a HTTP POST parameter with a specified filter
The Twig function disallows the use of the callback filter.
| string | $name | name of the HTTP POST parameter to filter |
| integer|string | $filter | the filter to apply |
| mixed|array | $options | either a associative options array to be used by the filter or a scalar default value |
| integer|string|array<mixed,integer>|array<mixed,string> | $flags | flags and flag strings to be used by the filter |
either the filtered data, FALSE if the filter fails, or NULL if the HTTP POST parameter doesn't exist and no default value is given
pagesFunction(string $start = '', integer|null $depth, integer $depthOffset, integer $offset = 1) : array<mixed,array>
Returns all pages within a particular branch of Pico's page tree
This function should be used most of the time when dealing with Pico's pages array, as it allows one to easily traverse Pico's pages tree (\Pico::getPageTree()) to retrieve a subset of Pico's pages array in a very convenient and performant way.
The function's default parameters are $start = "", $depth = 0,
$depthOffset = 0 and $offset = 1. A positive $offset is equivalent
to $depth = $depth + $offset, $depthOffset = $depthOffset + $offset
and $offset = 0.
Consequently the default $start = "", $depth = 0, $depthOffset = 0
and $offset = 1 is equivalent to $depth = 1, $depthOffset = 1 and
$offset = 0. $start = "" instruct the function to start from the
root node (i.e. the node of Pico's main index page at index.md).
$depth tells the function what pages to return. In this example,
$depth = 1 matches the start node (i.e. the zeroth generation) and all
its descendant pages until the first generation (i.e. the start node's
children). $depthOffset instructs the function to exclude some of the
older generations. $depthOffset = 1 specifically tells the function
to exclude the zeroth generation, so that the function returns all of
Pico's main index page's direct child pages (like sub/index.md and
page.md, but not sub/page.md) only.
Passing $depthOffset = -1 only is the same as passing $start = "",
$depth = 1, $depthOffset = 0 and $offset = 0. The only difference
is that $depthOffset won't exclude the zeroth generation, so that the
function returns Pico's main index page as well as all of its direct
child pages.
Passing $depth = 0, $depthOffset = -2 and $offset = 2 is the same
as passing $depth = 2, $depthOffset = 0 and $offset = 0. Both will
return the zeroth, first and second generation of pages. For Pico's main
index page this would be index.md (0th gen), sub/index.md (1st gen),
sub/page.md (2nd gen) and page.md (1st gen). If you want to return
2nd gen pages only, pass $offset = 2 only (with implicit $depth = 0
and $depthOffset = 0 it's the same as $depth = 2, $depthOffset = 2
and $offset = 0).
Instead of an integer you can also pass $depth = null. This is the
same as passing an infinitely large number as $depth, so that this
function simply returns all descendant pages. Consequently passing
$start = "", $depth = null, $depthOffset = 0 and $offset = 0
returns Pico's full pages array.
If $depth is negative after taking $offset into consideration, the
function will throw a \Twig_Error_Runtime exception, since this
would simply make no sense and is likely an error. Passing a negative
$depthOffset is equivalent to passing $depthOffset = 0.
But what about a negative $offset? Passing $offset = -1 instructs
the function not to start from the given $start node, but its parent
node. Consequently $offset = -2 instructs the function to use the
$start node's grandparent node. Obviously this won't make any sense
for Pico's root node, but just image $start = "sub/index". Passing
this together with $offset = -1 is equivalent to $start = "" and
$offset = 0.
| string | $start | name of the node to start from |
| integer|null | $depth | return pages until the given maximum depth; pass NULL to return all descendant pages; defaults to 0 |
| integer | $depthOffset | start returning pages from the given minimum depth; defaults to 0 |
| integer | $offset | ascend (positive) or descend (negative) the given number of branches before returning pages; defaults to 1 |
the data of the matched pages