Setup and integration manual

  1. Definition of themes in the graphic charter
  2. InputData
    1. Activation for versions 2.13 and higher
    2. Versions below 2.13
  3. Data XML
  4. Example of use in the graphic charter
    1. Display dynamic information on thumbnails
  5. Colors
  6. Charter heritage

Definition of themes in the graphic charter

From version 2.13

From version 2.13 onwards, it is possible to define link themes specific to the graphic charter.

The themes are defined in the skins/[NOM_SKIN]/conf/link-directory.xml in the <definitions> as in the example below:

<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

The plugin link directory provides input data, enabling links for one or more themes to be inserted on all or part of the site's pages.

Activation for versions 2.13 and higher

Inputdata is activated in the graphic design, in the skins/[NOM_SKIN]/conf/link-directory.xml in the <inputdata> as in the example below:

<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>
  • The templates attribute contains the template(s) affected by this input data, separated by commas (* means all themes).
  • The configurable attribute determines whether link customization by a logged-in user is allowed (true or false).
  • The displayUserLinks attribute determines whether custom links can be added
  • The inputDataId attribute determines the identifier of the InputData to differentiate between links originating from multiple InputData responding to a single template. By default, the identifier is the empty string. Only available in version 2.12 and later.
  • Beacons <theme> allows you to choose which theme links will be displayed.
    • The id attribute corresponds to the theme identifier
    • The lang attribute determines the language of links selected for the given theme (optional).

The example above activates input data:

  • for the "index" template, input data will contain "OUTILS" links for FR links and "TOOLS" links for EN links
  • for "page" and "section" templates, the input data will contain links with the "FOOTER" theme. This theme is provided by the graphic charter.

Versions below 2.13

For versions below 2.13, to activate this input data and define its content, you must create a file in your graphic charter XML skins/[NOM_SKIN]/conf/link-themes.xml, which contains the link themes to be displayed for each template:

<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>     
  • The templates attribute contains the template(s) affected by this input data, separated by commas (* means all themes).
  • The configurable attribute determines whether link customization by a logged-in user is allowed (true or false).
  • The displayUserLinks attribute determines whether custom links can be added
  • The inputDataId attribute determines the identifier of the InputData to differentiate between links originating from multiple InputData responding to a single template. By default, the identifier is the empty string. Only available in version 2.12 and later.
  • Beacons <theme> allows you to choose which links (of which theme) will be displayed.
    • The id attribute corresponds to the identifier given to the theme in the CMS
    • The lang attribute determines the language of selected links

Data XML

The input data format is as follows:

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

Example of use in the graphic charter

The plugin link directory provides XSLT helpers that can be used in the graphic charter. All you need to do is import the file pages/services/directory/utils/inputdata_utils.xsl of plugin is to call the templates at the desired location:

Template name

Function

Parameters

display-configure-links-btn-inputdata

Inserts a "Customize" link to configure the order in which links are displayed.
The link is present only if links are configurable.
Provides a javascript dialog box in which the user can select
the links he wishes to see first.
  • maxCheckedLinks: Maximum number of links selectable by user

links-thumbnails-input-data

Displays input data links as thumbnails

  • moreThreshold: Maximum number of visible links by default

  • height: maximum thumbnail width
  • width: maximum thumbnail width

 

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

Going further
You can fully customize the display of links by overloading the templates XSLT provided by plugin.
Have a look at the XSL files in the https://svn directory .ametys.org/trunk/plugins /link-directory/tags/1 .1.0/main/plugin -link-directory/pages/services/directory/utils/ and overload the template(s) you need.
For example, if you want to replace the "Customize" link with an image, you'll need to overload the "configure-links-btn" template.

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

Display dynamic information on thumbnails

If your links/applications contain dynamic information that can be displayed as a tooltip, import the file pages/services/directory/utils/thumbnail_utils into your graphic charter.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>    

Colors

Since version 2.6.0, links can be color-coded.

To override the default list of available colors, create a file at WEB-INF/param/linkdirectory-colors.xml containing :

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

Charter heritage

From Ametys 4.5

Missing file

As the generic inheritance rule indicates, if the file is absent, the file from the parent charter is used.

Heritage

If the file is present, it will be mixed with the parent chart file according to the rules described below.

For definitions/themes :

  • si une balise <theme> with an existing id in the parent charter is present:
    • use the remove="true" attribute to remove the theme
    • 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

For inputdata (inputdata/themes) :

  • si une balise <themes> with an existing identifier (inputDataId) in the parent charter is present:
    • using the remove="true" attribute deletes the inputdata
    • all attributes (templates, configurable, displayUserLinks) can be overloaded
    • 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"/>

Example of overloading:

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

Blocking inheritance

To disable inheritance, use the inherit="false" attribute on the root tag

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

Back to top

Link directory