Vous voulez developper votre module zwook, l'arranger a votre sauce, et par la meme occasion enrichir la communaute : Bravo ! La toute chose a prendre en consideration pour cela, c'est l'ensemble des modules deja existents. Trois cas peuvent se presenter:
Considerons donc a present que vous n'avez pas trouve chaussure a votre pied. Vous voici donc en coulisses, dans la ZMI (Zope management interface). Tout ce que Zope vous permet de faire, vous pouvez le faire ici, dans Zwook. Pour plus d'information sur le sujet, voyez directement La page de Zope. Mais ce qui nous interesse ici, c'est Zwook. Un seul prerequis : il vous faut un compte avec les droits de Manage pour pouvoir continuer.
Pour programmer en Zwook, vous devez evoluer dans la ZMI. Celle-ci vous permet de vous deplacer au sein de vos donnees Zope/Zwook, i.e. d'evoluer dans la ZODB (Zope Object DataBase). Presenter la ZODB n'est pas l'objet de ce tutoriel. Cependant quelques informations peuvent vous etre utiles.
Tout dabord, le type d'objets que vous aller creer pour programmer votre module sont des script Python. Si vous ne connaissez pas ce langage, allez donc voir Le site Python. Attention cependant, les scripts que vous allez ecrire et placer dans la ZODB n'ont pas acces a toutes les fonctions python ; disons, pour simplifier, que vous pouvez manipuler tout les built-in (int, float, str , dict, list), et les dates.
Les donnees que votre module va stocker dans la ZODB, et que vous verez donc apparaitre dans la ZMI, sont principalement des Folder et des Image. Attention cependant, si une Image est bien ce a quoi l'on s'attend, un Folder est bien plus qu'un repertoire. En effet l'objet Folder peut contenir d'autres objets et de permettre la contruction d'arborescences. Mais il peut aussi contenir une miriade de proprietes. Pensez a un repertoire, avec sa date de creation. Le Folder lui, peut se voir affubler de bien plus de proprietes. Les types les plus courants de ces proprietes sont: int, float, string (str), et lines (lines est un tuple de str). Voici donc la facon la plus simple de stocker vos infos : dans des Folder et des arborescences de Folder.
Deux dernieres remarques pour vous rassurer avant de commencer. En premier lieu : vous pouvez vous tromper ! la ZMI prevoit un mecanisme de Undo (ouf!). En second lieu : vous pouvez vous tromper ! Car tout script executer et aboutissant sur une erreur vous l'ensemble de ses effets annuler. Ainsi, supposons que votre script calcule, puis modifie une donnee, puis calcul, puis plante. Lors de l'execution, vous recerez une message d'erreur, et la donnee modifiee retrouvera son etat d'origine (ie avant execution du script).
Alors, Allons-y!
Du point de vue de Zwook, un module n'est rien de plus qu'un Folder, place dans l'arborescence de votre site, dans le Folder 'zwo_modules'. Le nom de ce Folder sera l'identifiant du module. Pour etre correctement repere par Zwook, le Folder devra porter plusieurs proprietes:
Il est utile de faire une disctinction entre un module et ses instances. Le travail sur lequel nous nous concentrons ici est l'ecriture d'un module. Une fois celui-ci terminer, il deviendra disponible dans l'interface Zwook, pour le contenu de nos pages ou de nos skins. Chaque fois que le module sera utilise, c'est une instance qui sera creee. Toutes les instances auront le meme comportement, et c'est ce que nous allons decrire a present, en ecrivant les scripts du module. Chacune des instances reagira eventuellement aux interactions avec les utilisateurs, et en fonction de ses donnees propres, mais toujours en suivant les regles que vous aurez decrites dans les scripts places dans le Folder portant son nom.
Les scripts du module sont appelles automatiquement par Zwook, en fonction des requetes des utilisateurs. Il existe dont trois point d'entree fondamentaux:
Vous aurez remarquer que la convention veut que l'on reserve au system et a ses derivees les nom debutant par le prefixe 'zwo_'. De meme, on employera le suffixe '_html' pour indiquer que les script produit un affichage, et eventuellement une interaction. On recommendera alors l'utilisation du suffixe '_ok' pour le script traitant l'interaction.
Zwook prevoit que l'on puisse manipuler les intances des modules, de facon a pouvoir librement modifier le contenu des sites. Certaines actions particulieres sont ainsi definies dans les interfaces de gestion du contenu. Par defaut, elles sont prises en charge par Zwook. Il vous est cependant possible de definir des comportements specifiques pour votre module.
Les operations standard sont :
Toutes ces actions ont un comportement par defaut, specifie dans le noyau Zwook. Elles peuvent s'appliquer a une ou plusieurs instances, selon le cas. Si vous desirer modifier leur comportement, vous devez alors ajouter un ou plusiseurs scripts dans la description du module.
Ainsi, supposons que vous vouliez accomplir une tache particuliere lors de la suppression d'une instance (par exemple un nettoyage du disque, ou un message d'adieu). Deux option se presentent a vous. La plus simple correspond au cas ou l'action peut etre entreprise de maniere automatique. Dans ce cas, cous devez fournir un script zwo_del_ok qui sera appelle automatiquement par Zwook. Il recevra comme en parametres d'execution, le dictionnary mem et l'identifiant de l'instance a suprimee.
Votre module peut avoir des contraintes specifiques qui ne permettent pas une suppression automatique sur ces seules informations, mais requiert une interaction avec l'utilisateur. Dans ce cas, vous devrez fournir un script zwo_del_html qui recevra la main lors des suppressions. Il est de bon ton, qu'une fois les traitements termines, vous rendiez la main a /zwo_bo/edit. Remarquez qu'une fois ce script specifie, les instances devront alors etre eliminees une par une, et non plus en groupe ; Zwook se chargera de controle cela, et ne vous donnera qu'un identifiant d'instance a la fois.
Le shema decrit ci-dessus se repete pour les quatre evenements sites. chacun a ses specificites cependant, puisque pour le renomage, un nouvel identifiant sera fourni a zwo_rename_ok et pour zwo_clone_ok ; pour le deplacement, c'est une case qui sera specifiee. Il fautr de plus remarquer que la mise a jour des infos sur la disposition des contenus sera alors a votre charge. vous pouvez prendre exemple sur le code utilise au sein du noyau pour ce point.
Nous pouvons a present nous lancer dans la programmation d'un module. Pour cela, nous allons prendre l'exemple du module texte, qui permet l'affichage d'un texte dans une page, au niveau du contenu, ou au niveau du skin. Nous allons donc voir comment creer les scripts indispensables, comment stocker et manipuler les donnees, et comment interagir avec Zwook.
Nous allons reprendre le code du kzexptext, fourni avec tout noyau Zwook. Aller dans la ZMI, deplacer vous jusqu'au Folder /zwo_modules/kzexptext, et visulisez le proprietes. vous devriez constater que les informations requises sont presentes.
Les scripts dont nous avons besoin y figurent aussi, nous allons donc les commenter.
Commencons par l'affichage. C'est le script zwo_view_html qui sera appele lorsqu'un page contenant un texte du type kzexptext devra etre affichee. ouvrez ce script, vous y decouvrez:
A cela s'ajoute un detail, dans la Parameter List, vous pouvez voir les noms des parametres que recoit le script lorsque Zwook lui passe la main: mem et instance
La premiere ligne est un residu appelant un produit Zope pour l'affichage des textes html. Elle n'est en rien requise, mais vous montre la syntaxe des appels de produit Zope au sein de Zwook
Le second volet demande la mise a jour de la variable mem, en faisant appelle au script mem_mod_data, situe dans le Folder zwo_lib. C'est la syntaxe usuelle pour acceder a des script en Zope : context, puis le chemin menant au script, avec le symbole '.' pour faire le lien.
Le dictionnaire mem est un outil fondamental de la programmation Zwook. C'est un outil qui contient la plus part des informations necessaire a l'execution de vos scripts. Ainsi, on constate, dans les deux lignes suivantes, qu'il possedent une entree droit_vue_dossier, qui vaut 1 si l'utilisateur a les droits necessaire a la visualisation de la page demandee. Remarquez que vous devrez toujours debuter vos scripts d'affichage par ce genre de controle de securite
Le parametre instance est le pointeur qui vous indique le Folder ou le document DTML ou sont stocke les premieres informations concernant l'instance que l'on veut voir. Ce Folder ou se document DTML, c'est vous qui devrez le placer dans l'arborescence du site, lors de la creation de l'instance. Il devra contenir des informations standards necessaires a Zwook, mais il pourra aussi contenir toutes les informations supplementaires que vous jugerez necessaire. Ici, c'est justement le cas du texte a afficher ! Il est stocke dans une propriete de nom data. La 5eme ligne recupere donc le texte a affiche.
Maintenant que nous avons le texte en main, il faut l'afficher. Pour cela, nous allons construire un message, c'est a dire un bout de code html, que nous rendrons en fin de script a Zwook pour qu'il finisse de construire la page dans laquelle doit s'afficher l'instance.
Nous avons pris l'habitude de contruire les messages a afficher a l'aide d'une liste dans laquelle les morceaux du message sont progressivement empiles. Cette liste est ensuite traduite en uns chaine de characteres (str) par l'action de tring.join(message). C'est une petite optimisation qui permet d'eviter des recopies inherente a python. Elle est necessaire car il faut bien avoir en tete que le script zwo_view_html est de loin celui qui sera le plus frequement execute lors de la vie du site.
Le texte a affiche a ete memorise dans la propriete data, de type lines. Il s'agit donc s'une sequence de str. Pour reconstituer le message, il faut donc les recuperer toutes, et c'est ce que fait la boucle for, qui les empile dans message. Ignorons pour l'instant les trois lignes suivantes : Notre affichage est pret!
Nous savons a present comment afficher le texte. Mais comment creer une nouvelle instance. Pour cela, il nous faut definir le script zwo_new_html. La seule chose a faire, est de prevoir la place pour memoriser le texte (accede precedement comme data). Il faudra en plus satisfaire aux attentes de Zwook.
Ouvrez le script zwo_new_html. Vous y trouvez:
Les parametres n'ont que peut changer. Le script recoit toujours le dictionnaire des informations utiles mem. Il recoit en plus le pointeur dossier qui indique dans quel Folder devra etre placee l'instance, c'est a dire en fait dans quelle page on desire creer un kzexptext.
Le premier travail consiste a trouver un nom pour la nouvelle instance. Ce'st ce que realise les six premiere lignes de code, en choisissant un nom par defaut, puis en lui accollant un numero de suffixe de plus en plus grand, jusqu'a ce qu'aucun element du Folder ne porte deja ce nom. On obtient alors un identifiant unique pour l'instance, relativement a sa page.
Vous appercevez ensuite une methode deprecated de construction du message a afficher, qui simule la possibilite d'afficher les morceaux au fur et a mesure. Celle-ci ne fonctionne qu'avec l'ajout de l'instruction finale return printed, et pose le probleme de recopie des string precedement mentionne.
Le noyau de Zwook s'occupe de mettre en place une page tout autour de la zone ou nous allons afficher le formulaire de creation de l'instance. Pas la peine donc de debuter avec les balises body, head, etc.. Nous pouvons coder le formulaire directement. C'est ce que fait le reste du script.
Ce formulaire sera traite par le script new_ok du repertoire correspondant a notre module (kzexptext) au sein des modules (zwo_modules). L'identifiant precalcule est propose, mais l'utilisateur peut en choisir un autre. Il faudra alors controler qu'il est disponible. Une zone textarea est ensuite ouverte pour la saisie du texte a afficher. Ignorons la ligne correspondant au RapidEdit pour l'heure.
Le dernier point concerne le placement de l'instance. On transemet au script traitant la creation effective, l'info de savoir si elle doit etre placee dans le skin ou dans la zone de contenu, via la variable type. De meme, on transmet l'information recue concernant le nom du Folder ou elle doit etre placee.
Lorsque l'utilisateur aura saisie l'identifiant de l'instance, s'il desirait le modifier, et le contenu du texte, son clic sur Creer l'element provoquera la reception du formulaire par le script new_ok. L'url fournie provoque un acces direct a ce script, dont le contenu est :
La Parameter List est titre, data, type, nom, rapidedit='non', et contient donc les parametres emis par le formulaire.
L'url permettant un acces direct au script, il nous faut a nouveau controler les droits de l'utilisateur, pour eviter qu'un pirate habile n'exploite cette url a la main. C'est le travail fait par la contruction du dictionnaire des informations utiles, et le test de droit qui suit.
La fonction mix_id_zope est ensuite utilisee pour debarasser l'identifiant propose de tout les characteres illegaux pour un identifiant Zope. Il serait adroit de mettre en place ici un controle de disponibilite de l'identifiant qui a potentiellement ete modifie par l'utilisateur. Faites cela en exercice ; decouvrez le message d'erreur Zope ; et constater que la ZODB n'a pas ete alteree lors de l'erreure.
La fonction Zope manage_addDTMLDocument nous permet de creer l'objet DTML dans lequel nous allons stocker les informations de l'instance. Cet objet est place dans le Folder utilise pour invoquer la fonction. Selon que l'on place dans le skin ou dans une page, il s'agira du Folder pointe par skin, ou de celui pointe dans mem sous le nom rep_obj.
Un fois cet objet creer, Zwook saura que lorsque l'url correspondant au Folder dossier, ou bien une url travaillant avec le skin nom, seront demandees, il devra passer a view un pointeur sur cette instance pour qu'il en calcule l'affichage. Pour que cela fonctionne, il faut ajouter quelques infomations necessaire a Zwook, et les donnees que nous voulons conserver avec cette instance.
Les informations necessaire a Zwook, sont les deux premiere proprietes qui indiquen respectivement que l'objet est bien un element zwook, et qu'il s'agit d'une instance du module kzexptext. La propriete suivante stocke le contenu du textarea dans un champs Zope de type lines. Ignorons la partie RapidEdit.
C'est pret! il ne reste plus qu'a rendre la main au script zwo_bo/edit/zwo_place, qui va interagir avec l'utilisteur pour positionner l'instance dans la page ou le skin. Il faut pour cela lui transmettre l'identifiant de l'instance que l'on vient de creer.
Zwook est un systeme de gestion du contenu. Le texte que nous venos de creer n'est donc pas voue a etre immuable. C'est ici qu'interviens le script zwo_config_html. Ouvrez ce script. Vous y decouvrez :
Les parametres standard recus par ce script (Parameter List) sont : mem, rep, instance. Le premier est le desormais celebre dictionnaires des informations utiles. Le second est un pointeur sur l'objet Folder ou se trouve l'instance. Le dernier est un pointeur sur l'objet que nous avons cree dans ce Folder, a la suite de l'appel du script zwo_new_html.
Observons a present le code du script de configuration. Il debute de la facon la plus classique : par le controle des droits d'acces. Comme pour le script zwo_new_html, il est appelle par Zwook, et place au sein d'une interface d'edition de contenu. Nous n'avons donc pas besoin de nous soucier des balises html, head, body, etc. La construction du formulaire de saisie du nouveau texte peut donc commencer.
La construction du resultat se fait a nouveau selon la methode de l'empilement des bout de string qui le composeront au sein d'une liste (ici res). Remarquez l'emploi de la fonction extend: elle permet en une seule instruction d'ajouter une liste de string a la liste en cours de construction. La lisibilite n'est pas toujours au rendez-vous. Si necessaire, debutez par l'ecriture qui vous semble la plus lisible, et passez ensuite a la construction par listes.
Les lignes 3 et 4 debutent donc la construction du formulaire. La ligne 5 recupere le contenu actuel du kzexptext, et le place dans la variable message. (Remarquez l'emploi de la fonction join: nous vous conseillons un lecture minutieuse de la bibliotheque string de python.) Une fois le contenu actuel recupere, il est affiche dans le formulaire pour que l'utilisateur puisse librement le modifier. Ignorons pour l'instant les lignes 7 a 11.
La partie visible du formulaire est prete. Les autres informations ajoutees nous serviront au traitement de la saisie. Le traitement se fait dans le script config_ok. Pour mener sa tache a bien, en plus du contenu de la zone textarea, il devra disposer de l'identifiant de l'instance traitee et du nom du repertoire ou celle-ci se situe.
Observons a present le contenu du script config_ok:
Les parametres recus sont ceux generes par le formulaire. Il nous faut donc calculer le dictionnaire mem. Le premier pas ensuite est comme toujours de controler les droits d'acces a ce script. Le premier test if-else nous sert a determiner le positionnement de l'instance: est-il dans le contenu d'une page ou dans un skin? Une fois le pointeur sur l'instance calcule, nous pouvons la modifier
Zope nous fourni les fonction necessaire a la manipulation des objets que nous placons dans la ZMI. Ici, pour modifier un propriete, nous disposons de la fonction manage_changeProperties, qui utilise en fait un dictionnaire base sur les noms des proprietes a mettre a jour, et les valeurs qu'elles doivent prendre. Consulter l'API de Zope pour plus d'information.
C'est fait ! Le script peut rendre la main a Zwook. Mais vous en avez peut etre assez d'ignorer le RapidEdit? Alors regardons-y de plus pres.
nous avons a present repondu a toutes les exigence de Zwook et termine notre premier module. Qu'est ce alors que le RapidEdit. Il s'agit en fait d'une fonctionnalite supplementaire que peuvent offrir certains modules legers, comme par exemple kzexptext.
Une instance de kzexptexte est en fait un element tres simple, dont le contenu (la configuration) peut etre amene a evolue bien plus frequement que celui des autres modules. Il peut alors etre fastidieux de devoir passer par l'interface d'edition du Zwook pour effectuer cette modification. Le but du RapidEdit est de permettre a un utilisateur ayant les droit, d'effectuer la modification du contenu en meme temps qu'il consulte les pages. Cela semble faisable, puisque la seule chose que nous avons du faire ce n'etait finalement qu'un manage_changeProperties.
Reconsiderons les ligne de code ignorees jusqu'ici. En premier lieu, dans le view. C'est la que l'acces a la modification doit etre offert. Si l'instance permet un RapidEdit, et si l'utilisateur a les droits requis, un lien vers le script rapidedit_html est alors propose. ce script s'occupera de saisir la modification, puis de rendre la main, sur le meme principe que zwo_config_html.
L'eventuel acces au RapidEdit pour l'instance doit donc etre gere au niveau de la creation des instances. C'est ce que nous observons dans le code de zwo_new_html, avec la case a cocher proposee dans le formulaire. Lorsque cette case est cochee, le script new_ok placera la valeur de l'option a '1'.Pour etre complet, le script zwo_config_html permet de changer la valeur de l'option RapidEdit, et ainsi d'active ou de desactiver l'affichage du lien au cours de la vie de chaque instance.
Il nous faut donc a present consulter le script rapidedit_html, charge de l'edition en ligne:
On retrouve ici une copie du script zwo_config_html, qui ne propose cependant pas l'option de desactiver le RapidEdit. Remarquez aussi l'emploi de l'entree parent dans mem pour acceder au pointeur sur le Folder contenant l'objet en cours d'edition.
Le script de saisie de la modification redirige vers le script de traitement rapidedit_ok:
On retrouve ici le script config_ok, en simplifie, puisque la modification de l'option RapidEdit n'est plus a traiter. Une fois l'enregistrement de la mise a jour effectuee, ce script rend la main a la navigation en redirigeant automatiquement l'utilisateur vers la page ou se trouve l'instance qu'il vient de modifier. Son url nous est fourni par l'entree rep_url de mem.
Le principe du RapidEdit est tres pratique et peut s'appliquer a d'autres modules. Attention cependant a ne pas le generalise trop attivement. Ce qui le rend simple, c'est aussi que les modifications a faire sur l'instance ne sont pas complexes. si un module necessite des modifications frequentes mais plus complexes, il ne s'agit peut etre pas a proprement parler d'un travail similaire a celui effectue par zwo_config_html, mais peut etre plus d'une fonctionnalite de votre module.