--- /dev/null
+
+===================================
+eZTelemeta - Mise en place et usage
+===================================
+
+Olivier Guilyardi <olivier samalyse com> - |today|
+
+.. contents:: **Table des matières**
+
+I - Introduction
+~~~~~~~~~~~~~~~~
+
+Le présent document décrit les procédures de mise en place et d'usage
+de l'extension eZPublish eZTelemeta. Cette extension a pour but de
+permettre l'intégration dynamique d'éléments sonore en provenance du
+logiciel Telemeta.
+
+II - Pré-requis
+~~~~~~~~~~~~~~~
+
+- Système Linux ou FreeBSD:
+- PHP version 5.2 ou supérieur
+- Apache version 1.3 ou supérieur
+- eZPublish 4.1.0
+- l'accès distant à une installation Telemeta
+
+III - Mise en place
+~~~~~~~~~~~~~~~~~~~
+
+III.1 - Installation de l'extension
+-----------------------------------
+
+eZTelemeta est distribuée sous la forme d'une archive .zip, contenant le
+répertoire ``eztelemeta``, à placer dans le répertoire ``extension``
+de l'installation eZPublish.
+
+Puis activer l'extension dans l'administration, onglet Setup/Extensions, et
+régénerer les données de chargement automatique (``Regenerate autoload
+arrays for extensions``)
+
+III.2 - Création de la classe principale
+----------------------------------------
+
+eZTelemeta définit un nouveau type de données, appelé ``Telemeta
+Item``. Les utilisateur avancés de eZPublish peuvent envisager
+différents scénarios d'utilisation de ce type de données. La procédure
+décrite ici consiste à créer une classe qui ne contiendra qu'un seul
+attribut, de type ``Telemeta Item``. Il est fortement recommandé de
+procéder ainsi lors d'une première mise en place, notamment pour intégrer
+facilement le lecteur audio aux pages publiques.
+
+Dans l'administration, dans Setup/Classes, dans le groupe Media, créer
+une classe avec les paramètres suivants::
+
+ - Name: Telemeta Audio Item
+ - Identifier: telemetaitem
+ - Object name pattern: <item>
+
+Ajouter un attribut de type ``Telemeta Item``, avec pour paramètres::
+
+ - Name: Item
+ - Identifier: item
+ - Required: activé
+ - Searchable: activé
+
+Cliquer sur OK pour enregistrer la nouvelle classe.
+
+III.3 - Création d'un objet de contenu
+--------------------------------------
+
+Il est maintenant possible de créer un objet de contenu (une instance)
+à partir de cette classe, par exemple dans l'onglet Media Library,
+dossier Multimedia, créer un objet de type Telemeta Audio Item avec
+pour paramètres::
+
+ - Telemeta URL: L'url de l'installation Telemeta distante.
+ (exemple: http://mucem.telemeta.org)
+
+ - Item Identifier: La cote de l'item. Celle-ci peut être trouvée
+ en accédant à l'interface web de Telemeta, sur
+ la page de l'item choisi.
+
+Puis enregistrer les modifications (``Send for publishing``).
+
+**Remarque**: au moment de l'enregistrement, eZTelemeta établit une connexion
+avec l'installation Telemeta distante, en utilisant le protocole OAI-PMH via HTTP.
+Si la cote de l'item est invalide, ou si la connexion HTTP ne peut-être établi
+à cause d'un mauvais URL, l'item ne sera pas enregistré, et une erreur s'affichera.
+Dans ce cas vérifiez bien votre saisie.
+
+III.4 - Intégration de l'objet de contenu dans un article
+---------------------------------------------------------
+
+Maintenant que nous disposons d'un objet de contenu Telemeta, il est facile
+de l'intégrer à un article. Pour ce faire, lors de l'édition d'un article:
+
+1. Cliquer sur l'icône représentant un *trombone* (``Insérer/modifier un objet``)
+2. Une fenêtre DHTML doit s'ouvrir, cliquer sur Parcourir, Media puis sur Multimedia
+3. Seléctionner l'item Telemeta à insérer, un aperçu (lien, titre, etc...) doit s'afficher
+4. Cliquer sur OK
+
+L'item doit maintenant être intégré au corps de l'article, sous la forme d'une liste de
+définition HTML (``<dl>...</dl>``), affichant le titre de l'item sous la forme d'un lien vers
+le fichier son hébergé sur le serveur Telemeta, la durée (HH:MM:SS) de l'item, et suivant les
+informations qui sont disponibles, un ou plusieurs éléments parmi les suivants: Auteur/Collecteur,
+Description, Droits d'usage.
+
+L'intégration sous la forme d'une liste de définition HTML a plusieurs avantages:
+
+- en terme de contenu, c'est la construction HTML la plus adaptée à une liste de méta-données
+- la présentation est facilement personalisable avec des feuilles de styles CSS.
+- elle est accessible, facilitant la consultation à l'aide de périphériques de type lecteur
+ d'écran destinés aux aveugles.
+
+IV - Intégration du lecteur audio
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+IV.1 - Remarques sur le lecteur audio
+-------------------------------------
+
+eZTelemeta inclut un lecteur audio web employant javascript et flash de
+façon dîte *dégradable*: si flash ou javascript sont absents, le lien
+HTML vers le fichier son (mp3) est laissé intacte, et la lecture reste
+donc possible à l'aide d'un module externe au navigateur (Windows Media
+Player, iTunes, VLC, etc...).
+
+Cependant, la plupart des utilisateurs pourront profiter du lecteur audio
+permettant la lecture interactive du son sans quitter la page en cours,
+et nottamment sous:
+
+- Internet Explorer 6 et 7
+- Firefox 2 et 3
+- Safari 3
+- Opera 9
+
+Dans le respect des règles de l'art du web actuel, les routines
+javascript sont séparées de façon stricte du contenu HTML. L'affichage
+interactif du lecteur est entièrement personalisable via CSS et/ou
+modification des templates eZPublish. Flash est utilisé de façon
+invisible, via la librairie SoundManager2, offrant une API javascript
+dédiée au son.
+
+**Remarque :** Pour simplifier la mise en place du lecteur, il est
+recommandé d'utiliser une classe de contenu eZPublish dont l'identifiant
+est ``telemetaitem`` comme indiqué en III.2.
+
+IV.2 - Mise en place du lecteur audio
+-------------------------------------
+
+Le lecteur possède des dépendances CSS et Javascript qui doivent êtres
+chargées dans la section ``<head/>`` des pages du site. Pour ce faire
+eZTelemeta contient un template qui doit être inclu dans cette section,
+en personalisant le template ``pagelayout.tpl``. Ce template est utilisé
+par eZPublish pour construire toutes les pages.
+
+Pour ce faire, se rendre dans l'onglet Design de l'espace
+d'administration eZPublish, et (si ce n'est déjà fait) y créer
+un ``override`` du template ``pagelayout.tpl`` pour le ou les sites
+concernés. Il est également recommandé de créer un tel ``override``
+pour le template ``pagelayout.tpl`` de la partie administrative.
+
+Puis, dans chacun des templates ``pagelayout.tpl`` concernés, inclure
+le template d'initialisation en plaçant l'expression suivante dans la section
+``<head/>``::
+
+{include uri="design:eztelemeta_head.tpl"}
+
+Enfin, vider le cache eZPublish. Le lecteur audio doit maintenant être actif
+à la fois sur les pages publiques intégrant un item Telemeta, et lors de la
+prévisualisation d'un article dans l'espace administratif.
+
+**Remarque**: le fait d'inclure le template ``eztelemeta_head.tpl`` dans toutes
+les pages du site via la personalisation de ``pagelayout.tpl``, n'alourdit pas
+inutilement le chargement des pages. Les dépendences CSS, JS et Flash ne sont
+chargées que si la page en cours contient effectivement un item Telemeta.
+
+.. |today| date::
+.. vim: set ft=rst:
projects / telemeta.git / commitdiff