Outils pour utilisateurs

Outils du site


Panneau latéral

ref:xml_import:document

Importer un document

Un script d'import commence systématiquement par l'inclusion d'un ou plusieurs bindings permettant de définir les documents (et éventuellement autres objets) qui pourront être importés ainsi que les classes PHP correspondantes.

Exemple :

<binding fileName="modules/media/persistentdocument/import/media_binding.xml" />

On peut ensuite déclarer les documents à importer sous forme hiérarchisée.

Exemple :

<rootfolder module="media">
    <folder label="Exemple de media">
        <media path="framework/builder/webapp/media/backoffice/logo_change_only.png" label="RBS Change 4"/>
        <folder label="Logos">
            <media path="framework/builder/webapp/media/backoffice/change.png" label="Logo RBS Change 4"/>
        </folder>
    </folder>
</rootfolder>

Certains types de propriétés demandent un traitement particulier :

  • propriétés localisées (voir plus bas)
  • propriétés de type document (voir plus bas)
  • propriétés de type richtext ou XHTMLFragment (voir ici)

Faire référence à des documents

Principe général

Il est possible de faire référence à des documents importés précédemment. Pour cela il faut leur placer un attribut id qui permet de les identifier par la suite. Cet attribut peut être une chaîne de caractères quelconque à ceci près qu'elle ne doit pas ne comporter que des chiffres. Cet id est local au script d'import et ne doit pas être confondu avec l'id présent en base de données.

Une propriété de type document : il suffit de placer l'attribut maPropriete-refid=“maReference”. Ce mécanisme est implémenté en standard sur toutes les propriétés de type document sur des documents et sur des blocs également.

Exemple : Après avoir importé les média suivants :

<media path="modules/news/setup/sample/Anniversaire3.jpg" label="Anniversaire 3" id="photo1" />
<media path="modules/news/setup/sample/papillon_change.jpg" label="Papillon change" id="photo3" />
On peut importer l'actualité suivante :
<news listvisual-refid="photo3" detailvisual-refid="photo1" ... />

On peut également, pour les propriétés de type document multi-valuées, renseigner plusieurs valeurs à la fois via l'attribut maPropriete-refids=“ref1,ref2,ref3,…” (les différentes références aux documents à lier sont séparées par des virgules, sans espaces).

Par défaut on ne fera qu'ajouter les documents indiqués dans la propriété. À partir de la version 3.6.0, il est possible de vider la propriété en utilisant ==.

Exemple : Après avoir importé les média suivants :

<media path="modules/catalog/setup/book-catalog-sample/L1-1.jpg" byLabel="Windows Vista et Internet pour les Nuls (avant)" id="V-L1-1" />
<media path="modules/catalog/setup/book-catalog-sample/L1-2.jpg" byLabel="Windows Vista et Internet pour les Nuls (arrière)" id="V-L1-2" />
<media path="modules/catalog/setup/book-catalog-sample/L1-3.jpg" byLabel="Windows Vista et Internet pour les Nuls (sommaire)" id="V-L1-3" />

On peut importer les produits suivants :

<!-- Ajouter les documents V-L1-2 et V-L1-3 aux documents déjà présents dans la propriété. -->
<simpleproduct additionnalVisual-refids="V-L1-2,V-L1-3" ... />

<!-- Remplacer le contenu de la propriété par les documents V-L1-2 et V-L1-3 en ajoutant == devant. -->
<simpleproduct additionnalVisual-refids="==,V-L1-2,V-L1-3" ... />

Cela peut servir dans d'autres cas comme :

Retrouver un document en base

Il est possible de faire référence à des documents déjà présents dans la base de données.

Par une propriété

L'attribut XML byLabel (ou byXXX où XXX est une propriété du document) permet d'identifier un document par son label (la recherche est restreinte aux enfants de l'élément parent). Si le document n'est pas trouvé un nouveau document sera créé avec ce label.

Exemple : la ligne suivante permet de récupérer le dossier ayant le label “Exemple de media Actualité” directement enfant du dossier racine de la médiathèque :

<rootfolder module="media">
    <folder byLabel="Exemple de media Actualité" />
</rootfolder>

La requête est faite en tenant compte du document donné comme parent du document recherché dans le script. La restriction sur le parent est calculée de la manière suivante :

Jusqu'à la version 3.5.2 incluse :

  1. si le parent est dans l'arbre, la restriction portera dessus
  2. sinon, aucune restriction sur le parent ne sera appliquée et le document sera recherché parmi l'ensemble des document de ce type

À partir de la version 3.5.3 :

  1. si le modèle du document recherché contient une propriété treenode acceptant des documents du type du parent, la restriction portera dessus
  2. sinon, si le modèle du parent contient une propriété treenode et inverse acceptant des documents du type recherché, la restriction portera dessus
  3. sinon, si le parent est dans l'arbre, la restriction portera dessus
  4. sinon, aucune restriction sur le parent ne sera appliquée et le document sera recherché parmi l'ensemble des document de ce type

Dans tous les cas, si la liaison avec son parent est faite d'une autre manière, il est toujours possible d'implémenter une requête spécifique au niveau de la classe XxxScriptDocumentElement du document recherché.

Par un tag

L'attribut XML byTag permet d'identifier un document par l'un de ses tags :

  • pour les tags contextuels, la recherche se fait contextuellement au site contenant l'élément.
  • pour les tags fonctionnels, la recherche est restreinte aux enfants de l'élément parent.
  • pour les tags simples et exclusifs, la recherche se fait dans toute la base.

Si aucun document n'est retourné, un nouveau document sera créé et le tag lui sera affecté.

Exemple : la ligne suivante permet de récupérer le site par défaut :

<website byTag="default_modules_website_default-website" />

ATTENTION : pour les deux premiers types de tags (contextuels et fonctionnels), ceci ne fonctionne que pour des documents présents dans l'arbre. Pour les documents présents dans des arborescences virtuelles, il faudra gérer cet attribut de manière spécifique au niveau de la classe XxxScriptDocumentElement qui leurs sont associé.

L'élément documentRef

Pour juste récupérer un document sans le modifier, on peut également utiliser l'élément documentRef qui dispose des attributs suivants :

  • type (obligatoire) : le modèle du document que l'on veut trouver.
    Exemple : modules_website/page
  • id : la référence par laquelle on souhaite identifier le document.
  • byLabel : cf plus haut.
  • byTag : cf plus haut.

Attention, en utilisant l'élément documentRef, le document ne sera en aucun cas mis à jour, même si d'autres attributs sont définis. A fortiori, il ne sera pas non plus créé et si aucun document correspondant n'est trouvé (ou si le document trouvé n'a pas le bon type), une exception sera lancée.

Exemple :

<?xml version="1.0" encoding="UTF-8"?>
<script>
    <binding fileName="modules/website/persistentdocument/import/website_binding.xml" />
    <binding fileName="modules/media/persistentdocument/import/media_binding.xml" />

    <rootfolder module="media">
        <folder byLabel="Exemple de media Actualité">
            <documentRef type="modules_media/media" id="uneImage" byLabel="Anniversaire 3">
                <tag name="default_modules_media_sample" />
            </documentRef>
        </folder>
    </rootfolder>
    <website byTag="default_modules_website_default-website" template="tplNewFree">
        <documentRef type="modules_website/topic" byLabel="Outils">
            <documentRef type="modules_website/page" id="unePage" byLabel="Ajouter aux favoris" />
        </documentRef>
        <topic byTag="default_modules_website_sample" label="Rubrique de test">
            <page label="page test" template="tplNewHome" id="homepage">
                <changecontent>
                    <changeblock type="richtext">
                        <![CDATA[
                        <h2>Bloc dans un layout implicite</h2>
                        <p>Un peu de contenu...</p>
                        <p>
                        Lien vers une page : <a lang="fr" cmpref="{ref-id:unePage}">
                        Ajouter aux favoris qsd</a><br/><br/>
                        Image : <img lang="fr" alt="RBS Change 4" cmpref="{ref-id:uneImage}" />
                        </p>
                        ]]>
                    </changeblock>
                </changecontent>
            </page>
        </topic>
    </website>
</script>
Aperçu du résultat

Propriétés localisées

A partir de la version 3.0.4
Pour les versions antérieures voir plus bas

Dans le fichier d'import les documents sont déclarés dans la langue par défaut du projet. Leur traduction est importée dans un second temps par l'intermédiaire de la balise i18n ; une par langue de traduction. Il est également possible de faire référence à un document importé par le script comme on le voit dans l'exemple ci dessous avec l'attribut byRefid pour la page d'id homepage.

<?xml version="1.0" encoding="UTF-8"?>
<script>
	<binding fileName="modules/website/persistentdocument/import/website_binding.xml" />
	<binding fileName="modules/theme/persistentdocument/import/theme_binding.xml" />

	<pagetemplate byCodename-attr="templateHome" id="tplOne" />
	<pagetemplate byCodename-attr="template" id="tplTwo" />
	
	<website id="website" byDocumentId-attr="" label="Site web par défaut" protocol="http" localizebypath="true" allowedpagetemplate-refids="tplOne,tplTwo">
		<page id="homepage" label="Page d'accueil" isHomePage="true" template-attr="templateHome" >
			<changecontent for="content-block">
				<changeblock type="richtext">
					<![CDATA[<h2>Bienvenue</h2><p>...</p>]]>
				</changeblock>
			</changecontent>
		</page>

		<topic id="tools" label="Outils" navigationVisibility="hidden">
			<page id="print" label="Imprimer" indexingstatus="false" byTag="contextual_website_website_print">
				<documenturl lang="fr" url="/imprimer" />
				<changecontent for="content-block">
					<changeblock type="richtext">
						<![CDATA[<p>Ici vos instructions pour imprimer une page. (Cette page n'est utilisée que lorsque javascript n'est pas activé)</p>]]>
					</changeblock>
				</changecontent>
			</page>
		</topic>
	</website>
		
	<i18n lang="en">
	<website byRefid="website" label="Default website" >
		<page byRefid="homepage" label="Homepage">
			<changecontent for="content-block">
				<changeblock type="richtext">
					<![CDATA[<h2>Welcome</h2><p>...</p>]]>
				</changeblock>
			</changecontent>
		</page>		

		<topic byRefid="tools" label="Tools" navigationVisibility="hidden">
			<page byRefid="print" label="Print">
				<documenturl lang="en" url="/print" />
				<changecontent for="content-block">
					<changeblock type="richtext">
						<![CDATA[<p>Some text explaining how to print a page. (This page is only used when javascript is disabled).</p>]]>
					</changeblock>
				</changecontent>
			</page>
		</topic>
	</website>
	</i18n>	
</script>

Pour les versions de 3.0 à 3.0.3
Pour les versions supérieures voir plus haut

Les propriétés localisées peuvent être renseignées pour chaque langue. Pour cela il suffit de suffixer le nom de la propriété par la langue. Exemple :
<media path="..." label="Les aventures de Toto" label-en="The adventures of Toto" />

Gestion du statut de publication

Pour gérer le statut de publication d'un document lors de son import XML il suffit de définir un attribut publicationStatus suivi du statut. Exemple pour importer un document et le publier il vaut mieux le mettre en statut ACTIVE de sorte à permettre l'exécution des listeners éventuels : qu'il pourait y avoir :

   <mydocument label="Document Label"
               publicationStatus="ACTIVE"
               ... />

ref/xml_import/document.txt · Dernière modification: 2017/01/19 14:54 (modification externe)