Manuel utilisateur

Le plugin Import de contenus permet d'importer des contenus :

  • soit à partir de documents DOCX ou XML déposés sur le serveur
  • soit par l'utilisation de web services
  1. Import de contenus à partir de documents DOCX ou XML
    1. Règles d'import
    2. Import docx
      1. Utilisation du modèle Word
      2. Limitations de styles
    3. Import XML
      1. Avantages de l'import XML
      2. Limitations
  2. Import de contenus par web services
    1. Génération d'une clé d'API
    2. Utilisation du web service
    3. Tester le web service

Import de contenus à partir de documents DOCX ou XML

L'import de contenus à partir de documents au format docx ou XML donnera lieu, pour chaque fichier importé, à la création d'une page et d'un contenu.

Le répertoire d'import racine peut contenir des sous répertoires afin de créer une hiérarchie de page et contenus.

Pour importer des contenus, vous devez d'abord sélectionné une page ou la racine du plan du site à partir du ou de laquelle sera créé les pages et contenus.

Puis cliquez sur "Import de contenus". Dans la boite de dialogue qui s'ouvre alors, saisissez le chemin du répertoire serveur contenant les fichiers à importer :

Règles d'import

Les fichiers doivent être organisés dans une arborescence. Cette arborescence est reprise via le mécanisme d’import, par exemple :

Hiérarchie de fichiers sur le serveurPages et contenus créés après import

Les règles suivantes sont appliquées :

  1. Tout fichier .docx (ou xml) donne lieu à la création d'une page avec un contenu avec le contenu du document .docx (ou xml)
  2. Tout répertoire donne lieu à la création d'une sous-page
    1. si le répertoire contient un fichier docx (ou xml) du nom du répertoire, la page créé contiendra le contenu de ce fichier (ex: Services en ligne, Evènements)
    2. sinon la page créée sera une page "vierge" (ex: Grands dossiers)

Les noms de fichiers ou de répertoire sont repris en tant que nom de page. Sur le site web, une page est accessible par son URL. Dans le CMS Ametys, l’URL de la page est obtenue à partie du chemin et du nom de la page, par exemple http://xxxxxx.fr/fr/ma-rubrique/qui-sommes-nous/grands-dossiers/objectif-2050.html

Il faut donc porter une attention particulière aux noms des fichiers et des répertoires car ce sont cela qui sont utilisés dans l’arborescence au cours de l’importation.

Ces règles sont appliquées pour un import DOCX ou XML

Import docx

Utilisation du modèle Word

Les fichiers docx doivent respecté le modèle suivant WORD 2007 suivant: page_template.dotx

Ouvrez le fichier avec Word 2007 ou supérieur. Vous devez obtenir :

 

Commencez par enregistrer votre document au format « docx (Word 2007) », en utilisant comme nom de fichier, le nom de page souhaitée.

Puis complétez chaque champ de ce document.

Ce document est découpé de la sorte :

 

  • L’en-tête permet de définir :
    • Gabarit (obligatoire) : Le gabarit de la page, qui peut prendre deux valeurs, Accueil ou Page. De manière générale il faut utiliser Page
    • Le titre long (facultatif) : il permet de renseigner le titre long de la page.
    • Type de contenu : permet de définir le type de contenu à insérer parmi Article, Actualité, Galerie Photo, Galerie Vidéo, Galerie audio. De manière générale il faut utiliser Article. Les galeries ne permettent pas de définir les objets multimédia de la galerie.

  • Les étiquettes (uniquement pour la page) :
    • Rubrique principale : permet de définir si c’est une rubrique principale : oui/non
    • Accès direct : permet de définir si c’est un accès direct : oui/non
    • Pied de page : permet de définir si la page doit être affichée dans le pied de page
    • Evènement : permet de définir si l’actualité est un événement. Cet événement est alors affiché dans le calendrier: oui/non
  • Contenu est défini par :
    • Titre (obligatoire) : le titre du contenu
    • Sous-titre (facultatif) : le sous-titre du contenu
    • Illustration (facultatif) : il permet de définir l’image principale du contenu, dite l’illustration.
    • Abstract, résumé : il permet de définir le résumé. Le résumé est utilisé lors de l’affichage en vue résumé du contenu, par exemple dans une liste en page d’accueil, en général un lien « Lire la suite » est ajouté pour accéder au contenu dans sa globalité.
    • Contenu : il permet de définir le contenu. Il est possible d’utiliser les niveaux de titres (vérifiez les limitations de styles, chapitre suivant)
Limitations de styles

L’utilisation de styles est bien évidemment possible mais doit se limiter aux styles de bases de Word c’est-à-dire :

  • « Titre 1 », « Titre 2 », « Titre 3 »… proposé par Word lors de l’installation mais pas les modifications ou créations de styles qui pourraient être liés à une entité ;
  • Gras, Italique… ;
  • les retraits et niveaux de puces (sans les images des puces), la puce par défaut est reprise ;
  • les tableaux sont repris sans les couleurs ;
  • les images ;

Concernant les titres, nous vous conseillons de respecter l’enchainement des niveaux de titre, c’est-à-dire d’avoir « Titre 1 » puis « Titre 2 » puis « Titre 3 » et non « Titre 1 » puis « Titre 3 » car il manque entre les deux le « Titre 2 ».

Les styles suivant ne sont pas pris en compte afin de respecter la charte du site web de destination :

  • les couleurs ;
  • les polices ;
  • les images des puces ;
  • les WordArt et SmartArt ;
  • les graphiques ;
  • les formes ;
  • les cliparts ;
  • les équations ;
  • les objets ;
  • les lettrines ;
  • … toute forme spécifique.

Import XML

Les fichiers XML doivent respecté le modèle XML décrit ci-dessous:

  • L'élément racine est <content>, l'attribut type porte l'identifiant du type de contenu à créer
  • Une métadonnée simple écrit :

    <nom_metadonnee>[Valeur]</nom_metadonnee>
    
  • La balise <title>[Titre du contenu]</title> est obligatoire

  • Une métadonnée multiple s'écrit :

    <nom_metadonnee>
    	<value>[Valeur 1]</value>
    	<value>[Valeur 2]</value>
    </nom_metadonnee>
    
  • Un repeateur s'écrit :

    <nom_repeater>
    	<entry>
    		<nom_metadonnee1>[Texte]</nom_metadonnee1>
    		<nom_metadonnee2>[Texte]</nom_metadonnee2>
    	</entry>
    	<entry>
    		<nom_metadonnee1>[Texte]</nom_metadonnee1>
    		<nom_metadonnee2>[Texte]</nom_metadonnee2>
    	</entry>
    </nom_repeater>
    
  • Un texte riche s'écrit au format docbook

    <article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:html="http://www.w3.org/1999/xhtml" version="5.0">
    	<section>
    		<title>[Titre]</title>
    		<para>[Texte]</para>
    	</section>
    </article>
    

Voici un exemple de fichier XML : 

<?xml version="1.0" encoding="UTF-8"?>
<content type="org.ametys.web.default.Content.article">
  <title>Titre du contenu</title>
  <document-subtitle>Sous titre</document-subtitle>
  <abstract>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Tubulo putas dicere? Ne in odium veniam, si amicum destitero tueri.</abstract>
  <illustration>
    <image>http://www2.ametys.org/skins/Canvas/resources/img/logo.png</image>
    <alt-text>Logo Ametys</alt-text>
  </illustration>
  <content>
    <article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:html="http://www.w3.org/1999/xhtml" version="5.0">
      <para>Un paragraphe</para>
      <section>
        <title>Titre 1</title>
        <para>Sed emolumenta communia esse dicuntur, recte autem facta et peccata non habentur communia. Huius, Lyco, oratione locuples, rebus ipsis ielunior.</para>
        <itemizedlist mark="square">
          <listitem>
            <para>Ab his oratores, ab his imperatores ac rerum publicarum principes extiterunt.</para>
          </listitem>
          <listitem>
            <para>Scaevola tribunus plebis ferret ad plebem</para>
          </listitem>
        </itemizedlist>
        <para>Si quae forte-possumus. Unum nescio, quo modo possit, si luxuriosus sit, finitas cupiditates habere.</para>
      </section>
    </article>
  </content>
  <contact>
    <name>Pierre Martin</name>
    <mail>contact@ametys.org</mail>
  </contact>
  <dc>
    <dc_subject>
      <value>mots</value>
      <value>clés</value>
    </dc_subject>
  </dc>
</content>
Avantages de l'import XML
  • vous pouvez importer n'importe quel type de contenus

  • vous pouvez importer n'importe quelles métadonnées du contenus

Limitations
  • Il n'est pas possible de choisir le gabarit de la page. Le gabarit "Page" est systématiquement utilisé
  • Il n'est pas possible de définir des étiquettes sur la page ou le contenu
  • Les textes riches doivent être au format docbook

Import de contenus par web services

Génération d'une clé d'API

Vous devez d'abord générer une clé d'API qui sera utilisé par le web service pour vous identifier.

Pour cela, allez sur "Clé d'API" du menu Ametys :

Cliquez sur "Générer une clé d'API" pour générer votre clé

Vous pouvez ensuite copier la clé générée :

Pour pouvoir générer une clé d'API, vous devez posséder le droit "Géréner une clé d'API".

Utilisation du web service

Le web service est disponible à l'url : http://<url>/_contentio/import/content/<site>/<lang>[/<path>]

avec : 

  • url : l'url du CMS
  • site: le nom du site cible, obligatoire 
  • lang: la langue du plan du site dans lequel créer la page et le contenu, obligatoire
  • path: chemin de la page parente, facultatif. Si omis, la page sera créée à la racine du plan du site

L'appel à ce webservice nécessite deux paramètres:

  • key: la clé d'API précédemment générée
  • content: le fichier XML à importer

Le fichier XML doit respecter le format XML décrit au chapitre Import XML

Suite à l'appel au web service :

  • une page portant le nom du fichier est créée. Le template "page" est utilisé par défaut;
  • un contenu est créé avec les informations contenu dans le fichier XML
  • le contenu est inséré dans zone centrale (default) de la nouvelle page

Le web service renvoie le résultat suivant en cas de succès:

<ActionResult>
	<success>true</success>
</ActionResult>

En cas d'erreur, le web service renvoie le message d'erreur. Par exemple :

<ActionResult>
	<error>The API key provided is invalid, please check the value of the parameter 'key'.</error>
	<success>false</success>
</ActionResult>

 

Tester le web service

Pour tester le web service pour pouvez créer une simple page HTML comme ci-dessous :

<html>
    <head></head>
    <body>
        <form action="http://<url_cms>/_contentio/import/content/<sitename>/<lang>/<path>" method="post" enctype="multipart/form-data">
            <input type="text" name="key" placeholder="API key" />
            <br/>
            <input type="file" name="content" placeholder="content" />
            <br/>
            <input type="submit" />
        </form>
    </body>
</html> 

Vous pouvez également utiliser la ligne de commande curl (unix)

curl -F "key=<API KEY>" -F "content=@<MON FICHIER>" http://<url_cms>/_contentio/import/content/<sitename>/<lang>/<path>