Notions of views
For any service inserted in a zone, it is possible to choose its display mode, i.e. to define the name of the XSL style sheet to be used to build its rendering. All services have at least one rendering, known as the default rendering. It is the default value of the xslt parameter defined in the service at plugin.xml that determines the default view.
Each service display mode is defined by a [viewName].xml file, which determines the view label, and an associated [viewName].xsl stylesheet, which builds the HTML structure expected by the graphic charter.
<?xml version="1.0" encoding="UTF-8"?> <service> <label i18n="true">PLUGINS_WEB_SERVICE_FILTERED_PAGES_XSLT_LIST35_LABEL</label> </service>
It is possible to have several renderings for the same service.
Overloading the rendering of a service
To override the rendering of a service, create the file cms/skins/[skinName]/services/[pluginName]/pages/services/[serviceName]/[viewName].xsl which imports the corresponding XSL from plugin :
[viewName].xsl
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:i18n="http://apache.org/cocoon/i18n/2.1" xmlns:ametys="org.ametys.web.transformation.xslt.AmetysXSLTHelper" exclude-result-prefixes="ametys"> <xsl:import href="plugin:web://pages/services/filtered-pages/list_3.5.xsl"/> </xsl:stylesheet>
It is not necessary to override the XML file associated with the view. The XML file is only overloaded to make the view unavailable.
Create an additional rendering
It is sometimes necessary to add a rendering. To do this, create a new XSL rendering in the graphic charter cms/skins/[skinName]/services/[pluginName]/pages/services/[serviceName]/[viewName].xsl. For it to appear in the list of available renderings, you must also add a file XML with the same name: [viewName].xml with the following content:
[viewName].xml
<?xml version="1.0" encoding="UTF-8"?> <service> <label i18n="true">PLUGINS_[pluginName]_SERVICE_[serviceName]_XSLT_[viewName]_LABEL</label> </service>
To declare the wording i18n, seeinternationalization.
Make a view unavailable
As of Ametys 4.8, this method is obsolete.
To make a view unavailable, see the Services page (services-default.xml and services-views-default.xml ).
It may be useful, for example, to make a view unavailable due to graphic constraints. To do this, override the XML file that defines the rendering in the graphic charter cms/skins/[skinName]/services/[pluginName]/pages/services/[serviceName]/[viewName].xml and add the exclude="true" attribute to the service node.
[viewName].xml
<?xml version="1.0" encoding="UTF-8"?> <service exclude="true"> <label i18n="true">PLUGINS_[pluginName]_SERVICE_[serviceName]_XSLT_[viewName]_LABEL</label> </service>
Service templates
The templates for the various services are already defined at plugin , so that the service can be used without the need to apply a graphic charter. However, as the rendering is minimalist, it is generally necessary to overload the templates required to match the rendering expected by the graphic charter.
All kernel services are based on the same structure (service:web://pages/services/common.xsl), so that each part can be overloaded as easily as possible. We also recommend using this structure to create new services.
Here's how a service template is structured:
Templates in white are defined in a commons file.xsl.
The same service can have several renderings (called display modes). For example, for content feeds, it is possible to define a list rendering and a carousel rendering.
common-service-head-title
Ce template correspond au titre de la page (balise <title>), il fait appel au template common-service-head-title-content avec les paramètres title et default-title. Ce dernier est facultatif, si le titre est vide, c'est le titre par défaut qui sera pris en compte.
<xsl:template name="common-service-head-title">
<xsl:call-template name="common-service-head-title-content">
<xsl:with-param name="title" select="ametys:serviceParameter('header')/text()"/>
<xsl:with-param name="default-title">Mon titre par défaut</xsl:with-param>
</xsl:call-template>
</xsl:template>common-service-head-js
It is advisable to place the Javascript calls that will be used by the service in this template.
<xsl:template name="common-service-head-js">
<script type="text/javascript" src="{ametys:pluginResourceURL('myplugin', 'js/myfile.js')}"><xsl:comment>empty</xsl:comment></script>
<script type="text/javascript">
// ...
</script>
</xsl:template>common-service-head-css
Service-specific style sheets are called up in this template.
<xsl:template name="common-service-head-css">
<link type="text/css" href="{ametys:pluginResourceURL('myplugin', 'css/myfile.css')}" rel="stylesheet" />
</xsl:template>common-service-head-other
In this template, it is possible to add flow definitions RSS for example.
<xsl:template name="common-service-head-css">
<link rel="alternate" type="application/rss+xml" title="Mon flux RSS" href="{$uri-prefix}/{RSSFeedURL}"/>
</xsl:template>common-service-body-nonempty-content-title
This template is used to display the service title. To do this, we recommend calling the common-service-body-content-title-content template with the title and default-title parameters (optional), which in turn calls common-service-body-content-title-empty or common-service-body-content-title-rendering, depending on the parameter values.
<xsl:template name="common-service-body-nonempty-content-title">
<xsl:call-template name="common-service-body-nonempty-content-title-content">
<xsl:with-param name="title" select="ametys:serviceParameter('header')/text()"/>
<xsl:with-param name="default-title">Mon titre par défaut</xsl:with-param>
</xsl:call-template>
</xsl:template>common-service-body-nonempty-content-content
Finally, the common-service-body-nonempty-content-content template is the most important to override, as it contains the entire service display.
Useful variables
common-service-name
The common-service-name variable is optional: it is not used by the kernel, but only by the graphic charter when necessary. For example, for a display common to several services but not all, and to avoid overloading several services in the same way, overload the common.xsl file (cms/skins/[skinName]/services/web/pages/services folder).
common.xsl
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:import href="plugin:web://pages/services/common.xsl"/>
<xsl:template name="common-service-body-nonempty-content-title">
<xsl:if test="not($common-service-name = 'service1' or $common-service-name = 'service2')">
<xsl:call-template name="common-service-body-nonempty-content-title-content">
<xsl:with-param name="title" select="ametys:serviceParameter('header')/text()"/>
</xsl:call-template>
</xsl:if>
</xsl:template>
</xsl:stylesheet>common-service-css-class-name
This variable corresponds to the CSS class that will be used on the service's encompassing DIV.
is-empty
Depending on whether the service returns a null value or not, the expected behavior is often not the same. In the common service stylesheet, the common-service-body template tests whether the value returned by the service is empty.
<!-- The template called in the BODY tag --> <xsl:template name="common-service-body"> <xsl:choose> <xsl:when test="$is-empty"> <xsl:call-template name="common-service-body-empty"/> </xsl:when> <xsl:otherwise> <xsl:call-template name="common-service-body-nonempty"/> </xsl:otherwise> </xsl:choose> </xsl:template>
It is therefore possible to describe 2 different behaviors for the same service, depending on whether it returns a result or not. For example, this variable is used for the search engine, which displays a list of results in the first case, or a message like"No results match your search" in the other case.
The is-empty variable is defined in each service. If required, it can be overloaded. To ignore the behavior of a service that returns a null value, enter false() as the value of the variable.
<xsl:variable name="is-empty" select="not(/Node//Node[contains(@mimetype , 'image')])"/>
Further information
In the demo layout, a number of display modes other than those defined by default have been created. You can use the XSL and XML files defining these display modes to adapt them to your graphic charter.
For example:
- animated list and carousel display modes for content from the content feed service;
- the Image Slideshow and Image Gallery display modes of the Directory Content service.
Back to top