- Notions of views
- Content type templates
- common-content-head-title
- common-content-head-js
- common-content-head-css
- common-content-head-other
- common-content-body-title
- common-content-body-content
- common-content-body-image
- common-content-body-image-bigsize
- common-content-body-image-smallsize
- common-content-body-simpletext
- common-content-body-content-rich
- common-content-body-contact
- common-content-body-publish-date
- common-content-body-meta
- common-content-body-comments
- common-content-body-readmore
- common-content-body-link
- Useful variables
- Dynamic typing
- Further information
Notions of views
For any content inserted in a zone, you can choose its view, i.e., define the name of the XSL style sheet to be used to build its rendering.
The name and fields used for the different views of a content type are defined in the plugin from which it is extracted.
<!-- [viewName] view --> <cms:metadata-set name="[viewName]" type="view"> <cms:metadata-ref name="title" /> <cms:metadata-ref name="illustration"> <cms:metadata-ref name="image" /> <cms:metadata-ref name="alt-text" /> </cms:metadata-ref> <cms:metadata-ref name="abstract" /> <cms:metadata-ref name="content" /> <cms:label i18n="true">PLUGINS_[pluginName]_VIEW_[viewName]</cms:label> <cms:description i18n="true">PLUGINS_[pluginName]_VIEW_[viewName]_DESC</cms:description> </cms:metadata-set>
For each of the views defined in plugin, a XSL style sheet is associated: the XML data transmitted by CMS are transformed by the XSL rendering [contentType]-[viewName].xsl so as to display them in the HTML structure expected by the graphic charter.
|
[contentType]-[viewName].xsl |
HTML generated |
|---|---|
<?xml version="1.0" encoding="UTF-8"?> <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:docbook="http://docbook.org/ns/docbook" xmlns:i18n="http://apache.org/cocoon/i18n/2.1" xmlns:cms="http://ametys.org/cms/3.0" xmlns:resolver="org.ametys.cms.transformation.xslt.ResolveURIComponent" xmlns:ametys="org.ametys.web.transformation.xslt.AmetysXSLTHelper" extension-element-prefixes="cms" exclude-result-prefixes="docbook resolver ametys"> <xsl:import href="view://stylesheets/content/common.xsl"/> <xsl:variable name="common-content-css-class-name">[contentType] view-[viewName]</xsl:variable> <!-- + | BODY + --> <!-- Used in common.xsl --> <xsl:template name="common-content-body-content"> <!-- Image --> <xsl:call-template name="common-content-body-image-smallsize"/> <!-- Abstract --> <xsl:call-template name="common-content-body-simpletext"> <xsl:with-param name="css-class-name">content-abstract</xsl:with-param> <xsl:with-param name="text" select="metadata/abstract"/> <xsl:with-param name="defaultText" select="metadata/content/docbook:article"/> <xsl:with-param name="maxDefaultTextSize" select="200"/> </xsl:call-template> <!-- Read more --> <xsl:call-template name="common-content-body-readmore"/> <div class="content-richtext-end"><xsl:comment>empty</xsl:comment></div> </xsl:template> </xsl:stylesheet> |
<div class="ametys-cms-content [contentType] view-[viewName] wrapper"> <h1> <span class="content-title summary">Titre de l'article</span> </h1> <div class="content-illustration small"> <img src="/cms/preview/ametys.org/_contents-images/ametys-internal%253Asites/ametys.org/ametys-internal%253Acontents/test-article-article/_metadata/illustration/image_max80x80/presse.png?objectId=defaultWebContent://2f9c1221-3058-43c8-a9c6-b218bf27a23a" alt="Alternative de l'illustration" /> </div> <p class="content-abstract"> Entête ou résumé de mon article <a href="/cms/preview/ametys.org/fr/test-article.html">Lire la suite</a> </p> <div class="content-richtext-end"><!--empty--></div> </div> |
It is this [contentType]-[viewName] file.xsl, whichAmetys uses to define the rendering of the selected view. This style sheet is found in :
-
cms/skins/[skinName]/stylesheets/content/[contentType]/
-
WEB-INF/param/content-types/web/stylesheets/[contentType]/
-
plugins/[pluginName]/stylesheets/content/[contentType]/
If the expected rendering file cannot be found in one of the directories mentioned, CMS looks for the [contentType].xsl style sheet, which ignores the expected view. Failing to find the latter style sheet, it uses a substitute XSL file named default-content.xsl and devoid of style.
In the example above, the [contentType]-[viewName] style sheet.xsl uses a commons style sheet.xsl.
In fact, content types necessarily have common templates that can be defined in a common XSL and then imported into each rendering style sheet.
Ametys provides a common style sheet by default.xsl usually called in a common XSL style sheet at project level via the view:// import protocol.
This import protocol respects a specific processing order that systematically gives priority to elements that are overloaded in the graphic charter. For more information on the view:// import protocol, visit the import protocols page.
This XSL rendering provides a basic structure and as many useful templates for integration. It is recommended that you retain this template structure for all new content types, in order to homogenize the graphic rendering of content and simplify future maintenance and upgrades to the project. For further information, please refer to the content type templates section.
In addition, Ametys already defines content types (notably the article content type ) with 3 rendering style sheets by default:
- [contentType]-main.xsl corresponding to a complete rendering of the content with all public data
- [contentType]-abstract.xsl corresponds to a synthesized rendering of the content often used in content feeds.
-
[contentType]-link corresponds to a simplified rendering of content, often including only its title and a link. It is used by plugin Calendar, for example.
Some plugins Ametys sites use the main, abstract or link views, and the absence of one of these views for a given content type could lead to errors.
It is therefore preferable to always include at least these 3 views for any new content type.
Please note that to view content in CMS, a XSL wrapper may be required. Since content can only be inserted into a template zone, its rendering is generally dependent on the tags that make up the template. To be viewed on its own in CMS, this environment must be recreated. The XSL wrapper performs this function. For more information on XSL embedding, visit XSL embedding.
View available views
To view the views available for a content type, consult the plugin.xml file of the plugin from which the content type is extracted (see Declaring and modifying a content type).
Article views and corresponding XSL files (plugins/web/plugin.xml) :
- Complete (main): plugins/web/stylesheets/content/article/article-main. xsl
- Abstract: plugins/web/stylesheets/content/article/article-abstract. xsl
- Link: plugins/web/stylesheets/content/article/article-link. xsl
- Export PDF : plugins/web/stylesheets/content/article/article2pdf-main. xsl
-
Common to all views: plugins/web/stylesheets/content/article/article. xsl
Depending on plugins , a project can benefit by default from many other types of content, all with a common structure.
Overloading a view
It is possible to overload a view. To do this, create the file cms/skins/[skinName]/stylesheets/content/[contentType]/[contentType]-[view].xsl which imports the XSL of the plugin corresponding to it and, in practice, a XSL common to all views of the type of content found in the graphic charter:
CONTENTTYPE-VIEW.xsl
<?xml version="1.0" encoding="UTF-8"?> <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:[pluginName]://stylesheets/content/[contentType]/[contentType]-[view].xsl"/> <xsl:import href="[contentType].xsl"/> <!-- Surcharge des templates du type de contenu --> </xsl:stylesheet>
Depending on the content view, the input XML is more or less complete. The templates that make up the different content views help organize the information.
By default, the complete view of an item is organized as follows:
- The article title, defined in a common file.xsl in a template named common-content-body-title
- Article content:
- The illustration
- Content entered by the contributor in a rich field
- Author and publication date
- Comments if activated by the contributor.
Each element is preceded by a test to avoid generating the code HTML if the corresponding field has not been filled in by the contributor.
<xsl:template name="common-content-body-content"> <!-- Image --> <xsl:call-template name="common-content-body-image-bigsize"/> <!-- Rich content --> <xsl:call-template name="common-content-body-content-rich"/> <div class="content-richtext-end"><xsl:comment>empty</xsl:comment></div> <!-- Contact, Publish date... --> <xsl:call-template name="common-content-body-meta"/> <!-- Comments --> <xsl:call-template name="common-content-body-comments"/> </xsl:template>
Many templates are pooled in a common style sheet. However, for each view of each content type, these templates can be overloaded for specific rendering.
For example, to define a larger image size in full-view articles, redefine the template common-content-body-image-bigsize in the XSL corresponding to the view cms/[skinName]/stylesheets/content/article/article-main. xsl
Add a new view
To add a new view to a content type, you need to define the content fields to be displayed in this view in the plugin definition file ( XML ), and associate a XSL file to model the corresponding rendering. The associated XSL file must have the same name as the view declared in plugin. To find out more, see Declaring and modifying a content type.
A new content type can be declared either in plugin or in the WEB-INF/param/content-types parameters. Then, depending on whether the new content type has been declared in one of the two directories, the associated style sheets will be placed in the same directory.
|
In a plugin |
In settings |
|---|---|
|
|
|
These new stylesheets can import common project and/or kernel stylesheets in the same way as stylesheets that are overridden in the cms/skins/[skinName]/stylesheets/content/ folder.
Add a new rendering view to the chart (version 4.6.x and higher)
Starting with version 4.6.x, a graphic charter can add one or more new rendering views to a content type, without having to override the content type model in WEB-INF/params/content-types/_override.
The view is therefore simply a rendering view, and not a view in the sense of the model.
This view must be attached to an existing view in the model.
Example use case: create a "carousel" view specific to the graphic charter, using the "abstract" view of the News template, for use in a news carousel.
View definition
The view must be defined in a XML skins/[skinName]/stylesheets/content/[contentTypeAlias]/[contentTypeAlias]-[viewName].xml
For example: skins/[skinName]/stylesheets/content/news/news-carousel.xml
The file must contain the view definition: label, description, icon and the template view to be used according to the following model:
<content-type> <label i18n="true">SKIN_NEWS_VIEW_CAROUSEL</label> <description i18n="true">SKIN_NEWS_VIEW_CAROUSEL_DESC</description> <view>abstract</view> <icons> <glyph>ametysicon-column3</glyph> <decorator>decorator-ametysicon-multimedia-command-play</decorator> </icons> </content-type>
The default catalog is i18n .
As with other views, it must be associated with a XSL renderer with the same name. skins/[skinName]/stylesheets/content/news/news-carousel.xsl
The view is now available in the search, content upload, ... services and in the "Content view" gallery only for the site(s) using this chart.
If the definition of a charter view contains an error (non-existent model view, missing configuration, ....), the view will be ignored. Inspect the application's warning logs if the view does not appear to find out why.
In "Developer" mode, chart views are added and modified without the need to restart the server.
Delete a view
Warning
It is not advisable to delete one of the 3 views defined by default for each type of content, as many plugins use these views to render services.
To delete a view other than the 3 defined by default in the Ametys kernel, you need to modify the XML file defining plugin on the one hand, and delete the corresponding XSL rendering file on the other.
To find out more, see Declaring and modifying a content type.
Content type templates
All core content is based on the same structure(view://stylesheets/content/common.xsl). This structure is broken down into templates to simplify and limit overloading during graphic integration. We recommend that you also use this structure to create new content.
This is the template structure for content:
Templates in white are defined in a commons file.xsl.
Templates for the various types of content are already defined in the plugin kernel, so that content 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.
common-content-head-title
Ce template correspond au titre de la page (balise <title>), il fait référence au template common-content-head-title-content avec les paramètres title (facultatif, par défaut : metadata/title).
<xsl:template name="common-content-head-title"> <xsl:call-template name="common-content-head-title-content"> <xsl:with-param name="title" select="'Mon titre'"/> </xsl:call-template> </xsl:template>
common-content-head-js
It is advisable to place the Javascript calls that will be used by the service in this template.
<xsl:template name="common-content-head-js">
<script type="text/javascript" src="{ametys:pluginResourceURL('monplugin', 'js/monfichier.js')}"><xsl:comment>empty</xsl:comment></script>
<script type="text/javascript">
// ...
</script>
</xsl:template> common-content-head-css
Service-specific style sheets must appear in this template.
<xsl:template name="common-content-head-css">
<link type="text/css" href="{ametys:pluginResourceURL('monplugin', 'css/monfichier.css')}" rel="stylesheet" />
</xsl:template> common-content-head-other
In this template, it is possible to add flow definitions RSS for example.
<xsl:template name="common-content-head-css">
<link rel="alternate" type="application/rss+xml" title="Mon flux RSS" href="{$uri-prefix}/{RSSFeedURL}"/>
</xsl:template> common-content-body-title
This template is used to display the content title. To do this, we recommend calling the common-content-body-title-content template with the title and subtitle parameters (optional, default: metadata/title and metadata/document-subtitle respectively).
<xsl:template name="common-content-body-title"> <xsl:call-template name="common-content-body-title-content"> <xsl:with-param name="title" select="metadata/header"/> <xsl:with-param name="subtitle" select="metadata/subtitle"/> </xsl:call-template> </xsl:template>
common-content-body-content
Finally, the common-content-body-content template is the most important to override: it's the one that contains the content data display.
It often consists of the following templates:
common-content-body-image
Description :
Display the resized image in a surrounding frame.
Parameters :
- image: image node
- alternative: alternative text
- maxWidth: maximum image width (in pixels)
- maxHeight: maximum image height (in pixels)
- class: DIV class CSS encompassing
common-content-body-image-bigsize
Description :
Same as common-content-body-image but with default values.
Parameters :
- image: by default, metadata/illustration/image
- alternative: default metadata/illustration/alt-text
- maxWidth: default 150
- maxHeight: default 150
- class: by default, big
- type: default 'bounded' (can also be 'cropped')
common-content-body-image-smallsize
Description :
Same as common-content-body-image but with default values.
Parameters :
- image: by default, metadata/illustration/image
- alternative: default metadata/illustration/alt-text
- maxWidth: default 100
- maxHeight: default 100
- class: default, small
- type: default 'bounded' (can also be 'cropped')
common-content-body-simpletext
Description :
Transforme un texte avec des sauts de lignes (\n) par des balises <br/>.
Parameters :
- text: text to be transformed
- defaultText: default text if text is empty
- maxDefaultTextSize: maximum text size to be displayed, default is 200
- css-class-name: class CSS of the enclosing paragraph
common-content-body-content-rich
Description :
Displays rich text, transforming it from Docbook to HTML and taking into account the current title level.
Parameters :
- level: last title level applied, default is 0
- content: rich text to be transformed, by default, metadata/content
common-content-body-contact
Description :
Displays contact name andemail (with anti-spam utility).
Example:
<a href="mailto:jean.dupont@ametys.org">jean.dupont<span style="position: absolute; left: -1000px; top: -1000px;"> </span>@<span style="position: absolute; left: -1000px; top: -1000px;"> </span>ametys.org</a>
common-content-body-publish-date
Description :
Displays the latest content publication date.
common-content-body-meta
Description :
Displays template common-content-body-contact followed by template common-content-body-publish-date.
common-content-body-comments
Description :
Displays the list of comments and lets you add a comment if comments are enabled for the content.
common-content-body-readmore
Description :
Creates a link to the page containing the content. This is particularly useful for non-full views of content (summaries, for example), which are regularly used in content feeds.
common-content-body-link
Description :
Content title with link to the page containing the content if it exists, particularly used for the link view of content that compacts the content information to a maximum.
Useful variables
common-content-name
The common-content-name variable is optional; it is not used by the kernel, but only by the graphic charters. For example, for a display common to several content types but not all, to avoid overloading several contents in the same way, it is preferable to overload the file common.xsl (folder cms/skins/[skinName]/stylesheets/content).
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="view://stylesheets/content/common.xsl"/> <xsl:template name="common-content-body-title"> <xsl:if test="not($common-content-name = 'type1' or $common-content-name = 'type2')"> <xsl:call-template name="common-content-body-title-content"/> </xsl:if> </xsl:template> </xsl:stylesheet>
common-content-css-class-name
This variable corresponds to the CSS class that will be used on the content's encompassing DIV.
Dynamic typing
In the back-office tool, contributors can use a tool to multi-type content:
- He creates his content by selecting a first type of content
- It can then add/delete additional content types
Views are merged
By default, graphics are rendered for the first type of content: first in the i18n key sorting (excluding catalogs) of the label.
It is possible, however, to transform dynamic typing into a true content type, and to render graphics specific to multityping.
La XSL de rendu par défaut est : WEB-INF/param/_dynamic/{pluginName}/stylesheets/{id}/{id}-{view}.xsl
Ametys will search for the closest content type:
Let be a typed content A, B and C :
- rendering used A
- if dynamic content type AB: rendering used AB
- if dynamic content type AB and ABC: render ABC
Example of installation
2 content types "content-type.A" and "content-type.B" defined in plugin "mycontenttypes".
To define dynamic rendering for A and B content types, define a WEB-INF/param/content-types/_dynamic/mycontenttypes/AB file. xml
The file contains the description of this "dynamic" type:
<?xml version="1.0" encoding="UTF-8"?> <cms:dynamic-content-type-descriptor extends="content-type.A,content-type.B" xmlns:cms="http://www.ametys.org/schema/cms"> <cms:label>AB</cms:label> </cms:dynamic-content-type-descriptor
The file name gives the identifier of this "dynamic" type, in this case "dynamic-content-type.AB".
The plugin "mycontenttypes" must define the rendering pipeline for these dynamic types:
<map:match pattern="dynamic-content-type.*.html">
<map:act type="get-ctype-info">
<map:generate type="content" label="content">
<map:parameter name="contentId" value="{request-param:contentId}"/>
<map:parameter name="metadataSetName" value="{request-param:metadataSetName}"/>
<map:parameter name="isEditionMetadataSet" value="{request-param:isEditionMetadataSet}"/>
<map:parameter name="fallbackMetadataSetName" value="{request-param:fallbackMetadataSetName}"/>
</map:generate>
<map:transform type="i18n">
<map:parameter name="locale" value="{request-attr:renderingLanguage}"/>
<map:parameter name="plugin" value="{request-attr:pluginName}"/>
</map:transform>
<map:transform src="content-view://{../1}/view-{request-param:metadataSetName}/html.xsl">
<map:parameter name="pluginName" value="{pluginName}"/>
</map:transform>
<map:transform type="i18n">
<map:parameter name="locale" value="{request-attr:renderingLanguage}"/>
<map:parameter name="plugin" value="{pluginName}"/>
</map:transform>
<map:serialize type="xhtml"/>
</map:act>
</map:match> For XSL renderings, go to WEB-INF/param/_dynamic/mycontenttypes/stylesheets/AB/AB-{view}.xsl
Note that if the dynamic type is declared in the folder, WEB-INF/param/_dynamic/web, it won't be necessary to define a specific rendering pipeline.
Further information
In the demo layout, a number of views other than those defined by default have been created. It is possible to use the files defining these views to adapt them to a specific graphic charter.
For example: 2-column item and 3-column item views
plugin:cms://stylesheets/content/common.xsl
Back to top