Certains éléments de ces tableaux sont obligatoires d'autres facultatifs (entre crochets).
rss : encoding, language
channel => title, link, description, [copyright], [webmaster], [pubdate], [url_flux]
[image => [title], url, [link], [decription], [width], [height] ]
[item => title, link, [description], [category], [author], [pubdate], [modified] ]
Les données "obligatoires" correspondent à un flux minimal, cependant dans certains cas pour que le flux soit valide, des données considérées comme facultatives ci-dessus devront être obligatoirement renseignées (ex pubdate et modified pour les items dans les flux atom 1.0). La classe fournie n'est qu'un outil, les données utilsées, leur pertinence et leur format sont des éléments que seul le webmaster ou le développeur mettant en place cette classe est en mesure d'apprécier. Par exemple ce sera aussi à lui d'apprécier le nombre de caractères des champs "description". (on trouve des flux fournissant l'intégralité de l'article et d'autres ne mettant qu'une ligne). les longeurs recommandées sont de 100 caractères maximun pour les titres, copyright,... et de 500 pour les descriptions.
• $rss = new rss_write ();
Constructeur de la classe.
• $rss -> rss ($encode, $langue);
Défini les deux paramètres obligatoires de tout flux.
$encodage = l'encodage du flux, typiquement ISO-8859-1 ou UTF-8. Il est de la responsabilité du préparateur de données et non de la classe que celles-ci soient conformes à l'encodage déclaré. (utiliser au besoin la fonction php utf8_encode(string)).
$langue, le code de la langue utilisée dans le flux (fr = français, en = anglais, liste complète ici...)
• $rss -> channel ($title, $link, $description);
Déclare les éléments obligatoires title, link, description de l'élément channel :
Il est obligatoire de déclarer un et un seul élément channel.
Obligatoires :
- $title correspond au nom du channel, doit être le titre de votre site web.
- $link correspond à une URL pointant sur le site web nommé dans $title.
- $description correspond à une phrase qui décrit votre channel.
• $rss -> channel_element ($balise, $value);
Déclare les éléments obligatoires ou falcultatifs de l'élément channel. Pour les éléments obligatoires il est possible d'utiliser la fonction channel.
exemple $rss -> channel_element ('webmaster', 'the_webmaster@exemple.com');
$balise doit prendre l'une des valeurs suivantes :
- 'tilte', 'link', 'description' (voir ci-dessus)
- 'copyright' correspond à une note de copyright sur le contenu du channel.
- 'webmaster' correspond au nom du webmaster
- 'pubdate' date de génération du flux (voir note au sujet des formats de date)
- 'url_flux', url du flux lui-même (nécessaire seulement pour les flux atom 1.0).
• $rss -> image ($url, [$title], [$link]);
Déclare l'élément image avec title, url, link, width, height,
description :
L'élément image est optionnel. (il n'est pas obligatoire d'en déclarer un)
Obligatoire :
- $url correspond à l'URL d'une image GIF, JPEG or PNG qui représente le channel.
Optionnels :
- $title correspond à la description de l'image qui est utilisée dans l'attribut ALT du tag HTML <img>.
- $link correspond à l'URL du site (lien vers le site).
En pratique $title et $link doivent avoir la même valeur que $title et $link de channel.
• $rss -> image_element ($balise, $value);
Déclare les éléments obligatoires ou falcultatifs de l'élément image. Pour les éléments obligatoires il est possible d'utiliser la fonction image.
$balise doit prendre l'une des valeurs suivantes :
- 'title', 'link', 'url' (voir fonction "image")
- 'width' correspond à la largeur de l'image en pixels.
(Valeur maximum 144 pour le RSS)
- 'height' correspond à la hauteur de l'image en pixels.
(Valeur maximum 400 pour le RSS)
- 'description' correspond au texte qui est placé dans l'attribut TITLE du lien formé autour de l'image dans l'affichage HTML.
• $rss -> item ($title, $link, [$description]);
Ajoute un élément item au channel :
Vous pouvez ajouter autant d'élément item que vous le souhaitez en appelant plusieurs fois $rss -> item(..).
Obligatoires :
$title correspond au titre de l'item (titre de la news par ex.).
$link correspond à l'URL (lien absolu http://... vers la news par ex.).Optionnel :
$description correspond à la description de l'item (le début du texte d'une news par exemple).
• $rss -> item_element ($balise, $value);
Déclare les éléments obligatoires ou falcultatifs de l'élément item. Pour les éléments obligatoires il est possible d'utiliser la fonction item.
$balise doit prendre l'une des valeurs suivantes :
- 'tilte', 'link', 'description' (voir fonction précédente)
- 'author', nom et mail éventuel) de l'auteur.
- 'category', categorie de l'item
- 'pubdate', date de publication de l'article, doit être générée au format défini.
- 'modified', date de modification de l'article, doit être générée au format défini.
• $rss -> new_item ();
Passe à l'item suivant. On peut utiliser l'une ou l'autre des programmations suivantes
1. première méthode
$rss -> item ('le titre', 'http://www.example.com/article2.html');
$rss -> item_element ('category', 'divers et variés');
$rss -> item ('autre titre', 'http://www.example.com/article3.html')
$rss -> item_element ('category', 'autres');
2. deuxième méthode
$rss -> new_item();
$rss -> item_element ('title', 'le titre');
$rss -> item_element ('link', 'http://www.example.com/article2.html');
$rss -> item_element ('category', 'divers et variés');
$rss -> new_item();
$rss -> item_element ('title', 'autre titre');
$rss -> item_element ('link', 'http://www.example.com/article3.html');
$rss -> item_element ('category', 'autres');
Les flux produits seront les mêmes. (Il est même possible de mixer les deux méthodes, mais pour des questions de cohérence de programmation cela n'est pas conseillé).
• $string = $rss -> generate ($format, $erreur);
Retourne une chaine dans $string contenant l'objet RSS ou false en cas d'erreur. Le type d'erreur est alors disponible dans la variable $erreur passée par référence.
exemple :
$res = $rss -> generate('rdf10',$erreur);
if ($res) {
$res = htmlentities($res);
echo str_replace("\n",'<br />', $res);
} else {
echo $erreur;
}
Voir note sur les formats dispo.
• $rss -> save ($filename, $format, $erreur);
Créer l'objet RSS dans le fichier $filename, au format $format. Le type d'erreur est alors disponible dans la variable $erreur passée par référence.
$res = $rss -> save('monflux.rss', 'rdf10', $erreur);
if ($res) {
echo 'flux ok'
} else {
echo $erreur;
}
• les formats de flux
pour le moment :
rss20, format rss 2.0
rdf10, format rss/rdf 1.0
atom03, format atom 0.3
atom10, format atom 1.0
• les formats de dates
dans les flux deux grands formats de date
celui de type 1 (RFC 822): Wed, 12 Oct 2005 12:45:00 +0200 équivalent aussi à Wed, 12 Oct 2005 10:45:00 GMT (notez la différence sur les heures)
le format de type 2 (ISO 8601) : 2005-10-12T12:45:00+02:00 équivalent à 2005-10-12T10:45:00Z
Pour simplifier la tâche du programmeur, les dates passées dans les paramètres des fonctions channel_element('pubdate', $date) et item_element('pubdate', $date) seront au format "AAAA-MM-JJ HH:MM:SS" ou en anglais "YYYY-MM-DD HH:MM:SS". Elles seront mises au format de type 1 ou de type 2 suivant le type de flux demandé. Ainsi si on veut la date du jour comme élément pubdate de channel il suffira d'utiliser
$rss -> channel_element ('pubdate', date("Y-m-d h:i:s"));
• les plugins
à faire....