<?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_indexation SYSTEM "actions_indexation.xml" NDATA XML>
  <!ENTITY actions_localisation SYSTEM "actions_localisation.xml" NDATA XML>
  <!ENTITY actions_requetes SYSTEM "actions_requetes.xml" NDATA XML>
  <!ENTITY ations_generalites SYSTEM "actions_generalites.xml" NDATA XML>
  <!ENTITY pages_xsp SYSTEM "xsp.xml" NDATA XML>
  <!ENTITY parametres_sdx SYSTEM "parametres_sdx.xml" NDATA XML>
]>

<webpage id="actions_recuperation">

  <head>
	 <title lang="fr">Affichage des documents</title>
	 <titleabbrev lang="fr">Documents</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-11-26</date>
		</revision>
	 </revhistory>
  </head>

  <itemizedlist>
	 <title>Liste des actions décrites dans cette page : </title>
	 <listitem>
		<para><ulink url="#sdx_includedocument"><sgmltag class="element">sdx:includeDocument</sgmltag></ulink> ; </para>
	 </listitem><listitem>
		<para><ulink url="#sdx_show"><sgmltag class="element">sdx:show</sgmltag></ulink>.</para>
	 </listitem>
  </itemizedlist>
  <section id="concepts" lang="fr">
	 <title>Concepts clés</title>
	 <para>La recherche documentaire au sein d'une collection de documents XML est la fonction première de SDX. Si l'affichage de ces documents est une fonction secondaire, elle demeure relativement incontournable.</para>
	 <para>SDX offre une action permettant l'inclusion d'un document XML dans une page (cf.
		<olink targetdocent="actions_localisation" localinfo="sdx_page"><sgmltag class="element">sdx:page</sgmltag></olink> sur la notion de page SDX) :
		<ulink url="#sdx_includedocument"><sgmltag class="element">sdx:includeDocument</sgmltag></ulink>. Le document est offert tel quel ; c'est-à-dire comme un ensemble d'éléments (au sens XML du terme). Ce système simple présente un intérêt majeur puisqu'il permet de travailler le document dynamiquement. Plusieurs styles d'affichage peuvent donc être définis. Par exemple, on peut masquer une partie du document suivant l'identité de l'utilisateur courant ou simplement modifier l'organisation des informations. Bref, c'est toute la puissance du couple XML/XSLT qui est offerte ici.</para>
	 <para>En relation avec la lecture d'un document XML issus d'une requête, SDX offre des fonctions de navigation au sein des résultats (cf.
		<olink localinfo="sdx_navigation" targetdocent="actions_controle"><sgmltag class="element">sdx:navigation</sgmltag></olink>). 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>
  </section>
  <section lang="fr" id="sdx_includedocument">
	 <title><sgmltag class="element">sdx:includeDocument</sgmltag></title>
	 <para>L'action <sgmltag class="element">sdx:includeDocument</sgmltag> permet d'inclure un document dans une page SDX. Le document est offert tel quel ; c'est-à-dire comme un ensemble d'éléments (au sens XML du terme). Ce système simple présente un intérêt majeur puisqu'il permet de travailler le document dynamiquement. Plusieurs styles d'affichage peuvent donc être définis. Par exemple, on peut masquer une partie du document suivant l'identité de l'utilisateur courant ou simplement modifier l'organisation des informations. Bref, c'est toute la puissance du couple XML/XSLT qui est offerte ici.</para>
	 <para>La seule condition nécessaire à l'utilisation de cette action est de connaître l'identifiant du document (<sgmltag class="attribute">id</sgmltag>). Dans certains cas, il peut être nécessaire de préciser l'application (<sgmltag class="attribute">app</sgmltag>) et la base de documents (<sgmltag class="attribute">base</sgmltag>) gérant le document.</para>
	 <informaltable lang="fr">
		<tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="1.00*"/><colspec colnum="2" colname="col2" colwidth="2.48*"/><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 un
				  <olink targetdocent="ations_generalites" localinfo="sdx_page"><sgmltag class="element">sdx:page</sgmltag></olink>.</entry>
			 </row>
			 <row><entry colname="col1">Contenu éventuel</entry><entry colname="col2">Aucun.</entry>
			 </row></tbody>
		</tgroup>
	 </informaltable>
	 <table id="sdx_includedocument_param_comm">
	 <title>Paramètres communs</title>
	 <tgroup cols="4"><colspec colnum="1" colname="col1" colwidth="1.70*"/><colspec colnum="2" colname="col2" colwidth="3.28*"/><colspec colnum="3" colname="col3" colwidth="2.72*"/><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">base</sgmltag></entry><entry colname="col2">Identifiant de la base de documents.</entry><entry colname="col3"><olink targetdocent="actions_localisation" localinfo="sdx_base"><sgmltag class="element">sdx:base</sgmltag></olink></entry><entry colname="col4">Facultatif</entry>
		  </row>
		  <row><entry colname="col1"><sgmltag class="attribute">id</sgmltag></entry><entry colname="col2">Identifiant du document.</entry><entry colname="col3"><olink targetdocent="actions_localisation" localinfo="sdx_id"><sgmltag class="element">sdx:id</sgmltag></olink></entry><entry colname="col4">Obligatoire</entry>
		  </row>
		  <row><entry colname="col1"><sgmltag class="attribute">attid</sgmltag></entry><entry colname="col2">Identifiant</entry><entry colname="col3"><olink targetdocent="actions_localisation" localinfo="sdx_id"><sgmltag class="element">sdx:id</sgmltag></olink></entry><entry colname="col4">Facultatif</entry>
		  </row>
		  <row><entry colname="col1"><sgmltag class="attribute">qid</sgmltag></entry><entry colname="col2">Identifiant de la requête.</entry><entry colname="col3"><olink targetdocent="actions_controle" localinfo="sdx_navigation"><sgmltag class="element">sdx:navigation</sgmltag></olink></entry><entry colname="col4">Facultatif</entry>
		  </row>
		  <row><entry colname="col1"><sgmltag class="attribute">no</sgmltag></entry><entry colname="col2">Identifiant du résultat au sein de la requête.</entry><entry colname="col3"><olink targetdocent="actions_controle" localinfo="sdx_navigation"><sgmltag class="element">sdx:navigation</sgmltag></olink></entry><entry colname="col4">Facultatif</entry>
		  </row>
		  <row><entry colname="col1"><sgmltag class="attribute">hilite</sgmltag></entry><entry colname="col2">Paramètre gérant la lise en surbrillance du (des) terme(s) de la requête. Les valeur autorisées sont <sgmltag class="attvalue">true</sgmltag> et <sgmltag class="attvalue">false</sgmltag>.</entry><entry colname="col3"><sgmltag class="element">sdx:hilite</sgmltag></entry><entry colname="col4">Facultatif</entry>
		  </row></tbody>
	 </tgroup></table>
	 <example lang="fr" id="exemple_includedocument_01">
		<title>Inclure un document dans une page SDX</title>
		<para>L'exemple suivant est une page XSP dans laquelle on demande l'inclusion d'un document XML. Le choix du conteneur de ce document (ici <sgmltag class="element">document</sgmltag>) est complètement arbitraire.</para>
		<programlisting>
&lt;sdx:page&gt;
  &lt;document&gt;
    &lt;sdx:includeDocument idParam="id" baseParam="base"/&gt;
  &lt;/document&gt;
&lt;/sdx:page&gt;
</programlisting>
		<para>Voici le XML virtuel généré par cette page XSP : </para>
		<programlisting>
&lt;sdx:page&gt;
  &lt;document&gt;
    &lt;article id="F1614199900014"&gt;
     &lt;articleinfo&gt;...&lt;/articleinfo&gt;
     &lt;section&gt;
      &lt;para&gt;...&lt;/para&gt;
      &lt;mediaobject&gt;...&lt;/mediaobject&gt;
     &lt;/section&gt;
    &lt;/article&gt;
  &lt;/document&gt;
&lt;/sdx:page&gt;
</programlisting>
	 </example>
	 <example id="exemple_sdx_includedocument_02">
		<title>Afficher un document issu d'une requête</title>
		<para>Dans l'exemple suivant, on affiche un document issu d'une requête. L'élément <sgmltag class="element">sdx:hilite</sgmltag> permet de passer l'information nécessaire pour la mise en surbrillance du ou des termes de la requête. Noter que l'élément <sgmltag class="element">sdx:includeDocument</sgmltag> de la page XSP demandait l'activation de cette option.</para>
		<programlisting>
&lt;sdx:page&gt;
 &lt;document&gt;

  &lt;sdx:includeDocument
    idParam="id"
    qidParam="qid"
    noParam="n"
    hilite="true"
  /&gt;

  &lt;/document&gt;
&lt;/sdx:page&gt;
</programlisting>
		<para>Voici le résultat de l'URL <literal>{serveur SDX}/sdxtest/doc.xsp?id=F1614199900014&amp;qid=q0&amp;n=3</literal></para>
		<programlisting>
&lt;sdx:page&gt;
  &lt;document&gt;
    &lt;sdx:hilites&gt;
      &lt;sdx:term value="france"/&gt;
    &lt;/sdx:hilites&gt;
    &lt;article id="F1614199900014"&gt;
      ... &lt;sdx:hilite no="1" term="france"&gt;France&lt;sdx:hilite&gt; ...
    &lt;/article&gt;
    &lt;sdx:navigation qid="q0" page="1" no="3" queryId="q0" docNo="3"&gt;
      &lt;sdx:previous
        id="F1388199800042"
        base="docs"
        app="fr.culture.sdx.adfi"
        no="2"
        page="1"
        docId="F1388199800042"/&gt;
      &lt;sdx:next
        id="F1354199500011"
        base="docs"
        app="fr.culture.sdx.adfi"
        no="4"
        page="1"
        docId="F1354199500011"/&gt;
    &lt;/sdx:navigation&gt;
  &lt;/document&gt;
&lt;/sdx:page&gt;
</programlisting>
	 </example>
  </section>
  <section lang="fr" id="sdx_show">
	 <title><sgmltag class="element">sdx:show</sgmltag>(CHECK)</title>
	 <para>Comme il a été dit dans l'introduction de cette page, sdx:show n'est pas une action SDX à proprement parlé. Elle offre des
		<olink targetdocent="parametres_sdx">paramètres SDX</olink> utilisables par des actions (généralement des
		<olink targetdocent="actions_requetes">actions de recherche</olink>). Le résultat demeure le même qu'en utilisant
		<ulink url="#sdx_includedocument"><sgmltag class="element">sdx:includeDocument</sgmltag></ulink> : le document est inclus dans le XML virtuel prêt à être transformé et affiché dans le navigateur (voir la section
		<olink targetdocent="pages_xsp">Pages XSP</olink> pour approfondir la notion de génération/transformation/sérialisation).</para>
	 <informaltable lang="fr">
		<tgroup cols="2"><colspec colnum="1" colname="col1" colwidth="1.00*"/><colspec colnum="2" colname="col2" colwidth="3.25*"/><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">sdx:show et ses paramètres spécifiques peuvent peuvent être employés dans
				  <olink localinfo="sdx_deletedocuments" targetdocent="actions_indexation"><sgmltag class="element">sdx:deleteDocuments</sgmltag></olink> et avec l'ensemble des
				  <olink targetdocent="actions_requetes">actions de recherche</olink>.</entry>
			 </row>
			 <row><entry colname="col1">Contenu éventuel</entry><entry colname="col2">Aucun.</entry>
			 </row></tbody>
		</tgroup>
	 </informaltable><table lang="fr" id="sdx_show_param">
	 <title>Paramètres spécifiques</title>
	 <tgroup cols="3"><colspec colnum="1" colname="col1" colwidth="1.00*"/><colspec colnum="2" colname="col2" colwidth="10.05*"/><colspec colname="col3" colnum="3" colwidth="2.07*"/><thead>
		  <row><entry colname="col1">Nom</entry><entry colname="col2">Description</entry><entry colname="col3"></entry>
		  </row></thead><tbody>
		  <row><entry colname="col1">docs</entry><entry colname="col2">Paramètre gérant l'inclusion des documents dans la liste des résultats. Les valeurs autorisées sont <sgmltag class="attvalue">true</sgmltag> ou <sgmltag class="attvalue">false</sgmltag>.</entry><entry colname="col3">Obligatoire</entry>
		  </row>
		  <row><entry colname="col1">no</entry><entry colname="col2">Numéro du résultat que l'on souhaite afficher.</entry><entry colname="col3">Obligatoire</entry>
		  </row>
		  <row><entry colname="col1">n</entry><entry colname="col2"><emphasis role="italic">Idem</emphasis>. <emphasis role="bold">Déprécié</emphasis></entry><entry colname="col3"></entry>
		  </row>
		  <row><entry colname="col1">page</entry><entry colname="col2">Numéro de la page que l'on souhaite afficher.</entry><entry colname="col3">Obligatoire</entry>
		  </row>
		  <row><entry colname="col1">p</entry><entry colname="col2"><emphasis role="italic">Idem</emphasis>. <emphasis role="bold">Déprécié</emphasis></entry><entry colname="col3"></entry>
		  </row>
		</tbody>
	 </tgroup></table>
  </section>

</webpage>
