FrançaisEnglish

AmetysXSLTHelper

 This helper is here to grant you access to a lot of features from any XSLT file (content type rendering, service rendering...). It is available from version 3.3.

  1. How to use it ?
  2. Reference
    1. URL Prefixes / Application Context
      1. uriPrefix - returns the server url prefix, relatively to server
      2. absoluteUriPrefix - same as uriPrefix but absolutely
      3. siteUriPrefix - returns the server url prefix for the current site or specific site, relatively to server
      4. absoluteSiteUriPrefix - same as siteUriPrefix but absolutely
    2. Skin
      1. skin - returns the name of the skin
      2. skinURL - returns a path to a skin resource
      3. skinResources - Returns an object describing a directory of the skin resources
      4. template - returns the name of the current template
      5. templateURL - returns a path to a template resources
      6. zone - returns the name of the currently processed zone
    3. Page
      1. site - returns the current site
      2. lang - returns the current language
      3. pagePath - returns the path of the current page
      4. pageId - Returns the unique identifier of the current page
      5. pageTitle - Returns the title of a page
      6. pageLongTitle - Returns the long title of a page
      7. pageMetadata - Returns the value of a metadata of a page
      8. pageHasRestrictedAccess - Returns the status of a page to determine if it is restricted or not
    4. Content
      1. contentAttachments - Returns an object corresponding to the attachments of a content
      2. contentTags - Returns the tags applied to the current content
    5. Resources explorer
      1. resourcesById - Returns an object (given by its id) corresponding to a resource path of the explorer
      2. resourcesByPath - Returns an object (given by its path) corresponding to a resource path of the explorer
    6. Tags
      1. tagLabel - Return the readable label of a tag
      2. tagDescription - Return the readable description of a tag
      3. tagCategory - Return the category ID of a tag
    7. Misc
      1. renderingContext - Determine if the page is rendered in the back-office or in preview mode or for the site
      2. escapeJS - escape a string to insert it in a script
      3. pluginResourceURL - returns the path to a resource of a plugin
      4. sitemap - returns  the whole current sitemap object
      5. sitemap (pageId) - returns the subsitemap object of the given page
      6. user - Returns the connected user object
    8. Parameters
      1. config - Returns the value of a configuration parameter
      2. siteParameter - Returns the value of a site parameter
      3. serviceParameter - Returns the value of a parameter of the current service
      4. requestParameter - Return the value of a request parameter

How to use it ?

Add this in your xslt header

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
         ...
         xmlns:ametys="org.ametys.web.transformation.xslt.AmetysXSLTHelper"
         ...
         extension-element-prefixes="... ametys ...">

You can then call any of the following XSLT functions using "ametys:functionName(argument1, argument2)"
Example :

<xsl:if test="ametys:zone() = 'default">
    <!-- We are in the default zone -->
    ...
</xsl:if>

Reference

URL Prefixes / Application Context

uriPrefix - returns the server url prefix, relatively to server

Description :
Returns the server url prefix to root path, relatively to server. E.g. '', '/cms', '/cms/preview'.
This can be used to access server for AJAX requests.
Can be empty if the application is at root of the domain name.

Signature :
String uriPrefix()

Sample :

$j.post("<xsl:value-of select="ametys:uriPrefix()"/>/plugins/cms/comments/add-comment", data, result);

absoluteUriPrefix - same as uriPrefix but absolutely

Description :
Same as uriPrefix but absolutly. E.g. 'http://www.ametys.org' or 'http://www.ametys.org/cms' or 'http://www.ametys.org/cms/preview'. 

Signature :
String absoluteUriPrefix()

siteUriPrefix - returns the server url prefix for the current site or specific site, relatively to server

Description :
Returns the server url prefix to root path of the current site - if used with no argument -, or of the given site passed in argument, relatively to server. E.g. '', '/cms/www', '/cms/preview/www'.
This can be used to build page path.
Can be empty if the application is at root of the domain name on the site.

Signature :
String siteUriPrefix()
String siteUriPrefix(String siteName)

Arguments :

Name

Type

Description

siteName

String

The name of the site

Sample :

<a href="{ametys:siteUriPrefix()}/{ametys:lang()}/index.html">Accueil</a>
<a href="{ametys:siteUriPrefix('www')}/{ametys:lang()}/index.html">Accueil</a>

absoluteSiteUriPrefix - same as siteUriPrefix but absolutely

Description :
Same as siteUriPrefix but absolutly. E.g. 'http://www.ametys.org' or 'http://www.ametys.org/cms/www' or 'http://www.ametys.org/cms/preview/www'.
Use full when you need the web site url (to create "I like facebook" button for example)

Signature :
String absoluteUriPrefix()
String absoluteUriPrefix(String siteName)

Arguments :

Name

Type

Description

siteName

String

The name of the site

Skin

skin - returns the name of the skin

Description :
Returns the name of the skin used in the current site.
As it is not possible to load a XSL using a variable , you can use the template protocol. e.g. <xsl:import href="skin://stylesheets/common.xsl"/>

Signature :
String skin()

skinURL - returns a path to a skin resource

Description :
Returns the path to a resource file of the skin.

Signature :
String skinURL(String path)

Arguments :

Name

Type

Description

path

String

A path in the directory structure of the skin (under the resources directory)

Sample :
Insert an image located in the directory "skins/MYSKIN/resources/img/myimage.png"

<img src="{ametys:skinURL('img/myimage.png')}"/>

skinResources - Returns an object describing a directory of the skin resources

Description :
Returns a DOM representing a directory of the resources subdirectory of the current skin.
This allows for example to have a slideshow of the images of a directory without knowing the name of every file.

See resourcesById to see the DOM description.

Signature :
Node skinResources(String path)

Arguments :

Name

Type

Description

path

String

A path in the directory structure of the skin (under the resources directory)

Sample :

<ul>
	<xsl:for-each select="ametys:skinResources('img/slideshow')/resource">
 <img src="{ametys:skinURL(concat('img/slideshow/', @name))}"/>
 </xsl:for-each>
</ul>

template - returns the name of the current template

Signature :
String template()

templateURL - returns a path to a template resources

Description :
Returns the path to a resource file of the current template of the skin

Signature :
String templateURL(String path)

Arguments :

Name

Type

Description

path

String

A path in the directory structure of the template of the skin (under the resources directory)

Sample : Insert an image located in the directory "skins/MYSKIN/templates/CURRENTTEMPLATE/resources/img/myimage.png"

<img src="ametys:templateURL('img/myimage.png')"/>

zone - returns the name of the currently processed zone

Description :
Returns the name of the zone currently processed. Can be used in a service or content rendering.
But keep in mind that a content rendering can be done outside of any page and have no zone associated : you can set a default value

Signature :
String zone (String defaultValue)

Arguments :

Name

Type

Description

defaultValue

String

The default value returned if no zone is currently processed

Sample :

<xsl:variable name="zone" select="ametys:zone('default')"/>
<xsl:choose>
    <xsl:if test="$zone = 'default'">
        <!-- We are in the default zone -->
        ...
    </xsl:when>
    <xsl:when test="$zone = 'right'">
        <!-- We are in the right zone -->
        ...
    </xsl:when>
    <xsl:otherwise>
        <!-- We are in the left zone -->
        ...
    </xsl:otherwise>
</xsl:choose>

Page

site - returns the current site

Description :
Returns the identifier of the site holding the current page.

Signature :
String site() 

lang - returns the current language

Description :
Returns the language code of the page currently processed

Signature :
String lang()

Sample :

<a href="{ametys:siteUriPrefix()}/{ametys:lang()}/index.html">Home</a>

pagePath - returns the path of the current page

Description :
Returns the path of the current page. The path is relative to the current sitemap.

Signature :
String pagePath()

pageId - Returns the unique identifier of the current page

Description :
Returns the id of the current page.

Signature :
String pageId()

pageTitle - Returns the title of a page

Description :
Returns the readeable title of a page

Signature :
String pageTitle(String sitename, String lang, String path)
String pageTitle(String pageId)

Arguments : 

Name

Type

Description

sitename

String

The identifier of a site

langStringThe language code in the site
pathStringThe page path in the language sitemap of the site

Name

Type

Description

pageId

String

A page unique identifier

Sample : 
This will returns the title of the index page. Such as 'Home' or 'Accueil'.

<xsl:value-of select="ametys:pageTitle(ametys:site(), ametys:lang(), 'index')"/>

pageLongTitle - Returns the long title of a page

Description :
The same as pageTitle but returning the "long" title of a page.
Note that if no long title is specified, the title will be returned.

Signature :
String longPageTitle(String sitename, String lang, String path)
String longPageTitle(String pageId)

Arguments : 

Name

Type

Description

sitename

String

The identifier of a site

langStringThe language code in the site
pathStringThe page path in the language sitemap of the site

Name

Type

Description

pageId

String

A page unique identifier

pageMetadata - Returns the value of a metadata of a page

Description :
Returns as a string the value of a metadata of a page.

Signature : 
String pageMetadata (String sitename, String lang, String path, String metadataName)
String pageMetadata (String pageId, String metadataName)

 

Signature :
String pageTitle(String sitename, String lang, String path)
String pageTitle(String pageId)

Arguments :

Name

Type

Description

sitename

String

The identifier of a site

langStringThe language code in the site
pathStringThe page path in the language sitemap of the site
metadateNameStringThe name of the metadata. Use '/' character to describe composite metadata.

Name

Type

Description

pageId

String

A page unique identifier

metadataNameStringThe name of the metadata. Use '/' character to describe composite metadata.

pageHasRestrictedAccess - Returns the status of a page to determine if it is restricted or not

Description :
Return false if a page is public, true otherwise.

Signature :
boolean pageHasRestrictedAccess(String pageId)

Arguments :

Name

Type

Description

pageId

String

A page unique identifier

Content

contentAttachments - Returns an object corresponding to the attachments of a content

Description :
Returns a DOM corresponding to the attached files of the current content or a specified content.

The returned DOM description is the same as in resourcesById.

Signature :
Node contentAttachments()
Node contentAttachments(String contentId)

Arguments :

Name

Type

Description

contentId

String

The unique identifier of a content

contentTags - Returns the tags applied to the current content

Description :
Returns a DOM of the tags applied to the current content.

The return DOM is like :

<tag name="TAGNAME"/>
...

Signature :
NodeList contentTags() 

Resources explorer

resourcesById - Returns an object (given by its id) corresponding to a resource path of the explorer

Description :
Returns a dom corresponding to a path of the resource explorer. The directory is given by its id.

The returned DOM is like

<collection name="DIRECTORYNAME" id="DIRECTORYID">
	<collection name="SUBDIRECTORY" id="SUBDIRECTORYID">
	...
	</collection>
	...
	<resource name="FILENAME" id="FILEID" length="LENGTHINBYTES"/>
	...
</collection>

Optionnally a resource can have:

last-modified="YYYY-MM-DD'T'hh:mm:ss'Z'"

Signature :
Node resourcesById(String collectionId)

Arguments :  

Name

Type

Description

collectionId

String

The UUID of a directory of the resources explorer

Sample :

<xsl:for-each select="ametys:resourcesById($resourcesId)/resource">
...
</xsl:for-each>

resourcesByPath - Returns an object (given by its path) corresponding to a resource path of the explorer

Description :
Like resourcesById but using a path local to the resources explorer of the current site.

See resourcesById for the DOM format.

Signature :
Node resourcesByPath(String path)

Arguments :

Name

Type

Description

path

String

A path to a directory of the resources explorer

Tags

tagLabel - Return the readable label of a tag

Description : Returns a human readable label of a given tag

Signature : String tagLabel(String siteName, String tagName, String lang)

Arguments :

Name

Type

Description

siteName

String

The identifier of a site

tagNameStringThe name of a tag for this site
langStringThe language code to use to translate the label if possible. The contributor tags labels are available in only one language, but tags provided by plugins or skins may be internationalized.

Sample :

This will returns the beautiful name for SECTION ('Section', 'Rubrique'...)

<xsl:value-of select="ametys:tagLabel(ametys:site(), 'SECTION', ametys:lang())"/>

tagDescription - Return the readable description of a tag

Description :
Returns a human readable description of a given tag

Signature :
String tagDescription(String siteName, String tagName, String lang)

Arguments : 

Name

Type

Description

siteName

String

The identifier of a site

tagNameStringThe name of a tag for this site
langStringThe language code to use to translate the description if possible.
The contributor tags description are available in only one language, but tags provided by plugins or skins may be internationalized.

tagCategory - Return the category ID of a tag

Description :
Returns the identifier of the category of a tag. The category of a tag is its parent.
This method allows to know if a tag (e.g. applied to the current content) is part of a know category.

Signature :
String tagCategory(String siteName, String tagName) 

Arguments :

Name

Type

Description

siteName

String

The identifier of a site

tagNameStringThe name of a tag for this site

Misc

renderingContext - Determine if the page is rendered in the back-office or in preview mode or for the site

Description :
Returns the current rendering context :

  • "back" - if the render is made in the backoffice
  • "preview" - if the render is made in preview (or live) mode
  • "front" - if the render is made in the web site

This allows for example to display warning messages in preview situations without  displaying to final visitor.

Signature :
String renderingContext()

Sample:

<xsl:variable name="dest">
	<xsl:choose>
		<xsl:when test="ametys:renderingContext() = 'back'">
			<xsl:text>javascript:alert("This feature cannot be used in the back-office. Open the preview to use it");</xsl:text>
		</xsl:when test>
		<xsl:otherwise>
			<xsl:value-of select="@href"/>
		</xsl:otherwise>
	</xsl:choose>
</xsl:variable>
<a href="{$dest}>Open</a>

escapeJS - escape a string to insert it in a script

Description :
Escape caracters from a string to be javascript compatible.
E.G. change linebreak to \n, change " to \"...

Signature :
String escapeJS(String value)

Arguments :

Name

Type

Description

value

String

The value to escape

Sample :

If you want to set in a JS variable a value incomming from the XML, you cannot affect it directly because if there is a " or a line return this would not be a valid javascript line.

<script type="text/javascript">
	var name = "<xsl:value-of select="ametys:escapeJS(@name)"/>";
</script>

pluginResourceURL - returns the path to a resource of a plugin

Description :
Returns the path to a resource file stored in a plugin.

Signature :
String pluginResourceURL(String plugin, String path)

Arguments :

Name

Type

Description

plugin

String

The name of the plugin hosting the file

pathStringThe path in the resource directory of the plugin

Sample :

<script type="text/javascript" src="{ametys:pluginResourceURL('web', 'js/jquery.treeview.min.js')}"/>

sitemap - returns  the whole current sitemap object

Description : 
Returns the current sitemap node. The page visible are the one visible by the user if access limitation is set.

The returned DOM is like :

<sitemap sitemap:site="www" sitemap:lang="fr">
	<page sitemap:id="page://uniqueid" sitemap:name="index" sitemap:title="Accueil" sitemap:long-title="Accueil" sitemap:path="index">
        	<page .../>
		...
	</page>
	...
</sitemap>

On a page tag, you can have the following attributes depending on the page type :

sitemap:type="CONTAINER" sitemap:container="true"
OR sitemap:type="NODE"
OR sitemap:type="LINK" sitemap:link="http://www.ametys.org" sitemap:link-type="WEB"
OR sitemap:type="LINK" sitemap:link="page://uniqueid" sitemap:link-type="PAGE"

On a page tag, you can have the following attributes, depending on the current page

sitemap:in-path="true" // if the page is in the breadcrumb (can be the current one)
sitemap:current="true" // if the page is the current page

On a page tag, you will find the tags applied prefixed with PLUGIN_TAGS

sitemap:PLUGIN_TAGS_INVISIBLE="true" // if the page has the "invisible" tag

On a page tag, you will find any metadata of the page (except if its type is composite, binary or richtext and except if it is multiple)

Signature :
Node sitemap()

Sample :

<ul>
	<xsl:for-each select="ametys:sitemap()/page">
		<li><xsl:value-of select="@sitemap:title"/></li>
	</xsl:for-each>
</ul>

sitemap (pageId) - returns the subsitemap object of the given page

Description : 
Returns the part of the sitemap node. The page visible are the one visible by the user if access limitation is set.

Signature :
String sitemap (String pageId)

Arguments :

Name

Type

Description

pageId

String

The id of the page

<ul>
    <xsl:for-each select="ametys:sitemap('page://xxxxxx')/page">
        <li><xsl:value-of select="@sitemap:title"/></li>
    </xsl:for-each>
</ul>

See ametys:sitemap() method for more details.

user - Returns the connected user object

Description :
Returns a DOM corresponding to the connected user.
This also allows to know if a user is connected.
Please not that this method should not be called in cachable environnement (cacheable service, content...)

The DOM returned is really dependant on the UsersManager your are using (LDAP, SQL, others...).

Here is a description of what you can receive from the StaticUsersManager (the one used for demo purpose with hard coded users) or from the JDBCUsersManager (the one with users stored in a sql database) :

<user login="USERLOGIN">
	<firstname>FIRSTNAME</firstname>
	<lastname>LASTNAME</lastname>
	<email>EMAIL</email>
</user>

Signature :
Node user() 

Sample :
To know what you can receive in your conditions. Execute the following code and analyse the source code produced ON A LIMITED PAGE (to avoid cache purpose and to do not have empty result).

<MARKER><xsl:copy-of select="ametys:user()"/></MARKER>

Parameters

config - Returns the value of a configuration parameter

Description :
Returns the value of a configuration parameter.

Signature :
String config(String id)

Arguments :

Name

Type

Description

id

String

The identifier of the parameter to get

Sample :

<script type="text/javascript">
    alert("You will receive an email from <xsl:value-of select="ametys:config('smtp.mail.from')"/>");
</script>

siteParameter - Returns the value of a site parameter

Description :
Returns the value of a site parameter. 

Signature :
String siteParameter(String parameter)

Arguments :

Name

Type

Description

parameter

String

The identifier of the parameter to get

Sample :

<script type="text/javascript">
    var googleAnalyticsIdentifier = "<xsl:value-of select="ametys:siteParameter('site-param-google-web-property-id')"/>";
</script>

serviceParameter - Returns the value of a parameter of the current service

Description :
Returns the value of the parameter of the service currently rendered.
This should only be called in a service rendering. 
You can optionnaly provide a default value.

Signature :
String serviceParameter (String parameter)
String serviceParamter (String parameter, String defaultValue)

Arguments :

Name

Type

Description

parameter

String

The identifier of the parameter to get in the current service

Name

Type

Description

parameter

String

The identifier of the parameter to get in the current service

defaultValueStringIf the value is not set, switch to this default value (this can happend when a new parameter is added, to be compatible with existing data).

requestParameter - Return the value of a request parameter

Description :
Returns the value of a request parameter.
Be carefull! This should only be used in non cachable xsl file (e.g. non cachable service). If not, the result of the first visitor will be used for every visitor...

Signature :
String requestParameter(String parameter)

Arguments :

Name

Type

Description

parameter

String

The identifier of the parameter to get

Sample :

If you call the following url http://www.ametys.org/fr/index.html?id=3

<input type="hidden" name="id" value="{ametys:requestParameter('id')}"/>

 

 

 

Back to top

Integration