Structure des fichiers de configuration

Avant de débuter la configuration avancée du module ori-oai-search, il est important de comprendre la structure. La configuration générale du projet se fait dans le dossier conf. Ce dossier est découpé comme suit :

...

• Le fichier services.properties permet de définir les paramètres de connexion aux autres modules ORI-OAI
• Le fichier log4j.properties permet de configurer l'emplacement et le niveau de logs
• Le fichier ehcache.xml définit les propriétés de gestion des différents caches dans le module
• Le dossier i18n contient les bundles de messages génériques dans toutes les langues gérées par l'application
• Le fichier vues.properties est lié au développement et n'est pas à modifier

Paramétrage avancé de l'application

Configurer les logs

La configuration de l'emplacement et du niveau des logs se fait dans le fichier conf/properties/log4j.properties. Les paramètres à adapter sont dans la rubrique logs ori-oai-search. Vous pouvez trouver plus de documentation en ligne sur la syntaxe log4j à cette adresse: http://logging.apache.org/log4j/docs/manual.html.

Niveau de logs

Dans la rubrique level, vous pouvez changer le niveau d'affichage des logs: INFO, DEBUG, ERROR, etc. Il est préconisé d'utiliser le mode INFO en production et DEBUG lors des phases de test et de débogage.

Console ou fichier

Dans la rubrique console or file vous pouvez choisir que les messages de logs s'affichent dans la console de Tomcat ou dans un fichier de logs.

...

Pour afficher dans un fichier, vous commentez la ligne sous la rubrique console. Ensuite, vous spécifiez le nom et chemin du fichier dans le paramètre log4j.appender.orioaisearch.File, la taille maximale du fichier dans log4j.appender.orioaisearch.MaxFileSize et le nombre maximal de backups de fichiers de logs dans log4j.appender.orioaisearch.MaxBackupIndex.

Pattern

Vous pouvez si vous le désirez changer le pattern d'affichage des logs par le paramètre log4j.appender.orioaisearch.layout.ConversionPattern dans la rubrique pattern en vous reportant à la syntaxe log4j.

Gestion des vocabulaires du démarrage de l'application

Le module ori-oai-search est pré-configuré pour pré-charger tous les vocabulaires dont on aura besoin dans l'application dès le démarrage du Tomcat. Ceci peut être modifié dans les configurations avancées. Pour cela, il faut se reporter au fichier webapp/WEB-INF/applicationContext-common.xml. Vous y verrez la définition suivante :

...

Aussi, le chargement efface par défaut tous les vocabulaires, même si ceux-ci sont toujours valides au moment du démarrage. Vous pouvez changer ceci en remplaçant la valeur de l'attribut clearCache par false.

Personnalisation des interfaces de recherche et de résultat de l'application

Dans ce chapitre, nous verrons comment paramétrer l'application en fonction des besoins. Toutes les configurations proposées par défaut se trouvent dans le dossier conf/search.

Structure d'une configuration personnalisée

Une configuration personnalisée est représentée par un dossier dans conf/search. Il en existe plusieurs par défaut (le nom du dossier commence par default). Certaines proviennent aussi des membres de la communauté ORI-OAI (le nom commence par contrib).
Nous vous encourageons à contribuer et à nous fournir vos configurations. Nous les proposerons alors aux utilisateurs afin de faciliter de travail de configuration. Reportez-vous pour cela à la page suivante de notre site.

...

Passons en détail toutes les configurations :

Fichier config.xml : paramètres généraux

Quelques paramètres généraux

Voici quelques paramètres globaux à l'application:
default_docs_per_page

...

Configurer les interfaces de recherche

Toutes les interfaces de recherche sont configurées dans la balise menu. Cette balise est composée de champs search_menu comme suit:

...

<menu>

	<search_menu key="menu_1">
		<date_search/>
		<thematic_search/>
		<advanced_search/>
		<authorization/>
	</search_menu>

	<search_menu key="menu_2">
		<date_search/>
		<thematic_search/>
		<advanced_search/>
		<authorization/>
	</search_menu>

</menu>

Définition des paramètres de recherche par défaut

Depuis la version 1.5 de ORI-OAI-search, il est possible de limiter la taille du fichier config.xml en définissant des paramètres de résultats utilisables dans tous les menus de recherche. Ceux-ci touchent les balises: <result_fields> (Voir la Section "Champs de résultats à afficher" pour configurer cette partie), <sort_fields> (Voir la Section "Tri des résultats" pour configurer cette partie) et <rss_fields> (Voir la Section "Paramétrage des flux RSS" pour configurer cette partie).

...

Les définitions <result_fields>, <sort_fields> et <rss_fields> pourront donc simplement être appelées via leur identifiant id dans les différentes définitions de recherche.

Recherche par date

Ce type de recherche permet de faire de la recherche de documents uniquement en fonction de la durée entre la date courante et un champ date spécifié dans la fiche de métadonnées ou le datestamp OAI. Cette recherche se configure comme ceci:

...

Permet de configurer les autorisations d'accès en mode portlet. Voir la Section "Autorisation d'accès" pour configurer cette partie.

Recherche thématique

Ce type de recherche permet de naviguer dans différentes catégories provenant de vocabulaires du module ORI-OAI-vocabulary (thématiques de documents, auteurs, mots-clefs, etc.). Cette recherche se configure comme ceci:

...

Permet de configurer les autorisations d'accès en mode portlet. Voir la Section "Autorisation d'accès" pour configurer cette partie.

Recherche avancée

Ce type de recherche permet de rechercher des documents depuis un formulaire de recherche simple ou avancée:

...

Permet de configurer les autorisations d'accès en mode portlet. Voir la Section "Autorisation d'accès" pour configurer cette partie.

Configurer un formulaire de recherche avancée

Un formulaire de recherche avancée se configure comme dans l'exemple ci-dessous (eette recherche se configure dans le dossier advanced) :

...

La configuration détaillée de ce fichier est la suivante:

group

Les formulaires de recherche avancée sont découpées en différents groupes de champs de recherche. Ces groupes sont identifiés par la balise group et les champs par les balises fields ou field. Dans l'interface, les groupes seront séparés les uns des autres, cela permet de ranger les champs de recherche dans différentes catégories.
id

Chaque groupe doit avoir ici un identifiant unique. N'utilisez pas de caractères spéciaux.

...

fields

Un fields correspond à un groupement de champs de recherche du formulaire. Ceci représente une interface de recherche experte dans laquelle on pourra croiser des recherches à partir des booléens ET, OU et SAUF. Une balise field contient plusieurs sous-balises field. Les attributs suivants sont à configurer :
id

...

Ce champ permet de spécifier le nombre de croisements que l'on peut faire dans les interfaces. Ceci affichera un certain nombre de fois (valeur fixe) la répétition des champs.

field

Un field correspond à un champ de recherche du formulaire. Chaque champ a plusieurs possibilités de configurations suivants les attributs suivants:
id

...

Ce paramètre prend la valeur true ou false et permet de dire si on souhaite afficher le sélecteur lorsque le champ est de type date. La valeur est true par défaut.

metadata

Chaque field doit contenir une ou plusieurs balise metadata. Chaque metadata permet de définir une métadonnée sur laquelle on va faire la recherche. On peut spécifier plusieurs métadonnées, dans ce cas, on lancera la recherche sur chacune de ces métadonnées.
dateFormat

Avec ce paramètre, on permet de dissocier le format de saisie dans le formulaire du format de date dans la requête. Ce paramètre n'est à utiliser que si l'on a spécifier qu'on est sur un champ de type date. On pourra alors spécifier que l'on saisit une date comme 22-06-2005 mais qu'elle est transformée en 20050622 pour la requête en mettant pour valeur dateFormat="yyyyMMdd".

hidden_voc_id

Chaque field peut contenir une ou plusieurs balise hidden_voc_id lorsque l'on est sur un champ de saisie basé sur un vocabulaire donné. Chaque hidden_voc_id permet de définir l'identifiant d'une entrée du vocabulaire sur laquelle on ne souhaite pas faire de recherche. Ainsi, l'entrée du vocabulaire ne sera pas proposée lors de la saisie dans l'interface de recherche.
dateFormat

Avec ce paramètre, on permet de dissocier le format de saisie dans le formulaire du format de date dans la requête. Ce paramètre n'est à utiliser que si l'on a spécifier qu'on est sur un champ de type date. On pourra alors spécifier que l'on saisit une date comme 22-06-2005 mais qu'elle est transformée en 20050622 pour la requête en mettant pour valeur dateFormat="yyyyMMdd".

condition

Chaque group ou field peut contenir une ou plusieurs balise condition. Cette balise permet de mettre une condition sur l'affichage de certains champs. On souhaitera par exemple n'afficher que les champs spécifiques au format LOM/LOMFR/SupLOMFR qu'à la condition d'avoir coché la case "Ressource pédagogique".
Cette fonctionnalité est extensible à tous les champs et à toutes les valeurs. Dès que l'utilisateur respecte la condition, les champs s'affichent ou disparaissent.
fieldId

...

Ce champ peut prendre 2 valeurs: show ou hide suivant que l'on veuille montrer ou masquer le field ou le group quand la condition est respectée.

authorization

Dans les balises group et field, il est possible d'utiliser la balise authorization (cf. Section "Autorisation d'accès") afin de filtrer l'accès au groupe ou au champ de recherche. Exemple:

<form>

	<group id="group_id1">
		<field id="field_id1" format="text" defaultValue="value_1" readOnly="true" hidden="false">
			<metadata>...</metadata>
			<metadata>...</metadata>
		</field>
		<field id="field_id2" format="text" vocabularyId="vocabulary_1">
			<metadata>...</metadata>
			<authorization>
				...
			</authorization>
		</field>
	</group>

	<group id="group_id2">
		...
		<authorization>
			...
		</authorization>
	</group>

</form>

Champs de recherche cachés

Il est possible d'ajouter des valeurs cachées aux formulaires de recherche par date, thématique ou avancée. Ceci ajoutera des paramètres à la requête qui est envoyée au module ORI-OAI-indexing. La syntaxe est la suivante:

...

<hidden_field>
	<metadata>//lom:lifeCycle/lom:contribute[lom:role/lom:value='author']/lom:entity(name)</metadata>
	<value>{displayName}</value>
</hidden_field>

Champs de résultats à afficher

Dans cette partie, on indique les champs de résultats que l'on veut afficher. On va donc passer par une balise result_fields composée de plusieurs champs result_field, chaque result_field étant un champ de résultat. Voici un exemple:

...

Lorsque l'on utilise un format vocabulaire qui fournit des vcards, il est nécessaire d'indiquer quel attribut on veut récupérer dans la vcard à afficher. C'est dans ce paramètre qu'on l'indique. Exemple, on mettra vcard_att="FN" si on veut récupérer le champ FN de la vcard.

Tri des résultats

Dans la configuration, vous pouvez spécifier dans quel ordre seront triés les resultats de la recherche. Si vous ne le faîtes pas, les documents seront triés par rapport au score géré par le module ORI-OAI-indexing.

...

Notons que tous les champs mentionnés dans la balise sort_fields pourront être re-triés différemment par l'utilisateur. En effet, celui-ci aura la possibilité de cliquer sur le nom du champ pour trier suivant un autre champ ou dans l'ordre inversé.

Paramétrage du flux RSS

En mode servlet, il existe la possibilité de générer des flux RSS dynamiques sur toutes les requêtes formulées par l'utilisateur. Pour cela, une icône est disponible sur chaque page de résultat ainsi que dans la barre d'adresse de certains navigateurs. La configuration se fait dans les blocs de chaque menu de recherche:

...

Ce champ permet de dire quelle métadonnée va servir à remplir la date de publication du flux dans les tags RSS. La valeur ici correspond à la valeur de l'attribut key du result_field désiré.

Autorisation d'accès

En mode portlet, il est possible de spécifier quels utilisateurs pourront visualiser une partie de l'interface de recherche. Ce filtrage est basé sur les attributs de l'utilisateur. Ce filtrage se base sur la syntaxe suivante. Dans ce cas, seuls les utilisateurs ayant pour uid ycolmant ou bourges auront accès et verront l'interface visée.

...

Cette balise permet de spécifier une partie du filtre sur un attribut. L'utilisateur répond bien à ce filtre si son attribut contenu dans attribute a bien la valeur contenue dans value. Si l'opérateur or est utilisé, il faut que l'utilisateur réponde au minimum à un allowed, si c'est un and, il faut qu'il réponse à tous les allowed.
Il est possible de faire ce filtrage sur un nom de groupe du portail. En effet, en utilisant pour attribut la valeur attribute="portal_group", le filtrage sera fait sur le groupe de l'utilisateur. Par exemple, <allowed attribute="portal_group" value="pags.mon_groupe"/> fera un fitrage pour tous les utilisateurs qui font partie du groupe pags.mon_groupe.

Lien vers les documents dans la liste des résultats de recherche

Les différents formats de métadonnées sont identifiés par le namespace XML du document. Pour chaque format, donc pour chaque namespace, il est nécessaire d'indiquer quelle est la métadonnée qui contient les URL des documents référencés par la fiche de métadonnées. C'est le but de la balise href_formats. Celle-ci est composée de plusieurs sous-balises format pour chaque format de métadonnée. Voici un exemple où on définit les métadonnées pour le LOM et le Dublin Core:

...

Chaque balise metadata contient elle la métadonnée où se trouve le lien du document.

Les modes de recherche simple

En plus des interfaces de recherche décrites ci-dessus, il existe différentes possibilités d'effectuer des "recherches simples".

Champ de recherche simple accessible sur toutes les pages

Il est prévu dans l'interface de pouvoir lancer facilement une recherche depuis un champ accessible sur toutes les pages de l'interface. On appele ce mode recherche simple. Son fonctionnement est simple: ce champ n'est en réalité qu'un pointeur vers un champ de recherche d'un formulaire avancé configuré au préalable. En lançant une recherche depuis ce formulaire, vous lancez concrêtement une recherche depuis le champ de saisie pointé.

...

<form name="simple_search_form" method="get" action="http://[HOST_SEARCH]:[PORT_SEARCH]/[CONTEXT_SEARCH]/simple-search.html">
	Recherche simple:<br/>
	<input type="hidden" name="menuKey" value="menu_test"/>
	<input type="hidden" name="submenuKey" value="advanced_test"/>
	<input type="hidden" name="fieldId" value="field_test"/>
	<input class="input-text" name="light-request" size="20" type="text"/>
	<input class="searchButton" value="OK" type="submit"/>
</form>

Recherche des nouveautés accessible sur toutes les pages

Tout comme le champ de recherche simple, il est possible d'avoir un lien sur toutes les pages vers la recherche de nouveautés. Ce lien n'est en fait qu'un pointeur vers le formulaire de recherche par date que vous aurez désigné.

...

Cette variable doit donc contenir la clef du sous-menu de recherche par date souhaité.

Plugin OpenSearch pour Firefox (à partir de la version 2) et Internet Explorer (à partir de la version 7)

OpenSearch est une collection de technologies permettant à des sites webs et des moteurs de recherche de publier des résultats de recherche dans un format standardisé (http://www.opensearch.org). Il permet l'intégration de plugins de recherche dans différents navigateurs comme Firefox 2 et Internet Explorer 7 à la manière des plugins Google.

...

Un lien vers le site institutionnel de votre établissement ou tout pointeur que vous voulez voir apparaître depuis Firefox 2.

Les formats de métadonnées supportés

Dans cette section, nous allons voir comment définir tous les formats de métadonnées supportés dans l'application en vue d'afficher la fiche de métadonnées.

...

Le principe est de définir une balise format par format à supporter. Pour chacune de ces balises, on créé des sous-balises metadata pour chaque métadonnée que l'on veut transformer avant son affichage. Typiquement si l'on veut traduire un terme de la fiche ou modifier un format de date. C'est ici un principe semblable au formats que l'on définit dans les champs de résultats result_field.

Configuration des formats

Les attributs de la balise format sont les suivants:

...

Exemple de la relation haspart du LOM:

Code Block
xml xml
<metadata> //lom:relation[lom:kind/lom:value='haspart'] <notice_link key="lom_haspart" labelXpath="lom:resource/lom:description/lom:string[starts-with(@language,'fr')]" targetXpath="lom:resource/lom:identifier/lom:entry" xpathInTarget="//lom:general/lom:identifier/lom:entry"/> </metadata>

Dossier i18n : Personnalisation des messages et libellés

Tous les messages et libellés de la configuration de recherche personnalisée sont stockés dans des bundles i18n dans le dossier i18n. Il y a 3 différents fichiers: menus_XX.properties, forms_XX.properties et custom_XX.properties où XX représentent les codes de langues. Les différents fichiers doivent donc être disponibles pour chaque langue que l'on souhaite gérer dans l'application.

Tous les fichiers sont décrits en français et en anglais dans cette distribution. Voyons en détail comment sont construits ces fichiers.

menus_XX.properties

Ce fichier contient les libellés liés aux différents menus de recherche. Vous pouvez les adapter ou l'agrémenter si vous ajouter de nouvelles interfaces de recherche.

...

menu.result.menuKey.submenuKey.resultFieldKey=Libellé du champ

forms_XX.properties

Ce fichier permet de configurer tous les messages liés aux formulaires de recherche avancée.

...

menu.form.label.menuKey.submenuKey.fieldId=Libellé du champ de recherche
menu.form.comment.menuKey.submenuKey.fieldId=Commentaire, aide sur le champ de recherche

custom_XX.properties

Contient tous les messages que vous souhaitez surcharger par rapport aux messages par défaut. En effet, tous les messages génériques de l'application sont stockés dans les fichiers du dossier conf/properties/i18n.
Si vous souhaitez modifier un ou plusieurs de ces libellés, vous n'avez qu'à reprendre ces clefs de messages dans custom_XX.properties et modifier le libellé.
Ces nouveaux messages sont donc utilisés à la place des messages par défaut.

Dossier stylesheets : 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 webapps/WEB-INF/stylesheets vers le dossier stylesheets de votre configuration. Attention l'arborescence des fichiers surchargés doit rester la même entre webapps/WEB-INF/stylesheets et stylesheets.

Dossier xsl: transformation XSL des fiches de métadonnées

Afin de personnaliser vos fichiers XSL de transformation ou ajouter de nouveaux formats, il est recommandé de regarder les formats fournits avec l'application.

...

<a href="http://[HOST_SEARCH]:[PORT_SEARCH]/[CONTEXT_SEARCH]/thematic-search.html?menuKey={@ori-menuKey}&amp;submenuKey={@ori-submenuKey}&amp;id={@ori-id}"><xsl:value-of select="@ori-label"/></a>

Personnalisation des interfaces graphiques

Un skin personnalisé est représenté par un dossier dans conf/skins. 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.

...