<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (C) 2000-2010  Ministere de la culture et de la communication (France), AJLSM
See LICENCE file
-->
<!DOCTYPE webpage PUBLIC "-//Norman Walsh//DTD Website V2.1b1//EN" "../../../dtd/website.dtd" [
<!ENTITY actions_controle SYSTEM "actions_controle.xml" NDATA XML>
<!ENTITY actions_index SYSTEM "actions_index.xml" NDATA XML>
<!ENTITY actions_indexation SYSTEM "actions_indexation.xml" NDATA XML>
<!ENTITY actions_recuperation SYSTEM "actions_recuperation.xml" NDATA XML>
<!ENTITY actions_requetes SYSTEM "actions_requetes.xml" NDATA XML>
]>

<webpage id="actions_controle">

  <head>
	 <title lang="fr">Gestion des résultats</title>
	 <titleabbrev lang="fr">Résultats</titleabbrev>
	 <author lang="fr"><firstname>Malo</firstname><surname>Pichot</surname><affiliation><orgname>AJLSM</orgname></affiliation></author><revhistory>
		<revision lang="fr">
		  <revnumber>1.0</revnumber><date>2005-03-16</date>
		</revision>
	 </revhistory>
  </head>

  <itemizedlist>
	 <title>Liste des actions décrites dans cette page : </title>
	 <listitem>
		<para><ulink url="#sdx_results"><sgmltag class="element">sdx:results</sgmltag></ulink> ; </para>
	 </listitem><listitem>
		<para><ulink url="#sdx_hpp"><sgmltag class="element">sdx:hpp</sgmltag></ulink> ; </para>
	 </listitem><listitem>
		<para><ulink url="#sdx_sort"><sgmltag class="element">sdx:sort</sgmltag></ulink> ; </para>
	 </listitem>
	 <listitem>
		<para><ulink url="#sdx_sort"><sgmltag class="element">sdx:sorts</sgmltag></ulink> ; </para>
	 </listitem><listitem>
		<para><ulink url="#sdx_navigation"><sgmltag class="element">sdx:navigation</sgmltag></ulink>.</para>
	 </listitem>
  </itemizedlist>
  <section>
	 <title>Concepts clés</title>
	 <para>SDX offre plusieurs actions permettant de travailler le résultat d'une requête. Il est ainsi possible de préciser le nombre de réponses que l'on veut voir sortir par page de résultats (on ne veut peut être pas avoir à traiter une document XML virtuel long de plusieurs centaines de réponses) avec
		<ulink url="#sdx_hpp"><sgmltag class="element">sdx:hpp</sgmltag></ulink>, trier ces résultats avec
		<ulink url="#sdx_sorts"><sgmltag class="element">sdx:sorts</sgmltag></ulink> et
		<ulink url="#sdx_sort"><sgmltag class="element">sdx:sort</sgmltag></ulink>, naviguer parmi les différents documents issus d'une même requête avec
		<ulink url="#sdx_navigation"><sgmltag class="element">sdx:navigation</sgmltag></ulink>. Enfin, parce qu'il arrive que l'on exécute la même requête et qu'une recherche prend du temps, il est possible de récupérer un résultat déjà obtenu avec
		<ulink url="#sdx_results"><sgmltag class="element">sdx:results</sgmltag></ulink>.</para>
  </section>
  <section lang="fr" id="sdx_results">
	 <title><sgmltag class="element">sdx:results</sgmltag></title>
	 <para>Lors de son exécution, une requête reçoit un identifiant (paramètre <sgmltag class="attribute">qid</sgmltag> transmis dynamiquement par SDX ou statiquement par le développeur dans une page XSP). <sgmltag class="element">sdx:results</sgmltag> permet de récupérer le résultat de cette requête sans avoir à la ré-exécuter.</para>
   <para>Par défaut SDX conserve en mémoire les cinq derniers résultats de requête. Le sixième &quot;chasse&quot; le premier. Ce nombre peut être modifié en changeant la variable <literal>sdx_qmax</literal> (cf. la logicsheet <filename>sdx.xsl</filename>).</para>
	 <para>Il est possible de conserver un résultat de requête durant toute la session d'un utilisateur en passant soi-même un identifiant (attribut <sgmltag class="attribute">qid</sgmltag> d'une requête). Quoi qu'il en soit, l'identifiant d'une requête demeure dans la mémoire de la session de l'utilisateur courant. Cela signifie, qu'à l'arrêt de la session (i.e. fermeture du navigateur ou déconnexion de l'utilisateur), l'identifiant est supprimé de la cache et qu'un identifiant de requête ne peut pas être partagé entre plusieurs sessions d'utilisateurs. Il n'y a pas encore de mécanisme de mémorisation d'une requête au niveau du serveur, mais ce n'est pas impossible et relativement économe en ligne de code (TODO : cf. message de Frédéric Glorieux dans la liste sdx-developers).</para>
	 <informaltable lang="fr">
		<tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="1.00*"/><colspec colnum="2" colname="col2" colwidth="3.30*"/><tbody>
			 <row><entry colname="col1">Code implémentant cette action</entry><entry colname="col2"><filename>sdx-queries.xsl</filename></entry>
			 </row>
			 <row><entry colname="col1">Contexte d'utilisation</entry><entry colname="col2"> <sgmltag class="element">sdx:results</sgmltag> et ses paramètres spécifiques peut être employé avec
				  <olink localinfo="sdx_deletedocuments" targetdocent="actions_indexation"><sgmltag class="element">sdx:deleteDocuments</sgmltag></olink> et l'ensemble des
				  <olink targetdocent="actions_requetes">actions d'exécution de requêtes</olink> (excepté
				  <olink localinfo="sdx_terms" targetdocent="actions_index"><sgmltag class="element">sdx:terms</sgmltag></olink>).</entry>
			 </row>
			 <row><entry colname="col1">Contenu éventuel</entry><entry colname="col2"><sgmltag class="element">sdx:results</sgmltag> peut contenir les actions
				  <olink localinfo="sdx_success" targetdocent="actions_controle"><sgmltag class="element"> sdx:success</sgmltag></olink> et
				  <olink localinfo="sdx_fallback" targetdocent="actions_controle"><sgmltag class="element">sdx:fallback</sgmltag></olink>. Il est donc permis de définir des "stratégies"</entry>
			 </row></tbody>
		</tgroup>
	 </informaltable><table lang="fr" id="sdx_results_param">
	 <title>Paramètres spécifiques</title>
	 <tgroup cols="3"><colspec colnum="1" colname="col1" colwidth="1.58*"/><colspec colnum="2" colname="col2" colwidth="3.76*"/><colspec colname="col3" colnum="3" colwidth="1.00*"/><thead>
		  <row><entry colname="col1">Nom</entry><entry colname="col2">Description</entry><entry colname="col3"></entry>
		  </row></thead><tbody>
		  <row><entry colname="col1"><sgmltag class="attribute">qid</sgmltag></entry><entry colname="col2">Identifiant de la requête, ce paramètre permet de récupérer le résultat d'une requête demeuré en mémoire de la session de l'utilisateur. Il n'y a pas encore de mécanisme de mémorisation d'une requête au niveau du serveur, mais ce n'est pas impossible à réaliser (TODO : cf. message de Frédéric Glorieux dans la liste sdx-developers).</entry><entry colname="col3">Facultatif</entry>
		  </row>
		  <row><entry colname="col1"><sgmltag class="attribute">force</sgmltag></entry><entry colname="col2">Fixé à <literal>true</literal>, ce paramètre force l'application à ré-exécuter une requête identifiée par son <sgmltag class="attribute">qid</sgmltag>. C'est une manière de recréer un jeu de résultats tout en conservant la syntaxe d'une requête.</entry><entry colname="col3">Facultatif</entry>
		  </row>
		  <row><entry colname="col1"><sgmltag class="attribute">page</sgmltag></entry><entry colname="col2">Identifie une page dans un jeu de résultats de requête caché dans la session de l'utilisateur.</entry><entry colname="col3">Facultatif</entry>
		  </row>
		  <row><entry colname="col1"><sgmltag class="attribute">p</sgmltag></entry><entry colname="col2">Numéro de page. <emphasis role="bold">Déprécié</emphasis></entry><entry colname="col3">Facultatif</entry>
		  </row></tbody>
	 </tgroup></table><table id="sdx_results_param_comm">
	 <title>Paramètres communs</title>
	 <tgroup cols="4"><colspec colnum="1" colname="col1" colwidth="1.27*"/><colspec colnum="2" colname="col2" colwidth="3.86*"/><colspec colnum="3" colname="col3" colwidth="1.13*"/><colspec colnum="4" colname="col4" colwidth="1.00*"/><thead>
		  <row><entry colname="col1">Nom</entry><entry colname="col2">Description</entry><entry colname="col3">Elément correspondant</entry><entry colname="col4"></entry>
		  </row></thead><tbody>
		  <row><entry colname="col1"><sgmltag class="attribute">hpp</sgmltag></entry><entry colname="col2">Spécifie le nombre de réponses que devra contenir la page de résultats. Par défaut, ce nombre est fixé à vingt.</entry><entry colname="col3"><ulink url="#sdx_hpp"><sgmltag class="element">sdx:hpp</sgmltag></ulink></entry><entry colname="col4">Facultatif</entry>
		  </row>
		  <row><entry colname="col1"><sgmltag class="attribute">sf</sgmltag></entry><entry colname="col2">Identifie le champ sur lequel on souhaite effectuer le tri. Ce paramètre est répétable en autant de clés de tri désirées.</entry><entry colname="col3"><ulink url="#sdx_sorts"><sgmltag class="element">sdx:sorts</sgmltag></ulink></entry><entry colname="col4">Facultatif</entry>
		  </row>
		  <row><entry colname="col1"><sgmltag class="attribute">so</sgmltag></entry><entry colname="col2">Identifie l'ordre de classement d'une clé de tri. Par défaut, le classement s'effectue de manière ascendante.</entry><entry colname="col3"><ulink url="#sdx_sorts"><sgmltag class="element">sdx:sorts</sgmltag></ulink></entry><entry colname="col4">Facultatif</entry>
		  </row></tbody>
	 </tgroup></table>
   <example lang="fr" id="exemple_sdx_results_01">
		<title>Identifier statiquement un résultat de requête</title>
    <para>Cette page XSP exécute une requête sur le champ <literal>sdxall</literal> avec la valeur <literal>1</literal> (ceci a pour effet de retourner l'ensemble des documents d'une base) et identifie statiquement son résultat. On ne laisse pas SDX effectuer automatiquement cette identification. De cette manière, on cherche à conserver le jeu de résultats durant toute la session de l'utilisateur, sans qu'il soit supprimé après un certain nombre de requête, par défaut ce nombre est fixé à 5. Il est possible de modifier la valeur par défaut en ajoutant un attribut <sgmltag class="attribute">sessionObjectLimit</sgmltag> à l'élément racine <sgmltag class="element">sdx:application</sgmltag> dans le fichier <filename>application.xconf</filename> d'une application.</para>
		<programlisting>
&lt;sdx:page&gt;
 &lt;sdx:executeFieldQuery field="sdxall" value="1" qid="selectAllAtStart" /&gt;
&lt;/sdx:page&gt;
</programlisting>
  <para>Ceci nous permet de conserver l'ensemble des documents présents dans la ou les bases au moment cette requête est exécutée. Imaginons que nous exécutions cette requête au début de la session d'un utilisateur. Il nous serait possible de restituer le nombre de résultat à n'importe quel moment de la session de l'utilisateur courant et, par exemple, de le comparer avec le nombre de documents à un instant T en utilisant le code suivant (noter que le type de requête n'a aucune importance) :</para>
<programlisting>
&lt;sdx:page&gt;
 &lt;sdx:executeSimpleQuery qid="selectAllAtStart" /&gt;
&lt;/sdx:page&gt;
</programlisting>
	 </example>
  </section>
  <section lang="fr" id="sdx_hpp">
	 <title><sgmltag class="element">sdx:hpp</sgmltag></title>
	 <para><sgmltag class="element">sdx:hpp</sgmltag> permet de créer les groupes de résultats en déterminant leur nombre. S'il n'est pas expressément défini, les résultats seront regroupé par lot de vingt dans chaque page. Noter que la valeur <literal>-1</literal> génère une liste complète des résultats sur une seule page.</para>
	 <informaltable lang="fr">
		<tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="*"/><colspec colnum="2" colname="col2" colwidth="*"/><tbody>
			 <row><entry colname="col1">Code implémentant cette action</entry><entry colname="col2"><filename>sdx-parameters.xsl</filename></entry>
			 </row>
			 <row><entry colname="col1">Contexte d'utilisation</entry><entry colname="col2"><sgmltag class="element">sdx:hpp</sgmltag> s'emploie avec les actions suivantes :
				  <olink localinfo="sdx_terms" targetdocent="actions_index"><sgmltag class="element">sdx:terms</sgmltag></olink> et
				  <ulink url="#sdx_results"><sgmltag class="element">sdx:results</sgmltag></ulink></entry>
			 </row>
			 <row><entry colname="col1">Contenu éventuel</entry><entry colname="col2">Aucun.</entry>
			 </row></tbody>
		</tgroup>
	 </informaltable><table lang="fr" id="sdx_hpp_param">
	 <title>Paramètres spécifiques</title>
	 <tgroup cols="3"><colspec colnum="1" colname="col1" colwidth="1.13*"/><colspec colnum="2" colname="col2" colwidth="4.26*"/><colspec colname="col3" colnum="3" colwidth="1.00*"/><thead>
		  <row><entry colname="col1">Nom</entry><entry colname="col2">Description</entry><entry colname="col3"></entry>
		  </row></thead><tbody>
		  <row><entry colname="col1"><sgmltag class="attribute">hpp</sgmltag></entry><entry colname="col2">Porte le nombre résultats souhaités par page de résultats. Par défaut, sa valeur est 20.</entry><entry colname="col3">Obligatoire</entry>
		  </row>
		</tbody>
	 </tgroup></table>
  </section>
  <section lang="fr" id="sdx_sort">
	 <title><sgmltag class="element">sdx:sort</sgmltag></title>
	 <para><sgmltag class="element">sdx:sort</sgmltag> est utilisé pour trier les résultats d'une requête. Il admet deux ordres de tri (<sgmltag class="attvalue">ascendant</sgmltag> et <sgmltag class="attvalue">descendant</sgmltag>). Il peut être répété (au sein de son conteneur, multiple ou non,
		<ulink url="#sdx_sorts"><sgmltag class="element">sdx:sorts</sgmltag></ulink>) afin de paramétrer plusieurs clés de tri. Son utilisation s'apparente à la commande <sgmltag class="element">xsl:sort</sgmltag> d'une feuille XSLT.</para>
	 <informaltable lang="fr">
		<tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="*"/><colspec colnum="2" colname="col2" colwidth="*"/><tbody>
			 <row><entry colname="col1">Code implémentant cette action</entry><entry colname="col2"><filename>sdx-queries.xsl</filename></entry>
			 </row>
			 <row><entry colname="col1">Contexte d'utilisation</entry><entry colname="col2"><sgmltag class="element">sdx:sort</sgmltag> s'emploie avec sdx:results et donc avec l'ensemble des
				  <olink targetdocent="actions_requetes">actions d'exécution de requête </olink><sgmltag class="element">sdx:execute*Query</sgmltag> et
				  <olink localinfo="sdx_terms" targetdocent="actions_index"><sgmltag class="element">sdx:terms</sgmltag></olink>.</entry>
			 </row>
			 <row><entry colname="col1">Contenu éventuel</entry><entry colname="col2">Aucun.</entry>
			 </row></tbody>
		</tgroup>
	 </informaltable><table lang="fr" id="sdx_sort_param">
	 <title>Paramètres spécifiques</title>
	 <tgroup cols="3"><colspec colnum="1" colname="col1" colwidth="1.13*"/><colspec colnum="2" colname="col2" colwidth="4.26*"/><colspec colname="col3" colnum="3" colwidth="1.00*"/><thead>
		  <row><entry colname="col1">Nom</entry><entry colname="col2">Description</entry><entry colname="col3"></entry>
		  </row></thead><tbody>
		  <row><entry colname="col1"><sgmltag class="attribute">field</sgmltag></entry><entry colname="col2">Identifie le champ sur lequel on souhaite effectuer le tri.</entry><entry colname="col3">Obligatoire</entry>
		  </row>
		  <row><entry colname="col1"><sgmltag class="attribute">order</sgmltag></entry><entry colname="col2">Spécifie l'ordre de classement de la clé de tri : <sgmltag class="attvalue">ascendant</sgmltag> ou <sgmltag class="attvalue">descendant</sgmltag>. Par défaut, le tri est ascendant.</entry><entry colname="col3">Facultatif</entry>
		  </row></tbody>
	 </tgroup></table>
	 <example lang="fr" id="exemple_sdx_sort_01">
		<title>Double clé de tri</title>
		<para>Cette page XSP génère une requête dans l'index <literal>ville</literal>. Les résultats obtenus seront triés par nom de pays puis par nom de ville (si tant est que ces deux champs soient présents dans la page de résultat : attribut <sgmltag class="attribute">brief="true"</sgmltag> dans le fichier <filename>application.xconf</filename>) FIXME.</para>
		<programlisting>
&lt;sdx:page&gt;
 &lt;sdx:executeSimpleQuery field="ville" queryParam="question"&gt;
  &lt;sdx:sort field="pays" order="descendant"/&gt;
  &lt;sdx:sort field="ville" order="descendant"/&gt;
 &lt;/sdx:executeSimpleQuery&gt;
&lt;/sdx:page&gt;
</programlisting>
	 </example>
  </section>
  <section lang="fr" id="sdx_sorts">
	 <title><sgmltag class="element">sdx:sorts</sgmltag></title>
	 <para><sgmltag class="element">sdx:sorts</sgmltag> est le conteneur multiple de
		<ulink url="#sdx_sort"><sgmltag class="element">sdx:sort</sgmltag></ulink>. Il permet également de passer dynamiquement de multiples paramètres de tri dans une URL.</para>
	 <informaltable lang="fr">
		<tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="*"/><colspec colnum="2" colname="col2" colwidth="*"/><tbody>
			 <row><entry colname="col1">Code implémentant cette action</entry><entry colname="col2"><filename>sdx-queries.xsl</filename></entry>
			 </row>
			 <row><entry colname="col1">Contexte d'utilisation</entry><entry colname="col2"><sgmltag class="element">sdx:sort</sgmltag> s'emploie avec sdx:results et donc avec l'ensemble des
				  <olink targetdocent="actions_requetes">actions d'exécution de requête </olink><sgmltag class="element">sdx:execute*Query</sgmltag> et
				  <olink localinfo="sdx_terms" targetdocent="actions_index"><sgmltag class="element">sdx:terms</sgmltag></olink>.</entry>
			 </row>
			 <row><entry colname="col1">Contenu éventuel</entry><entry colname="col2">Un ou plusieurs
				  <ulink url="#sdx_sort"><sgmltag class="element">sdx:sort</sgmltag></ulink>.</entry>
			 </row></tbody>
		</tgroup>
	 </informaltable>
	 <table lang="fr" id="sdx_sorts_param">
	 <title>Paramètres spécifiques</title>
	 <tgroup cols="3"><colspec colnum="1" colname="col1" colwidth="1.13*"/><colspec colnum="2" colname="col2" colwidth="4.26*"/><colspec colname="col3" colnum="3" colwidth="1.00*"/><thead>
		  <row><entry colname="col1">Nom</entry><entry colname="col2">Description</entry><entry colname="col3"></entry>
		  </row></thead><tbody>
		  <row><entry colname="col1"><sgmltag class="attribute">sf</sgmltag></entry><entry colname="col2">Identifie le champ sur lequel on souhaite effectuer le tri.</entry><entry colname="col3">Obligatoire</entry>
		  </row>
		  <row><entry colname="col1"><sgmltag class="attribute">so</sgmltag></entry><entry colname="col2">Spécifie l'ordre de classement de la clé de tri : <sgmltag class="attvalue">ascendant</sgmltag> ou <sgmltag class="attvalue">descendant</sgmltag>. Par défaut, le tri est ascendant..</entry><entry colname="col3">Facultatif</entry>
		  </row></tbody>
	 </tgroup></table>
	 <example lang="fr">
		<title>Clé de tri double en paramètre dynamique</title>
		<para>La page XSP suivante : </para>
		<programlisting>
&lt;sdx:page&gt;
 &lt;sdx:executeSimpleQuery
  field="ville"
  queryParam="question"
  baseParam="base"
  sfParam="sortfield"
  soParam="sortorder"
 /&gt;
&lt;/sdx:page&gt;
</programlisting>
		<para>permet de récupérer un résultat trié selon les mêmes clés de tri que dans l'exemple précédent au moyen de l'URL <literal>{serveur SDX}/sdxtest/ss.xsp?1=docs&amp;2=france&amp;3=pays&amp;4=descendant&amp;3=ville&amp;4=descendant</literal>.</para>
	 </example>
  </section>
  <section lang="fr" id="sdx_navigation">
	 <title><sgmltag class="element">sdx:navigation</sgmltag></title>
	 <para>En relation avec la lecture d'un document XML, SDX offre des fonctions de navigation au sein des résultats d'une requête. Le développeur d'application peut ainsi permettre au lecteur de naviguer littéralement d'un document à un autre suivant un système de document précédent-suivant.</para>
	 <table lang="fr" id="sdx_navigation_param">
	 <title>Paramètre spécifique</title>
	 <tgroup cols="3"><colspec colnum="1" colname="col1" colwidth="1.92*"/><colspec colnum="2" colname="col2" colwidth="5.88*"/><colspec colname="col3" colnum="3" colwidth="1.00*"/><thead>
		  <row><entry colname="col1">Nom</entry><entry colname="col2">Description</entry><entry colname="col3"></entry>
		  </row></thead><tbody>
		  <row><entry colname="col1"><sgmltag class="attribute">qid</sgmltag></entry><entry colname="col2">Identifiant de la requête.</entry><entry colname="col3">Obligatoire</entry>
		  </row>
		  <row><entry colname="col1"><sgmltag class="attribute">no</sgmltag></entry><entry colname="col2">Identifiant d'un résultat dans une requête</entry><entry colname="col3">Obligatoire</entry>
		  </row>
		  <row><entry colname="col1"><sgmltag class="attribute">n</sgmltag></entry><entry colname="col2"><emphasis role="bold">Déprécié</emphasis>
				<para>Identifiant d'un résultat dans une requête.</para>
			 </entry><entry colname="col3">&#160;</entry>
		  </row>
		</tbody>
	 </tgroup></table>
	 <para>L'action <sgmltag class="element">sdx:navigation</sgmltag> n'emploie aucun paramètre commun.</para>
	 <para>Un exemple de l'utilisation de <sgmltag class="element">sdx:navigation</sgmltag> est proposé avec l'action
		<olink localinfo="exemple_includedocument_01" targetdocent="actions_recuperation"><sgmltag class="element">sdx:includeDocument</sgmltag></olink>.</para>
  </section>

</webpage>
