Information Center

Although a lot can be done with XSL there are some limitations, especially as we can use only XSLT 1.0 and not XSLT 2.0 as there is no PHP support available for XSLT 2.0, means your server has only XSLT 1.0 installed. To overcome these limitations, it is necessary to call PHP for some functions. Therefore SobiPro provides not only built-in PHP functions, but also allows to add your own PHP code.

Declaring your PHP functions

For security reasons it is not possible to call every PHP function directly from a template file. Every PHP function which should be available in the template has to be registered for its usage.

To allow the usage of your own defined PHP function, they need to fulfil the following:

1. The functions must be inside of a PHP file (by default template.php) in the root folder of your template package.
2. This PHP file has to contain an abstract PHP class with static functions (by default tplDefault3). If you have duplicated a template in the global template manager of SobiPro, the name of the abstract class depends on the name of your template. SobiPro will correct the abstract class name for you while duplicating the template.
3. The name of this PHP file has to be defined in the global configuration file of the template package.

To make things easier, the SobiPro templates already include by default the PHP file template.php in the root of the template folder. This PHP file already contains the needed structure (including an abstract class) inside of it and it's already defined in the global configuration file. You only need to care about adding your own functions to this file and call them from your templates.

Example of a PHP file containing your own PHP functions:

<?php
    defined( 'SOBIPRO' ) || exit( 'Restricted access' );
 
    abstract class tplDefault4
    {
        public static function MyFirstFunction($para1, $para2)
        {
            ...
            return myResult;
        }
 
        public static function MySecondFunction($para1, $para2)
        {
            ...
            return myResult;
 
        }
    }
?>

Every PHP function defined within the abstract class in the PHP file is available in your template files. Of course you can use your own PHP file, with your own abstract class, but frankly, there is no reason to do so.

Register a PHP function

The following PHP functions are registered by default:

• date: Format a local time/date
• getdate: Get date/time information
• gettimeofday: Get current time
• gmdate: Format a GMT/UTC date/time
• localtime: Get the local time
• strtotime: Parse about any English textual datetime description into a Unix timestamp
• time: Return current Unix timestamp
• json_decode: Decodes a JSON string
• json_encode: Returns the JSON representation of a value
• htmlentities: Convert all applicable characters to HTML entities
• htmlspecialchars: Convert special characters to HTML entities
• number_format: Format a number with grouped thousands
• ucfirst: Make a string's first character uppercase
• ucwords: Uppercase the first character of each word in a string
• wordwrap: Wraps a string to a given number of characters
• rand: Generate a random integer
• strip_tags: Strip HTML and PHP tags from a string

To register another PHP function, create an override file of the file template_functions.ini located in the /components/com_sobipro/etc folder. The name of your override file will be template_functions_override.ini. To register a PHP function, extend the section [functions] by a new line. The key will be the name of the PHP function and the value is true.

Calling a PHP function within a XSL template file

To call a PHP function in one of your template files, you have to extend the definition of the template document to include the PHP namespace (xmlns:php="https://secure.php.net/xsl") in the stylesheet tag. Normally this is already added to all template files, but in case you have an older file or a file from a 3rd party developer who doesn't included this tag, you need to add it in order to use a PHP function in the template file.

To call a PHP function, defined in your PHP file, use the following structure:

<xsl:value-of select="php:function ('tplDefault3::MyFirstFunction', 'para1', 'para2')"/>

Where tplDefault4 is the name of the abstract class defined in your PHP functions file. If using the default SobiPro template, this will be 'tplDefault4'. This may be different for older or 3rd party templates.

MyFirstFunction is the name of the function itself, and para1 and para2 are strings passed to the function as arguments.

A function which is used in an XSL template can return either a simple string or in case you need a more advanced structure, a DOMDocument element (it may also return nothing). Depending on what it returns, it can be used alone, or will require additional code to handle the data returned.

Global PHP File

Functions defined in each template's template.php file, are "limited" to that specific template, meaning you won't be able to use them in other templates or in SobiPro modules, unless you double them.

It is possible to define a global PHP functions file to use in all section templates and the module's template files.

To define global PHP functions, you need to create a global PHP file containing all functions you want to use globally within SobiPro. The structure of that file will be the same as for the SobiPro template's template.php files. The global PHP file has to be located in the front folder of SobiPro template's area, accessible via the global template manager. It is wise, to use a different name for its abstract class name, for example abstract class GlobalFunctions, to distinguish it from the local PHP functions.

All your global PHP functions need to be registered in order to use them. For that create an override file of the file template_functions.ini located in the /components/com_sobipro/etc folder. The name of your override file will be template_functions_override.ini. To register your own global PHP function, create a section in the file with the name and path of your global PHP file in the front folder. Replace the slashes with dots and leave the file extension.
If you named your global PHP file my-global-functions.php the section will be [usr.templates.front.my-global-functions]. Now add a line for each PHP function in your global file, where the key is the name of the PHP function and the value is true.
If you have for example two PHP functions "IsNew()" and "IsUpdated()", your section will look like:

[usr.templates.front.my-global-functions]
IsNew = true
IsUpdated = true

Predefined PHP functions

There are several predefined SobiPro PHP functions available to use in the template files.

Overview of predefined PHP functions

The predefined PHP functions don't need to be mentioned in the local or global PHP files. The abstract class for these predefined PHP functions is always SobiPro.

• SobiPro::Cfg
• SobiPro::My
• SobiPro::User
• SobiPro::Tooltip
• SobiPro::Txt
• SobiPro::Url
• SobiPro::Request
• SobiPro::AlternateLink
• SobiPro::Can
• SobiPro::Currency

SobiPro::Cfg

The function SobiPro::Cfg returns a SobiPro configuration setting...

public static function Cfg($key, $def = null, $section = 'general')

...and has the following parameters:

$key

Name of configuration key

$def

Default value in case it does not exist

$section

Configuration section name of the key; section name 'general' is used if not given

Example usage: returns the live URL address of the site

<xsl:value-of select="php:function( 'SobiPro::Cfg', 'live_site' )"/>

SobiPro::My

The function SobiPro::My returns the selected property of the current user...

public static function My($property)

...and has the following parameters:

$property

Name of the property to show; for example: 'name', 'username', 'id'

Example usage: welcomes a registered user

Welcome <xsl:value-of select="php:function('SobiPro::My', 'name')"/>

SobiPro::User

The function SobiPro::User returns a selected property of an user identified by the given id...

public static function User($id, $property)

...and has the following parameters:

$id

The id of the user

$property

Name of the property to show; for example: 'name', 'username'

Example usage: returns the real name of the author of the currently displayed entry

<xsl:variable name="author">
    <xsl:value-of select="entry/author"/>
</xsl:variable>
Author: <xsl:value-of select="php:function('SobiPro::User', $author, 'name')"/>
 

SobiPro::Tooltip

The function SobiPro::Tooltip creates a tooltip with given text and title...

public static function Tooltip($tooltip, $title = null)

...and has the following parameters:

$tooltip

Tooltip text to show

$title

Title of the tooltip

Example usage:

<xsl:variable name="desc">
    <xsl:value-of select="description"/>
</xsl:variable>
<xsl:variable name="label">
    <xsl:value-of select="label"/>
</xsl:variable>
<xsl:value-of select="php:function( 'SobiPro::Tooltip', $desc, $label )" disable-output-escaping="yes"/>

SobiPro::Txt

Default SobiPro translation method. The function SobiPro::Txt returns a translated string depending on the currently active language...

public static function Txt($txt)

...and has the following parameters:

$txt

Text to translate.

You will see the usage of this function in all default SobiPro template files.

Example usage:

<xsl:value-of select="php:function('SobiPro::Txt', 'Text to show')"/>

SobiPro::Url

The function SobiPro::Url creates an internal URL to SobiPro functions/listings...

public static function Url($var = null, $js = false)

...and has the following parameters:

$var

A JSON encoded array with the URL parameters in form of {"key1":"value1","key2":"value2"}

$js

If true, the URL will be given in the raw, HTML unsafe form; default value is false.

If SEF is enabled and available for SobiPro, the URL will be search engine friendly.

Example usage: creates the link /index.php?option=com_sobipro&sid=600&task=entry.edit&Itemid=99

<xsl:variable name="Url">
    {"sid":"600","task":"entry.edit"}
</xsl:variable>
<xsl:value-of select="php:function('SobiPro::Url', $Url)"/>

SobiPro::Request

The function SobiPro::Request retrieves a parameter from the request (POST/GET)...

public static function Request($key, $def = null)

...and has the following parameters:

$key

Name of the parameter to get

$def

Default value if not available

SobiPro::AlternateLink

The function SobiPro::AlternateLink allows to add an alternate link to the HTML header of the displayed document...

public static function AlternateLink($url, $type, $title = null)

...and has the following parameters:

$url

A JSON encoded array with the URL parameters; see also SobiPro::Url

$type

Type of the link; for example: application/atom+xml or application/rss+xml

$title

Optional title for the link

Refer to Links and search engines on W3C for more information about alternate links.

Example usage: in the template file section/view.xsl, to create an alternate link for RSS feeds

<xsl:variable name="rssUrl">
    {"sid":"<xsl:value-of select="id"/>", "sptpl":"feeds.rss","out":"raw"}
</xsl:variable>
<xsl:variable name="sectionName">
    <xsl:value-of select="name"/>
</xsl:variable>
<xsl:value-of select="php:function( 'SobiPro::AlternateLink', $rssUrl, 'application/atom+xml', $sectionName )"/>

The example above generates the following alternate link:

<link href="/component/sobipro/600/view,rss?Itemid=23" rel="alternate" type="application/atom+xml" title="Section Name"/>

SobiPro::Can

The function SobiPro::Can checks the permission for an action...

public static function Can($subject, $action = 'access', $section = null, $ownership = 'valid')

...and has the following parameters:

$subject

category or entry

$action

e.g. access (default), edit, see_unpublished, ...

$section

Section name; if not given, the current section will be used

$ownership

own, all or valid (default).

Example usage: checks if entry owner may see unpublished entries

<xsl:value-of select="php:function('SobiPro::Can','entry','see_unpublished','own')"/>

To shorten this, it can also be used also in a short form (section is always the current section):

<xsl:value-of select="php:function('SobiPro::Can', 'subject.action.ownership')"/>

SobiPro::Currency

public static function Currency($value)

Formats a given value using currency options as set in Global Configuration - Payment Options (currency -€, $...-, currency symbol position, decimal point, thousands separator).

It and has the following parameters:

$value

numeric value to be formatted

Example usage:

<xsl:variable name="price">
   <xsl:value-of select="fields/field_price/data"/>
</xsl:variable>
<xsl:value-of select="php:function( 'SobiPro::Currency', $price )"/>