<?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_generalites SYSTEM "actions_generalites.xml" NDATA XML>
  <!ENTITY actions_localisation SYSTEM "actions_localisation.xml" NDATA XML>
  <!ENTITY actions_recuperation SYSTEM "actions_recuperation.xml" NDATA XML>
  <!ENTITY actions_amender SYSTEM "actions_amender.xml" NDATA XML>
  <!ENTITY actions_requetes SYSTEM "actions_requetes.xml" NDATA XML>
  <!ENTITY actions_parametres SYSTEM "actions_parametres.xml" NDATA XML>
  <!ENTITY indexation SYSTEM "actions_indexation.xml" NDATA XML>
]>
<webpage id="actions_index">

  <head>
    <title lang="fr">Contenu d'index</title>
    <titleabbrev lang="fr">Index</titleabbrev>
    <author lang="fr">
      <firstname>Malo</firstname>
      <surname>Pichot</surname>
      <affiliation>
        <orgname>AJLSM</orgname>
      </affiliation>
    </author>
    <revhistory>
      <revision lang="fr">
        <revnumber>1.1</revnumber>
        <date>2005-03-22</date>
      </revision>
    </revhistory>
  </head>

  <itemizedlist>
    <title>Liste des actions décrites dans cette page : </title>
    <listitem>
      <para>
        <ulink url="#sdx_terms">
          <sgmltag class="element">sdx:terms</sgmltag>
        </ulink>.</para>
    </listitem>
  </itemizedlist>
  <para lang="fr">Si cette section ne se trouve pas dans le chapitre
    <olink targetdocent="indexation">indexation</olink>, c'est que les actions décrites ici sont en réalité des requêtes exécutées dans les index d'une base de document.</para>
  <section lang="fr" id="sdx_terms">
    <title>
      <sgmltag class="element">sdx:terms</sgmltag>
    </title>
    <para>
      <sgmltag class="element">sdx:terms</sgmltag> permet de retirer la liste des termes d'un index. Il s'agit donc d'une requête à part entière. </para>
    <para>Si <sgmltag class="element">sdx:terms</sgmltag> peut s'employer tel quel dans une page XSP, elle admet un certain nombre de paramètres permettant d'affiner la requête. De même qu'il est possible de retirer l'ensemble des termes d'un index, on peut ainsi choisir de filtrer les résultats, d'affiner la recherche.</para>
    <note id="sdx_terms_note01" lang="fr">
      <para>Attention, depuis la version 2.2, le résultat d'une requête sur un index a changé : le nom  du champ interrogé se situe désormais dans l'attribut <sgmltag class="attribute">field</sgmltag> de l'élément <sgmltag class="element">sdx:terms</sgmltag>.</para>
      <para>Pour des raisons de compatibilité avec les applications existantes, l'attribut <sgmltag class="attribute">field</sgmltag> se trouve également dans les <sgmltag class="element">sdx:term</sgmltag>, fils de <sgmltag class="element">sdx:terms</sgmltag>. Il convient donc de ne pas en ternir compte pour les applications SDX développées à partir de la version 2.2 (cf. illustration donnée dans l'<ulink url="#exemple_sdx_terms_01">exemple suivant</ulink>).</para>
    </note>
    <para>
      Il est souvent intéressant de construire une liste de termes à partir du
      croisement de plusieurs index. On devrait naturellement se retourner vers
      l'élément <olink targetdocent="actions_amender" localinfo="sdx_filter"><sgmltag class="element">sdx:filter</sgmltag></olink> qui fait normalement
      ce travail avec l'ensemble des actions de requêtes. Malheureusement,
      <sgmltag class="element">sdx:terms</sgmltag> ne permet pas de l'utiliser.
      Malgré tout, on peut obtenir cette liste filtrée de 2 manière&#160;:
		</para>
		<variablelist>
			<varlistentry>
				<term>Couples champs/valeurs</term>
				<listitem><para>En construisant un ensemble de couples champs/valeurs grâce à l'élément <sgmltag class="element">sdx:parameter</sgmltag>
      ou les paramètres d'URL comme le présente l'<ulink url="#exemple_sdx_terms_04">exemple ci-dessous</ulink>.</para></listitem>
			</varlistentry>
			<varlistentry>
				<term>Filtrer sur un <olink localinfo="sdx_results" targetdocent="actions_controle"><sgmltag class="element">sdx:results</sgmltag></olink></term>
				<listitem><para>En utilisant le résultat d'un précédente requête grâce au paramètre <sgmltag class="attribute">bqid</sgmltag>. Dans ce cas, il est indispensable que le ou les champs sur lesquels on souhaite exécuter le <sgmltag class="element">sdx:terms</sgmltag> soient de type <literal>brief</literal>, c'est-à-dire qu'ils soient présent dans le résultat de requête (cf. <filename>application.xconf</filename>).</para></listitem>
			</varlistentry>
		</variablelist>
    <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-actions.xsl</filename>
            </entry>
          </row>
          <row>
            <entry colname="col1">Contexte d'utilisation</entry>
            <entry colname="col2">N'importe où dans une
              <olink targetdocent="actions_generalites" localinfo="sdx_page"><sgmltag class="element">sdx:page</sgmltag>
              </olink>.</entry>
          </row>
          <row>
            <entry colname="col1">Contenu éventuel</entry>
            <entry colname="col2">Une liste de champs valeurs construite à partir d'éléments
              <olink targetdocent="actions_parametres" localinfo="sdx_parameter">
                <sgmltag class="element">sdx:parameter</sgmltag>
              </olink> afin de retourner une liste de termes filtrée (cf. l'<ulink url="#exemple_sdx_terms_04">exemple ci-dessous</ulink>).
            </entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
    <table lang="fr" id="sdx_terms_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 que l'on désire interroger.</entry>
            <entry colname="col3">Obligatoire</entry>
          </row>
          <row>
            <entry colname="col1">
              <sgmltag class="attribute">f</sgmltag>
              <emphasis role="bold">Déprécié</emphasis>
            </entry>
            <entry colname="col2">
              <emphasis role="italic">Idem</emphasis>.</entry>
            <entry colname="col3">Obligatoire</entry>
          </row>
          <row>
            <entry colname="col1">
              <sgmltag class="attribute">value</sgmltag>
            </entry>
            <entry colname="col2">Identifie la valeur que l'on souhaite retrouver. Utilisé pour le cas où l'on cherche à filtrer la requête.</entry>
            <entry colname="col3">Facultatif</entry>
          </row>
          <row>
            <entry colname="col1">
              <sgmltag class="attribute">v</sgmltag>
              <emphasis role="bold">Déprécié</emphasis>
            </entry>
            <entry colname="col2">
              <emphasis role="italic">Idem</emphasis>.</entry>
            <entry colname="col3">Facultatif</entry>
          </row>
          <row>
            <entry colname="col1">
              <sgmltag class="attribute">qid</sgmltag>
            </entry>
            <entry colname="col2">Identifiant du <sgmltag class="element">sdx:terms</sgmltag>. Permet de récupérer un <sgmltag class="element">sdx:terms</sgmltag> caché ou tout simplement de forcer l'identifiant allouer au <sgmltag class="element">sdx:terms</sgmltag> courant.</entry>
            <entry colname="col3">Facultatif</entry>
          </row>
					<row>
            <entry colname="col1">
              <sgmltag class="attribute">bqid</sgmltag>
            </entry>
            <entry colname="col2">Identifiant du <sgmltag class="element">sdx:results</sgmltag> dans lequel on souhaite exécuter le <sgmltag class="element">sdx:terms</sgmltag>.</entry>
            <entry colname="col3">Facultatif</entry>
          </row>
          <row>
            <entry colname="col1">
              <sgmltag class="attribute">page</sgmltag>
            </entry>
            <entry colname="col2">Identifiant de la page.</entry>
            <entry colname="col3">Facultatif</entry>
          </row>
          <row>
            <entry colname="col1">
              <sgmltag class="attribute">p</sgmltag>
              <emphasis role="bold">Déprécié</emphasis>
            </entry>
            <entry colname="col2">Identifiant de la page.</entry>
            <entry colname="col3">Facultatif</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
    <table id="sdx_terms_param_comm">
      <title>Paramètres communs</title>
      <tgroup cols="4">
        <colspec colnum="1" colname="col1" colwidth="1.15*"/>
        <colspec colnum="2" colname="col2" colwidth="3.15*"/>
        <colspec colnum="3" colname="col3" colwidth="1.09*"/>
        <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">app</sgmltag>
            </entry>
            <entry colname="col2">Identifie l'application dans laquelle on souhaite effectuer l'interrogation. Par défaut, il s'agit de l'application courante.</entry>
            <entry colname="col3">
              <olink localinfo="sdx_app" targetdocent="actions_localisation">
                <sgmltag class="element">sdx:app</sgmltag>
              </olink>
            </entry>
            <entry colname="col4">Facultatif</entry>
          </row>
          <row>
            <entry colname="col1">
              <sgmltag class="attribute">base</sgmltag>
            </entry>
            <entry colname="col2">Identifie la base de documents dans laquelle on souhaite effectuer l'interrogation. Si non spécifiée, il s'agit de la base de documents par défaut.</entry>
            <entry colname="col3">
              <olink localinfo="sdx_base" targetdocent="actions_localisation">
                <sgmltag class="element">sdx:base</sgmltag>
              </olink>
            </entry>
            <entry colname="col4">Facultatif</entry>
          </row>
          <row>
            <entry colname="col1">
              <sgmltag class="attribute">repo</sgmltag>
            </entry>
            <entry colname="col2">Identifie l'entrepôt dans lequel on souhaite effectuer l'interrogation. Si non spécifié, il s'agit de l'entrepôt par défaut.</entry>
            <entry colname="col3">
              <olink localinfo="sdx_repo" targetdocent="actions_localisation">
                <sgmltag class="element">sdx:repo</sgmltag>
              </olink>
            </entry>
            <entry colname="col4">Facultatif</entry>
          </row>
          <row>
            <entry colname="col1">
              <sgmltag class="attribute">hpp</sgmltag>
            </entry>
            <entry colname="col2">Définit le nombre de résultats souhaités par page. Par défaut, le nombre est fixé à 20.</entry>
            <entry colname="col3">
              <olink localinfo="sdx_hpp" targetdocent="actions_controle">
                <sgmltag class="element">sdx:hpp</sgmltag>
              </olink>
            </entry>
            <entry colname="col4">Facultatif</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
    <example lang="fr" id="exemple_sdx_terms_01">
      <title>Lister l'ensemble des termes d'un index</title>
      <para>Dans l'exemple suivant, on demande la liste des termes d'un index. Celui-ci n'est pas spécifié directement dans la page. Il est passé dynamiquement dans l'URL : <literal>{serveur sdx}/sdx/sdxtest/terms.xsp?champ=commune&amp;base=docs</literal>
      </para>
      <programlisting>
&lt;sdx:page&gt;
  &lt;sdx:terms fieldParam="champ"/&gt;
&lt;/sdx:page&gt;
</programlisting>
      <para>Le résultat de la requête (i.e. le XML virtuel généré par cette page XSP) : </para>
      <programlisting>
...
  &lt;sdx:terms field="commune" qid="q4" page="1" hpp="20" pages="28" nb="554"
    start="1"
    end="20"
    id="q4"
    currentPage="1"
    nbPages="28"&gt;

    &lt;sdx:term no="1" value="Rennes" escapedValue="Rennes" field="commune"
      docs="1"
      id="F1980199800001"
      base="docs"
      app="fr.culture.sdx.adfi"
      docId="F1980199800001"
      docFreq="1"/&gt;

    &lt;sdx:term no="2" value="Nantes" escapedValue="Nantes" field="commune"
      docs="3"
      docFreq="3"/&gt;
    ...
  &lt;/sdx:terms&gt;
...
</programlisting>
      <para>Les résultats sont présentés dans un élément <sgmltag class="element">sdx:terms</sgmltag> portant plusieurs informations : le nom du champ interrogé, l'identifiant de la requête (<sgmltag class="attribute">qid</sgmltag>), le numéro de la page courante (<sgmltag class="attribute">page</sgmltag> et <sgmltag class="attribute">currentPage</sgmltag>), le nombre de résultats par page (<sgmltag class="attribute">hpp</sgmltag>), le nombre de pages contenant des résultats (<sgmltag class="attribute">pages</sgmltag> et <sgmltag class="attribute">nbPages</sgmltag>), le nombre total de résultats (<sgmltag class="attribute">nb</sgmltag>), le numéro du premier résultat (<sgmltag class="attribute">start</sgmltag>), celui du dernier (<sgmltag class="attribute">end</sgmltag>) dans la page.</para>
      <para>Chacun des résultats est présenté dans un élément <sgmltag class="element">sdx:term</sgmltag>. Dans l'exemple qui nous intéresse, le premier résultat identifie un seul document localisé sur la commune de Rennes (<literal>docFreq="1"</literal>). L'identifiant de ce document (<sgmltag class="attribute">id</sgmltag> et <sgmltag class="attribute">docId</sgmltag>) permettra de l'afficher à la demande (voir le chapitre sur l'<olink targetdocent="actions_recuperation">affichage de document</olink>).</para>
      <para>Le second résultat (<literal>no="2"</literal>) identifie trois documents localisés sur la commune de <literal>Nantes</literal>. Leur identifiant ne sont pas donnés dans le résultat ; il faudra effectuer une nouvelle interrogation afin de dresser la liste de ces documents (voir la section sur l'<olink targetdocent="actions_requetes">exécution d'une requête</olink> :
        <olink localinfo="sdx_executefieldquery" targetdocent="actions_requetes"><sgmltag class="element">sdx:executeFieldQuery</sgmltag>
        </olink>).</para>
      <para>Attention, des modifications ont été apportées dans le résultat d'une requête avec <sgmltag class="element">sdx:terms</sgmltag> depuis la version 2.2 de SDX, comme indiqué dans la <ulink url="#sdx_terms_note01">note précédente</ulink>.</para>
    </example>
    <example id="exemple_sdx_terms_02">
      <title>Filtrer une liste de termes d'un index</title>
      <para>Dans l'exemple suivant, on demande la liste complète des communes dont le nom commence par la lettre "<literal>A</literal>" : </para>
      <programlisting>
&lt;sdx:page&gt;
  &lt;sdx:terms field="commune" value="a*" hpp="-1"&gt;
    &lt;sdx:fallback&gt;
      &lt;xsl:message type="echec_requete"/&gt;
    &lt;/sdx:fallback&gt;
  &lt;/sdx:terms&gt;
&lt;/sdx:page&gt;
</programlisting>
    </example>
    <example id="exemple_sdx_terms_03">
      <title>Retourne le nombre de documents</title>
      <para>Dans l'exemple suivant, on cherche à retourner le nombre de documents indexés dans une base de documents :</para>
      <programlisting>
&lt;sdx:page&gt;
  &lt;sdx:terms
    field="sdxall"
    app="fr.sdx.test"
    base="sdxworld"&gt;
&lt;/sdx:page&gt;
</programlisting>
      <para>On obtient alors le résultat suivant :</para>
      <programlisting>
&lt;sdx:document ...&gt;
  &lt;sdx:terms qid="q28" ...&gt;
    &lt;sdx:term
      no="1"   
      value="1"
      escapedValue="1"
      field="sdxall"
      docs="12"
      docFreq="12"/&gt;
  &lt;/sdx:terms&gt;
&lt;/sdx:document&gt;
</programlisting>
      <para>Il nous apprend que 12 documents ont été indexés dans la base <literal>sdxworld</literal> de l'application identitiée par <literal>fr.sdx.test</literal>
      </para>
    </example>
    <example id="exemple_sdx_terms_04">
      <title>Construire une liste de termes filtrée</title>
      <para>Dans l'exemple suivant, on cherche à retourner les villes de la région Aquitaine&#160;:</para>
      <programlisting>
&lt;sdx:page&gt;
  &lt;sdx:terms&gt;
      &lt;sdx:parameter name="field" value="region" /&gt;
      &lt;sdx:parameter name="value" value="Aquitaine" /&gt;
      &lt;sdx:parameter name="field" value="ville" /&gt;
  &lt;/sdx:terms&gt;
&lt;/sdx:page&gt;
</programlisting>
      <para>L'ordre des couples champs/valeurs est important. Le dernier paramètre doit être un champs, non suivie de valeur.</para>
      <para>On peut obtenir le même résultat en utilisant les paramètres d'URL. On aura ainsi une XSP plus simple&#160;:</para>
      <programlisting>
&lt;sdx:page&gt;
  &lt;sdx:terms /&gt;
&lt;/sdx:page&gt;
</programlisting>
      <para>On utilisera une URL de ce type&#160;: <literal>http://[sdx]/[monapplication]/monxsp.xsp?field=region&amp;value=Aquitaine&amp;field=ville</literal></para>
    </example>
  </section>

</webpage>
