Skip to content

Functions

Jump to bottom Edit New page
kbrookes edited this page Nov 10, 2021 · 61 revisions

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()

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

snippet()

The snippet() function calls the snippet template helper. The function makes it very easy to define, expand and check if a snippet exists.

define

<? $snippet = '
<a class="button" href="$url" $attributes>
    $icon<span>$label</span>
</a>'
?>

<? snippet('button', $snippet); ?>

expand

<? snippet('button', [
    'url' => 'http://exampme.com'
    'icon' => /path/to/icon
    'label' => 'Press here'
    'attributes' => attributes([…])
]); ?>

exists

<? if(snippet('button')) : ?>
…
<?endif?>

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()

The date() function has been refactored and the arguments have been switched to follow its PHP counterpart

date( string $format = '', [, mixed $date = 'now' ])

The date argument accepts:

slug()

Functions transforms any string into a slug, using following approach: Replace all accented UTF-8 characters by unaccented ASCII-7 "equivalents", replace whitespaces by hyphens and lowercase the result.

json()

This function is a shortcut for json_encode

format()

This function is a shortcut for sprintf

replace()

This function is a shortcut for strtr

debug()

Returns true if template debug is enabled.

url()

[todo]

user()

The user([username|id]) template function allow to load a user object for a specific user.

  • The function accepts a user id, or username as parameter and will return the respective user object if the user exists, or an anonymous object if no user can be found
  • If no parameter is passed it will return the active user object or an anonymous object if no user is logged in
<? $user = user() ?>

or

  • var_dump of the user object is possible and will return the user data for easy introspection.
<? var_dump(user()) ?>

The user object can be used to easily perform permission checks, for example to check if the user is logged in, part of a group, or if the user has a specific role.

logged in

Check if the user is logged in.

<? if(user()->isAuthentic()) : ?>
…
<?endif?>

Note: A user that has logged in, is authentic.

groups Check if a user is part of a any of the specified groups: hasGroup([groups], [strict])

<? if(user()->hasGroup(['manager', 'administrator'], true)) : ?>
…
<?endif?>

Note1: The value passed can both be a single group name, group id, or an array of group names or id's. The check will return true of the user is part of at least one of the groups. Note2: The method has a second strict parameter. If true the user needs to be part of all the groups. If not the methods will return false.

roles

Check if the user has a specific role: hasRole([roles], [strict])

<? if(user()->hasRole('special')) : ?>
…
<?endif?>

Note1: A role is the same as a view level.

Note2: The method has a second strict parameter. If true the user needs to have all the roles. If not the methods will return false.

Note3: The value passed can both be a single role name, role id, or an array of role names or id's. The check will return true of the user has at least one of the provided roles.

For more user methods please check the KUserInterface and ComKoowaUserInterface

empty()

The empty(mixed $var) function works in the same way as its PHP counterpart but also offers support for Traversable and Countable objects.

  • Traversable: If an object is traversable it will return TRUE if iterator_count() returns not 0
  • Countable: If an object is countable it will return TRUE if the count is not 0

config()

Function gives easy access to both the site runtime configuration as the configuration of extensions or other objects.

Access site configuration

<?= config()->http_cache ?>

Access object configuration

<?= config('ext:template.helper.foo')->bar ?>

To access a specific objects its configuration you can call the config method with the object identifier.

element()

This function can be used to create HTML elements without dealing with escaping or whitespace. It's modelled after React.createElement

Example:

<?= element('a', ['href' => 'https://example.com/'], 'example link'); ?>
// returns '<a href="https://example.com/">example link</a>

<?=element('meta', ['name' => 'foo', 'content' => 'bar']); ?>
returns '<meta name="foo" content="bar" />

unbox()

The function accepts any variable, if the variable is an object it will unbox the object returning the object properties as a a PHP array. It will perform following operations on the object, in order:

  • If the object has a toArray()method it will call it
  • If the object implements [\Traversable](https://www.php.net/manual/en/class.traversable.php) interface it will call [iterator_to_array](https://www.php.net/manual/en/function.iterator-to-array.php)
  • It will fallback to [get_object_vars()](https://www.php.net/manual/en/function.get-object-vars.php)

Custom functions

You can also define your own custom template functions. Template functions can be defined in two places:

  1. A custom extension: /extensions/[name]/template/function/[file].php
  2. The pages extension (*): /extensions/pages/template/function/[file].php

The pages extension is a special reserved namespace that cannot be used.

The [file] name represents the function name and the file should return an closure. Using $this inside the closure will return the active template object (ComPagesTemplateDefault).

For example /extensions/[name]/template/function/foo.php

<?php
return function($var)
{
    return $var;
};

Can be called as <?= foo('bar') ?>.

Overwriting existing functions

Please take note that if a custom function uses the same name as a build in php function or a build in Pages function it will overwrite that function. This is a very powerful mechanism as it allow you to extend PHP as a programming language. However to prevent possible conflicts it's recommended to prefix your own custom functions.

Got a question or need help? We have a forum on Github Discussions where you can get in touch with us.

Clone this wiki locally