Lutece : guide intégrateur
Gérer les types de documents
Un document (du plugin Document), est défini par son type, c'est-à-dire par les informations qui le structurent. Un document possède par défaut un titre et une description. Le type va être spécialisé par l'ensemble des autres champs (adresse, fichier, image...) qui le décriront.
Par défaut, le plugin Document propose des types de documents prédéfinis, à savoir :
- Article
- Bannière
- Brèves
- Fiches acteurs
- Fichiers en téléchargements
- Images
- Vidéos en ligne
Chacun des types est composé par un ou plusieurs éléments, ou type de champs, que l'on peut utiliser pour le définir :
- Date
- Fichier
- Image
- Lien interne
- Liste de valeurs
- Texte multiligne
- Texte numérique
- Texte riche
- Texte
- Url
Ce paramétrage peut être modifié en fonction des besoins. Il est possible de créer des types de documents particuliers pour se conformer au plus près aux besoins éditoriaux. Il est possible par exemple de créer un type de document "Projet" qui permettra de décrire des projets en y ajoutant des contenus éditoriaux, des images, un fichier PDF et une URL.
Créer un type de document
Par le menu Contenu > Gestion des types de documents, vous pouvez accéder au bouton de création d'un nouveau type de document. Le code du document servira à l'appeler dans les feuilles de style XSL et ne pourra pas être modifié par la suite.
Une fois les informations saisies, vous pouvez gérer les attributs du nouveau type de document.
N.B. : Le modèle de métadonnées défini par défaut est "none" (soit pas de modèle défini) sachant qu'est disponible aussi le modèle "Dublin-core", un schéma de métadonnées générique qui permet de décrire des ressources numériques ou physiques et d’établir des relations avec d'autres ressources.
Les propriétés d'un type de document
Après la création du document, il est possible de modifier toutes les informations saisies précédemment à l'exception du code du type de document.
Créer des attributs
Pour ajouter un attribut, il faut choisir son type parmi les valeurs proposées dans la liste déroulante (date, fichier, texte, image...) et cliquer sur "Ajouter".
On retrouve des attributs communs à tous les champs, titre, code interne, description, déterminer si le champ est obligatoire en saisie, s'il doit être indexé par le moteur de recherche, et, en fonction des types, des attributs particuliers :
- Liste des extensions acceptées pour les attributs fichier et image
- Longueur du champ et nombre de caractères maximum acceptés pour l'attribut texte et texte numérique
- Définition de la date par défaut pour l'attribut date
- Liste des valeurs et valeur par défaut pour l'attribut liste de valeur.
N.B.: Si le plugin "plugin-regularexpression" permettant de gérer les expressions régulières est installé, vous pouvez appliquer à chaque attribut des règles contrôlées par des expressions régulières, afin de vérifier la valeur saisie par l'utilisateur. Par défaut, une règle de vérification d'e-mail existe, qui associée à l'attribut "E-mail" vérifiera la conformité d'adresse e-mail saisie.Vous pouvez ajouter autant de règles que nécessaire.
Une fois les attributs créés ils apparaissent dans la liste :
Nous avons donc créé un type de document "projet" avec trois attributs : illustration, description et coût du projet.
Création d'un document
L'interface de création des documents se trouve dans Contenu > Gestion des documents.
Afin d'être en mesure de créer un nouveau document, il doit exister un espace de documents acceptant le nouveau type de document créé. A cet effet, il est possible de :
- Créer un nouvel espace de documents en cliquant sur le bouton
- Ou modifier un espace de documents existant en cliquant sur le bouton
Dans la section "type de documents autorisés" de l'espace, cocher la case correspondant au nouveau type de document précédemment créé, et en veiller à ce que la case "Création de documents" soit cochée.
Procéder ensuite à la création du document.
Après l'avoir validé, il faut ensuite le publier sur le site, par exemple dans une nouvelle rubrique de type "Document" via Site > Administration du site, en sélectionnant "Projet Test" dans le type de documents, puis en choisissant le style approprié créé au préalable. Il reste ensuite à publier le document dans la rubrique.
Personnaliser le rendu du document en front office dans une rubrique (portlet)
Pour un affichage du nouveau type de document créé dans un portlet, il faut passer par le menu Charte > Gestion des Styles puis Charte > Gestion des Feuilles de style XSL (voir le chapitre : Gestion des styles qui détaille la procédure de création d'un style).
La feuille de style XSL doit appeler les attributs du document créé au préalable dans Contenu > Gestion des types de documents.
Chacun des attributs du document peut être affiché via l'arbre XML :
document-portlet/document/document-xml-content/nom_document/nom_document-nom_attributpour un portlet document ;
document-list-portlet/document/document-xml-content/nom_document/nom_document-nom_attributpour un portlet liste de documents.
Note : Il est possible de reprendre une feuille de style XSL incluse par défaut et de l'adapter au nouveau document créé.
Voici une feuille de style XSL pour l'affichage du type de document "Projet" dans un portlet :
<?xml version="1.0"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:param name="site-path" select="site-path" />
<xsl:variable name="portlet-id" select="portlet/portlet-id" />
<xsl:template match="portlet">
<xsl:variable name="device_class">
<xsl:choose>
<xsl:when test="string(display-on-small-device)='0'">hidden-xs</xsl:when>
<xsl:when test="string(display-on-normal-device)='0'">hidden-sm</xsl:when>
<xsl:when test="string(display-on-large-device)='0'">hidden-md</xsl:when>
<xsl:when test="string(display-on-xlarge-device)='0'">hidden-lg</xsl:when>
<xsl:otherwise></xsl:otherwise>
</xsl:choose>
</xsl:variable>
<div class="{$device_class}">
<div class="row">
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-12">
<xsl:if test="not(string(display-portlet-title)='1')">
<h2>
<xsl:value-of disable-output-escaping="yes" select="portlet-name" />
</h2>
</xsl:if>
</div>
</div>
<xsl:apply-templates select="document-portlet" />
</div>
</xsl:template>
<xsl:template match="document-portlet">
<div class="row">
<xsl:apply-templates select="document" />
</div>
</xsl:template>
<xsl:template match="document">
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-12">
<xsl:apply-templates select="document-xml-content/projet" />
</div>
</xsl:template>
<xsl:template match="document-xml-content/projet">
<div class="">
<div>
<p>
<a href="{$site-path}?document_id={document-id}&portlet_id={$portlet-id}" target="_top">
Titre du projet : <xsl:value-of select="document-title" />
</a>
</p>
<p><xsl:value-of disable-output-escaping="yes" select="substring(projet-description,1,100)"/>...</p>
<p><xsl:value-of select="projet-cout" /> €</p>
</div>
<div class="">
<a href="{$site-path}?document_id={document-id}&portlet_id={$portlet-id}" target="_top">
<xsl:choose>
<xsl:when test="projet-illustration/file-resource!=''">
<xsl:apply-templates select="projet-illustration/file-resource" />
</xsl:when>
<xsl:otherwise></xsl:otherwise>
</xsl:choose>
</a>
</div>
</div>
</xsl:template>
<xsl:template match="file-resource">
<xsl:choose>
<xsl:when test="(resource-content-type='image/jpeg' or resource-content-type='image/jpg' or resource-content-type='image/pjpeg' or resource-content-type='image/gif' or resource-content-type='image/png')">
<img src="document?id={resource-document-id}&id_attribute={resource-attribute-id}" class="img-responsive" title="{../../document-title}" alt="{../../document-title}" />
</xsl:when>
<xsl:otherwise>
<a href="document?id={resource-document-id}&id_attribute={resource-attribute-id}">
<img src="images/admin/skin/plugins/document/filetypes/file.png" border="0" class="img-responsive" />
</a>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
</xsl:stylesheet>
Voici un exemple de rendu simple, de notre document de type "Projet Test" dans la colonne 2 de la page d'accueil du site :
Le portlet document reprend le contenu des attributs présents dans la feuille de style XSL, et l'URL du titre renvoie vers l'affichage du document en pleine page.
Personnaliser le rendu du document en front office en pleine page ("document content service")
Chaque document peut être affiché individuellement sur une page dédiée utilisant le "Content Service" du plugin Document, via le fichier document_content_service_default_xsl.html.
Pour personnaliser le rendu du document, il faut créer la feuille de style XSL pour chaque type de document, via Contenu > Gestion des types de documents, puis sélectionner le type de document dont on veut modifier la feuille de style.
Il est possible d'ajouter ou de télécharger une feuille de style, pour le front office et le back office. Dans le cas de l'ajout ou de la mise à jour du fichier, il est nécessaire de cocher la case "Mettre à jour le fichier" pour que les changements soient pris en compte.
Vous pouvez récupérer une XSL existante en téléchargeant le fichier via le bouton "Télécharger la feuille de style XSL" sur l'un des types de documents par défaut (comme Article, par exemple). Il conviendra ensuite de la modifier pour qu'elle soit adaptée au nouveau type de document créé, en remplaçant le code du type de document par le code de celui que vous avez créé.
Voici un exemple de feuille de style XSL pour l'affichage pleine page d'un document de type "Projet Test" :
<?xml version="1.0"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:param name="publication-date" select="publication-date" />
<!--
How to display the publication date :
<xsl:value-of select="$publication-date" />
-->
<xsl:output method="html" indent="yes"/>
<xsl:template match="content">
<xsl:apply-templates select="projet"/>
</xsl:template>
<xsl:template match="projet">
<div class="row">
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-12">
<h1><xsl:value-of select="document-title" /></h1>
</div>
</div>
<div class="row">
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-12">
<xsl:choose>
<xsl:when test="not(string(projet-illustration)='')" >
<xsl:apply-templates select="projet-illustration/file-resource" />
</xsl:when>
<xsl:otherwise></xsl:otherwise>
</xsl:choose>
</div>
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-12">
<xsl:choose>
<xsl:when test="not(string(projet-description)='')" >
<xsl:value-of disable-output-escaping="yes" select="projet-description" />
</xsl:when>
<xsl:otherwise></xsl:otherwise>
</xsl:choose>
</div>
</div>
<div class="row">
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-12">
<xsl:if test="not(string(projet-cout)='')">
Coût du projet : <xsl:value-of select="projet-cout" />
</xsl:if>
</div>
</div>
</xsl:template>
<xsl:template match="file-resource">
<xsl:choose>
<xsl:when test="(resource-content-type='image/jpeg' or resource-content-type='image/jpg' or resource-content-type='image/pjpeg' or resource-content-type='image/gif' or resource-content-type='image/png')" >
<img src="document?id={resource-document-id}&id_attribute={resource-attribute-id}" alt="" title="" class="img-responsive" />
</xsl:when>
<xsl:otherwise></xsl:otherwise>
</xsl:choose>
</xsl:template>
</xsl:stylesheet>
Il est possible de choisir parmi plusieurs modèles de présentation pour l'affichage pleine page du document. Ce choix s'effectue dans l'écran d'édition d'un document via Contenu > Gestion des documents, éditer le document dans l'espace de Documents auquel il est affecté, et dans Propriétés avancées, trois modèles de présentation sont sélectionnables :
- Défaut (correspondant au fichier WEB-INF/templates/skin/plugins/document/document_content_service.html)
- Pleine page (correspondant au fichier WEB-INF/templates/skin/plugins/document/page_templates/page_template_document1.html)
- Rubrique en-dessous (correspondant au fichier WEB-INF/templates/skin/plugins/document/page_templates/page_template_document2.html)
Ces fichiers sont pleinement personnalisables pour répondre au mieux à la charte graphique du site. Les templates par défaut incluent les Extenders (balises Freemarker utilisées pour les composants du plugin Extend - voir le chapitre Paramétrer les Extensions).
Voici un exemple de rendu simple du document affiché en pleine page via le template "pleine page" :
Note : Un document doit obligatoirement être publié dans un portlet pour pouvoir être visualisé en front office. L'ID du portlet figure ainsi dans l'URL du document, exemple : /jsp/site/Portal.jsp?document_id=24&portlet_id=3