Rendu graphique d'un contenu

  1. Notions de vues
    1. Consulter les vues disponibles
    2. Surcharger une vue
    3. Ajouter une nouvelle vue
    4. Supprimer une vue
  2. Templates des types de contenu
    1. common-content-head-title
    2. common-content-head-js
    3. common-content-head-css
    4. common-content-head-other
    5. common-content-body-title
    6. common-content-body-content
      1. common-content-body-image
      2. common-content-body-image-bigsize
      3. common-content-body-image-smallsize
      4. common-content-body-simpletext
      5. common-content-body-content-rich
      6. common-content-body-contact
      7. common-content-body-publish-date
      8. common-content-body-meta
      9. common-content-body-comments
      10. common-content-body-readmore
      11. common-content-body-link
  3. Les variables utiles
    1. common-content-name
    2. common-content-css-class-name
  4. Typage dynamique
  5. Pour aller plus loin

Notions de vues

Pour tout contenu inséré dans une zone, il est possible de choisir sa vue, c'est-à-dire, de définir le nom de la feuille de style XSL à utiliser pour construire son rendu.

Le nom et les champs utilisés pour les différentes vues d'un type de contenu sont définis dans le plugin d'où il est extrait.

<!-- [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>

Pour chacune des vues définies dans le plugin, une feuille de styles XSL est associée : les données XML transmises par le CMS sont transformées par la XSL de rendu [contentType]-[viewName].xsl de manière à les afficher dans la structure HTML attendue par la charte graphique.

[contentType]-[viewName].xslHTML généré
<?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>

C'est ce fichier [contentType]-[viewName].xsl, qu'Ametys utilise pour définir le rendu de la vue sélectionnée. Cette feuille de style est recherchée dans :

  • cms/skins/[skinName]/stylesheets/content/[contentType]/

  • WEB-INF/param/content-types/web/stylesheets/[contentType]/

  • plugins/[pluginName]/stylesheets/content/[contentType]/

A défaut de trouver le fichier de rendu attendu dans l'un des répertoire mentionnés, le CMS recherche la feuille de style [contentType].xsl ignorant la vue attendue. A défaut de trouver cette dernière feuille de style, il utilise un fichier XSL de substitution nommée default-content.xsl et dépourvu de style.

Dans l'exemple ci-dessus, la feuille de style [contentType]-[viewName].xsl fait appel à une feuille de styles commons.xsl.

En effet, les types de contenus ont nécessairement des templates communs qui peut être définis dans une XSL commune puis importée dans chaque feuille de style de rendu.

Ametys fourni par défaut une feuille de style common.xsl généralement appelée dans une feuille de style XSL commune au niveau du projet via le protocole d'import view://

Ce protocole d'import respecte un ordre de traitement spécifique qui donne systématiquement la priorité aux éléments surchargés dans la charte graphique. Pour plus d'information sur le protocole d'import view://, consulter la page protocoles d'import

Cette XSL de rendu apporte une structure de base et autant de templates utiles à l'intégration. Il est recommandé de conserver ce découpage de templates pour construire tout nouveau type de contenu afin d'homogénéiser les rendus graphiques des contenus mais aussi afin de simplifier les maintenances et évolutions qui pourraient avoir lieu à l'avenir sur le projet. Pour plus d'information, se reporter à la section templates des types de contenus

Par ailleurs, Ametys défini déjà des types de contenus (notamment le type de contenu article) avec par défaut 3 feuilles de styles de rendu :

  • [contentType]-main.xsl correspondant à un rendu complet du contenu avec toutes les données publiques
  • [contentType]-abstract.xsl correspondant à un rendu synthétisé du contenu souvent utilisé dans les remontées de contenus
  • [contentType]-link correspondant à un rendu simplifié d'un contenu, ne comportant souvent que son titre et un lien, il est notamment utilisé par le plugin Calendar

 

Certains plugins Ametys font appel aux vues main, abstract ou link, l'absence de l'une de ces vues pour un type de contenu donné pourrait engendrer des erreurs.
Il est donc préférable de toujours prévoir au minimum ces 3 vues pour tout nouveau type de contenu.

 

Noter que pour visualiser un contenu dans le CMS, une XSL d'enrobage peut-être nécessaire. En effet, les contenus ne pouvant être insérés que dans une zone de gabarit, son rendu est généralement dépendant des balises qui constituent le gabarit. Pour être visualisé seul dans le CMS, il faut recréer cet environnement. C'est la XSL d'enrobage qui rempli cette fonction. Pour plus d'information concernant les XSL d'enrobage, consulter la page XSL d'enrobage.

Consulter les vues disponibles

Afin de consulter les vues disponibles pour un type de contenu, consulter le fichier plugin.xml du plugin dont le type de contenu est extrait (voir Déclaration et modification d'un type de contenu).

Vues d'un article et fichiers XSL correspondants (plugins/web/plugin.xml) :

Selon les plugins importés, un projet peut bénéficier par défaut de nombreux autres types de contenus tous avec une structure commune.

Surcharger une vue

Il est possible de surcharger une vue, pour cela, créer le fichier cms/skins/[skinName]/stylesheets/content/[contentType]/[contentType]-[view].xsl qui importe la XSL du plugin lui correspondant et en pratique une XSL commune à toutes les vues du type de contenu qui se trouve dans la charte graphique :

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>

Selon la vue du contenu, le XML d'entrée est plus ou moins complet. Les templates qui constituent les différentes vues des contenus permettent d'organiser l'information.

Par défaut, la vue complète d'un article est organisée comme suit :

  • Le titre de l'article, définie dans un fichier common.xsl dans un template nommé common-content-body-title
  • Le contenu de l'article:
    • L'illustration
    • Le contenu saisi par le contributeur dans un champ riche
    • L'auteur et la date de publication
    • Les commentaires s'ils ont été activé par le contributeur.

Chaque élément est précédé d'un test afin de ne pas générer le code HTML si le champ correspondant n'a pas été renseigné par le contributeur.

<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>

 

De nombreux templates sont mutualisés dans une feuille de style commune. Cependant, pour chaque vue de chaque type de contenu, ces templates peuvent être surchargés pour un rendu spécifique.

Par exemple, pour définir une taille d'image plus grande dans les articles en vue complète, redéfinir le template common-content-body-image-bigsize dans la XSL correspondant à la vue cms/[skinName]/stylesheets/content/article/article-main.xsl

Ajouter une nouvelle vue

Pour ajouter une nouvelle vue à un type de contenu, il faut, d'une part, définir les champs du contenus qui doivent remonter dans cette vue dans le fichier XML de définition du plugin, d'autre part, associer un fichier XSL pour modéliser le rendu correspondant. Le fichier XSL associé doit porter le même nom que la vue déclarée dans le plugin. Pour en savoir plus, consultez Déclaration et modification d'un type de contenu.

Un nouveau type de contenu peut être déclaré soit dans un plugin, soit dans les paramètres WEB-INF/param/content-types. Dès lors, selon que le nouveau type de contenu ai été déclaré dans l'un ou l'autre des deux répertoires, les feuilles de styles associées seront placée dans le même répertoire.

Dans un pluginDans les paramètres

Ces nouvelles feuilles de style peuvent importer des feuilles de style communes au projet et/ou au noyau de la même manière que pour les feuilles de style qui sont surchargées dans le dossier cms/skins/[skinName]/stylesheets/content/.

Supprimer une vue

 

Attention
Il est déconseillé de supprimer une des 3 vues définies par défaut pour chaque type de contenu car ne nombreux plugins utilisent ces vues dans le rendu des services.

Pour supprimer une vue autre que les 3 vues définies par défaut dans le noyau Ametys, il faut modifier le fichier XML de définition du plugin d'une part et supprimer le fichier XSL du rendu correspondant d'autre part.

Pour en savoir plus consultez Déclaration et modification d'un type de contenu.

Templates des types de contenu

Tous les contenus du noyau sont basés sur la même structure (view://stylesheets/content/common.xsl). Cette structure est découpée en templates de sorte à simplifier et limiter leur surcharge lors de l'intégration graphique. Il est recommandé d'utiliser également cette structure pour créer de nouveaux contenus.

Voici la structure de templates d'un contenu :

Les templates en blanc sont définis dans un fichier commons.xsl.

Les templates des différents types de contenus sont déjà définis dans le plugin du noyau afin que le contenu soit utilisable sans nécessiter l'application de charte graphique. Cependant, le rendu étant minimaliste, il faut généralement surcharger les templates nécessaires pour correspondre au rendu attendu par la charte graphique.

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

Il est conseillé de placer dans ce template les appels Javascript qui seront utilisés par le service.

<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

Les feuilles de styles spécifiques au service doivent apparaître dans ce 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

Dans ce template, il est possible d'ajouter des définitions de flux RSS par exemple.

<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

Ce template permet d'afficher le titre du contenu. Pour cela, il est recommandé d'appeler le template common-content-body-title-content avec les paramètres title et subtitle (facultatifs, par défaut : respectivement metadata/title et metadata/document-subtitle).

<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

Enfin, le template common-content-body-content est le plus important à surcharger, c'est celui qui contient l'affichage des données du contenu.

Il est souvent constitué des templates suivants :

common-content-body-image

Description :

Affichage de l'image redimensionnée dans un cadre englobant.

Paramètres :

  • image : noeud de l'image
  • alternative : texte alternatif
  • maxWidth : largeur maximale de l'image (en pixels)
  • maxHeight : hauteur maximale de l'image (en pixels)
  • class : classe CSS du DIV englobant
common-content-body-image-bigsize

Description :

Identique à common-content-body-image mais avec des valeurs par défaut.

Paramètres :

  • image : par défaut, metadata/illustration/image
  • alternative : par défaut, metadata/illustration/alt-text
  • maxWidth : par défaut, 150
  • maxHeight : par défaut, 150
  • class : par défaut, big
  • type : par défaut, 'bounded' (peut également prendre la valeur 'cropped')
common-content-body-image-smallsize

Description :

Identique à common-content-body-image mais avec des valeurs par défaut.

Paramètres :

  • image : par défaut, metadata/illustration/image
  • alternative : par défaut, metadata/illustration/alt-text
  • maxWidth : par défaut, 100
  • maxHeight : par défaut, 100
  • class : par défaut, small
  • type : par défaut, 'bounded' (peut également prendre la valeur 'cropped')
common-content-body-simpletext

Description :

Transforme un texte avec des sauts de lignes (\n) par des balises <br/>.

Paramètres :

  • text : texte à transformer
  • defaultText : texte par défaut si text est vide
  • maxDefaultTextSize : taille maximale du texte à afficher, par défaut, 200
  • css-class-name : classe CSS du paragraphe englobant
common-content-body-content-rich

Description :

Affiche du texte riche en le transformant de Docbook à HTML et en tenant compte du niveau de titre courant.

Paramètres :

  • level : dernier niveau de titre appliqué, par défaut, 0
  • content : texte riche à transformer, par défaut, metadata/content
common-content-body-contact

Description :

Affiche le nom et l'email du contact (avec un utilitaire antispam).

Exemple :

<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 :

Affiche la dernière date de publication du contenu.

common-content-body-meta

Description :

Affiche le template common-content-body-contact suivi du template common-content-body-publish-date.

common-content-body-comments

Description :

Affiche la liste des commentaires et permet d'ajouter un commentaire si ceux-ci sont activés pour le contenu.

common-content-body-readmore

Description :

Crée un lien vers la page qui contient le contenu. C'est notamment utilisée pour les vues non pleines du contenu (résumé par exemple) qui sont régulièrement utilisés dans les remontées de contenus.

common-content-body-link

Description :

Titre du contenu avec lien vers la page contenant le contenu si elle existe, particulièrement utilisé pour la vue lien d'un contenu qui compacte au maximum les informations du contenu.

Les variables utiles

common-content-name

La variable common-content-name est facultative, elle n'est pas utilisée par le noyau mais uniquement par les chartes graphique. Par exemple, pour un affichage commun à plusieurs types de contenu mais pas tous, afin d'éviter de surcharger plusieurs contenus de la même manière, il est préférable de surcharger le fichier common.xsl (dossier 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

Cette variable correspond à la classe CSS qui sera utilisée sur le DIV englobant du contenu.

Typage dynamique

Dans l'outil back-office, le contributeur peut disposer un outil pour multi-typer un contenu :

  • Il crée son contenu en sélectionnant un premier type de contenu
  • Ensuite il peut ajouter/supprimer des types de contenus supplémentaires

Les vues sont fusionnées

Par défaut, le rendu graphique est opéré par le premier type de contenu : premier dans le tri par clef i18n (hors catalogue) du libellé.

Il est cependant possible de transformer un typage dynamique en vrai type de contenu et d'avoir un rendu graphique spécifique à un multitypage.

La XSL de rendu par défaut est : WEB-INF/param/_dynamic/{pluginName}/stylesheets/{id}/{id}-{view}.xsl

Ametys va rechercher le type de contenu le plus proche :

Soit un contenu typé A, B et C :

  • rendu utilisé A
  • si type de contenu dynamique AB : rendu utilisé AB
  • si type de contenu dynamique AB et ABC : rendu utilisé ABC

Pour aller plus loin

Dans la charte graphique de démonstration, quelques vues autres que celles définies par défaut ont été créées. Il est possible de reprendre les fichiers définissant ces vues pour les adapter à une charte graphique.

Par exemple : les vues article sur 2 colonnes et article sur 3 colonnes

plugin:cms://stylesheets/content/common.xsl