Le Manuel d'Ara

© 2007-2014 Denis Sureau

http://www.scriptol.fr/

 

Qu'est-ce que Ara?

ARA signifie Atom and RSS API, c'est une bibliothèque de fonctions pour le traitement de fichiers Atom et RSS et notamment, la génération, l'édition et l'affichage de flux de syndication.

Ce manuel est consacré à l'éditeur et générateur de fichiers de flux.

Pré-requis

Pour pouvoir utiliser Ara, votre hébergement doit supporter PHP 5. Le fichier d'installation vous renseignera en affichant la version de PHP. Si PHP n'est pas disponible sur le site, rien ne sera affiché.
Quelquefois l'hébergement supporte PHP 5 mais est configuré en PHP 4 par défaut. Dans ce cas il faudra le reconfigurer par une simple ligne dans un fichier .htaccess placé dans le répertoire de Ara.

SetEnv PHP_VER 5
ou
AddType x-mapp-php5 .php

Selon le serveur et le système d'exploitation, le libellé des options de configuration peut être différent, renseignez-vous auprès de votre hébergeur ou votre logiciel serveur.

Le programme utilise le framework Ajax Anaa qui est inclut dans l'archive.

Installation et utilisation

Ara est une page Web contenant un formulaire. Pour utiliser l'éditeur Ara, il faut l'installer sur le site Web dont vous voulez syndiquer le contenu. Cela consiste simplement à télécharger le contenu de l'archive dans un sous-répertoire, qui se nomme par défaut ara, mais dont vous pouvez choisir le nom.
Vous devez placer sur le site
- tous les fichiers dont le nom commence par Ara, ainsi que
- anaa.js et
- install.php.

Une fois les fichiers mis en ligne sur votre site, vous tapez l'URL (l'adresse complète de page Web) du fichier d'installation:

http://www.scriptol.fr/ara/install.php

Celui-ci vous demande d'enregistrer un login et un mot de passe. Ceux-ci sont indispensables avant d'utiliser le programme, pour avoir le droit de créer et mettre à jour un fichier RSS sur votre site, sans que n'importe puisse le modifier à sa guise.

Notez par écrit le login et le mot de passe que vous avez choisis, puis effacez le fichier install.php par mesure de sécurité.

La création d'un flux

Grâce aux automatismes nombreux intégrés dans l'éditeur Ara au moyen de scripts PHP, l'opération est très simple. Pour créer un nouveau fichier, entrez son nom, puis entrer l'url d'un article à syndiquer et cliquez sur le bouton "Add", enfin cliquez sur "Create an RSS feed". Et c'est tout. Nous allons voir en détail ces différentes étapes.

1) Se loguer

Dans le premier cadre, entrez votre login et votre mot de passe. Puis cliquer sur Check User (vérification de l'utilisateur). Vous resterez logué sur la durée de la session, donc tant que vous ne fermez pas le navigateur.
Une fois les login et mot de passe reconnus par le programme, deux boutons inactifs en grisé deviennent actifs, le bouton "Reload" et le bouton "Create an RSS feed".
Vous êtes alors autorisé à créer un flux.

2) Choisir un nom de fichier

Le second cadre permet d'entrer le nom d'un flux RSS. Si vous avez déja créé un flux que vous voulez éditer, cliquez sur le bouton "Reload".
Par mesure de sécurité, le nom de fichier doit avoir une extension, et celle-ci doit faire partie de la liste suivante:

.atom
.rss
.xml
.rdf

Le chemin racine

Si vous voulez créer le flux rss.xml et le placer à la racine du site, taper:

/rss.xml

N'utilisez pas d'URL complète avec le nom de domaine.
Le nom donné au chargement sera le nom donné à la création ou mise à jour du fichier. Mais le chemin est différente car les fonctions PHP utilisées pour sauvegarder un fichier XML utiliser un chemin local sur le serveur.
Cependant la translation est faite automatiquement par le programme et le chemin local est affiché dans le champ de chemin à coté du bouton Create an RSS feed.

Ces questions sur les noms de fichiers ne s'appliquent pas aux noms des pages Web contenant les articles du flux, qui elles seront designée par une URL complète.

3) Définir les options

Le troisième formulaire contient plusieurs options:

number of items

C'est le nombre maximum d'articles que contiendra le fichier. Choisir un nombre dans la liste déroulante ou tapez directement un nombre.

add description

Cocher pour ajouter les descriptions aux articles.

add date

Cochez pour inclure aussi la date de parution.

4) Indiquer le canal

La quatrième formulaire permet d'entrer l'URL du site du canal, donc le site concerné par le flux, et sur lequel vous avez téléchargé Ara.
Entrez l'URL complète.
Vous pouvez éditer le titre, la description et la date en cliquant sur Edit. L'éditeur se trouve en bas de page, nous allons y venir.

5) Désigner les articles

Le cinquième formulaire permet d'entrer les URL des articles et contient un champ de texte, ainsi qu'un bouton Add pour ajouter l'URL à la liste.
Notez qu'il est plus facile de fournir les URL des articles en ouvrant le navigateur dans une seconde fenêtre, en affichant les articles et en récupérant l'URL exacte dans la barre d'URL par un double clic. Ensuite vous tapez CTRL+C pour copiez et dans le champ d'article de Ara, vous tapez CTRL+V.
Lorsque vous ajoutez l'URL d'un article, le titre (et non l'URL) apparaît dans une liste au-dessus dans le cadre du cinquième formulaire.
A gauche de chaque titre, un bouton EDIT est affiché. Bien que les données descriptives de l'article soient extraites automatiquement de la page, vous pouvez souhaiter les modifier.

6) Editer un descriptif

Le formulaire de descriptif est commun au canal et aux articles du flux. Pour éditer un article, on clique sur le bouton EDIT à gauche du titre dans la liste.
Il est alors possible de changer le titre, la description, la date.
Puis on clique sur le bouton Replace sous le descriptif.

Le bouton Clear Fields efface le contenu de tous les champs.

En fait on peut créer un élément à partir de zéro avec l'éditeur de descriptif, en donnant l'URL et tous les éléments de description. Le bouton Replace ajoute alors le nouvel élément à la liste.

7) Effacer un élément

Pour rajeunir votre flux de syndication, vous avez besoin de supprimer les articles les plus anciens afin d'en ajouter de nouveaux.
C'est en passant par la fenêtre d'édition que l'on supprime un article. On clique sur EDIT, et dans le formulaire d'édition sur le bouton Delete Item.

8) Créer le flux

Si vous avez déja tapé le nom du fichier dans le formulaire du haut de page, que vous avez indiqué le canal et ajouté au moins un article, vous pouvez créer un fichier de flux en cliquant sur le bouton Create an RSS Feed.

Si le flux à été chargé dans un fichier, le chemin sur le serveur doit être affiché dans le champ de texte au dessus du bouton Create an RSS feed. Sinon taper le chemin relatif, /rss.xml par exemple et cliquez sur le bouton Convert à droite.
Vous pouvez aussi taper directement le chemin local sur le serveur.

Notre que si Ara est installé à la racine du site, ou si vous créez le fichier dans le répertoire ara ou un sous-répertoire, il suffit de taper le nom (éventuellement avec le nom du sous-répertoire) et les problèmes de conversion de chemin n'existent pas.

Rendre le flux visible

Votre fichier une fois créé, et placé à la racine du site, ou dans un sous-répertoire s'il concerne un dossier particulier, il reste à le rendre visible au public et aux logiciels.

Pour qu'un navigateur puisse reconnaître la présence d'un flux, il faut ajouter la balise suivante à l'intérieur de la section HEAD de la page d'accueil ou de la page d'accueil d'un dossier, pour un fichier au format RSS:

<link rel="alternate" type="application/rss+xml" href="http://www.scriptol.fr/rss.xml">

et s'il est au format Atom:

<link rel="alternate" type="application/atom+xml" href="http://www.scriptol.fr/atom.xml">

Vous remplacez bien sûr scriptol.fr par le nom de domaine de votre site.
Et pour que les visiteurs puissent y accéder, on utilise une image avec un lien sur le fichier, placé n'importe où sur une page:

 <a href="rss.xml"> <img src="images/feed-24x24.png" border="0">Mon flux</a>

Ce qui donne en 16 pixels ou en 24 pixels.

Questions de sécurité

Comme vous pouvez le constater, Ara ne fonctionnera que si l'on donne d'abord un mot de passe. Le nom d'utilisateur et le mot de passe sont choisis par vous-même lors de l'installation. Vous restez logués sur l'éditeur et pouvez l'utiliser tant que vous ne vous déconnectez pas du site, ce qui arrive quand vous fermez le navigateur ou l'onglet du site.
Une autre mesure de sécurité est le contrôle du type de fichier. Seuls les fichiers ayant les extensions dont la liste est donnée plus haut peuvent être créés sur le site.
N'oubliez pas d'effacer le fichier install.php une fois que vous vous être enregistré. Cette précaution prise, il est normalement impossible à un utilisateur malveillant d'affecter votre site en passant par les scripts d'Ara. Cependant, si vous avez un doute sur la sécurité du logiciel, ajoutez un commentaire sur la page Ara du site web.

Conditions d'utilisation

Ara est sous licence GNU GPL. Vous pouvez l'utilisez librement et gratuitement. Il vous est permis de modifier le source et de le distribuer mais en conservant les notices de copyright dans les fichiers. Il est interdit de modifier le programme pour supprimer les mesures de sécurité qu'il comporte et le distribuer sous cette forme.


Par Denis Sureau le 21 Juin 2007. Logiciel et documentation disponibles sur Scriptol.fr.