Les comportements par défaut
Nous fournissons ci-dessous la description des comportements par défaut pour les principales fonctions impliquées dans la gestion standard des événements. Pour chaque fonction le signe
surchargeable signifie que vous pouvez définir une fonction de votre choix dont le comportement remplacera le comportement par défaut, suivant les règles décrites dans la
première section.
Pour écrire votre propre fonction, vous pouvez partir de la fonction définie par défaut: les fonctions que vous pouvez vouloir recopier se trouvent dans scripts/qsn_defaultbehaviors.js.
Rappelez-vous que l'appel par exemple de qsn_addnote( id , true ) (avec un argument supplémentaire égal à true) force le comportement par défaut et ne sera pas redirigé vers votre fonction fred_addnote, qui peut donc inclure un tel appel pour invoquer le comportement par défaut.
- qsn_addnote( id ) affiche une smartnote existante dans un nouveau bloc, soit en mode view soit en mode edit, selon la valeur de qsn_currstate. surchargeable
- qsn_template( id ) retourne l'id du modèle HTML de votre smartnote, selon la valeur de qsn_currstate, et en supposant que vous avez fourni les ids de vos modèles sous la forme fred_notetemplate et fred_notetemplate_edit. surchargeable
- qsn_renderhtml( id ) appelle common_renderhtml, puis votre fonction fred_en_renderhtml, que vous devez obligatoirement fournir dans votre fichier Javascript. Utilisez qsn_currstate pour savoir si l'appel s'effectue en mode view ou en mode edit. surchargeable
- qsn_initdone() retourne true si l'initialisation des smartnotes de la page courante est terminée, sinon false.
- qsn_newnote( kind ) est appellé par le système quand l'utilisateur demande la création d'une nouvelle instance de smartnote avec kind comme signature. surchargeable (la fonction personnalisée fred_newnote( ) ne requiert aucun argument).
- qsn_entereditmode( id ) fait une copie des données, masque la note courante, l'affiche en mode édition, affiche le bloc d'options dans la marge gauche, modifie l'opacité de toutes les autres notes pour les rendre semi-transparentes, et enfin ramène la note courante au premier plan.surchargeable
- qsn_makeedittarget( id ) masque la smartnote, et l'affiche en mode édition.
- qsn_showsettings( id ) affiche le bloc d'options dans la marge gauche, et appelle votre routine fred_displaysettings, que vous devez obligatoirement fournir, et qui doit mettre à jour le bloc d'options pour rendre compte des propriétés de la note actuellement en mode édition.
- qsn_username( id ) retourne le nom d'utilisateur du créateur de la note identifiée par id.
- qsn_suppressnote( id ) peut être appellé par le système, ou par le lien supprimer de votre smartnote. surchargeable
- qsn_allowsuppress si le créateur de la note n'est pas Quomodo, demande à l'utilisateur de confirmer qu'il veut supprimer la note. surchargeable
- qsn_editnote( id ) passe la smartnote en mode édition, en mettant qsn_currstate à true puis en appelant qsn_entereditmode.
- qsn_canceledit() met fin au mode édition de la note, rétablit la note qui était en mode édition (et les autres) dans l'état qu'elle avait avant de passer en mode édition, et rétablit également qsn_thenotes à la valeur précédemment stockée par qsn_entereditmode. surchargeable
Note: qsn_canceledit ne prend pas d'argument. Ainsi, pour appeler le comportement par défaut, ajouter un argument true:
qsn_canceledit( true )
- qsn_saveedit() a le même effet que qsn_canceledit mais le nouveau contenu de qsn_thenotes[ noteid ] est enregistré sur le serveur. surchargeable
- qsn_mouseover( elem , e ) est appelé périodiquement tant que la souris est au-dessus de la smartnote. Le comportement par défaut consiste à rendre visibles les liens en haut de la note (modifier et supprimer) et à transformer le curseur en flèche de redimensionnement si la souris est assez proche du bord droit de la note.
surchargeable
elem: une référence à l'élément DIV qui affiche la smartnote,
e: la variable globale d'événement.
- qsn_mouseout( elem , e ) est appelée quand la souris quitte la note. Le comportement par défaut consiste à rendre invisibles les liens en haut de la note et à remettre le curseur standard.surchargeable
elem: une référence à l'élément DIV qui affiche la smartnote,
e: la variable globale d'événement.
- qsn_handleclick( this ), s'il est installé comme gestionnaire de l'événement onclick dans un bouton radio personnalisé Quomodo, lance un appel:fred_en_handleclick( r ) où r contient trois clés: r.id, qui contient la valeur de l'attribut id du bouton radio, r.name, qui contient son attribut name, et r.checked, un booléen qui décrit le nouvel état du bouton.
this: une référence à l'élément de HTML du bouton
- qsn_clonejsontemplate( notekind ) sert à cloner le JSON associer à une smartnote.surchargeable
notekind: le type de la note à cloner
- fred_en_upgradejson( r ) est une fonction que vous devez inclure dans votre script pour gérer les Source Data produites par les versions antérieures de votre smartnote. fred_en_upgradejson est appelé automatiquement quand le script détecte un Source Data avec un numéro de version inférieur au numéro de version le plus récent.
r inclut une clé r.version, un nombre entier que vous devez comparer avec la version courante de votre smartnote, qui est stockée dans fred_json_template.version. fred_en_upgradejson doit retourner le Source Data
mis à jour, dans un nouveau Object Javascript. Le résultat doit donc inclure une clé version remise à jour, c'est-à-dire dont la valeur est égale à fred_json_template.version.
r: le Source Data original de votre smartnote, possiblement d'une version antérieure.
Les comportements par héritage
L'héritage (en anglais inheritance) est un principe connu de la programmation orientée objet qui permet, chez Quomodo, de ne pas avoir à repartir de zéro lorsque l'on veut créer une smartnote. L'héritage concerne donc une smartnote enfant et une ou plusieurs smarnote(s) parent(s). Par analogie, la note enfant possède les caractéristiques (données) et les comportements (fonctions) de ses parents.
Bien que dans la vie ceux sont les parents qui conçoient l'enfant, c'est à nous de dire quels sont les parents de notre smartnote. Pour cela il faut spécifier les parents dans le JSON. Cette manipulation permet de surcharger les fonctions de la smartnote enfant par celles de ses parents et donc d'éviter de recopier les mêmes lignes de codes plusieurs fois.
Par exemple, si on voulait que fred hérite de la note bnq_intl, on devrait spécifier son JSON de cette manière :
var fred_json_template = {common : { inherited : [ { notekind : "bnq_intl" } ], n_days: 3, max_t: {"11°C", "14°C", "13°C"}, min_t: {"4°C", "8°C", "4°C"}}
La clé
inherited situé dans
common a pour valeur une liste de clé-valeur, ou les clés sont des
notekind et les valeurs sont des types de notes. On peut ajouter autant de
notekind que l'on souhaite en les séparant par des virgules.
Remarque. Lorsqu'une smartnote hérite de plusieurs autres smartnotes parents et que celles-ci possèdent des fonctions qui ont les mêmes noms, c'est la fonction associée à la première smartnote de la liste inherited qui est prise en compte chez l'enfant. Sinon si le premier parent ne possède pas une fonction que le deuxième parent possède, alors c'est celle du deuxième parent qui est prise en compte.
Enregistrement des modifications d'une note
Quand l'utilisateur procède à des modifications sur la smartnote, vous souhaiterez la plupart du temps enregistrer les modifications sur le serveur. L'enregistrement des modifications permet que 1/ la prochaine fois que l'utilisateur rechargera la page les modifications seront prises en compte, et 2/ les autres membres du même espace qui sont connectés à ce moment-là voient les modifications sur leur écran en temps réel.
Les modifications qui ont lieu pendant que la smartnote est en mode édition sont automatiquement enregistrées quand l'utilisateur clique le bouton
valider, du moment que vous avez installé le gestionnaire par défaut
qsn_saveedit dans ce bouton, ou que le gestionnaire personnalisé
fred_saveedit que vous avez pu installer appelle lui-même le comportement par défaut.
Par contre, il se peut que vous installiez des éléments d'interface dans votre smartnote telle qu'elle est visible en mode normal ("view"), et il se peut que les actions de l'utilisateur dans cette interface entraînent des modifications qui doivent être enregistrées. Dans ce cas, votre gestionnaire doit appeler explicitement une des trois fonctions prévues à cet effet, et que nous présentons ci-dessous.
Remarque importante. Vous devez respecter une précaution importante. Si vous installez un gestionnaire d'événement pour un événement souris - par exemple un gestionnaire de clic
onclick = "fred_somehandler( this )" - et si cette fonction appelle à un certain moment une des fonctions d'enregistrement sur le serveur, vous devez impérativement désactiver la gestion par défaut des événements souris. Pour cela, installez un gestionnaire de l'événement
onmousedown qui devra appeler la fonction
disabledrag(). Autrement dit, si votre fonction
fred_somehandler appelle, par exemple,
qsn_notechanged, alors:
onclick = "fred_somehandler( this )"
implique de programmer dans le même élément un attribut:
onmousedown = "disabledrag()"
ou, si vous installez les gestionnaires d'événements dynamiquement en Javascript:
theelement.onmousedown = disabledrag
(où
theelement contient une référence à l'élément
DIV).
Sinon, le gestionnaire par défaut peut envoyer une requête AJAX au serveur juste avant la vôtre, ce qui peut annuler celle-ci et finalement empêcher l'enregistrement des modifications.
Voici les fonctions que vous devez appeler quand vous devez enregistrer les modifications de la note sur le serveur.
- qsn_notechanged( id , action , callBack ) envoie au serveur la version courante des données de la note dont le noteid est id, autrement dit qsn_thenotes[ id ]. Le serveur va enregistrer les données, et va retourner ou non un nouvel noteid pour la note, en fonction de si action est "newnote" (signifie que les données correspondent à une nouvelle note, qui n'a encore jamais été enregistrée sur le serveur) ou "notechanged" (la note existait déjà, et on souhaite enregistrer des modifications). Appelez qsn_notechanged avec "notechanged" comme paramètre action chaque fois que vous voulez stocker le dernier état de la note sur le serveur.
id: le noteid de la note dont il faut enregistrer les modifications,
action: une chaîne de caractères, égale soit à "newnote" soit à "notechanged" selon qu'il s'agit d'une nouvelle note ou pas,
callBack: facultatif, une référence à une routine. Si elle est présente, cette routine recevra les données retournées par le serveur, à savoir la liste des changements n'ayant pas encore été pris en compte par la page (par exemple, une note nouvellement créée par un autre utilisateur). Si vous ne fournissez pas d'argument callBack, la callBack par défaut est appelée, celle-ci applique les changements renvoyés par le serveur et le cas échéant (cas d'une note nouvellement créée) attribue un nouvel identifiant (unique) à la nouvelle note: à sa création dans la page, une nouvelle note reçoit en effet un id unique mais provisoire.
- qsn_spacedefaultsnotechanged( id , callBack ) fonctionne comme qsn_notechanged sauf que qsn_spacedefaultsnotechanged limite la sauvegarde au contenu de la clé spacedefaults des Source Data. Le système utilise les paires clé-valeur trouvées dans spacedefaults à la place de ceux contenus dans le sous-objet user tant que ce dernier n'est pas renseigné - typiquement, tant que l'utilisateur n'a pas chargé la page où est installée la smartnote. Vous pouvez par conséquent stocker certains changements ou certains réglages spécifiques effectués par l'utilisateur créateur de le smartnote dans le sous-objet spacedefaults: ils seront utilisés comme valeurs par défaut dans la page des autres utilisateurs. Le memberid de l'utilisateur qui a créé la smartnote est stocké dans le champ common.ownerid du Source Data de la smartnote.
- qsn_usernotechanged( id , callBack ) fonctionne comme qsn_notechanged sauf que qsn_usernotechanged limite la sauvegarde au contenu de la clé user du Source Data, le sous-objet dans lequel sont stockées (s'il y en a) les données privées de l'utilisateur (celles que les autres utilisateurs n'ont pas à connaître).
- qsn_childremoved( id , callBack ) est appelée quand une note fille est supprimée.
Quand vous testez votre smartnote dans l'environnement de développement (QAT), bien entendu les données ne sont pas stockées sur un serveur distant. A la place, QAT utilise les cookies de votre navigateur pour simuler le serveur, et y stocker les données. La clé sous laquelle ces données sont stockées dans les cookies est serverdata.
Ainsi, afin de simuler le comportement normal, dans lequel la page recharge automatiquement les notes qui ont été précédemment enregistrées, la page HTML doit pouvoir utiliser les cookies. Sous certaines configurations (Safari),
ceci peut impliquer d'ouvrir le HTML, non comme un fichier (protocole file://), mais par l'intermédiaire d'un serveur Web local avec http://localhost.
Créer une note unique
Il se trouve dans certain cas que l'on veuille avoir, sur une page donnée, une et une seule occurence de la smartnote que l'on conçoit. Ceci est possible en spécifiant que la note est unique dans son JSON. Par exemple, si on voulait rendre unique la note
fred, on devrait spécifier son JSON de cette manière :
var fredunique_json_template = {common: {unique: { true }}, members: {mem_00001: {common: {invisible: false }}}, n_days: 3, max_t: {"11°C", "14°C", "13°C"}, min_t: {"4°C", "8°C", "4°C"}}
Comme la note est unique pour tous les membres, chaque membre peut choisir de
fermer la note. Dans ce cas, la note est seulement cachée à l'utilisateur qui l'a fermée et reste visible aux autres membres de l'espace. Pour cela, vous pouvez deviner qu'il faut évidemment mettre à jour la partie soulignée du JSON ci-dessus en remplaçant
mem00001 par le
memberid du membre ayant effectué l'action.
Le fait qu'une smartnote soit unique implique, comme on l'a vu, un changement partiel dans ses comportements. Voici la liste des fonctions qui se comportent différement si la smartnote est unique:
- qsn_newnote ( kind ) vérifie, avant de créer la smartnote, si celle-ci ne serait pas seulement cachée à l'utilisateur. Si c'est le cas, elle met invisible à false dans le JSON, sinon elle créée la note comme d'habitude.
-
qsn_closenote( id ) vérifie, avant de fermer la smartnote (invisible à true), si celle-ci est bien unique. Sinon, elle supprime la note. surchargeable.
Il faut faire attention à rendre accessible par des contrôles (boutons, comportement par défaut ou autres) les deux cas d'utilisations : fermeture de la note (qsn_closenote( id )) et suppression de la note (qsn_suppressnote( id )). Il est important de savoir qu'une note, tant qu'elle n'est pas supprimée de l'espace, serait en théorie périodiquement facturée au client. Mais une smartnote que l'on ne peut pas supprimer de l'espace est considérée comme buggée et ne serait pas acceptée.
