Functions

Joomlatools Pages comes out-of-the-box with template functions that help you to easily customise your template. Functions are only supported for the PHP engine. Of course, you can also use any PHP function in your templates.

Table of contents

• page()
• collection()
• data()
• route()
• state()
• attributes()
• helper()
• import()
• date()
• slug()
• json()
• format()
• replace()
• url()
• [Custom Functions](#Custom functions)

page()

The page() template function allows you to retrieve a page object which contains the page properties such as title, content, layout, etc.

You can use the page() function to target the current page or any active page. If a page path is not provided, the method will return the current page.

Examples:

$title = page()->title;                // Return the title of the current page.
$title = page('path/to/page')->title;  // Return the title of another page, not the current page.

See also: Page

collection()

The collection()template function allows you to retrieve a collection. It will return a traversable object.

The $state function parameter should be a php array that defines the specific state to be used to filter the collection.

See also: Page > Collection

Example:

$collection = collection('pages', ['limit' => 3, 'order' => 'shuffle');

data()

The data($path) template function allows you to work with structured data in templates. It receives a relative path or URL to the data file that needs to be loaded.

Example:

$data = data('company/team');

See also: Data

route()

If you want to generate an URL for a page you can use the route($page, $query = array(), $escape = false) template function. The function accepts three parameters:

• $page: A page path, or page object
• $query: Additional query parameters used to generate the URL
• $escape: If true, the URL will be escaped, for example for use in javascript.

Fragments that are included in the path are also appended to the resulting URL.

Example:

$url = route('path/to/page#fragment');

or

$url = route(page()#fragment);

See also: URLs and Linking > Routing

state()

The state() function gives you access to the active state. It returns a KModelStateInterface object.

Example:

$state = state();

See also: Collection > State

attributes()

The attributes() template function allows you to generate HTML element attributes. This is especially useful if the attribute could be empty and you don't want to render its name. The function can be used in two ways:

attributes($key, $value)

For example:

<a <?= attribute('class', $classes);?> <!-- if $classes is empty, it will not generate anything.-->

attributes($array)

For example:

<a <?= attribute(['class' => $classes, 'id' => 'id']);?> <!-- if $classes is empty, it will not generate a class attribute.-->

helper()

The helper($identifier, $config = array()) template function allows you to include template helpers, it accepts a helper identifier and an optional array of config options for the helper.

See also: Templates > Helpers

import()

The import($path, $data = array()) template function allows you to import a partial into a page or into another partial. For the sake of consistency, it is best to place them in the /partials directory.

Locating partials

However, you can import partials relative to the root pages folder /pages. The path to resolve the location of the partial can be both relative to the folder the partial is imported in, or absolute to the root pages folder.

The following partials are resolved against the root pages folder:

• file.html
• folder/file.html

The following partials are resolved relative to the folder the partials are imported into.

• ../file.html
• ../folder/file.html

Passing variables

You can also pass variables to a partial. For example, suppose you have a partial called note.html in your /partials directory that contains this formatting:

<div>
<?= $note ?>
</div>

The <?= $note ?> is a variable that gets populated when you import the partial and specify a value for that parameter, like this:

<?= import('/partials/note.html, ['content' => "This is my sample note."]) ?>

The value of content (which is "This is my sample note") will be inserted into the $note variable.

Passing variables to includes is especially helpful when you want to hide away complex formatting from your Markdown content.

See also: Templates > Partials

date()

[todo]

slug()

[todo]

json()

[todo]

format()

[todo]

replace()

[todo]

debug()

[todo]

url()

[todo]

Custom functions

Writing your own functions is also possible and fully supported in Pages.

Where to add functions

If you are writing functions for a specific extension, such as Joomla, it should be added to template functions for that specific extension:

/extensions/[extension name]/template/function/[function name].php

If your function needs to be available more globally, you can extend Pages itself by creating a 'pages' directory within the extensions directory:

/extensions/pages/template/function/[function name].php

Naming functions

Writing functions in Pages is practically the same as in any other php environment, but there are a couple of differences.

The filename is the function name

If I'm calling readTimeEstimator($var);, then there needs to be a corresponding filename called readTimeEstimator.php

Don't use the function name in the function itself

A typical function would be written like so:

myFunctionName($var){
  // do something
  return $var;
}

Custom template functions in pages must use the following terminology:

return function($var){
  // do something
  return $var;
}

Template functions written like this and added to the /extensions/pages/template/function/ directory will be available globally and can be called by their function name.