PAGENODE

Selector API Reference

A Selector provides a query interface to retrieve your nodes from the file system. See Selecting Content for some examples.

select([$path])

Create a new selector PN_Selector to retrieve nodes from the specified $path. If no path is specifed, the current directory is used.

foundNodes()

Return the total number of Nodes matched by the last query, before limiting to $count.

select($path)->one([$params], [$raw])

Select the newest Node matching the specified $params. Returns a single PN_Node instance or null if no matching Node can be found.

• $params – an array or parameters to match. See Selector Params for the details. Default [] (an empty array).
• $raw – whether to not escape node values with htmlSpecialChars() and parse Markdown. Default false.

select($path)->newest([$count], [$params], [$raw])

Select the newest $count Nodes matching the specified $params. Returns an array of PN_Node instances.

• $count – the maximum number of Nodes to return or 0 for no limit. Default 0.
• $params – an array or parameters to match. See Selector Params for the details. Default [] (an empty array).
• $raw – whether to not escape node values with htmlSpecialChars() and parse Markdown. Default false.

select($path)->oldest([$count], [$params], [$raw])

Same as select()->newest() but in reverse order.

select($path)->query($sort, $order, $count, $params, [$raw])

Select the newest $count Nodes matching the specified $params with the specified ordering. Returns an array of PN_Node instances.

This function is somewhat lower level than one(), newest() or oldest() and should only be used when you need a custom sort order.

• $sort – the Node header value by which to sort nodes.
• $order – the sort direction. Either 'desc' or 'asc'.
• $params – an array or parameters to match. See Selector Params for the details.
• $count – the maximum number of Nodes to return or 0 for no limit.
• $raw – whether to not escape node values with htmlSpecialChars() and parse Markdown. Default false.

Selector Params

An array of keys and values to match nodes against. See Selecting Content for some examples.

$params['keyword']

Match the specified keyword. A keyword is the Node's file name minus the .md extension.

$params['date']

Match the specified date. The date can either be an array of [$y, $m, $d] (where $m and $d are optional) or a string in the format "yyyy.mm.dd".

$params['tags']

Match Nodes that contain all specified tags. Tags can either be an array or a string. If it is a string, it will be split into distinct tags by , (comma).

$params['meta']

Match by arbitrary header values, specifed by an assoc array. E.g.

$params['meta'] = ['title' => 'API-Reference']

$params['filter']

Match by a custom filter function. E.g. for a regexp search:

$params['filter'] = function($n) {
    return preg_match('/some.*thing/', $n['title']);
}

Note that the value provided to the filter function is the raw Node data as an assoc array, not a PN_Node instance.

$params['page']

When limiting the number of Nodes to select through $count, the page specifies the offset, starting at 0. E.g. if you want to select 3 nodes per page, you can select nodes 3, 4, 5 (skipping the first 3) with $count = 3 and $params['page'] = 1.