...

...

...

Avant de procéder à la configuration avancée, il est conseillé de consulter le document "Navigation dans les fichiers" pour mieux comprendre la structure des différents fichiers.

...

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 dossier properties qui contient tous les fichiers de configuration généraux à l'application
• le dossier search contient toutes les configurations proposées par ORI-OAI et la communauté
• le dossier skins contient tous les skins proposés par défaut

Les dossiers search et skins sont là pour vous permettre de personnaliser votre application en terme d'écran de recherche et de résultat et au niveau du look.
Toutes les personnalisations que vous souhaitez apporter doivent se retrouver concentrées uniquement dans ces dossiers. Vous ne devez en aucun cas modifier les fichiers (JSP, XSL, CSS, etc.) du dossier webapp de l'application.
Toutes vos spécificités doivent être surchargées dans search et/ou skins suivant le besoin.

Le dossier conf/properties contenant les fichiers de paramètres principaux est composé comme ceci:

• 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 la console, vous devez commenter (en faisant commencer la ligne par un #) chaque ligne sous la rubrique file.

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 :

...

<bean id="initVocabulariesCache" class="org.orioai.search.vocabulary.init.CreateVocabularyCache" init-method="initCaches">
	<property name="init">
		<value>[SEARCH_INIT_VOCABULARY_CACHE]</value>
	</property>
	<property name="vocabularyService">
		<ref local="vocabulary-service"/>
	</property>
	<property name="oriOaiVocabularyService">
		<ref local="ori-oai-vocabulary-service"/>
	</property>
	<property name="configurationService">
		<ref local="configuration-service"/>
	</property>
	<property name="advancedService">
		<ref local="advanced-service"/>
	</property>
	<property name="categoryVocabularyCache">
		<ref local="categoryVocabularyCache"/>
	</property>
	<property name="xmlVocabularyCache">
		<ref local="xmlVocabularyCache"/>
	</property>
	<property name="clearCache">
		<value>true</value>
	</property>
</bean>

Ceci peut s'avérer problématique si vous déployez le module ori-oai-search et ori-oai-vocabulary sur le même Tomcat ou si vous êtes en phase de configuration avancée et que vous devez souvent redémarrer votre serveur. Vous pouvez donc désactiver ce chargement.
Pour cela, remplacez la chaîne [SEARCH_INIT_VOCABULARY_CACHE] par false:

...

<bean id="initVocabulariesCache" class="org.orioai.search.vocabulary.init.CreateVocabularyCache" init-method="initCaches">
	<property name="init">
		<value>false</value>
	</property>
	...
</bean>

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.

Vous avez le choix entre :

• utiliser une des configurations proposées par défaut
• modifier une des configurations par défaut. Dans ce cas, nous vous conseillons de copier la configuration d'origine en la renommant avec un nom spécifique à votre établissement. Ensuite, nous vous conseillons de proposer cette configuration à la communauté
• créer une configuration en partant de zéro, mais le travail sera plus fastidieux

Un dossier de configuration est composé comme suit:

• Fichier config.xml : Ce fichier correspond à la configuration des interfaces de recherche et de résultat.
• Dossier advanced : Dans le cas de l'utilisation de recherche avancée, il existe un fichier de configuration par recherche avancée. Ces fichiers doivent se trouvent dans le dossier advanced.
• Dossier i18n : Tous les libellés propres à la configuration personnalisée sont définis dans ce dossier. Il est possible 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_XX.properties. Ces messages seront donc prioritaires sur ceux définis par défaut.
• Dossier ori-oai-vocabulary : Votre configuration de recherche peut nécessiter l'utilisation de vocabulaires spécifiques. Dans ce cas, nous conseillons de stocker dans ce dossier les vocabulaires statiques et les configurations de vocabulaires dynamiques nécessaires au bon fonctionnement du moteur de recherche. Ainsi, les établissements utilisant votre configuration pourront déployer MANUELLEMENT ces vocabulaires dans leur instance local. Aucun fichier contenu dans le dossier ori-oai-vocabulary n'est déployé ou utilisé en l'état. Ce dossier sert uniquement au bon échange des contributions dans la communauté.
• Dossier ori-oai-indexing : Votre configuration de recherche peut nécessiter une configuration spécifique du module ori-oai-indexing (configIndexing.xml, liusConfig.xml). Ainsi, les établissements utilisant votre configuration pourront déployer MANUELLEMENT ces fichiers de configuration dans leur instance local. Aucun fichier contenu dans le dossier ori-oai-indexing n'est déployé ou utilisé en l'état. Ce dossier sert uniquement au bon échange des contributions dans la communauté.
• Dossier stylesheets : 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 : Tout comme il est possible d'ajouter ou de surcharger certaines JSP, il est possible de le faire avec les XSL utilisées lors de l'affichage d'une fiche de métadonnées.
• Dossier opensearch : En mode servlet, il est possible de définir des configurations pour le plugin opensearch. Tout se fait dans ce dossier.

Dans ori-oai-search, plusieurs organisations des interfaces de recherche/résultats sont proposés par défaut :

• default_exemple-complet : Configuration d'exemple uniquement qui montre toutes les possibilités de paramétrage des interfaces du module. Il propose de la recherche sur les formats Dublin Core, LOM, TEF et CDM indépendamment. Il propose aussi à titre d'exemple un recherche multi-format pour une recherche croisée sur les différents types de métadonnées.
• default_etab-pedago : Configuration proposée par défaut aux établissements qui souhaitent gérer leurs ressources pédagogiques. Cette configuration peut servir de base et être adaptée.
• default_unt : Configuration proposée aux UNT et UNR pour la mise en place d'un portail de moissonnage OAI de ressources pédagogiques et documentaires.
• default_theses : Configuration proposée aux établissements pour la recherche de thèses en utilisant le format de métadonnées TEF.
• default_unr-formations : Configuration proposée à une UNR (par exemple) qui souhaite mettre en place un catalogue de formations au format CDM.

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

Ce paramètre est un entier qui indique le nombre de documents par défaut affichés par page lorsqu'un utilisateur lance une recherche.

...

Lorsqu'une page de résultats est affichée à l'utilisateur, il a la possibilités de changer le nombre de documents sur une page. Ce paramètre est donc un entier qui donne la limite que l'utilisateur peut sélectionner. Si le paramètre vaut par exemple 30, l'utilisateur aura la possibilité de choisir un nombre de documents entre 5 et 30 avec un intervalle de 5 entre chaque valeur: 5, 10, 15, 20, 25 et 30.

...

Ce paramètre vaut true ou false et indique si une page d'accueil est disponible dans le menu de l'application. Si c'est le cas, cette page doit être éditée dans le fichier webapp/WEB-INF/stylesheets/index/index_XX.jsp où XX correspond au code de la langue courante dans l'application. Autrement dit, vous devez éditer une page par langue disponible dans l'application.

...

Il est possible de configurer la page affichée par défaut dans l'application. Cela peut être la page d'accueil ou un menu de recherche:

• <defaut_page index="true"/> si vous voulez que la page par défaut soir l'index (à condition que index_available soit placé à true)
• <defaut_page index="false" menu_key="mon_menu" search_key="mon_sous_menu"/> où mon_menu correspond à la clef d'un menu de recherche search_menu et mon_sous_menu est la clef d'un formulaire de recherche date_search, thematic_search ou advanced_search comme il sera vu dans la Section "Configurer les interfaces de recherche".

...

Dans une recherche avancée, les champs de recherche sont placés les uns à la suite des autres. Ce paramètre est donc un entier qui indique le nombre de champs de saisie à partir duquel on affiche les champs sur 2 colonnes. Par exemple, si le paramètre vaut 10 mais qu'il n'y a que 6 champs à afficher, ils seront sur une colonne. Si on passe alors ce paramètre à 4, comme 10 > 4, on affiche sur 2 colonnes: 5 et 5.

...

Ce paramètre a le même principe que le précédent, mais correspond à l'affichage des catégories dans la recherche thématique.

...

Il est possible de configurer plusieurs langues dans l'application. Des liens avec un drapeau pour chaque langue est affiché dans l'interface et on peut basculer l'application d'une langue à une autre en prenant garde que les bundles de messages aient été renseignés dans toutes les langues comme vu à la Section "Personnalisation des messages et libellés". Dans l'exemple suivant, on rend l'application disponible en anglais, français et espagnol où le français est la langue par défaut:

...

<locales default="fr">
	<locale>en</locale>
	<locale>fr</locale>
	<locale>es</locale>
</locales>

Si vous ne voulez par exemple ne gérer que la langue française, utilisez cette configuration:

...

<locales default="fr">
	<locale>fr</locale>
</locales>

ajax

Il est possible d'utiliser AJAX dans certaines interfaces du module de recherche:

• advanced qui vaut true ou false si vous souhaitez utiliser ou non la possibilité d'ouvrir une fenêtre superposée lors de la modification d'une recherche avancée.
• notice qui vaut true ou false si vous souhaitez utiliser ou non la possibilité d'ouvrir une fenêtre superposée lors de l'affichage d'une notice depuis la liste des résultats.

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">
		...
	</search_menu>

	<search_menu key="menu_2">
		...
	</search_menu>

	<search_menu key="menu_3">
		...
	</search_menu>

</menu>

Chaque search_menu est donc un menu de recherche accessible depuis le menu de l'application. Chaque menu est alors découpé en différentes interfaces de recherche que l'on peut considérer comme des sous-menus. Ces sous-menus sont des recherches par date, thématiques et avancées identifiés par les balises date_search (Section "Recherche par date"), thematic_search (Section "Recherche thématique") et advanced_search (Section "Recherche avancée").

Un menu est donc composé par plusieurs sous-menus et par des balises authorization (Section "Autorisation d'accès") qui permettent de spécfier quel type d'utilisateur peut accéder à ce menu en mode portlet.

Notons que chaque menu doit avoir une clef unique pour le champ key.

Voici une illustration des possibilités de configuration:

...

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

Ceci se configure en amont de la balise <menu> dans une balise <default_results>:

...

<default_results>

	<!-- ======== result fields ======== -->
	<result_fields id="lom_dc_no_fulltext" ....>
		....
	</result_fields>

	<result_fields id="lom_no_fulltext" ....>
		....
	</result_fields>

	<!-- ======== sort fields ======== -->
	<sort_fields id="date_editor" ....>
		....
	</sort_fields>

	<sort_fields id="score_date" ....>
		...
	</sort_fields>

	<!-- ======== rss fields ======== -->
	<rss_fields id="default" ....>
		....
	</rss_fields>

</default_results>

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:

...

<date_search key="date_test" hide="false" start_days_period="30" max_days_period="365" days_interval="30">

	<metadatas>
		<metadata dateFormat="yyyyMMdd">md-ori-oai-datestamp</metadata>
	</metadatas>

	<hidden_fields>
		...
	</hidden_fields>
	<result_fields>
		...
	</result_fields>
	<sort_fields>
		...
	</sort_fields>
	<rss_fields>
		...
	</rss_fields>
	<authorization>
		...
	</authorization>

</date_search>

key

Contient la clef unique de ce sous-menu de recherche.

...

Vaut true ou false suivant que l'on veuille cacher ou non ce sous-menu de recherche. Cacher un sous-menu peut être utile lorsque l'on y accède en tant que client et que l'on ne veut pas le voir dans le menu de l'interface.

...

La recherche se faisant en sélectionnant une durée de jours d'ancienneté dans une liste déroulante, cette valeur est un entier qui contient la première durée affichée par défaut. Si on configure 30, on aura par défaut en se présentant sur cette recherche tous les documents dont la date est inférieure à 30 jours.

...

Ceci est un entier qui indique la dernière valeur possible dans la liste déroulante des périodes;

...

Cet entier est l'intervalle, en jours, entre chaque période de la liste.

...

Cette balise contient un ensemble de sous-balises metadata. Chacune de ces balises contient une métadonnée sur laquelle on veut faire une recherche.

...

Permet d'ajouter des champs de recherche cachés lors de la recherche. Voir la Section "Champs de recherche cachés" pour configurer cette partie.

...

Permet de configurer les champs que l'on veut afficher dans la page de résultats. Voir la Section "Champs de résultats à afficher" pour configurer cette partie.

...

Permet de configurer l'ordre de tri des résultats. Voir la Section "Tri des résultats" pour configurer cette partie.

...

Permet de configurer les champs à utiliser lors de la génération du flux RSS en mode servlet. Voir la Section "Paramétrage des flux RSS" pour configurer cette partie.

...

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:

...

<thematic_search key="thematic_test" hide="false" vocabulary_id="search_unit_taxonomie_regexp" keep_navigation_session="true" full_tree="false" show_empty_categories="true">

	<metadatas>
		<metadata>//lom:classification/lom:taxonPath[lom:source/lom:string='dewey']/lom:taxon/lom:id</metadata>
		<metadata vcard_att="FN">//lom:lifeCycle/lom:contribute[lom:role/lom:value='author']/lom:entity(name)</metadata>
	</metadatas>

	<hidden_fields>
		...
	</hidden_fields>
	<result_fields>
		...
	</result_fields>
	<sort_fields>
		...
	</sort_fields>
	<rss_fields>
		...
	</rss_fields>
	<authorization>
		...
	</authorization>

</thematic_search>

key

Contient la clef unique de ce sous-menu de recherche.

...

Vaut true ou false suivant que l'on veuille cacher ou non ce sous-menu de recherche. Cacher un sous-menu peut être utile lorsque l'on y accède en tant que client et que l'on ne veut pas le voir dans le menu de l'interface.

...

Contient l'identifiant du vocabulaire (provenant du module ORI-OAI-vocabulary) dans lequel on veut naviguer.

...

Lorsque l'on ne veut pas passer par un vocabulaire avec l'attribut vocabulary_id, on peut utiliser une valeur simple. Par exemple, on peut saisir value="V1" et dans ce cas, à chaque clic on verra directement la recherche sur la valeur unique V1. Ceci permet de proposer une liste de résultats sur n'importe quel paramètre.
En mode portlet, il est aussi possible de faire correspondre cette valeur à une valeur d'un attribut LDAP de l'utilisateur connecté. En effet, en utilisant la syntaxe value={mon_attribut_ldap}, la valeur sera remplacée par la valeur de l'attribut mon_attribut_ldap de l'utilisateur. Exemple d'un menu de recherche qui présente à l'utilisateur connecté toutes les ressources pédagogiques dont il est auteur:

...

<thematic_search key="my_author" value="{displayName}">
	<metadatas>
		<metadata>//lom:lifeCycle/lom:contribute[lom:role/lom:value='author']/lom:entity(name)</metadata>
	</metadatas>
	....
</thematic_search>

...

Ce paramètre vaut true ou false. Il permet de dire si on souhaite garder en session la navigation de l'utilisateur dans une recherche thématique. Si true, à chaque fois qu'un utilisateur reviendra dans la recherche thématique durant sa session, il se trouvera dans le dernier niveau de l'arbre visité. Dans le cas false, il reviendra toujours à la racine de l'arbre.

...

Ce paramètre vaut true ou false. Dans le cas false, nous sommes dans une recherche thématique classique: la recherche se fait par navigation successives dans l'arborescence de la thématique. Si on configure true, toute l'arborescence nous est présentée sous forme d'un arbre dépliable. On peut alors sélectionner tous les niveaux souhaités en une seule requête.

...

Ce paramètre vaut true ou false. Il permet de dire si on souhaite afficher ou non le nombre de résultats à côté de chaque catégorie.

...

Ce paramètre vaut true ou false. Il permet de dire si on souhaite montrer à l'utilisateur les catégories ne contenant aucune ressource.
Dans le cas où le paramètre vaut false, les catégories vides ne seront pas visibles dans l'IHM.

...

Ce paramètre vaut true ou false. Il permet de dire si on souhaite afficher tous les sous-niveaux de l'arbre des catégories par rapport au nœud courant. Ce paramètre n'est utilisé que si "full_tree" est différent de "true".

...

Cette balise contient un ensemble de sous-balises metadata. Chacune de ces balises contient une métadonnée sur laquelle on veut faire une recherche. Imaginons que l'on ait 2 métadonnées MD1 et MD2. On navigue dans la catégorie qui a pour valeurs V1 et V2. La requête générée sera alors du type: MD1=V1 ou MD1=V2 ou MD2=V1 ou MD2=V2.

...

...

Permet d'ajouter des champs de recherche cachés lors de la recherche. Voir la Section "Champs de recherche cachés" pour configurer cette partie.

...

Permet de configurer les champs que l'on veut afficher dans la page de résultats. Voir la Section "Champs de résultats à afficher" pour configurer cette partie.

...

Permet de configurer l'ordre de tri des résultats. Voir la Section "Tri des résultats" pour configurer cette partie.

...

Permet de configurer les champs à utiliser lors de la génération du flux RSS en mode servlet. Voir la Section "Paramétrage du flux RSS" pour configurer cette partie.

...

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:

...

<advanced_search key="advanced_test" hide="false" file="test.xml">

	<hidden_fields>
		...
	</hidden_fields>
	<result_fields>
		...
	</result_fields>
	<sort_fields>
		...
	</sort_fields>
	<rss_fields>
		...
	</rss_fields>
	<authorization>
		...
	</authorization>

</advanced_search>

key

Contient la clef unique de ce sous-menu de recherche.

...

Vaut true ou false suivant que l'on veuille cacher ou non ce sous-menu de recherche. Cacher un sous-menu peut être utile lorsque l'on y accède en tant que client et que l'on ne veut pas le voir dans le menu de l'interface.

...

Contient le nom du fichier XML contenant la définition du formulaire de recherche avancée. Ce fichier doit se trouver dans le dossier advanced. Il se configure comme décrit à la Section "Configurer un formulaire de recherche avancée".

...

Permet d'ajouter des champs de recherche cachés lors de la recherche. Voir la Section "Champs de recherche cachés" pour configurer cette partie.

...

Permet de configurer les champs que l'on veut afficher dans la page de résultats. Voir la Section "Champs de résultats à afficher" pour configurer cette partie.

...

Permet de configurer l'ordre de tri des résultats. Voir la Section "Tri des résultats" pour configurer cette partie.

...

Permet de configurer les champs à utiliser lors de la génération du flux RSS en mode servlet. Voir la Section "Paramétrage du flux RSS" pour configurer cette partie.

...

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

...

<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" type="radio">
			<metadata>...</metadata>
			<hidden_voc_id>voc_id_1</hidden_voc_id>
		</field>
		<field id="field_id3" format="text" thematicMenuKey="menu_test" thematicSearchKey="thematic_test">
			<metadata>...</metadata>

			<condition>...</condition>
		</field>
		<field id="field_id4" format="date:dd-MM-yyyy">
			<metadata dateFormat="yyyyMMdd">...</metadata>
		</field>

		<fields id="fields_id" maxChoiceSize="5">
			<field format="text" id="field_id5">
				<metadata>...</metadata>
			</field>
			<field format="text" id="field_id6">
				<metadata>...</metadata>
			</field>
		</fields>

		<condition>...</condition>
	</group>

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

</form>

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

Chaque champ doit avoir un identifiant unique dans tout le formulaire. N'utilisez pas de caractères spéciaux.

...

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

Chaque champ doit avoir un identifiant unique dans tout le formulaire. N'utilisez pas de caractères spéciaux.

...

Ce champ permet de spécifier de quel format est la valeur que l'on veut saisir. Pour tous les formats autres que du texte, une validation est faite au moment de la saisie afin de valider ou non le formulaire.
Les valeurs possibles sont text pour du texte simple, int pour un entier, float pour un flottant, boolean pour un booléen et date pour une date. Dans le cas d'une date, il est nécessaire de spécifier le format de saisie de la date dans le formulaire à l'aide de dd pour le jour, MM pour le mois et yyyy pour l'année. Par exemple, pour dire que le 22 juin 2005 doit être saisi comme 22-06-2005, il faudra paramétrer le formulaire comme ceci: format="date:dd-MM-yyyy".

...

Ce champ permet d'utiliser des listes déroulantes (ou d'autres formats) dans les champs de saisie. Il suffit de spécifier un identifiant de vocabulaire (provenant du module ORI-OAI-vocabulary). L'interface proposée sera alors une liste déroulante composée à partir du premier niveau de valeurs dans l'arbre des vocabulaires.

...

Cet attribut permet de dire quel type de champ on veut utiliser lors de saisie de valeur(s) parmi une liste fermée provenant d'un vocabulaire. Les valeurs possibles sont:

• select permet de saisir plusieurs valeurs dans une liste déroulante. Il faut spécifier le nombre de valeurs que l'on souhaite afficher sans avoir à dérouler la liste. Par exemple"select:4".
• checkbox permet la saisie de plusieurs valeurs dans des cases à cocher
• radio pour la saisie d'une seule valeur dans une liste de type "radio"

...

Il est possible de spécififer ici une valeur par défaut au formulaire.
Dans le cas d'une liste déroulante basée sur un vocabulaire, il faut spécifier l'identifiant de la catégorie souhaitée dans le vocabulaire.

...

Cette valeur vaut true ou false suivant que l'on veut que ce champ soit visible ou non. Ceci est utile dans le cas où on veut cacher une valeur dans la saisie. On pourra utiliser le champ defaultValue pour mettre une valeur par défaut, et le champ hidden pour cacher cette valeur. On peut comme ceci ajouter des paramètres à la requête sans que l'utilisateur ne le voit.

...

Dans le cas où on veut mettre une valeur par défaut dans un formulaire sans la cacher à l'utilisateur, mais sans que celui-ci ne puisse la modifier, on peut mettre se paramètre à la valeur true.

...

Cette variable doit OBLIGATOIREMENT être couplée à thematicSearchKey. Les 2 variables associées permettent d'aller sélectionner des valeurs pour ce champ depuis une navigation dans une recherche thématique en mode "esclave". Cet attribut doit donc contenir la clef du menu de recherche (défini dans config.xml) contenant la recherche thématique souhaitée.

...

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

...

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

Correspond à l'identifiant sur lequel on met la condition. Le group ou le field ne s'affichera ou ne disparaitra qu'à la condition que ce champ prenne une valeur donnée.

...

Ceci est la valeur que doit prendre le champ défini par fieldId pour qu'une action se fasse.

...

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_fields>
<!-- On veut que le namespace soit DC ou dublin_core ou oai_dc -->
	<hidden_field>
		<metadata>md-ori-oai-namespace</metadata>
		<value>DC</value>
		<value>"dublin core"</value>
		<value>oai_dc</value>
	</hidden_field>

<!-- On ne veut pas que le namespace soit du CDM -->
	<hidden_field vocabularyId="search_metadata_namespaces:cdm" not="true">
		<metadata>md-ori-oai-namespace</metadata>
	</hidden_field>

<!-- On veut que l'auteur soit abaddon -->
	<hidden_field vocabularyId="personnes:abaddon">
		<metadata vcard_att="FN">//lom:lifeCycle/lom:contribute[lom:role/lom:value='author']/lom:entity(name)</metadata>
	</hidden_field>
</hidden_fields>

Il ne doit y avoir qu'un seul hidden_fields qui lui est composé de plusieurs hidden_field. La requête générée par l'utilisateur sera alors modifiée par l'ajout des critères de chaque hidden_field.

Un hidden_field correspond à un champ caché. On y spécifie toutes les métadonnées concernées et les valeurs associées. Il peut y avoir plusieurs métadonnées dans les champs metadata. Il existe 2 méthodes pour définir les valeurs qui doivent être associées aux métadonnées:
value

On insère une série de balises value dans un hidden_field. On construira alors la requête où chaque métadonnée doit avoir au moins une valeur dans cette liste.

...

On spécifie cet attribut dans hidden_field (ne pas mettre dans ce cas de balises value) pour dire que les valeurs que doivent avoir les métadonnées spécifiées se trouve dans un vocabulaire du module ORI-OAI-vocabulary. La syntaxe est alors vocabularyId="identifiant_vocabulaire:identifiant_categorie" où identifiant_vocabulaire est l'identifiant du vocabulaire distant et identifiant_categorie est l'identifiant de la catégorie dans le vocabulaire. Les valeurs requises seront donc les valeurs associées à la catégorie dans le vocabulaire.

...

Permet de dire si on veut faire une négation sur ce champ caché. Si la valeur est not="true", il y aura alors négation sur la requête. Par exemple on ne veut pas que les résultats qui apparaissent soient de format CDM.

...

En mode portlet, il est aussi possible de faire correspondre une valeur de value à une valeur d'un attribut LDAP de l'utilisateur connecté. En effet, en utilisant la syntaxe value={mon_attribut_ldap}, la valeur sera remplacée par la valeur de l'attribut mon_attribut_ldap de l'utilisateur. Exemple d'un champ caché qui force l'interface de recherche à ne prendre que les ressources pédagogiques dont il est auteur:

...

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

...

<result_fields jsp_file="my_results.jsp">
	<result_field key="title" title_field="true" show_notice_link="true" href_document="true" highlight="true">
		<metadata>//lom:general/lom:title/lom:string[starts-with(@language,'fr')]</metadata>
	</result_field>

	<result_field key="date" format="date:dd-MM-yyyy" highlight="false">
		<metadata dateFormat="yyyyMMdd">//lom:lifeCycle/lom:contribute[lom:role/lom:value='author']/lom:date/lom:dateTime</metadata>
	</result_field>

	<result_field key="language" format="vocabulary:search_languages" highlight="false">
		<metadata>//lom:general/lom:language</metadata>
	</result_field>
</result_fields>

id

Dans le cas où le bloc <result_fields> est défini dans la balise <default_results>, il est obligatoire de définir un identifiant par bloc <result_fields>.
Au niveau de la balise <default_results>, le bloc <result_fields> sera défini en entier.

Au niveau du menu de recherche, il suffira simplement d'appeler le bloc <result_fields> par son identifiant comme suit:

...

<result_fields id="lom_dc_no_fulltext"/>

Il existe un attribut qui permet de spécifier la page JSP qui sert à la mise en page des résultats pour l'interface de recherche ici présente:
jsp_file

Nom du fichier JSP à utiliser. Il se trouve dans le dossier webapp/WEB-INF/stylesheets/results. On prendra par défaut si aucune valeur n'est saisie le fichier generic-results.jsp pour l'affichage en tableaux.

Il existe cependant plusieurs configurations d'affichage proposées au format jsp. Ces jsp ne sont compatibles qu'avec certaines configurations de formulaires de recherche En effet, les jsp proposées se reposent sur des champs de résultat (result_field) configurés dans les fichiers config.example.???.xml. Si vous voulez utiliser une de ces jsp dans votre contexte, il faut impérativement que tous les champs affichés par celle-ci soient référencés comme result_field dans votre configuration.

• documents-results.jsp qui affiche les résultats sous forme allégée comme dans beaucoup de moteurs de recherche classiques. Cette configuration est compatible avec les champs de résultats proposés dans les recherches liées aux ressources en Dublin Core et en LOM. La description et les mots-clefs sont affichés par survol avec la souris.
• documents-results-unt.jsp ressemble beaucoup à la précédente mais une partie de la description est affichée directement sous le titre.
• documents-results-cdm.jsp peut être utilisée pour afficher des formations dans le cas d'une recherche sur des fiches CDM.

Les balises result_field sont composées comme ceci:
key

Une clef unique pour ce champ de résultat dans cette interface de recherche.

...

Si vaut true, un lien vers l'affichage de la fiche de métadonnée est affiché dans ce champ. La définition des différents formats de métadonnées est décrite dans la Section "Les formats de métadonnées supportés".

...

Si vaut true, un lien vers le document est disponible. La définition des métadonnées relatives à ces liens est décrite dans la Section "Lien vers les documents dans la liste des résultats de recherche".

...

Cet attribut permet de spécifier une transformation de la valeur de métadonnées retrouvée. En effet, il est possible d'effectuer une transformation de la valeur lors de l'affichage.
Les valeurs possibles pour ce champ peuvent être:

• time pour l'affichage d'une durée de type P1Y2M3DT4H5M6S
• *size pour une taille de fichier en octets
• date pour une date. Dans ce cas, la date sera affichée dans le format désiré. La saisie de ce paramètre ce fait sous cette forme: *format="date:dd-MM-yyyy"
• vocabulary pour un vocabulaire. Dans ce cas, la valeur retrouvée est cherchée en correspondance dans les valeurs du vocabulaire choisi. Lorsque cette valeur est trouvée, on affiche le libellé correspondant dans la langue sélectionnée dans l'interface. Par exemple, on spécifiera comme ceci le vocabulaire des langues: *format="vocabulary:search_languages". Ceci peut être utilisée dans le cas de l'affichage de la langue de saisie d'une ressource pédagogique. Si la valeur fr-FR est retrouvée, elle sera automatiquement traduite en Français si on affiche en français, ou French si on affiche en anglais, etc.

...

Si vaut true, ce champ est considéré comme de type titre. Dans ce cas, la classe CSS utilisée pour l'affichage n'est pas la même que pour les autres champs.

...

Vaut true ou false si l'on souhaite oui ou non surligner les valeurs retrouvées dans l'interface des résultats.

Chaque result_field est également composé de sous-balises metadata décrites comme ceci:
dateFormat

Avec ce paramètre, on permet de dissocier le format d'affichage du résultat du format de date dans la métadonnée. 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 veut afficher une date comme 22-06-2005 mais qu'elle est stockée en 20050622 dans la métadonnée en mettant pour valeur dateFormat="yyyyMMdd".

...

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.

...

<sort_fields ascending="true">
	<sort_field_key>md-ori-oai-score</sort_field_key>
	<sort_field_key>title</sort_field_key>
	<sort_field_key>date</sort_field_key>
	<sort_field_key>repository</sort_field_key>
</sort_fields>

Dans l'exemple de configuration précédent, on voit le tri de documents suivant plusieurs sort_field_key. Chacune de ces valeurs correspond à la clef donnée pour les champs de résultat dans les balises result_fields/result_field, sauf pour md-ori-oai-score où là on spécifie que l'on ne trie pas par rapport à un champ, mais par rapport au score (i.e. à la pertinence de résultat; cette pertinence est à configurer au niveau du module ORI-OAI-indexing dans la définition des setBoost Lius). Les champs affichés seront donc triés en fonction des champs de résultats définis plus haut et au score.

Chaque champ de tri est interprété dans l'ordre où il est configuré. Dans l'exemple précédent, en imaginant plusieurs documents ayant le même score, le tri entre-eux se fera ensuite sur le champ title, puis par rapport au champ date et enfin repository.

id

Dans le cas où le bloc <sort_fields> est défini dans la balise <default_results>, il est obligatoire de définir un identifiant par bloc <sort_fields>.
Au niveau de la balise <default_results>, le bloc <sort_fields> sera défini en entier.

Au niveau du menu de recherche, il suffira simplement d'appeler le bloc <sort_fields> par son identifiant comme suit:

...

<sort_fields id="score_date"/>

ascending

Cet attribut peut valoir true ou false que l'on veuille trier dans l'ordre croissant ou décroissant. Pour le titre, on choisira true, tandis que pour trier des documents suivant la date la plus récente à la plus ancienne, on choisira false.

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:

...

<rss_fields link="notice">
	<title>title_md</title>
	<description>description_md</description>
	<pubDate>date_md</pubDate>
</rss_fields>

id

Dans le cas où le bloc <rss_fields> est défini dans la balise <default_results>, il est obligatoire de définir un identifiant par bloc <rss_fields>.
Au niveau de la balise <default_results>, le bloc <rss_fields> sera défini en entier.

Au niveau du menu de recherche, il suffira simplement d'appeler le bloc <rss_fields> par son identifiant comme suit:

...

<rss_fields id="default"/>

Les différents champs de ce bloc se configurent de la manière suivante:
link

Ce champ permet de dire si on souhaite pointer vers la fiche de métadonnée ou vers le document lui-même dans le flux RSS. Pour pointer vers la fiche de métadonnée, la valeur de ce champ doit être notice. Lorsque l'on souhaite pointer directement sur le document, on n'utilise pas le paramètre link.

...

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

...

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

...

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.

...

<authorization operator="or">
	<allowed attribute="uid" value="ycolmant"/>
	<allowed attribute="uid" value="bourges"/>
</authorization>

Il est possible de configurer plusieurs balises authorization à la suite. Dans ce cas, l'utilisateur aura accès si il répond à au moins un des 2 filtres.

operator

Cet attribut de la balise authorization a la valeur or ou and suivant que l'on utilise l'opération "ou" ou "et". Cette opération se fait sur l'ensemble des balises allowed contenues dans authorization.

...

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:

...

<href_formats formatsVocabulary="search_metadata_namespaces">
	<format hrefFormatValue="http://ltsc.ieee.org/xsd/LOM">
		<metadata>//lom:technical/lom:location</metadata>
	</format>

	<format hrefFormatValue="vocabulary:search_metadata_namespaces:dc">
		<metadata>//dc:identifier</metadata>
	</format>
</href_formats>

Voyons en détail les différents attributs de configuration:
formatsVocabulary

L'affichage des notices necessite la résolution d'un identifiant de format de métadonnées. Le paramètre formatsVocabulary est donc l'identifiant du vocabulaire qui contient tous les formats de métadonnées.

...

Cet attribut permet d'identifier le namespace du format de métadonnées XML. La valeur peut donc être simplement ce namespace, ou il peut être déduit d'un vocabulaire. La syntaxe est alors hrefFormatValue="vocabulary:identifiant_vocabulaire:identifiant_categorie" où identifiant_vocabulaire est l'identifiant du vocabulaire distant et identifiant_categorie est l'identifiant de la catégorie dans le vocabulaire où se trouve le(s) namespace(s) souhaité(s).

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

Pour configurer ce mode, vous devez changer les paramètres suivants:

...

<simple_search menu_key="menu_test" search_key="advanced_test" field_id="field_test"/>

menu_key

Cet attribut doit donc contenir la clef du menu de recherche (défini dans config.xml) contenant la recherche avancée souhaitée.

...

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

...

Ceci est l'identifiant du champ de recherche. Vous l'avez défini dans la configuration du formulaire avancé dans le dossier advanced. Il correspond à l'attribut id d'une balise field. Dans le cas présent, il est souvent préférable que ce champ soit l'aggrégation de plusieurs métadonnées pour pouvoir lancer une recherche large (titre, description, auteur, etc.).

Notons que cette configuration génère un formulaire HTML dans toutes les interfaces. Vous pouvez visualiser ce formulaire en regardant le code source d'une des pages de l'application. Vous pouvez donc si vous le souhaitez intégrer ce formulaire dans une autre page web pour rebondir vers cette recherche (uniquement dans le cas d'un déploiement en mode servlet).

Voici un exemple de formulaire généré dans lequel il faut compléter les paramètres en caractère gars:

...

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

1ère étape : préparer la configuration

Depuis le module ORI-OAI-quick-install, lancez la commande suivante :

ant init-config-search

Ceci va créer l'arborescence des dossiers et fichiers servant à personnaliser le module dans le dossier [PATH_CUSTOM_CONFIG]/ori-oai-search.

Structure du dossier [PATH_CUSTOM_CONFIG]/ori-oai-search

Depuis la version 2.0 de ORI-OAI, toutes les configurations et la personnalisation se font depuis le dossier [PATH_CUSTOM_CONFIG] (avec 1 sous-dossier par module).
Voyons la structure du module qui nous concerne ici :

Configurations avancées

Voici les différentes étapes par lesquelles passe la configuration avancée du module :

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

Pour cela, vous devez renseigner les paramètres suivants:

...

<simple_date_search menu_key="menu_test" search_key="date_test"/>

menu_key

Cet attribut doit donc contenir la clef du menu de recherche (défini dans config.xml) contenant la recherche par date souhaitée.

...

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.

Son fonctionnement est simple: on stocke sur le serveur des définitions de formulaires de recherche en XML au format OpenSearch. Ces fichiers sont référencés dans l'en-tête HEAD des pages HTML:

...

<link rel="search" type="application/opensearchdescription+xml" title="Recherche simple de mon établissement" href="....../opensearch/ma_recherche.xml"/>

Ceci permet alors au navigateur de détecter automatiquement qu'un plugin de recherche est disponible sur ce site et il est proposé à l'utilisateur. Il n'a plus qu'à l'intégrer à son navigateur. A partir de ce moment, l'utilisateur pourra lancer une recherche depuis son navigateur en rebondissant sur le moteur de recherche ORI-OAI.

La configuration est la suivante dans le fichier config.xml :

...

<open_search>
	<link title="Recherche de ressources pédagogiques" file="lom.xml"/>
	<link title="Recherche de thèses" file="tef.xml"/>
</open_search>

Il est possible de mettre plusieurs balises link dans la configuration pour rendre disponibles plusieurs types de recherche.

title

Le titre affiché pour ce plugin dans le navigateur au moment de la sélection.

...

Le nom du fichier de configuration OpenSearch contenu dans le dossier opensearch.

Voyons maintenant la configuration d'un plugin OpenSearch compatible Firefox 2 et Internet Explorer 7 (Vous pouvez plus de documentation pour la création de ces plugins pour Firefox 2 notamment à cette adresse: http://www.gatellier.be/blog/plugin-recherche-opensearch-firefox2.).
Ces fichiers sont stockés dans le dossier opensearch de votre configuration personnalisée.

...

<?xml version="1.0" encoding="iso-8859-1"?>
	<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/" xmlns:moz="http://www.mozilla.org/2006/browser/search/">
	<ShortName>Recherche de ressources pédagogiques</ShortName>
	<Description>Recherche sur des ressources pédagogiques de l'Université de Test</Description>
	<Contact>[SMTP_ADMINISTRATOR_MAIL]</Contact>
	<InputEncoding>iso-8859-1</InputEncoding>

	<Image width="16" height="16">data:image/x-icon;base64,AAABAAEAEBAAAAEAIABoBAA......</Image>
	<Url template="http://[HOST_SEARCH]:[PORT_SEARCH]/[CONTEXT_SEARCH]/simple-search.html?menuKey=menu_test&amp;submenuKey=advanced_test&amp;fieldId=field_test&amp;light-request={searchTerms}" type="text/html"/>

	<moz:SearchForm>http://[HOST_SEARCH]:[PORT_SEARCH]</moz:SearchForm>
</OpenSearchDescription>

ShortName

Le nom court du plugin qui est affiché dans le navigateur.

...

La description du plugin.

...

L'adresse d'un contact.

...

On renseigne ici le logo (.ico) qui est affiché dans le champ de recherche, il peut être de 2 types:

...

<Image height="16" width="16" type="image/x-icon">http://example.com/favicon.ico</Image>

...

<Image width="16" height="16">data:image/x-icon;base64,AAABAAEAEBAAAAEAIABoBAA......</Image>

...

On définit ici l'URL de recherche. Cette URL est de ce type:

Code Block
http://[HOST_SEARCH]:[PORT_SEARCH]/[CONTEXT_SEARCH]/simple-search.html?menuKey=menu_test&submenuKey=advanced_test&fieldId=field_test&light-request={searchTerms}

...

moz:SearchForm

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 bloc de configuration de cette partie se présente sous cette forme:

...

<notice_formats>
	<format formatMetadataValue="vocabulary:search_metadata_namespaces:lom" prefix="lom" xsl="lom.xsl" headXsl="lom.xsl">
		<metadata format="...">...</metadata>
	</format>

	<format ...>
		...
	</format>
<notice_formats>

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:

formatMetadataValue

On renseigne ici le namespace du format de métadonnées que l'on veut supporter. On peut avoir 2 types de configuration:

• formatMetadataValue="http://ltsc.ieee.org/xsd/LOM" : on renseigne directement le namespace. Dans le cas d'un format où plusieurs namespaces sont disponibles (dans le cas de changement de version par exemple), on peut avoir la syntaxe_formatMetadataValue="namespace_1_|namespace_2|namespace_3".
• formatMetadataValue="vocabulary:identifiant_vocabulaire:identifiant_categorie" où identifiant_vocabulaire est l'identifiant du vocabulaire distant et identifiant_categorie est l'identifiant de la catégorie dans le vocabulaire où se trouve le(s) namespace(s) souhaité(s)

...

On renseigne le préfixe XML correspondant au namespace.

...

L'affichage de la fiche de métadonnées se fait par transformation XSLT. Dans ce paramètre, on renseigne donc le fichier de transformation XSL qui se trouve lui-même dans le dossier webapp/WEB-INF/xsl. Voir la Section "Transformation XSL des fiches de métadonnées" pour la configuration de ce fichier XSL. Dans la distribution, il existe 2 affichages possibles pour la notice LOM et Dublin Core: lom.xsl et dc.xsl.

...

Ce champ permet de spécifier la XSL à utiliser pour afficher le bloc HEAD de la page HTML rendue lors de l'affichage d'une notice. Ce champ est OBLIGATOIRE. La XSL renseignée ici permet de spécifier le champ title et les metakeywords et description. Le fichier donné en configuration doit obligatoirement se trouver dans le dossier webapp/WEB-INF/xsl/head. Dans cette distribution, les XSL du LOM et Dublin Core sont disponibles: respectivement lom.xsl et dc.xsl.

Il est possible de définir des espaces de noms supplémentaires dans cette configuration en utilisant la balise additional_ns. Ceci peut être utilisé dans le cas d'un format utilisant plusieurs espaces de noms ou si vous avez ajouté un espace de nom dans un format existant. Ceux-ci doivent obligatoirement être définis pour qu'ils soient traités lors de la transformation XSLT qui permet le rendu de la fiche de métadonnées complète. Sans la définition des ces espaces supplémentaires, vous ne pourrez pas faire apparaître les champs liés à ces espaces dans le moteur de recherche. La balise additional_ns est répétable. Elle contient les attributs suivants:
prefix

On renseigne le préfixe XML correspondant au namespace.

...

Correspond au namespace.

...

Permet de dire si on souhaite proposer la visualisation de la fiche XML dans son état d'origine au niveau de l'interface de recherche. true pour une visualisation, false sinon. La valeur par défaut est true.

Chaque balise metadata permet de configurer une transformation avant affichage des métadonnées. Les attributs et configurations possibles sont les suivants:
Attribut format

Ceci renseigne le format du champ que l'on veut transformer. Il peut y avoir plusieurs types différents:

• format="date:dd-MM-yyyy" pour transformer une date vers le format désiré. En prenant la configuration citée ici, le 22 juin 2005 sera affiché comme 22-06-2005.
• format="vocabulary:identifiant_vocabulaire". Dans ce cas, la valeur retrouvée est cherchée en correspondance dans les valeurs du vocabulaire choisi. Lorsque cette valeur est trouvée, on affiche le libellé correspondant dans la langue sélectionnée dans l'interface. Par exemple, on spécifiera comme ceci le vocabulaire des langues: format="vocabulary:search_languages". Ceci peut être utilisée dans le cas de l'affichage de la langue de saisie d'une ressource pédagogique. Si la valeur fr-FR est retrouvée, elle sera automatiquement traduite en Français si on affiche en français, ou French si on affiche en anglais, etc.
• format="size:search_traduction_size" permet d'afficher une taille de fichiers en octets. search_traduction_size étant le vocabulaire permettant de traduire les termes bytes, Kb, Mb, etc.
• format="time:search_traduction_time" permet d'afficher une durée de type P1Y2M3DT4H5M6S. search_traduction_time étant le vocabulaire permettant de traduire les termes year, month, hour, etc.
• format="vcard". On indique ici que la métadonnée contient une vcard. Cette vcard est alors transformée en XML dans la fiche de métadonnée avant d'être fournie à la XSL. La XSL peut alors afficher tout ou partie de cette vcard en XML.

...

Cet attribut permet de dire dans quel format est stockée la date. Par exemple metadataDateFormat="yyyy-MM-dd". Pour dire que la métadonnée que l'on récupère est de la forme 2005-06-22 .

...

Le contenu est lui un chemin xpath correspondant au chemin de la métadonnée dans la fiche XML ou un nom de métadonnée dans le cas des métadonnées repository, datestamp, etc.

...

Il est possible pour certaines métadonnées d'ajouter un lien dans l'interface pour rebondir vers une recherche thématique sur celui-ci. Par exemple, lors de l'affichage d'un auteur, on pourra mettre un lien sur son nom pour lancer une recherche thématique uniquement sur ce nom. On peut imaginer la même chose pour les mots-clefs, etc.
Ceci se spécifie dans une sous-balise de metadata:thematic_link. Les attributs de thematic_link sont les suivants:

...

Ajout de liens versune autre notice

Il est possible pour certaines métadonnées d'ajouter un lien dans l'interface pour rebondir vers une autre notice. Par exemple, lors de l'utilisation des relations dans le format LOM.
Le concept est le suivant:

...

<metadata>
	/mon/xpath
	<notice_link key="mon_lien" labelXpath="ML" targetXpath="M1" typeXpath="T" xpathInTarget="/monautrexpath/M2"/>
</metadata>

Ceci se spécifie dans une sous-balise de metadata:notice_link. Les attributs de notice_link sont les suivants:

...

Exemple de la relation haspart du LOM:

...

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

On notera dans la suite:

• menuKey la clef d'un menu de recherche saisie dans conf/search/(ma configuration)/config.xml, à modifier en fonction du menu que l'on configure
• submenuKey la clef d'un formulaire de recherche à modifier
• resultFieldKey la clef d'un champ de résultat de recherche à modifier

Le libellé d'un menu de recherche est construit comme suit:

menu.label.menuKey=Libellé du menu

Les interfaces de recherche sont définies quant à elles comme ceci:

menu.label.menuKey.submenuKey=Libellé du formulaire de recherche
menu.description.menuKey.submenuKey=Description du formulaire de recherche

Enfin, on configure de la manière suivante les différents champs de résultat:

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.

On notera dans la suite:

• menuKey la clef d'un menu de recherche avancée saisie dans conf/search/(ma configuration)/config.xml, à modifier en fonction du menu que l'on configure
• submenuKey la clef d'un formulaire de recherche avancée à modifier
• groupId l'identifiant d'une balise group à modifier
• fieldId l'identifiant d'une balise field à modifier

Tous les paramètres suivants sont obligatoires. Si vous ne voulez pas de messages dans certains cas, définissez la valeur avec une chaîne vide.

Le libellé d'un groupe de champs se configure comme ceci:

menu.form.label.menuKey.submenuKey.groupId=Libellé du groupe de champs de recherche

Les champs de recherche sont eux configurés comme ceci:

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.

Toutefois, nous pouvons voir que les messages liés à l'internationalisation doivent êtres passés en paramètre des XSL. Ces messages doivent être déclarés en en-tête de la XSL sous forme de balises comme l'exemple <xsl:param name="xsl.lom.url"/> où xsl.lom.url est la clef du message (c.f. la Section "Personnalisation des messages et libellés") saisie dans les différents bundles de langues. Le passage des paramètres est effectué au niveau de la JSP webapps/WEB-INF/stylesheets/notice/notice.jsp par des balises de la forme:

...

<x:param name="xsl.lom.url">
	<fmt:message key="xsl.lom.url"/>
</x:param>

où <fmt:message key="xsl.lom.url"/> représente la récupération du message dans les différents bundles en fonction de la langue et <x:param name="xsl.lom.url">...</x:param> effectue ce passage à la XSL.

La construction des liens vers des recherches thématiques nécessite aussi une petite explication. En effet, lors de la configuration des différents formats (Section "Configuration des formats"), la fiche XML est modifiée pour voir apparaître tous les paramètres nécessaires à la construction du lien. Une métadonnée dont le xpath serait general/keyword deviendrait alors:

...

<general>
	<keyword ori-link-key="..." ori-menuKey="..." ori-submenuKey="..." ori-id="..." ori-label="...">Valeur d'origine</keyword>
</general>

où:
ori-link-key

la clef définie dans la configuration de la métadonnée dans le format

...

valeur de thematicMenuKey de la configuration

...

valeur de thematicSearchKey

...

l'identifiant de la catégorie du vocabulaire qui correspond à la valeur retrouvée dans la fiche de métadonnée

...

le libellé traduit correspondant à la valeur initiale et trouvée dans le vocabulaire en fonction de la langue de l'utilisateur

Un exemple de lien généré peut être le suivant:

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

Vous avez le choix entre :

• utiliser un des skins proposés par défaut
• modifier un des skins par défaut. Dans ce cas, nous vous conseillons de copier le skin d'origine en le renommant avec un nom spécifique à votre établissement. Ensuite, nous vous conseillons de proposer ce skin à la communauté
• créer un skin en partant de zéro, mais le travail sera plus fastidieux

Un dossier de skin est composé comme suit:

• Dossier css : Ce dossier contient toutes les CSS utilisées dans votre skin. Le fichier css/ori-oai-search.css est obligatoire.
• Dossier i18n : Tous les libellés propres au skin sont définis dans ce dossier. Il est possible 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.
• Dossier media : Ce dossier contient toutes les images utilisées dans le skin.
• Dossier stylesheets : 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 : Tout comme il est possible d'ajouter ou de surcharger certaines JSP, il est possible de le faire avec les XSL utilisées lors de l'affichage d'une fiche de métadonnées.

Dans ori-oai-search, plusieurs skins sont proposés par défaut :

• default_gray : skin proposé par défaut reprenant le bandeau ORI-OAI et un fond gris
• default_blue-old : look approchant celui de l'ancien site institutionnel du projet
• contrib_portlet-uvhc : skin défini pour la version portlet de l'université de Valenciennes
• contrib_unr-npdc : skin utilisé sur le site http://www.unr-npdc.org

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.

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 stylesheets 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 stylesheets 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 theme.
Par exemple, pour surcharger le comportement de la JSP documents-results.jsp:

• Copiez le fichier webapp/WEB-INF/stylesheets/results/documents-results.jsp vers conf/skins/votre_skin/stylesheets/results/documents-results.jsp
• Modifiez ce nouveau fichier qui surchargera le fichier d'origine lors du déploiement

...

Lors d'un déploiement en mode portlet dans un ENT par exemple, aucun en-tête HTML n'est généré par l'application. En effet, le HTML généré par la portlet ori-oai-search est intégré dans un environnement autre. Dans ce cas, aucune CSS n'est associée par défaut à votre interface. Il est donc impératif d'ajouter le lien vers votre CSS ori-oai-search.css depuis l'en-tête HEAD de votre moteur de portlet.

Dans le cas de l'ENT ESUP Portail, vous pouvez par exemple importer la CSS de ori-oai-search depuis la CSS ???_portlet..css du dossier VOTRE_CHEMIN/uPortal/media/org/jasig/portal/layout/AL_TabColumn/integratedModes/VOTRE_DOSSIER_DE_SKINS/skin comme ceci:

@import url("../../../../../../../../../../[CONTEXT_SEARCH]/css/ori-oai-search.css");

...