Manuel de paramétrage et d'intégration

  1. Définition de thématiques dans la charte graphique
  2. InputData (charte graphique)
    1. Activation pour les versions 2.13 et supérieures
    2. Versions inférieures à 2.13
    3. Configuration avancée (version 2.31.0 et supérieures)
  3. Données XML fournies
  4. Exemple d'utilisation dans la charte graphique
    1. Affichage des informations dynamiques sur les vignettes
  5. Couleurs
  6. Héritage de charte

Définition de thématiques dans la charte graphique

A partir de la version 2.13

A partir de la version 2.13 il est possible de définir des thématiques de liens propres à la charte graphique.

Les thématiques sont définies dans le fichier skins/[NOM_SKIN]/conf/link-directory.xml dans la section <definitions> comme dans l'exemple ci-après:

<link-themes>
    <!-- Define the themes for this skin -->
    <definitions>
        <theme id="FOOTER">
            <label i18n="true">SKIN_FOOTER_LINK_LABEL</label>
            <description i18n="true">SKIN_FOOTER_LINK_DESC</description>
        </theme>
    </definitions>
</link-themes>

InputData (charte graphique)

Le plugin Annuaire de liens fournit un input data, permettant d'insérer les liens d'une ou plusieurs thématiques sur l'ensemble ou partie des pages du site.

Activation pour les versions 2.13 et supérieures

L'activation de l'inputdata s'effectue au niveau de la charte graphique, dans le fichier skins/[NOM_SKIN]/conf/link-directory.xml dans la section <inputdata> comme dans l'exemple ci-après:

<link-themes>
    <!-- Configure the template's link directory inputdata here -->
    <inputdata>
        <themes templates="index" configurable="true" displayUserLinks="true">
            <theme id="TOOLS" lang="en"/>
            <theme id="OUTILS" lang="fr"/>
        </themes>
        <themes templates="page,section" configurable="false">
            <theme id="FOOTER"/>
        </themes>
    </inputdata>

    <!-- Define the themes for this skin -->
    <definitions>
        <theme id="FOOTER">
            <label i18n="false">SKIN_FOOTER_LINK_LABEL</label>
            <description i18n="true">SKIN_FOOTER_LINK_DESC</description>
        </theme>
    </definitions>
</link-themes>
  • L'attribut templates contient le ou les gabarits affectés par cet input data, séparés par des virgules (* signifie que tous les thèmes).
  • L'attribut configurable détermine si une personnalisation des liens par un utilisateur connecté est autorisée (true ou false)
  • L'attribut displayUserLinks détermine s'il est possible d'ajouter des liens personnalisés
  • L'attribut inputDataId détermine l'identifiant de l'InputData pour différencier les liens provenant de plusieurs InputData répondants à un seul gabarit. Par défaut, l'identifiant est la chaîne vide. Disponible uniquement à partir de la version 2.12.
  • Les balises <theme> permet de choisir les liens de quelle thématique seront affichés.
    • L'attribut id correspondant à l'identifiant du thème
    • L'attribut lang détermine la langue des liens qui seront sélectionnés pour le thème donné (optionnel)

L'exemple ci-dessus permet donc d'activer l'input data:

  • pour le gabarit "index", l'input data contiendra les liens ayant pour thématique "OUTILS" pour les liens FR et les liens ayant pour thématiques "TOOLS" pour les liens EN
  • pour les gabarits "page" et "section", l'input data contiendra les liens ayant pour thématique "FOOTER". Cette thématique est apportée par la charte graphique.

Versions inférieures à 2.13

Pour les versions inférieures à 2.13, pour activer cet input data et définir son contenu, vous devez créer dans votre charte graphique, un fichier XML skins/[NOM_SKIN]/conf/link-themes.xml, qui contient pour chaque gabarit, les thématiques de liens à afficher :

<link-themes>     
    <themes templates="index,page" configurable="true" displayUserLinks="true">     
        <theme id="OUTILS" lang="fr"/>     
    </themes>     
    <themes templates="news" configurable="false">     
        <theme id="ACTU" lang="fr"/>     
        <theme id="OUTILS" lang="fr"/>     
    </themes> 
    <themes templates="favorite-news" configurable="true" inputDataId="favNews">
        <theme id="ACTU" lang="fr"/>
    </themes> 
</link-themes>     
  • L'attribut templates contient le ou les gabarits affectés par cet input data, séparés par des virgules (* signifie que tous les thèmes).
  • L'attribut configurable détermine si une personnalisation des liens par un utilisateur connecté est autorisée (true ou false)
  • L'attribut displayUserLinks détermine s'il est possible d'ajouter des liens personnalisés
  • L'attribut inputDataId détermine l'identifiant de l'InputData pour différencier les liens provenant de plusieurs InputData répondants à un seul gabarit. Par défaut, l'identifiant est la chaîne vide. Disponible uniquement à partir de la version 2.12.
  • Les balises <theme> permet de choisir quels liens (de quelle thématique seront affichés).
    • L'attribut id correspondant à l'identifiant donné au thème dans le CMS
    • L'attribut lang détermine la langue des liens qui seront sélectionnés

Configuration avancée (version 2.31.0 et supérieures)

A partir de la version 2.31.0 il est possible de fournir plusieurs fichiers de configuration pour les liens de l'annuaire définis par la charte graphique (input data)

Par exemple on va séparer dans un fichier de configuration différent:

  • les liens ne dépendant pas de l'utilisateur connecté (ex: réseaux sociaux, partenaires, accès rapide, ...) et donc pouvant être mis en cache (calculés une seule fois)
  • les liens configurables ou dépendant des droits de l'utilisateur connecté (ex: applications métiers, favoris, ...) et donc ne pouvant pas être mise en cache

Tous les liens "cacheable" se trouvant alors dans le même fichier, l'input data associé à ce fichier devient "cacheable" également, ce qui peut améliorer les performances d'affichage, notamment dans le cas d'un extranet où certaines pages sont publiques. En effet, un input data non cacheable empêche une page d'être elle-même mise en cache, ce qui peut poser des gros problème de performance pour une page d'accueil non authentifiée par exemple.

De plus, il devient possible d'exclure le sax des liens accessibles qu'à des utlisateurs connectés au moyen de l'attribut "excludeAnonymous".
Ceci n'a d'intérêt que si l'application est accessible à un public non authentifié (extranet).

<inputdata>
     <themes templates="index,page,fullpage,search" configurable="true" displayUserLinks="true" inputDataId="myFavorites" excludeAnonymous="true">
            <theme id="MES_FAVORIS" lang="fr"/>
            <theme id="MES_FAVORIS" lang="en"/>
        </themes>
</inputdata>

Mise en place d'un fichier d'inputdata séparé

Pour chaque fichier inputdata supplémentaire il faut déclarer un nouveau point d'extension dans un fichier plugin.xml.
Exemple:

<extension point="org.ametys.web.inputdata.InputDataExtensionPoint"
                     id="fr.ametys.xxxx.linkdirectory.LinkDirectoryInputData"
                       class="org.ametys.plugins.linkdirectory.LinkDirectoryInputData">
    <config file="skin://conf/link-directory-cacheable.xml"/>
</extension>

Données XML fournies

Le format de l'input data est le suivant:

<cms>    
  <inputData>    
    <linkDirectory applicable="true" configurable="true" id="xxx">    
      <themes>    
        <theme>OUTILS</theme>
        <theme>FOOTER</theme>   
      </themes>    
      <links>    
        <link id="directoryLink://3e1d509b-7e3d-4ec4-98d5-e70e268e78d5" url="http://www.ametys.org/forum/" urlType="URL" title="Forum" content="" alternative="Forum Ametys" pictureAlternative="" user-selected="false" pictureType="external" picturePath="picture" pictureName="chat.png" pictureSize="4497" imageType="metadata" grantAnyUser="false" limitedAccess="false">    
          <themes>
             <theme id="OUTILS" name="OUTILS">
             <label>Outils</label>
          </themes>    
        </link>    
        <link id="directoryLink://c9921cec-fa6e-46c9-a256-a7a800bcc1c3" url="https://www.google.com/contacts" urlType="URL" title="Annuaire" content="" alternative="Annuaire" pictureAlternative="" user-selected="false" pictureType="external" picturePath="picture" pictureName="user.png" pictureSize="1868" imageType="metadata" grantAnyUser="true" limitedAccess="true">    
          <themes>
             <theme id="OUTILS" name="OUTILS">
             <label>Outils</label>
          </themes>    
        </link>  
        <link id="directoryLink://2e62b33d-fe90-4447-b135-01b11d6e270e" url="https://fr-fr.facebook.com/AmetysCMS" urlType="URL" title="Facebook" content="" alternative="Annuaire" pictureAlternative="" user-selected="false" color="#9900CC" pictureType="external" picturePath="picture" pictureName="facebook.png" pictureSize="2809" imageType="link-data" limitedAccess="false" userLink="false" isHidden="false" status="NORMAL">    
          <themes>
             <theme id="FOOTER" name="FOOTER">
             <label>Pied de page</label>
          </themes>    
        </link>    
      </links>    
    </linkDirectory>    
  </inputData>    
</cms>    

Exemple d'utilisation dans la charte graphique

Le plugin Annuaire de liens fournit des helpers XSLT qui peuvent être utilisés dans la charte graphique. Pour cela il vous suffit d'importer le fichier pages/services/directory/utils/inputdata_utils.xsl du plugin est d'appeler les templates à l'endroit souhaité:

Nom du template

Fonction

Paramètres

display-configure-links-btn-inputdata

Insère un lien "Personnaliser" pour configurer l'ordre d'affichage des liens.
Le lien est présent uniquement si les liens sont configurables.
Fournit une boite de dialogue javascript dans laquelle l'utilisateur pourra sélectionner
les liens qu'il souhaite voir en premier
  • maxCheckedLinks : Nombre maximun de liens sélectionnable par l'utilisateur

links-thumbnails-input-data

Affiche les liens de l'input data sous forme de vignettes

  • moreThreshold: Nombre maximum de liens visibles par défaut

  • height: largeur maximun des vignettes
  • width: largeur maximum des vignettes

 

<xsl:import href="plugin:link-directory://pages/services/directory/utils/inputdata_utils.xsl"/>    

<xsl:template name="template">    
    <-- // ... ->    
    <xsl:if test="/cms/inputData/linkDirectory/@applicable = 'true'">    
      <div class="block">    
        <div class="header">    
          <!-- Button pour configurer l'affichage des liens -->    
          <xsl:call-template name="display-configure-links-btn-inputdata">    
            <xsl:with-param name="maxCheckedLinks" select="7"/>    
          </xsl:call-template>    
          <i18n:text i18n:key="SKINS_LINKS_HEADER" i18n:catalogue="skin.{$skin}"/>    
        </div>    
            
        <div class="body">    
            
          <xsl:call-template name="links-thumbnails-inputdata">    
            <xsl:with-param name="moreThreshold" select="8"/>    
            <xsl:with-param name="height" select="50"/>    
            <xsl:with-param name="width" select="50"/>    
            <xsl:with-param name="themes" select="/cms/inputData/linkDirectory/themes"/>    
          </xsl:call-template>    
        </div>    
      </div>    
    </xsl:if>    
</xsl:template>    

Pour aller plus loin
Pour pouvez personnaliser entièrement l'affichage des liens en surchargeant les templates XSLT fournit par le plugin.
Regardez aux fichier XSL du répertoire https://svn.ametys.org/trunk/plugins/link-directory/tags/1.1.0/main/plugin-link-directory/pages/services/directory/utils/ et surchargez le ou les templates nécessaires.
Par exemple, si vous souhaitez remplacer le lien "Personnaliser" par une image, il vous faudra surcharger le template "configure-links-btn"

<xsl:template name="configure-links-btn">     
 <xsl:param name="buttonId"/>     

 <xsl:choose>     
     <xsl:when test="$rendering-context = 'front' and ametys:user()">     
         document.writeln("&lt;a id=\"configure-links-hyperlink-<xsl:value-of select="$buttonId"/>-disabled\" class=\"configure-links-service-button\" title=\"<i18n:text i18n:key="SKIN_LINKDIRECTORY_CONFIGURE_THUMBNAILS_TITLE_BO" i18n:catalogue="skin.{$skin}"/>\" i18n:attr=\"title\"&gt;");     
 document.writeln("&lt;img alt=\"<i18n:text i18n:key="PLUGINS_LINKDIRECTORY_CONFIGURE_THUMBNAILS" i18n:catalogue="plugin.link-directory"/>\" src=\"<xsl:value-of select="ametys:skinImageURL('img/config;png', 20, 20)\"/&gt;");     
 document.writeln("&lt;/a&gt;");     
 </xsl:when>     
        <xsl:otherwise>     
            <!-- NO FO user connected: the button is not displayed -->     
        </xsl:otherwise>     
    </xsl:choose>     
</xsl:template>     

Affichage des informations dynamiques sur les vignettes

Si vos liens/applications possèdent des informations dynamiques pouvant être affichées sous forme de pastille et tooltip, importez également dans votre charte graphique le fichier pages/services/directory/utils/thumbnail_utils.xsl

Puis faites appel au template XSL "link-dynamic-info-js" dans la section <head>. Par exemple :

<xsl:import href="plugin:link-directory://pages/services/directory/utils/thumbnails_utils.xsl"/>    

<xsl:template name="additionnal-script">    
       <xsl:call-template name="link-dynamic-info-js">    
            <xsl:with-param name="maxItems">5</xsl:with-param>    
            <xsl:with-param name="themes" select="/cms/inputData/linkDirectory/themes"/>    
       </xsl:call-template>    
</xsl:template>    

Couleurs

Depuis la version 2.6.0, les liens peuvent avoir une couleur.

Pour surcharger la liste des couleurs disponibles par défaut, créez un fichier à l'emplacement WEB-INF/param/linkdirectory-colors.xml contenant :

<?xml version="1.0" encoding="UTF-8"?>
<colors default="4">
    <color id="1">
        <main>#FF66FF</main>
        <text>#FFFFFF</text>
    </color>
    <color id="2">
        <main>#CC33CC</main>
        <text>#FFFFFF</text>
    </color>
...
</colors>

Héritage de charte

A partir de Ametys 4.5

Fichier absent

Comme la règle d'héritage générique l'indique, si le fichier est absent, c'est le fichier de la charte parente qui est utilisé.

Héritage

Si le fichier est présent il va être mélangé au fichier de la charte parente selon les règles décrites ci-dessous

Pour les thématiques (definitions/theme) :

  • si une balise <theme> avec un identifiant (id) existant dans la charte parente est présente:
    • l'utilisation de l'attribut remove="true" permet de supprimer la thématique
    • les balise <label> et <description> peuvent être remplacer pour surcharger le libellé/description de la thématique
  • si une balise <theme> avec un nouvel identifiant (id), est présente, la thématique est ajoutée

Pour les inputdata (inputdata/themes) :

  • si une balise <themes> avec un identifiant (inputDataId) existant dans la charte parente est présente:
    • l'utilisation de l'attribut remove="true" permet de supprimer l'inputdata
    • tous les attributs (templates, configurable, displayUserLinks) peuvent être surchargés
    • ajouter le support d'une langue et/ou d'une thématique avec un sous noeud <theme>
      <theme id="THEME_ID" lang="en"/>
    • supprimer le support d'une langue et/ou thématique avec l'attribut "remove"
      <theme id="THEME_ID" lang="fr" remove="true"/>

Exemple de surcharge:

<link-themes> 
  <definitions> 
    <!-- Removed theme --> 
    <theme id="SOCIAL_NETWORKS" remove="true"/> 

    <!-- Overriden theme to change label and description --> 
    <theme id="HOME"> 
        <label i18n="false">My own label</label> 
        <description i18n="false">My own description</description> 
    </theme> 

    <!-- Additional theme --> 
    <theme id="MY_THEME"> 
        <label i18n="false">My theme</label> 
        <description i18n="false">My theme</description> 
    </theme> 
  </definitions> 
  <inputdata> 
    <!-- Removed input data --> 
    <themes remove="true" inputDataId="socialNetworks"/> 

    <!-- Overriden input data to add "en" language support --> 
    <themes inputDataId="quickAccess"> 
        <theme id="QUICK_ACCESS" lang="en"/> 
    </themes> 

    <!-- Overriden input data to allow user links and remove language="fr"--> 
    <themes displayUserLinks="true" inputDataId="appsRh"> 
        <theme id="APPS_RH" lang="fr" remove="true"/> 
    </themes> 
  </inputdata> 
</link-themes>

 

Bloquer l'héritage

Pour désactiver l'héritage, utiliser l'attribut inherit="false" sur la balise racine

<?xml version="1.0" encoding="UTF-8"?> 
<link-themes inherit="false">
<!-- Definition of themes and input data -->
</link-themes>

 

Retour en haut

Link directory