User's manual

Use plugin to import content:

  • from DOCX or XML documents uploaded to the server
  • using web services
  1. Importing content from DOCX documents or XML
    1. Import rules
    2. Import docx
      1. Using the Word template
      2. Style limitations
    3. Import XML
      1. Import advantages XML
      2. Limitations
  2. Importing content via web services
    1. Generation of aAPI
    2. Using the web service
    3. Testing the web service

Importing content from DOCX documents or XML

Importing content from documents in docx or XML format will create a page and content for each file imported.

The root import directory can contain subdirectories to create a hierarchy of pages and content.

To import content, you must first select a page or sitemap root from which to create pages and content.

Then click on "Import content". In the dialog box that opens, enter the path to the server directory containing the files to be imported:

Import rules

Files must be organized in a tree structure. This tree structure is transferred via the import mechanism, for example :

File hierarchy on the serverPages and content created after import

The following rules apply:

  1. Every .docx (or xml) file creates a page with the contents of the .docx (or xml) document.
  2. A sub-page is created for each directory
    1. if the directory contains a docx file (or xml) with the directory name, the page created will contain the contents of this file (e.g. Online Services, Events).
    2. otherwise the page created will be a "blank" page (e.g. Large folders).

File and directory names are used as page names. On a website, a page can be accessed via its URL. In CMS Ametys , the pageURL is obtained from the path and the page name, for example http://xxxxxx.fr/fr/ma-rubrique/qui-sommes-nous/grands-dossiers/objectif-2050.html

Particular attention must therefore be paid to file and directory names, as these are the ones used in the tree structure during import.

These rules are applied for DOCX or XML

Import docx

Using the Word template

Docx files must follow the WORD 2007 template: page_template.dotx

Open the file with Word 2007 or higher. You should obtain :

 

Start by saving your document in "docx (Word 2007)" format, using the desired page name as the file name.

Then complete each field on this document.

This document is divided as follows:

 

Where

  • The header defines :
    • Template (mandatory): The page template, which can take two values, Home or Page. In general, use Page
    • Long title (optional): used to enter the page's long title.
    • Content type: defines the type of content to be inserted from among Article, News, Photo Gallery, Video Gallery, Audio Gallery. As a general rule, use Article. Galleries do not allow you to define the multimedia objects in the gallery.

  • Labels (page only) :
    • Main heading: defines whether this is a main heading: yes/no
    • Direct access: defines whether direct access is required: yes/no
    • Footer: defines whether the page is displayed in the footer
    • Event: defines whether the news item is an event. This event is then displayed in the calendar: yes/no
  • Content is defined by :
    • Title (mandatory): content title
    • Subtitle (optional): content subtitle
    • Illustration (optional): used to define the content's main image, known as the illustration.
    • Abstract: used to define the summary. The summary is used when displaying content in summary view, for example in a list on the home page. A "Read more" link is usually added to access the entire content.
    • Content: used to define content. It is possible to use title levels (check style limitations, next chapter).

Style limitations

The use of styles is of course possible, but must be limited to the basic Word styles, i.e. :

  • The "Title 1", "Title 2", "Title 3"... styles proposed by Word during installation, but not the modifications or creations of styles that could be linked to an entity;
  • Bold, Italic... ;
  • bullet indentations and levels (without bullet images), the default bullet is adopted;
  • the paintings are shown without the colors;
  • images ;

With regard to titles, we advise you to respect the sequence of title levels, i.e. to have "Title 1" then "Title 2" then "Title 3" and not "Title 1" then "Title 3", as "Title 2" is missing between the two.

The following styles are not taken into account in order to respect the charter of the destination website:

  • COLORS ;
  • fonts ;
  • chip images ;
  • WordArt and SmartArt ;
  • graphics ;
  • shapes ;
  • cliparts ;
  • equations ;
  • objects ;
  • lettering ;
  • ... any specific form.

Import XML

XML files must follow the XML model described below:

  • The root element is <content>attribute type carries the identifier of the type of content to be created

  • A simple metadata writes :

    <nom_metadonnee>[Valeur]</nom_metadonnee>

  • The <title>[Titre du contenu]</title> is mandatory

  • A multiple metadata is written as :

    <nom_metadonnee>
	<value>[Valeur 1]</value>
	<value>[Valeur 2]</value>
</nom_metadonnee>

  • A repeater is written :

    <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>

  • Rich text written in docbook format

    <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>

Here is an example of a XML file: 

<?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>

Import advantages XML

  • you can import any type of content

  • you can import any metadata from your content

Limitations

  • It is not possible to choose the page template. The "Page" template is always used.
  • It is not possible to define labels on the page or content.
  • Rich texts must be in docbook format

Importing content via web services

Generation of aAPI

You must first generate aAPI key that will be used by the web service to identify you.

To do this, go to "API key" in the Ametys menu:

Click on "Generate a key forAPI" to generate your key.

You can then copy the generated key:

To generate aAPI key, you must have the right to "Manage aAPI key".

Using the web service

The web service is available aturl : http://<url>/_contentio/import/content/<site>/<lang>[/<path>]

with : 

  • url url of the CMS
  • site: the name of the target site, mandatory 
  • lang: the language of the sitemap in which to create the page and content, mandatory
  • path: path of parent page, optional. If omitted, the page will be created at the root of the sitemap.

Calling this webservice requires two parameters:

  • key: the previously generatedAPI key
  • content: the XML file to be imported

The XML file must comply with the XML format described in the Import chapter. XML

Following a call to the :

  • a page with the file name is created. The "page" template is used by default;
  • a content is created with the information contained in the file XML
  • the content is inserted in the default zone of the new page

The web service returns the following result on success:

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

In the event of an error, the web service returns the error message. For example:

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

 

Testing the web service

To test the web service you can create a simple HTML page as shown below:

<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>

You can also use the command line curl (unix)

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

 

 

Back to top

Content IO