Quomodo Authoring Toolkit, Documentation

2. Guide de programmation

Contenu du téléchargement

L'environnement de debug

Premiers pas

1. Premièrement, sélectionnez un identifiant unique, la signature de votre smartnote. Vérifiez avec l'équipe Quomodo que la signature que vous avez choisie n'est pas déjà utilisée. La signature doit être une chaîne de lettres minuscules non accentuées, ou de chiffres excepté pour le 1er caractère. Vous emploierez la signature comme préfixe pour les noms de fichier, les id d'éléments HTML, etc. liés à votre smartnote: ceci permet à Quomodo de manipuler automatiquement les différentes sortes de smartnotes. Pour plus de clarté, nous supposons ci-dessous que la signature de votre smartnote est fred.
2. Maintenant, créez un nouveau répertoire pour votre smartnote, et appelez-le fred. Au lieu de créer un nouveau répertoire, vous pouvez prendre un des exemples (par exemple, bn), le dupliquer et le renommer suivant la signature de votre smartnote. Le répertoire contient un fichier HTML, un ou plusieurs fichiers Javascript (dans le sous-répertoire scripts) et probablement un ou plusieurs fichiers CSS (dans le sous-répertoire style) ou des images (dans le sous-répertoire images).
3. Renommez le fichier HTML fred_fr.html si vous faites votre smartnote en Français, fred_en.html si vous faites une version en Anglais. Renommez les autres fichiers suivant le même principe. Dans ce qui suit pour plus de simplicité nous supposons que votre smartnote emploie un fichier Javascript fred.js situé dans le répertoire scripts.
4. Ouvrez tous les fichiers du répertoire de votre smartnote, et changez toutes les occurrences de bn_ en fred_. Maintenant fred est un véritable clone de la smartnote bn. En affichant fred_fr.html sur votre navigateur, vous pourrez utiliser et tester toutes ses fonctions. La prochaine étape est d'apporter les changements appropriés afin de créer votre propre smartnote.

Que dois-je livrer?

• une signature unique
  La signature de votre smartnote doit commencer par une lettre minuscule et doit inclure seulement des lettres minuscules et des chiffres. Dans ce qui suit nous prenons fred comme signature de votre smartnote.
• un répertoire fred
  C'est là où vous stockerez tous les fichiers de votre projet.
• un fichier fred_fr.html,ou fred_en.html, ou tous les deux
  Situé dans le répertoire fred, ce fichier HTML doit être un XHTML valide et doit être encodé en UTF-8. La conformité à la DTD XHTML Transitional est recommandée mais pas exigée. Le fichier HTML doit contenir trois éléments DIV avec les attributs id suivants:
  • <div id="fred_template" ... >
    C'est le modèle HTML pour votre smartnote en mode normal (view).
  • <div id="fred_template_edit" ... >
    C'est le modèle HTML pour votre smartnote en mode édition (edit).
  • <div id="fred_editblock" ... >
    C'est le HTML pour le bloc d'options qui s'affiche dans la marge gauche de la page quand la smartnote passe en mode édition (edit). Le bloc d'options est facultatif, vous pouvez omettre le bloc fred_editblock dans votre HTML (mais vous ne devez pas en fournir un vide).
• un fichier fred.js
  Ce fichier Javascript doit être dans le sous-dossier fred/scripts du répertoire fred (donc, pas dans le répertoire commun scripts). Ce fichier Javascript doit être encodé en UTF-8 et il doit obligatoirement définir les quantités suivantes: 1 variable et 2 fonctions, avec des noms spécifiques (dans lequels vous devrez remplacer fred par la signature de votre smartnote).
  var fred_json_template = {n_days: 3, max_t: {"11°C", "14°C", "13°C"}, min_t: {"4°C", "8°C", "4°C"}}
  • var fred_json_template
    C'est un Object Javascript, le modèle du Source Data requis pour décrire votre smartnote.
  • function fred_renderhtml(noteid)
    Chaque fois qu'il doit afficher votre smartnote dans une page web, le système va faire une copie de l'un des modèles que vous fournissez dans le HTML, puis il va appeller fred_renderhtml pour remplir le modèle en fonction du Source Data de votre smartnote.
  • function fred_displaysettings()
    Quand l'utilisateur fait passer votre note en mode edit (édition), la marge gauche de la page masque son affichage habituel et affiche à la place le bloc d'options de votre smartnote: fred_displaysettings est la routine où vous remplissez ce bloc (vous renseignez les valeurs courantes des champs de texte, etc) suivant l'état de la note courante.
  fred_message = {"welcome": "We wish you an enjoyable time here.", "helpmsg": "Click 'done' when you are done."}
• un fichier fred_msgs_en.js, ou un fichier fred_msgs_fr.html, ou tous les deux
  Ce fichier Javascript doit être localisé dans fred/scripts/, et il doit définir un Object: fred_message. Dansfred.js, veillez à n'employer explicitement aucune chaîne de caractères appartenant à une langue. Utilisez plutôt fred_message[ somekey ], que vous définirez dans fred_msgs_fr.js. De cette façon, toutes les versions localisées de votre smartnote peuvent se servir du même fred.js.
  
  Vous êtes libre de définir n'importe quelle clé dans fred_message. Une seule est obligatoire: "plug". fred_message["plug"] est une courte phrase (moins de 80 caractères) à afficher comme une courte présentation, pour expliquer aux visiteurs pourquoi il devraient utiliser la smartnote. Ce texte doit commencer par le nom court que vous souhaitez donner à votre smartnote, suivi du signe souligné ( _ ). Le système reconnaîtra le nom de la smartnote et l'affichera séparément suivant ce qui est prévu par Quomodo. Exemple:
  var fred_message = { "plug": "Maître nageur_Apprenez à votre ordinateur à nager en quelques minutes avec cette smartnote" }
• un fichier help_fred_en.html ou un fichier help_fred_fr.html ou les deux
  Situé dans le répertoire fred, ce HTML doit expliquer comment la smartnote marche et, idéalement, ce qu'un utilisateur peut en faire. Dans votre smartnote, vous devez prévoir un lien, visible en mode édition, qui ouvre le fichier d'aide dans une nouvelle fenêtre. Appelez ce lien: [comment ça marche]. Basez-vous sur les smartnotes de base déjà installées sur le site, pour voir où le lien s'affiche, et pour consulter des exemples de fichiers d'aide.
• un fichier fred_32x32.png et un fichier fred_64x64.png
  Situés dans fred/images/, ces images sont utilisées par le système pour afficher une icône spécifique pour votre smartnote. Contentez-vous de fournir ces fichiers (par exemple en recopiant ceux d'une autre smartnote fournie dans QAT), vous n'avez pas à dessiner les icônes vous-même: Quomodo prendra cela en charge si votre note est sélectionnée pour être publiée en ligne.

Ecrire le Javascript

Où sont stockées les données de ma smartnote?

Le Source Data contient l'ensemble des données qui décrivent votre smartnote, dans un Object Javascript. Le modèle JSON fred_json_template que vous fournissez sert de données par défaut quand une nouvelle note est crée.

• Fournir un champ version avec une valeur entière. Cette valeur est le numéro de version de votre smartnote, vous l'incrémenterez à chaque fois que vous fournirez une nouvelle version (que ce soit une amélioration, une correction de bug, etc.)
  fred_json_template = { version: 3 , ... }
• N'utilisez aucun des champs suivants, qui sont réservés pour l'utilisation par le système (vous verrez plus bas dans ce chapitre à quel effet) : common, members, spacedefaults, user, parentid (et bien sûr ne surchargez pas version).

Comment accéder aux éléments HTML?

• L'id d'une note donnée est stocké dans son Source Data. Plus précisément, c'est le champ common.noteid de son Source Data.
• Quand une de vos fonctions est appelée, l'élément DIV qui affiche, ou qui est en train de se fabriquer pour afficher la smartnote prend le noteid de la smartnote comme attribut id.
• L'id d'une note donnée est le champ (la clé) sous lequel la variable globale qsn_thenotes stocke les données pour cette smartnote.

• Votre smartnote s'affiche en mode fonctionnement normal quand Quomodo sert à l'utilisateur une page où la smartnote est installée.
• Votre smartnote s'affiche en mode édition au moment où elle est créée, et plus tard quand l'utilisateur clique sur le lien modifier (ou edit en Anglais) de votre smartnote.

Comment accéder aux autres données dont j'ai besoin pour afficher la smartnote?

• qsn_noteidslist
  Un Array Javascript avec la liste des ids de toutes les notes installées dans la page :
  [ note_1 , note_2 , ... ]
  Nous mentionnons qsn_noteidslist (dont la fonction principale est de permettre de charger les notes dans un ordre donné) essentiellement pour la clarté. Normalement vous ne devriez pas utiliser cette variable, puisque l'on vous fournira toujours directement l'id de la note que vous devez gérer.
• qsn_thenotes
  Un Objectavec le Source Data pour toutes les notes, dont les clés (les noms des champs) sont les noteid des smartnotes, et les valeurs sont leurs Source Data, de la forme:
  {note_1: { ... }, note_2: { ... }, ...}
  Dans cet Object vous pouvez accéder au Source Data de votre smartnote, et vous pouvez y apporter des modifications à stocker sur le serveur Quomodo.
• members
  Un Object dont les clés sont les ids de tous les membres de l'espace (chaque membre est identifié par un identifiant unique dans l'espace) et dont la valeur pour un membre donné est à son tour un Object contenant les clés username et userlevel, qui contiennent respectivement le nom de l'utilisateur dans cet espace et son statut. userlevel peut prendre trois valeurs: "admin", "member", ou "invite" (tant que l'invitation du membre est en attente).
  {"member_1": {"username": "Mary" , "userlevel": "admin"}, "member_2": {"username": "Fred" , "userlevel": "member"}}
• memberid
  L'identifiant de l'utilisateur courant, qui est donc une des clés de members, par exemple :
  "member_2"
• qsn_currstate
  L'état courant, sous forme d'une chaîne de caractères: "edit" ou "view",
• qsn_edittarget
  Une référence à la smartnote en cours d'édition (donc, un élément DIV), ou null si aucune note n'est actuellement en mode édition. Il ne peut y avoir qu'une note en mode édition à la fois.

Pour accéder au Source Data de votre smartnote quand vous avez son id, il vous suffit donc d'écrire: En mode édition, et en particulier pour programmer fred_displaysettings(), utilisez qsn_edittarget. L'id de cet élément est le noteid de votre smartnote, ainsi l'Object où vous devez stocker un changement est

Comment stocker des données propres à l'utilisateur sur le serveur?

• members est lui même un Object Javascript, dont les clés sont les ids des membres de l'espace. members contient celles des informations propres à l'utilisateur qui sont publiques. Par conséquent, cet Object a les même clés que la variable globale members, que le système fournit dans la page.
  Quand les donnés du JSON sont envoyées au serveur (par exemple, quand l'utilisateur clique sur le bouton valider, en d'autres termes quand votre Javascript appelle qsn_saveedit), le sous-objet membersn'est pas enregisté en tant que tel: uniquement la paire clé-valeur relative à l'utilisateur courant (dont l'identifiant est stocké dans la variable globale memberid) est enregistré, en d'autres termes (si id est le noteid de votre smartnote):
  qsn_thenotes[ id ].members[ memberid ]
  En d'autres termes, votre smartnote peut accéder aux données publiques appartenant aux autres utilisateurs, mais elle ne peut pas les modifier.
• user est lui même un Object Javascript. user contient celles des informations propres à l'utilisateur qui sont privées. Les donnés que vous écrivez dans la clé user du JSON sont stockées par le serveur dans une zone propre à l'utilisateur: une smartnote ne peut donc pas accéder (ni en lecture ni en écriture) aux données privées des autres membres que l'utilisateur courant.
  Note: le système definit une clé common, donc n'utilisez pas de clé common dans le sous-objet user.

Par exemple, une application de travail collaborative enregistrerait tous les rendez-vous de tous les membres sous la clé members, et leurs préferences personnelles sous la clé user.

Comment gérer de nouvelles versions de ma smartnote?

Puisque fred_json_template est le Source Data qui est recopié dans chaque nouvelle note, le numéro de version stocké dans votre template JSON est écrit dans chaque note créée. Le mécanisme de chargement des smartnotes contrôle la version de chaque smartnote vis-à-vis de la valeur de la clé version trouvée dans fred_json_template.

Ecrire le HTML

Structure de la page

Les pages HTML de Quomodo contiennent un en-tête, qui affiche les onglets de l'utilisateur, au-dessus d'un bandeau bleu utilisé pour afficher de courts messages. Sous ce bandeau, l'espace est partagé entre une colonne ou marge gauche, d'une largeur de 200 pixels, et le reste de la page qui affiche le contenu proprement dit de la page - notamment les smartnotes.

en-tête: zone des onglets, hauteur = 28 px
bandeau bleu: affichage de messages courts, hauteur = 34 px
marge gauche: liens, outils, bloc d'options de la smartnote largeur = 200 px	zone principale votre smartnote

Le modèle HTML d'affichage

• Comme attribut id, indiquez fred_notetemplate
• Comme attribut class, indiquez note, stickynote (utilisés dans le CSS), et container (utilisé pour repérer l'élement HTML correspondant à la smartnote parmi tous les éléments DIV). Vous pouvez ajouter votre propre classe, par exemple si vous voulez fournir des propriétes particulieres dans la feuille CSS.
• Ne définissez pas l'attribut style. Quand votre smartnote sera finalisée vous utiliserez l'attribut style pour cacher le modèle pendant la réalisation de l'affichage, par exemple avec style="top: -400px".
• Pour installer la gestion par défaut des événements souris (notamment pour permettre à l'utilisateur de déplacer et redimensionner votre smartnote) installez les mêmes gestionnaires pour onmouseover, onmouseout, et onmousedown que dans les exemples.

Boutons et cases à cocher

• want lows
  au lieu des boutons radio et listes à choix multiples standard, utilisez des éléments A en leur fournissant la classe radio off. Indiquez qsn_handleclick comme gestionnaire de l'événement onclick:
  <a id="fred_lows_true" name="fred_lows" class="radio off" onclick="qsn_handleclick(this)">want lows</a>
  Quand l'utilisateur clique, cette commande appellera fred_handleclick( r ), où r est un Object contenant trois clés: r.name, le nom de l'élément (fred_lows dans l'exemple au-dessus), r.id l'identifiant de l'élément (fred_lows_true dans l'exemple) et r.checked: un booléen, l'état d'activation de l'élément.
  Si vous fournissez plusieurs de ces éléments avec le même attribut name, ils se comportent comme les boutons radio: l'activation de l'un d'entre eux désactive les autres.
  Il est de votre responsabilité de fournir la fonction fred_handleclick: cette fonction, reçoit à elle seule toutes les actions de l'utilisateur sur les éléments possédant class="radio".
  Vous pouvez utiliser trois fonctions pour traiter ces éléments:

  • getchecked ( x ) : retourne l'état d'une élément, sous forme d'un booléen
    x : l'identifiant de l'élément, ou bien une référence à l'élément lui-même
  • setchecked ( x , checked ) : définit l'état de l'élément
    x : l'identifiant de l'élément, ou bien une reférence à l'élément lui-même
    checked : booléen, l'état désiré
  • getcheckedid ( buttonfamilyname ) : retourne l'identifiant de l'élément coché dans la famille d'éléments
    buttonfamilyname : le nom de tous les éléments de la même famille
• validate entry
  au lieu des boutons standard, utilisez un élément A avec la classe button. Indiquez la fonction de votre choix pour gérer l'événement onclick.
  <a class="button" href="" onclick="fred_validate_entry(this) ; return false">validate entry</a>

Le modèle d'édition

• Comme attribut id, indiquez fred_notetemplate_edit
• Comme attribut class, indiquez note, stickynote, et container.
• Ne fournissez pas d'attribut style.
• Installer le gestionnaire standard onmousedown="qsn_beginDrag( this , event );" comme dans les exemples.

Le bloc d'options

• Comme l'attribut id, indiquez fred_ditblock
• Pour tester votre bloc d'options en situation réelle, installez-le dans la marge gauche comme dans les exemples.

Et ensuite ...