1ère étape : choisir ou s'inspirer d'un skin existant
Dans ori-oai-search, plusieurs skins sont proposés par défaut :
- default_skin : skin proposé par défaut
- d'autres à venir ...
Vous avez le choix entre :
- utiliser un des skins proposés par défaut,
- modifier un des skins par défaut,
- créer un skin en partant de zéro, mais le travail sera plus fastidieux !
Un skin personnalisé est représenté par un dossier dans [PATH_CUSTOM_CONFIG]/ori-oai-search/contribs-skin.
Pour définir votre propre skin, il est nécessaire de s'inspirer d'un skin existant ! Pour cela, il faut recopier un skin existant depuis les sources du modules ([ORI_HOME]/src/ori-oai-search-svn/src/main/resources/contribs-skin) vers le dossier de customisation ([PATH_CUSTOM_CONFIG]/ori-oai-search/contribs-skin).
Il en existe plusieurs par défaut (le nom du dossier commence par default). Certains proviennent aussi des membres de la communauté ORI-OAI (le nom commence par contrib).
Nous vous encourageons à contribuer et à nous fournir vos skins. Nous les proposerons alors aux utilisateurs afin de faciliter de travail de configuration. Reportez-vous pour cela à la page suivante de notre site.
2nde étape : adapter le skin
Dans ce chapitre, nous verrons comment paramétrer le skin en fonction des besoins.
Un dossier de skin est composé comme suit:
Dossier "css" : surcharge des CSS
Ce dossier contient toutes les CSS utilisées dans votre skin. Le fichier css/oos-custom.css est obligatoire. C'est dans ce fichier qu'il faut impérativement surcharger toutes les classes CSS définies par défaut. Cette CSS étant appelée en dernier dans l'ordre d'import, toutes les définitions qu'elle contient surchargeront celles par défaut.
Dossier "i18n" : personnalisation des messages et libellés
Tous les libellés propres au skin sont définis dans ce dossier. Il est possible de définir des nouveaux bundles, ou de surcharger également des bundles de message définis par défaut dans ORI-OAI. Pour cela, il faut les définir dans les fichiers custom_skin_XX.properties. Ces messages seront donc prioritaires sur ceux définis par défaut.
Mais pour les surcharger, il est nécessaire de savoir où ils sont stockés par défaut dans l'application :
- [ORI_HOME]/src/ori-oai-search-svn/src/main/resources/properties/i18n/messages_fr.properties et messages_en.properties : libellés génériques, ... ;
- [ORI_HOME]/src/ori-oai-search-svn/src/main/resources/properties/i18n/errors_fr.properties et errors_en.properties : messages d'erreur ;
- [ORI_HOME]/src/ori-oai-search-svn/src/main/resources/properties/i18n/results_fr.properties et results_en.properties : messages servant pour les résultats ;
- [ORI_HOME]/src/ori-oai-search-svn/src/main/resources/properties/i18n/xsl_fr.properties et xsl_en.properties : libellés utilisés dans les transformations XSL.
Si vous avez besoin de modifier un message, il faut donc copier/coller sa clef depuis le fichier d'origine vers les fichiers custom_skin_XX.properties et modifier le libellé associé au message.
Dossier "js" : surcharge des fichiers javascript
Dossier à utiliser pour surcharger éventuellement des javascripts utilisés par défaut. Pour modifier un des fichiers javascript, il faut copier le fichier d'origine depuis le dossier [ORI_HOME]/src/ori-oai-search-svn/src/main/webapp/js vers le dossier js de la contribution et le modifier ensuite.
Dossier "media" : les images du skin
Ce dossier contient toutes les images utilisées dans le skin.
Dossier "jsp" : surcharge des pages HTML générées
Dans certains cas, il est nécessaire de modifier les JSP utilisées lors de la génération des pages HTML du moteur de recherche. Les JSP par défaut peuvent donc être surchargées en les copiant depuis le dossier [ORI_HOME]/src/ori-oai-search-svn/src/main/webapp/WEB-INF/jsp vers le dossier jsp de votre configuration. Attention l'arborescence des fichiers surchargés doit rester la même entre [ORI_HOME]/src/ori-oai-search-svn/src/main/webapp/WEB-INF/jsp et jsp.
Toutes les interfaces ont été conçues pour pouvoir être au maximum modifiées depuis la CSS. Chacun de ces thèmes contient donc une CSS qui se trouve dans le dossier css du skin utilisé.
Dans le cas où les configurations des CSS ne sont pas suffisantes pour personnaliser les pages, il faudra surcharger les JSP de génération des interfaces qui se trouvent dans le dossier jsp de chaque skin.
Dans le cas où vous souhaitez pousser la modification d'autres JSP il vous suffit de surcharger les JSP d'origine en les écrasant depuis le dossier jsp du skin sélectionné. Dans ces cas là, faites un copier/coller de la JSP en respectant bien la même structure de dossier dans le dossier skin.
Par exemple, pour surcharger le comportement de la JSP generic-results.jsp:
- Copiez le fichier [ORI_HOME]/src/ori-oai-search-svn/src/main/webapp/WEB-INF/jsp/generic-results.jsp vers [PATH_CUSTOM_CONFIG]/ori-oai-search/contribs-skin/votre_skin/jsp/results/generic-results.jsp
- Modifiez ce nouveau fichier qui surchargera le fichier d'origine lors du déploiement
Dossier "xsl": transformation XSL des fiches de métadonnées
Afin de personnaliser vos fichiers XSL servant à l'affichage des notices, ou ajouter de nouveaux formats de métadonnées, il est recommandé de regarder les formats fournis avec l'application.
Il est possible de modifier les XSL fournies en les surchargeant dans ce dossier. Les XSL par défaut sont stockées dans le dossier [ORI_HOME]/src/ori-oai-search-svn/src/main/webapp/WEB-INF/xsl.
Ce dossier se découpe comme suit :
- dc.xsl : XSL servant à afficher une notice au format Dublin Core
- lom.xsl : XSL servant à afficher une notice au format LOM
- tef.xsl : XSL servant à afficher une notice au format TEF
- dcfr.xsl : XSL servant à afficher les publications
- head : dossier contenant les XSL (une par format de métadonnées) servant à générer les en-têtes HTML lors de l'affichage de la notice
- title : dossier contenant les XSL (une par format de métadonnées) servant à générer les titres lors de l'affichage de la notice
- templates : templates XSL génériques appelés dans les différentes XSL
Transformation des fiches dans ORI-OAI-indexing
La "traduction" des fiches en fonction des langues au niveau du module ORI-OAI-indexing nécessite une petite explication. En effet, lors de la transformation des fiches dans les différentes langues au niveau du module ORI-OAI-indexing, la fiche XML est modifiée pour voir apparaître toutes les informations de "traduction" des champs en fonction d'un vocabulaire.
Prenons par exemple la métadonnées lom:general/lom:keyword du format LOM. Nativement, cette métadonnée ressemble à ceci :
<keyword>
<string language="fre">climat</string>
</keyword>
Une fois "transformée", et les liens faits avec le vocabulaire "keywords_fr", cette métadonnée ressemble à ceci :
<keyword>
<string language="fre"
orioai-vocabularyId="keywords_fr"
orioai-termId="climat"
orioai-label="Climat"
orioai-termFullLabel="C&#160;&#160;&#187;&#160;&#160;Climat"
orioai-termFullLabelClean="C; Climat"
>climat</string>
</keyword>
où:
orioai-vocabularyId
l'identifiant du vocabulaire utilisé pour la traduction
orioai-termId
l'identifiant de la catégorie du vocabulaire qui correspond à la valeur retrouvée dans la fiche de métadonnée
orioai-label
le libellé traduit correspondant à la valeur initiale et trouvée dans le vocabulaire en fonction de la langue de l'utilisateur
orioai-termFullLabel
le libellé traduit correspondant au chemin complet vers la valeur trouvée dans le vocabulaire en fonction de la langue de l'utilisateur (encodage HTML)
orioai-termFullLabelClean
le libellé traduit correspondant au chemin complet vers la valeur trouvée dans le vocabulaire en fonction de la langue de l'utilisateur
Rebond vers une recherche thématique
La construction des liens vers des recherches thématiques nécessite aussi une petite explication. En effet, une fois la transformation des fiches faites dans les différentes langues au niveau du module ORI-OAI-indexing, il est possible de définir des rebonds vers une recherche thématique à partir de la valeur retrouvée dans un vocabulaire. Une fois le rebond calculé, la fiche XML est modifiée pour voir apparaître tous les paramètres nécessaires à la construction du lien.
Pour définir ces rebonds, il faut par exemple créer le bloc suivant dans le fichier config.xml :
<metadata>
//lom:general/lom:keyword/lom:string
<thematic_link key="lom_keywords" thematicMenuKey="lom" thematicSearchKey="keywords" showAbsoluteLink="false"/>
</metadata>
Dans ce cas, un lien sera fait vers la recherche thématique du menu lom et sous-menu keywords (uniquement dans le cas où la transformation de la fiche et le menu lom/*keywords s'appuient sur le même vocabulaire !
Dans notre exemple précédent, le XML avant transformation XSLT deviendrait alors:
<keyword>
<string language="fre"
orioai-vocabularyId="keywords_fr"
orioai-termId="climat"
orioai-label="Climat"
orioai-termFullLabel="C&#160;&#160;&#187;&#160;&#160;Climat"
orioai-termFullLabelClean="C; Climat"
orioai-link-key="lom_keywords"
orioai-menuKey="lom"
orioai-submenuKey="keywords"
>climat</string>
</keyword>
où:
orioai-link-key
la clef définie dans la configuration de la métadonnée dans le format
orioai-menuKey
valeur de thematicMenuKey de la configuration
orioai-submenuKey
valeur de thematicSearchKey
Enfin, l'utilisation du template
<xsl:call-template name="print_template">
dans la XSL automatise la génération du lien.
Un exemple de lien généré est alors le suivant:
<a href="http://[HOST_SEARCH]:[PORT_SEARCH]/[CONTEXT_SEARCH]/thematic-search.html?menuKey={@orioai-menuKey}&submenuKey={@orioai-submenuKey}&id={@orioai-id}"><xsl:value-of select="@orioai-label"/></a>
Définitions de nouveaux libellés à appeler dans la XSL
Dans le cas où il est nécessaire de définir de nouveaux messages, la première étape est de créer les messages dans le dossier i18n. Au sein des fichiers custom_fr.properties et custom_en.properties, ajouter par exemple la clef suivante :
xsl.ma_clef_de_message=Mon nouveau message
Ensuite, il est nécessaire de faire transiter ce message jusqu'à la XSL. Pour cela, il faudra surcharger le fichier notice-content-i18n-custom.jsp depuis [ORI_HOME]/src/ori-oai-search-svn/src/main/webapp/WEB-INF/jsp/notice vers le dossier jsp de la contribution.
Dans ce fichier, il faut alors définir le passage de paramètres au transformateur XSLT :
<x:param name="xsl.ma_clef_de_message"><fmt:message key="xsl.ma_clef_de_message"/></x:param>
Enfin, dans la XSL concernée, il faut définir ce message comme un paramètre d'entrée :
<xsl:param name="xsl.ma_clef_de_message"/>