View parameters
From Ametys 4.3
- Introduction
- Law
- Authorized types
- Template parameters
- Zone parameters
- Zone element parameters
- Service view parameters
- Content parameters
- Global view parameters
Introduction
View parameters are parameters defined by the graphic charter and assigned to the back office of your application. They influence the rendering of your pages, content and services.
There are 5 types of view settings:
- Template parameters
- Zone parameters
- Zone item parameters
- Service parameters
- Content parameters
Law
To access the buttons for configuring view parameters, the user must have the View parameters right in the Page rights section.
Authorized types
Here are the different parameter types supported:
- String
<parameter name="param" type="string"> <label i18n="false">String</label> <description i18n="false">String</description> </parameter>
- Long
<parameter name="param" type="long"> <label i18n="false">Long</label> <description i18n="false">Long</description> </parameter>
- Double
<parameter name="param" type="double"> <label i18n="false">Double</label> <description i18n="false">Double</description> </parameter>
- Boolean
<parameter name="param" type="boolean"> <label i18n="false">Boolean</label> <description i18n="false">Boolean</description> </parameter>
- Date
<parameter name="param" type="date"> <label i18n="false">Date</label> <description i18n="false">Date</description> </parameter>
- Datetime
<parameter name="param" type="datetime"> <label i18n="false">Datetime</label> <description i18n="false">Datetime</description> </parameter>
- Password
<parameter name="param" type="password"> <label i18n="false">Password</label> <description i18n="false">Password</description> </parameter>
- User
<parameter name="param" type="user"> <label i18n="false">User</label> <description i18n="false">User</description> </parameter>
- Geocode
<parameter name="param" type="geocode"> <label i18n="false">Geocode</label> <description i18n="false">Geocode</description> </parameter>
- File
<parameter name="param" type="file"> <label i18n="false">File</label> <description i18n="false">File</description> <widget>edition.file</widget> <widget-params> <param name="allowSources">resource</param> </widget-params> </parameter>
It's important to add the widget parameter allowSources = resource for the declaration of a file type parameter, as currently only explorer resources are supported.
Template parameters
Definition
Les paramètres de gabarit doivent être définis dans le fichier templates/[NOM_GABARIT]/template.xml du gabarit défini dans votre charte graphique.
Les paramètres sont définis sous une balise <parameters> comme dans l'exemple ci-dessous:
<template> <label i18n="true">SKIN_BO_ZONING_PAGE_LABEL</label> <description i18n="true">SKIN_BO_ZONING_PAGE_DESCRIPTION</description> <parameters> <parameter name="image" type="file"> <label i18n="false">Bannière d'illustration</label> <description i18n="false">Bannière d'illustration</description> <widget>edition.file</widget> <widget-params> <param name="allowSources">resource</param> <param name="filter">image</param> </widget-params> </parameter> </parameters> </template>
Setting
The template parameter settings are accessible :
- or from the Page with template > Template settings Page tab
- or from the View settings active when selecting a zone or zone element (content or service)
This button is selection-dependent, so it can provide additional view parameters related to zone, zone-item, service and content.
A dialog box displays the parameters available according to the selection, grouped by type:
Click "Ok" to save your settings.
Heritage
Template view parameters are inherited. By default, they are not inherited, so that if the parameter is not filled in, it remains empty, regardless of the value filled in on the parent page.
It is therefore possible to integrate a notion of inheritance that allows, when a view parameter is not filled in, to retrieve its value from its parent.
To do this, use the inherit attribute on the parameter tag. Its value can be :
|
inherit attribute value |
Meaning |
|
* |
It inherits the view parameter with the same name from the parent page. |
|
* -> [parameter name] |
It inherits the view parameter with name [parameter name] from the parent page, whatever its template. |
|
[template name] -> [parameter name]. |
It inherits the view parameter with name [parameter name] from the parent page if its template is [template name]. |
|
[template name] -> empty |
This view parameter is not inherited if the parent page's template is [template name]. |
Case 1 - No inheritance
<parameter name="param1"/>
The inherit attribute does not exist, there is no inheritance.
Case 2 - Simple inheritance
<parameter name="param1" inherit="*"/>
<parameter name="param1" inherit="*->param1"/>
Parameter param1 inherits parameter param1 from the parent page (provided it is properly defined in the parent page template).
Case 3 - Inheritance from another parameter
<parameter name="param1" inherit="*->param2"/>
Parameter param1 inherits parameter param2 from the parent page (if param2 is defined on the parent page template).
Case 4 - Inheritance by template
<parameter name="param1" inherit="t1->param1,t2->param2"/>
Parameter param1 inherits :
- of parameter param1 if the parent page uses template t1,
- parameter param2 if the parent page uses template t2.
Case 5 - Conditional inheritance
<parameter name="param1" inherit="t2->param2,t3->,*->param1"/>
Parameter param1 inherits :
- parameter param2 if the parent page uses template t2,
- nothing if the parent page uses the t3 template,
- parameter param1 in all other cases.
The order in which inheritances are defined is therefore important. If *->param1 were defined first, the rest would be irrelevant.
Use in the graphic charter
In our example, this template parameter is used to change the default banner illustration.
Using the XSLT AmetysXSLTHelper helper, you can display the header image on the skin side.(See helper documentation)
For example:
<div class="art-header-jpeg" style="background: none">
<xsl:variable name="banner" select="ametys:templateParameter('image')"/>
<xsl:choose>
<xsl:when test="$banner">
<img src="{resolver:resolveImage($banner/@type, $banner/@path, 300, 1920)}"/>
</xsl:when>
<xsl:otherwise>
<img src="{ametys:skinURL('img/header.jpg')}"/>
</xsl:otherwise>
</xsl:choose>
</div> Zone parameters
Definition
Zone parameters must be defined in the file templates/[GABARIT_NAME]/template.xml of the template defined in your graphic charter.
Les paramètres de zone sont définis sous une balise <parameters>, sous la balise <zone> concernée comme dans l'exemple ci-dessous:
<template> <zones> <zone id="default"> <parameters> <parameter name="color" type="file"> <label i18n="false">Couleur</label> <description i18n="false">Couleur</description> <widget>edition.colorpicker</widget> </parameter> </parameters> </zone> </zones> </template>
Setting
Zone parameter settings can be accessed via the Set view button, which is active when a zone or zone element (content or service) is selected.
This button is selection-dependent, so it can provide additional view parameters related to template, zone element, service and content.
A dialog box displays the parameters available according to the selection, grouped by type:
Click "Ok" to save your settings.
Heritage
Zone view parameters are inherited. By default, they are not inherited, so that if the parameter is not filled in, it remains empty, regardless of the value filled in on the parent page.
It is therefore possible to integrate a notion of inheritance that allows, when a view parameter is not filled in, to retrieve its value from its parent.
To do this, use the inherit attribute on the parameter tag. Its value can be :
|
inherit attribute value |
Meaning |
|
* |
It inherits the view parameter with the same name from the zone with the same name on the parent page. |
|
* -> [zone name] -> [parameter name]. |
It inherits the view parameter with name [parameter name] from zone [zone name] on the parent page, whatever its template. |
|
[template name] -> [zone name] -> [parameter name]. |
It inherits the view parameter with the name [parameter name] from the [zone name] zone on the parent page if its template is [template name]. |
|
[template name] -> empty |
This view parameter is not inherited if the parent page's template is [template name]. |
In all cases, param1 is set to the default zone:
Case 1 - No inheritance
<parameter name="param1"/>
The inherit attribute does not exist, there is no inheritance.
Case 2 - Simple inheritance
<parameter name="param1" inherit="*"/>
<parameter name="param1" inherit="*->default->param1"/>
The param1 parameter of the default zone inherits the param1 parameter of the default zone of the parent page (if set to the default zone of the parent page).
Case 3 - Inheritance from another parameter
<parameter name="param1" inherit="*->z1->param2"/>
The param1 parameter of the default zone inherits the param2 parameter of the z1 zone of the parent page (if param2 is set to the z1 zone of the parent page).
Case 4 - Inheritance by template
<parameter name="param1" inherit="t1->z1->param1,t2->z2->param2"/>
The param1 parameter of the default zone inherits :
- parameter param1 in zone z1 if the master page uses template t1,
- parameter param2 in zone z2 if the master page uses template t2.
Case 5 - Conditional inheritance
<parameter name="param1" inherit="t2->z2->param2,t3->,*->z1->param1"/>
The param1 parameter of the default zone inherits :
- parameter param2 in zone z2 if the master page uses template t2,
- nothing if the parent page uses the t3 template,
- parameter param1 of zone z1 in all other cases.
The order in which inheritances are defined is therefore important. If *->z1->param1 were defined first, the rest would be irrelevant.
Use in the graphic charter
In our example, this view parameter is used to change the zone's background color.
Using the XSLT ViewParametersXSLTHelper helper, you can change the zone's color.(See helper documentation)
For example:
<xsl:template name="zone-before"> <xsl:param name="count"/> <xsl:param name="zone-name"/> <xsl:param name="level"/> <xsl:param name="inherited"/> <xsl:variable name="color" select="ametys:zoneParameter($zone-name, 'color')"/> <xsl:if test="$color"> <xsl:attribute name="style">background-color:#<xsl:value-of select="$color"/></xsl:attribute> </xsl:if> </xsl:template>
Example of rendering:
Zone element parameters
Definition
As with template and zone parameters, zone element parameters must be defined in the file templates/[TEMPLATE_NAME]/template.xml of the template defined in your graphic charter.
Les paramètres d'élément de zone sont définis sous une balise <zone-items> de la zone concernée, comme dans l'exemple ci-dessous:
<template> <zones> <zone id="default"> <zone-items> <parameters> <parameter name="picto" type="file"> <label i18n="false">Pictogramme</label> <description i18n="false">Pictogramme</description> <widget>edition.file</widget> <widget-params> <param name="allowSources">resource</param> <param name="filter">image</param> </widget-params> </parameter> <parameter name="color" type="string"> <label i18n="false">Couleur</label> <description i18n="false">Couleur</description> <widget>edition.colorpicker</widget> </parameter> </parameters> </zone-items> </zone> </zones> </template>
Setting
Zone parameter settings can be accessed via the Set view button, which is active when a zone or zone element (content or service) is selected.
This button is selection-dependent, so it can provide additional view parameters related to template, zone, service and content.
A dialog box displays the parameters available according to the selection, grouped by type:
Click "Ok" to save your settings.
Use in the graphic charter
In our example, this view parameter lets you change the background color of the zone item and add an icon.
Using the XSLT ViewParametersXSLTHelper helper, you can change the color of the zone item and display the icon(see helper documentation).
For example:
<xsl:template name="zone-item-before">
<xsl:param name="position"/>
<xsl:param name="count"/>
<xsl:param name="zone-name"/>
<xsl:param name="level"/>
<xsl:param name="inherited"/>
<xsl:param name="id"/>
<xsl:param name="type"/>
<xsl:param name="content-id"/>
<xsl:param name="service"/>
<xsl:param name="content-type"/>
<xsl:variable name="color" select="ametys:zoneItemParameter($id, 'color')"/>
<xsl:if test="$color">
<xsl:attribute name="style">background-color:#<xsl:value-of select="$color"/></xsl:attribute>
</xsl:if>
<xsl:variable name="picto" select="ametys:zoneItemParameter($id, 'picto')"/>
<xsl:if test="$picto">
<img src="{resolver:resolveImage($picto/@type, $picto/@path, 80, 80)}" style="float:right;"/>
</xsl:if>
</xsl:template> Example of rendering:
Service view parameters
Definition
Service view parameters must be defined in the services/[PLUGIN_NAME]/pages/services/[SERVICE_NAME]/[VIEW_NAME] view description file .xml in your graphic charter.
For example, to define parameters for the service gallery view displaying the contents of a resource explorer directory, the file modified is services/web/pages/services/explorer-folder/galery_3.3.xml.
Les paramètres sont définis sous une balise <parameters> comme dans l'exemple ci-dessous:
<service> <parameters> <parameter name="iconSize" type="string"> <label i18n="false">Taille des icones</label> <description i18n="false">Couleur de la zone</description> <enumeration> <entry> <value>small</value> <label i18n="false">Petite</label> </entry> <entry> <value>medium</value> <label i18n="false">Moyenne</label> </entry> <entry> <value>big</value> <label i18n="false">Grande</label> </entry> </enumeration> </parameter> </parameters> </service>
Setting
Service view parameters can be set using the View settings active when selecting the service:
This button is selection-dependent, so it can provide additional view parameters related to template, zone and item zone.
A dialog box displays the parameters available according to the selection, grouped by type:
Click "Ok" to save your settings.
This dialog box contains any zone element parameters (Pictogram, Color), the service view and the parameters associated with the selected view.
Service view parameters can also be accessed from the service configuration window ( Service parameters button).
View parameters are displayed (if available) below the view selection drop-down list.
Use in the graphic charter
You can retrieve view parameters in service rendering using the XSLT ViewParametersXSLTHelper helper(see helper documentation).
In our example here, the view parameter is used to change the size of images in the resource explorer's image gallery.
<xsl:variable name="size" select="ametys:serviceViewParameter('iconSize')"/>
<xsl:choose>
<xsl:when test="$size = 'small'">
<img src="{resolver:resolveBoundedImage('explorer', @id, 70, 70)}" alt="{@name}"/>
</xsl:when>
<xsl:when test="$size = 'medium'">
<img src="{resolver:resolveBoundedImage('explorer', @id, 100, 100)}" alt="{@name}"/>
</xsl:when>
<xsl:when test="$size = 'big'">
<img src="{resolver:resolveBoundedImage('explorer', @id, 150, 150)}" alt="{@name}"/>
</xsl:when>
<xsl:otherwise>
<img src="{resolver:resolveBoundedImage('explorer', @id, 100, 100)}" alt="{@name}"/>
</xsl:otherwise>
</xsl:choose> Example of rendering:
- small icons
- large icons
Content parameters
Definition
To define content view parameters, create a XML file associated with the content view in the graphic charter.
For example, to define parameters for the "main" view of an article content type, create a folder with the content type identifier org.ametys.web.default.Content.article as its name, and add a xml file with the same name to this folder, associating a suffix for the content view: org.ametys.web.default.Content.article-main.xml.
The path to XML is: skins/[NOM_SKIN]/stylesheets/content/org.ametys.web.default.Content.article/org.ametys.web.default.Content.article-main.xml.
In this file, content view parameters are defined as in the example below:
<content> <parameters> <parameter name="hideTitle" type="boolean"> <label i18n="false">Cacher le titre</label> <description i18n="false">Cacher le titre</description> </parameter> </parameters> </content>
Setting
You can set the view parameters for a content item:
- or from the View settings active when selecting content:
- or from the Content view > View settings
A dialog box displays the parameters available according to the selection, grouped by type.
Also included are any template, zone and zone element parameters.
The content view can be modified from this dialog box.
Click "Ok" to save your settings.
This dialog box also allows you to select the content view
Use in the graphic charter
You can retrieve view parameters in content rendering using the XSLT ViewParametersXSLTHelper helper(see helper documentation).
In our example here, the view parameter is used to hide the main content title:
<xsl:variable name="hideTitle" select="ametys:contentViewParameter('hideTitle')" />
<xsl:if test="not($hideTitle) or $hideTitle = 'false'">
<xsl:call-template name="zone-header">
<xsl:with-param name="content">
<span class="content-title summary"><xsl:value-of select="$title"/></span>
<xsl:if test="$subtitle != ''">
<span class="content-subtitle"><xsl:value-of select="$subtitle"/></span>
</xsl:if>
</xsl:with-param>
</xsl:call-template>
</xsl:if> Global view parameters
Global view parameters are parameters that apply to all templates, zones, zone elements, service views and content.
They are defined in the conf/parameters file .xml.
In this file, parameters are defined according to their type under :
- une balise <templates>
- une balise <zones>
- une balise <zoneitems>
- une balise <contents>
- une balise <services>
Here is an example for this file, which includes all the parameters defined above:
<parameters> <templates> <parameter name="image" type="file" inherit="*"> <label i18n="false">Image d'entête</label> <description i18n="false">Image d'entête</description> <widget>edition.file</widget> <widget-params> <param name="allowSources">resource</param> <param name="filter">image</param> </widget-params> </parameter> </templates> <zones> <parameter name="color" type="string" inherit="*->default->color"> <label i18n="false">Couleur</label> <description i18n="false">Couleur</description> <widget>edition.colorpicker</widget> </parameter> </zones> <zoneitems> <parameter name="picto" type="file"> <label i18n="false">Pictogramme</label> <description i18n="false">Pictogramme</description> <widget>edition.file</widget> <widget-params> <param name="allowSources">resource</param> <param name="filter">image</param> </widget-params> </parameter> <parameter name="color" type="string"> <label i18n="false">Couleur</label> <description i18n="false">Couleur</description> <widget>edition.colorpicker</widget> </parameter> </zoneitems> <contents> <parameter name="hideTitle" type="boolean"> <label i18n="false">Cacher le titre</label> <description i18n="false">Cacher le titre</description> </parameter> </contents> <services> <parameter name="iconSize" type="string"> <label i18n="false">Taille des icones</label> <description i18n="false">Couleur de la zone</description> <enumeration> <entry> <value>small</value> <label i18n="false">Petite</label> </entry> <entry> <value>medium</value> <label i18n="false">Moyenne</label> </entry> <entry> <value>big</value> <label i18n="false">Grande</label> </entry> </enumeration> </parameter> </services> </parameters>
All these parameters will be added to the view parameters defined individually for each template, zone, item zone, content or service.
Managing these parameters is the same as explained above.
Please note that parameter names must be unique by type.
For example, if a global template parameter is named "image", it will not be possible to name another "local" template parameter with the same name.
Back to top