Graphic rendering of a service


  1. Notions of views
    1. Overloading the rendering of a service
    2. Create an additional rendering
    3. Make a view unavailable
  2. Service templates
    1. common-service-head-title
    2. common-service-head-js
    3. common-service-head-css
    4. common-service-head-other
    5. common-service-body-nonempty-content-title
    6. common-service-body-nonempty-content-content
  3. Useful variables
    1. common-service-name
    2. common-service-css-class-name
    3. is-empty
  4. Further information

 

 

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:

 

Back to top