<?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_requetes SYSTEM "actions_requetes.xml" NDATA XML>
<!ENTITY actions_recuperation SYSTEM "actions_recuperation.xml" NDATA XML>
<!ENTITY multilinguisme SYSTEM "../introduction/multilinguisme.xml" NDATA XML>
]>
<webpage id="actions_generalites" xmlns:html="http://www.w3.org/1999/xhtml" xmlns:rddl="http://www.rddl.org/" xmlns:xlink="http://www.w3.org/1999/xlink">
  <head>
    <title lang="fr">Structure d'une XSP et généralités</title>
    <titleabbrev lang="fr">Structure</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>2003-06-10</date>
      </revision>
    </revhistory>
  </head>
  <itemizedlist>
    <title>Liste des actions décrites dans cette page : </title>
    <listitem>
      <para><ulink url="#sdx_page"><sgmltag class="element">sdx:page</sgmltag></ulink> ; </para>
    </listitem>
    <listitem>
      <para><ulink url="#sdx_debug"><sgmltag class="element">sdx:debug</sgmltag></ulink>.</para>
    </listitem>
  </itemizedlist>
  <section id="sdx_page" lang="fr">
    <title><sgmltag class="element">sdx:page</sgmltag></title>
    <section id="sdx_page_desc">
      <title>Description</title>
      <para><sgmltag class="element">sdx:page</sgmltag> est l'élément primaire de l'API-XSP de SDX. Il crée un document SDX (i.e. un élément <sgmltag class="element">sdx:document</sgmltag>) dans laquelle seront traités n'importe quels éléments l'API-XSP ou autre — c'est le seul éléments de l'API-XSP de SDX qui le permet.</para>
      <para>C'est <sgmltag class="element">sdx:page</sgmltag> qui déclenche toutes les actions permettant d'initialiser les variables et les paramètres par défaut (comme <sgmltag class="attribute">hpp</sgmltag> par exemple). Corollaire : il est possible de modifier certains comportements par défaut de SDX en changeant les paramètres par défaut dans le fichier <filename>sdx.xsl</filename> de la logicsheet.</para>
      <informaltable>
        <tgroup cols="2">
          <colspec colname="col1" colnum="1" colwidth="1.00*"/>
          <colspec colname="col2" colnum="2" colwidth="3.16*"/>
          <tbody>
            <row>
              <entry colname="col1">Code implémentant cette action</entry>
              <entry colname="col2"><filename>sdx.xsl</filename></entry>
            </row>
            <row>
              <entry colname="col1">Contexte d'utilisation</entry>
              <entry colname="col2">Elément fils de <sgmltag class="element">xsp:page</sgmltag>.</entry>
            </row>
            <row>
              <entry colname="col1">Contenu éventuel</entry>
              <entry colname="col2">N'importe quel élément <sgmltag class="element">sdx:*</sgmltag> ou autre.</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </section>
    <section id="sdx_page_param">
      <title>Paramètres</title>
      <table id="sdx_page_param_comm">
        <title>Paramètres communs</title>
        <tgroup cols="4">
          <colspec colname="col1" colnum="1" colwidth="1.69*"/>
          <colspec colname="col2" colnum="2" colwidth="7.05*"/>
          <colspec colname="col3" colnum="3" colwidth="1.70*"/>
          <colspec colname="col4" colnum="4" 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">show</entry>
              <entry colname="col2"> Ce paramètre permet de définir le résumé des informations de l'environnement dans lequel la page SDX est utilisée. Les valeurs autorisées : <sgmltag class="attvalue">session</sgmltag>, <sgmltag class="attvalue">get</sgmltag>, <sgmltag class="attvalue">post</sgmltag>, <sgmltag class="attvalue">put</sgmltag>, <sgmltag class="attvalue">headers</sgmltag>, <sgmltag class="attvalue">application</sgmltag>, <sgmltag class="attvalue">user</sgmltag>. Par défaut, SDX renvoie les informations concernant l'utilisateur et les paramètres HTPP (show="user get").<variablelist>
                  <varlistentry>
                    <term>session</term>
                    <listitem>
                      <para>Résume les paramètres Session dans des éléments <sgmltag class="element">sdx:parameter type="session"</sgmltag>, fils de <sgmltag class="element">sdx:parameters</sgmltag>.</para>
                    </listitem>
                  </varlistentry>
                  <varlistentry>
                    <term>get</term>
                    <listitem>
                      <para>Résume les paramètres HTTP (e.g. index.xsp?base=docs) dans des éléments <sgmltag class="element">sdx:parameter type="get"</sgmltag>, fils de <sgmltag class="element">sdx:parameters</sgmltag>.</para>
                    </listitem>
                  </varlistentry>
                  <varlistentry>
                    <term>post</term>
                    <listitem>
                      <para>Résume les paramètres envoyé par un formulaire avec la methode "POST" dans des éléments <sgmltag class="element">sdx:parameter type="post"</sgmltag>, fils de <sgmltag class="element">sdx:parameters</sgmltag>.</para>
                    </listitem>
                  </varlistentry>
                  <varlistentry>
                    <term>user</term>
                    <listitem>
                      <para>Résume les informations sur l'utilisateur courant dans un élément <sgmltag class="element">sdx:user</sgmltag>.</para>
                    </listitem>
                  </varlistentry>
                  <varlistentry>
                    <term>headers</term>
                    <listitem>
                      <para>Résume les informations de l'environnement dans lequel la page XSP est activée telles que le type de navigateur, l'adresse de l'hôte, la langue acceptée par le navigateur, dans des éléments <sgmltag class="element">sdx:parameter type="header"</sgmltag>, fils de <sgmltag class="element">sdx:parameters</sgmltag>.</para>
                    </listitem>
                  </varlistentry>
                </variablelist></entry>
              <entry colname="col3"><sgmltag class="element">sdx:init</sgmltag></entry>
              <entry colname="col4">Facultatif</entry>
            </row>
            <row>
              <entry colname="col1">lang</entry>
              <entry colname="col2">Le paramètre de la langue est très important dans SDX (voir le chapitre  <olink><citetitle>SDX et le multilinguisme</citetitle></olink> pour approfondir cette notion). SDX contrôle d'abord la définition d'une langue en paramètre (<sgmltag class="element">sdx:parameter</sgmltag>), sinon il emploie un élément <sgmltag class="element">xml:lang lang=""</sgmltag> présent dans la page.</entry>
              <entry colname="col3"><sgmltag class="element">sdx:init</sgmltag></entry>
              <entry colname="col4">Facultatif</entry>
            </row>
          </tbody>
        </tgroup>
      </table>
    </section>
    <section id="sdx_page_exemple">
      <title>Exemple</title>
      <example>
        <title>Une page SDX simple</title>
        <para>Soit la page XSP suivante : </para>
        <programlisting>
&lt;xsp:page
 xmlns:xsp="http://appache.org/xsp"
 xmlns:sdx="http://www.culture.gouv.fr/ns/sdx/sdx"
 xmlns="http://www.culture.gouv.fr/ns/sdx/sdx"
 langage="java"
&gt;

 &lt;xsp:logicsheet
  location="sdxtest/conf/logicsheets/xsp-sdxtest.xsl"
 /&gt;
 &lt;xsp:logicsheet
  location="sdxtest/conf/logicsheets/xsp-navigation.xsl"
 /&gt;

 &lt;sdx:page langSession="l" langParam="l"&gt;
  &lt;message_accueil/&gt;
 &lt;/sdx:page&gt;

&lt;/xsp:page&gt;
</programlisting>
        <para>L'XML virtuel généré et prêt à être transformé : </para>
        <programlisting>
&lt;sdx:document
 xmlns:xsp="http://appache.org/xsp"
 xmlns:sdx="http://www.culture.gouv.fr/ns/sdx/sdx" 	
 xml:lan="fr-FR"
 server="localhost:8080/sdx"
 api-url="http://localhost:8080/sdx/sdx/api-url"
 app="fr.culture.sdx.sdxtest"
 appbypath="sdxtest"
 uri="http://localhost:8080/sdx/sdxtest/accueil.xsp"
 version="2.1"
 build="20030603"
 date="Tue Jun 30 12:46:32 CEST 2003"
&gt;

 &lt;message_accueil/&gt;

 &lt;sdx:user
  id="utilisateur01"
  firstname="Nom"
  lastname="Prénom"
  admin="false"
  email="id@mail"
  app="fr.culture.sdx.sdxtest"
  ip="127.0.0.1"
  host="localhost"
  xml:lang="fr"
 &gt;

  &lt;sdx:group id="lecteurs /&gt;

 &lt;/sdx:user&gt;

 &lt;sdx:parameters&gt;
  &lt;sdx:parameter 
    type="session" 
    name="lang" value="fr"
  /&gt;
  &lt;sdx:parameter 
    type="session"
    name="sdx_qi"
    value="q10"
  /&gt;
  &lt;sdx:parameter 
    type="session"
    name="sdx_user"
    value="fr.gouv.culture.sdx.user.UserInformation@1469c9"
  /&gt;
  &lt;sdx:parameter 
    type="session"
    name="sdx_q7"
    value="fr.gouv.culture.sdx.search.lucene.query.Results@141038c"
  /&gt;
  &lt;sdx:parameter 
    type="header"
    name="accept"
    value="image/gif, image/x-xbitmap, image/jpeg, ..."
  /&gt;
  &lt;sdx:parameter 
    type="header"
    name="referer"
    value="http://localhost:8080/sdx/sdxtest/accueil.xsp"
  /&gt;
  &lt;sdx:parameter 
    type="header"
    name="accept-language"
    value="fr"
  /&gt;
  &lt;sdx:parameter 
    type="header"
    name="user-agent"
    value="Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1"...
  /&gt;
  &lt;sdx:parameter 
    type="header"
    name="host"
    value="localhost:8080"
  /&gt;
  &lt;sdx:parameter 
    type="header"
    name="connection"
    value="Keep-Alive"
  /&gt;
  &lt;sdx:parameter 
    type="header"
    name="cookie"
    value="edit-false; JSESSIONID=..."
  /&gt;
 &lt;/sdx:parameters&gt;

&lt;/sdx:document&gt;
</programlisting>
        <para>Autrement dit, en-dehors d'un élément vide <sgmltag class="element">message_accueil</sgmltag>, on trouve tout un panel d'information sur l'environnement dans lequel la page SDX est activée (voir la description du  <ulink url="#sdx_page_param">paramètre show</ulink>).</para>
      </example>
    </section>
  </section>
  <section id="sdx_debug" lang="fr">
    <title><sgmltag class="element">sdx:debug</sgmltag></title>
    <para><sgmltag class="element">sdx:debug</sgmltag> est une action importante de l'API-XSP de SDX pour tout développeur d'application. Chargée d'offrir des informations de débogage sur toutes les actions SDX, elle se veut une aide à la construction d'application. Son utilisation est des plus simples. Il suffit d'englober les actions que l'on souhaite déboguer avec <sgmltag class="element">sdx:debug</sgmltag> dans la page XSP. Le flux XML (le XML virtuel généré par une page XSP) portera un surplus d'information sur les actions mentionnées.</para>
    <informaltable>
      <tgroup cols="2">
        <colspec colname="col1" colnum="1" colwidth="1.00*"/>
        <colspec colname="col2" colnum="2" colwidth="2.90*"/>
        <tbody>
          <row>
            <entry colname="col1">Code implémentant cette action</entry>
            <entry colname="col2"><filename>sdx.xsl</filename></entry>
          </row>
          <row>
            <entry colname="col1">Contexte d'utilisation</entry>
            <entry colname="col2">N'importe où dans <sgmltag class="element">sdx:page</sgmltag>. <sgmltag class="element">sdx:debug</sgmltag> englobe les actions que l'on souhaite déboguer.</entry>
          </row>
          <row>
            <entry colname="col1">Contenu éventuel</entry>
            <entry colname="col2">N'importe quel élément <sgmltag class="element">sdx:*</sgmltag> ou autre.</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
    <para>sdx:debug ne comporte aucun paramètre en particulier. Elle en traite un très grand nombre, différents pour chaque action que l'on souhaite déboguer.</para>
    <example id="exemple_sdx_hilite_01" lang="fr">
      <title>Activer la mise en évidence sur une ancienne requête</title>
      <para>Dans l'exemple suivant, on cherche à obtenir des informations de débogage sur l'action  <olink localinfo="sdx_executefieldquery" targetdocent="actions_requetes"><sgmltag class="element">sdx:executeFieldQuery</sgmltag></olink> mise en oeuvre.</para>
      <programlisting>
&lt;sdx:page&gt;
 &lt;sdx:debug&gt;
  &lt;sdx:executeFieldQuery 
     field="sdxdocid" 
     valueParam="id" 
     hpp="1" 
     docs="true" 
     hiliteParam="qid"&gt; 
 &lt;/sdx:debug&gt;
&lt;/sdx:page&gt;
</programlisting>
      <para>Noter le caractère peu orthodoxe de l'emploie de  <olink localinfo="sdx_executefieldquery" targetdocent="actions_requetes"><sgmltag class="element">sdx:executeFieldQuery</sgmltag></olink> dans cette page XSP. L'action est <emphasis role="italic">détournée</emphasis> de son utilisation d'origine (dresser la liste des documents contenant une certaine valeur dans un champ) pour inclure un document XML comme le ferait  <olink localinfo="sdx_includedocument"><sgmltag class="element">sdx:includeDocument</sgmltag></olink>.</para>
      <para>L'intérêt d'employer  <olink localinfo="sdx_executefieldquery" targetdocent="actions_requetes"><sgmltag class="element">sdx:executeFieldQuery</sgmltag></olink> est d'offrir au lecteur la possibilité de naviguer depuis n'importe résultat de requête vers n'importe quel autre résultat (du document numéro 2 de la requête <literal>q14</literal> vers la document numéro 24 de la même requête).  <olink localinfo="sdx_includedocument"><sgmltag class="element">sdx:includeDocument</sgmltag></olink>, qui inclue également des outils de navigation, ne permet effectivement que de naviguer avec un pas supérieur à 1 (depuis le document numéro 2 de la requête <literal>q14</literal>, on ne peut se rendre qu'aux documents numéros 1 et 3 de cette même requête).</para>
    </example>
  </section>
</webpage>
