diff -r 2afc9b5aab17 -r bb8bf2688d7e doc/evolution.rst --- a/doc/evolution.rst Wed Oct 02 05:30:19 2013 +0200 +++ b/doc/evolution.rst Sat Oct 05 14:36:29 2013 +0200 @@ -1,3 +1,6 @@ +:tocdepth: 4 +:tocmaxdepth: 3 + ********* Évolution ********* @@ -5,22 +8,280 @@ Internationalisation ==================== -gettext -ref django -fichiers src/p4l/locale/*/LC_MESSAGES/django.po +Le système d'internationalisation (i18n) utilise le mécanisme fourni par Django. + +Il est documenté aux adresses suivantes : + * https://docs.djangoproject.com/en/1.5/topics/i18n/ et + * https://docs.djangoproject.com/en/1.5/topics/i18n/translation/ + +Ce mécanisme est basé sur l'utilitaire `gettext `_. + +En particulier, dans l'arborescence des sources de l'application, les fichiers ``src/p4l/locale/*/LC_MESSAGES/django.[po,mo]`` sont les fichiers de resources de langues. +Les fichier éditable sont les fichiesr ``.po``. -makemessages -a -compilemessages +Deux commandes d'administration sont fournies par Django pour gérer les fichiers de resources de traduction: + + + * ``makemessages`` : https://docs.djangoproject.com/en/1.5/ref/django-admin/#django-admin-makemessages. + C'est la commande permettant la création et la mis ā jour des fichiers ``.po``. + Cette commande extrait des fichier sources de l'application les chaîne de caractères à traduire et les places dans les fichier ``.po``. + Typiquement, on ne lancera cette commande que si de nouvelle chaînes à trduire sont ajoutées dans l'application. + + * ``compilemessages`` : Compile les fichiers ``.po`` contitués par la commande précédente afin que les traduction soit prise en compte. + cette commande produit les fichier ``.mo``. modification des champs ======================= -liste des points à modifier +La modification de la liste des champs traitée par le back-office nécessite des changements a plusieurs niveaux. +Voici une liste des points à modifier. + + * Dans la :ref:`configuration ` (``settings.py``) : les propriétés ``SPARQL_REF_QUERIES`` et ``RDF_SCHEMES`` + * :ref:`Évolution du schéma ` de la base de données + * :ref:`Modification du parser ` pour l'import. + * :ref:`Modification du sérialiseur ` pour l'export + + modification de la constante ``p4l.mapping.constants.GRAPH_NAMESPACES`` + * :ref:`Modification du serialiseur rest `. + * + * modification de l'écran d'affichage du :ref:`détail ` d'une notice. + * modification de l'écran d':ref:`édition ` d'une notice. + +La description de ces modifications se base sur la condition que le type de champ ajouté est le même qu'un champ déjà existant. +La création d'un nouveau type de champ est hors du scope de cette documentation, +mais l'examen attentif des points suivants pourront être un point de dépard pour le développement. + + +.. _evol-config: + +Modification de la configuration +-------------------------------- + +Cette modification concerne seulement les champs dont la(es) valeur(s) est(sont) contrôlé(s) par un référentiel. +Les deux propriétés concernées sont ``SPARQL_REF_QUERIES`` et ``RDF_SCHEMES``. ce sont deux dictionnaires ayant les mêmes valeurs de clef. +Chaque clef correspond à un référentiel. + +.. _evol-config-SPARQL-REF-QUERIES: + +``SPARQL_REF_QUERIES`` +^^^^^^^^^^^^^^^^^^^^^^ + +les valeurs de ce dictionnaire sont elle même un dictionnaire qui contient les requêtes SPARQL d'exploration des reeférentiels. +les clés suivantes sont à renseigner: + + * ``url`` : url du endpoint pour ce référentiel. On n'y mettra ``SPARQL_QUERY_ENDPOINT`` la plupart du temps. + * ``filter`` : requête filtrant les entrées du référentiel selon une partie de terme. + Cette requète est utiliser pour faire de l'autocomplétion. + * ``root`` : Requête qui donne les racines des référentiels en arbre et l'ensemble des termes pour les autres + * ``childs`` : Requ6ete donnant les enfants d'un noeud particulier pour les référentiel "arbre". + Cette clé n'a pas besoin d'être renseigné pour les autres. + * ``child-count`` : Nombre denfant pour 1 noeud d'un référentiel arbre. N'a pas besoin d'être renseignee pour les autres. + + +``RDF_SCHEMES`` +^^^^^^^^^^^^^^^ + +Ce dictionnaire donne les uri des ``scheme`` des référentiels. + + +.. _evol-schema: + +Modification du schema de la base de donnée +------------------------------------------- + +Modification du modèle Django +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +La première étape consiste à modifier le modèle Django. +La documentation Django sur les modèle se trouve à l'url suivante https://docs.djangoproject.com/en/1.5/topics/db/models/ + +le modèle du projet se trouve dans ``src/p4l/models`` et en particulier la définition d'une notice (objet ``Record``) dans ``src/p4l/models/data.py``. +ce fichier contient toute les définitions des champs actuellement utilisés et pourra servir de base d'exemple pour les évolutions envisagées. + +Attention, contrairement à la documentation Django, il ne faut pas appliquer pas la commande ``syncdb`` pour mettre à jour le schema de la base de donnée. + + +Utilisation de South +^^^^^^^^^^^^^^^^^^^^ + +Pour assurer la gestion des migration de modèle de donnée sur des base en production nous utilison le module Django South : http://south.aeracode.org/. + +L'utilisation de ce module passe par la création de migrations. + +En particulier nous suivons l'exemple donné à l'url suivante: +http://south.readthedocs.org/en/latest/tutorial/part1.html#changing-the-model + +Les commandes ajoutées par South sont documentées à l'adresse suivante : +http://south.readthedocs.org/en/latest/commands.html + + +.. _evol-parser: + +Modification du parser pour l'import +------------------------------------ + +L'import des notice au format rdf se fait avec la commande ``import_record`` (cf :ref:`admin-import-record`). +Cette commande sépare le fichier rdf en sous graphes rdf, un par objet ``Record``. +Ces graphes sont alors pris en présent à un parser qui se charge de leur transformation en objets ``Record``. + +Le parser est définit dans le fichier ``src/p4l/mapping/parsers.py``, plus particulièrement dans la classe ``RecordParser``. +La définition des champs et des sous-objets se fait dans la méthode ``build_record``. + +Le parsing des données du graphe se fait en fait à l'aide de deux méthodes principales défines sur la classe ``RecordParser``: + + * ``extract_single_value_form_graph`` : permet d'extraire une valeur simple du graphe. elle est utilisée pour les champs simples monovalués. + * ``extract_multiple_values_from_graph`` : Gère l'ajout d'objet à un gestionnaire d'objets liés ("related object manager" : https://docs.djangoproject.com/en/1.5/ref/models/relations/). + Les données nécessaire pour la création des objets sont extraites du graphe. + + +Points à noter: + + #. les champs simples doivent être positionnés avant la sauvegarde de la notice (appel à la méthode save du modèle ``Record``). + Par contre les champs complexes (sous objets, champs multivalués,...) doivent être traités après l'appel à ``.save()`` + #. Lorsqu'une notice est mise à jour, l'objet ``Record`` et ces dépendances sont effacés et recréés + #. Sauf pour les champs gérés par un référentiel, ll y a une relation d'aggregation entre l'objet ``Record`` et ses sous objets. + Dans le cas des champs complexes avec référentiel, c'est une relation multiple (many to many). + Dans ce cas lors de l'effacement d'un object ``Record``, seul les entrées dans les tables de liason sont effacées. Les entrée dans les tables de référentiel se sont pas affectées. + #. Sur les champs avec référentiel, il n'y a pas de validation. Les entrées dans les tables de référentiels sont crées à la demande, sans validation par rapport au repository Sésame. + #. L'ensemble de la création (ou de l'effacement) d'un objet ``Record`` et de ces dépendances est fait dans une transaction. + + +.. _evol-serializer: + +Modification du serialiseur pour l'export +----------------------------------------- + +l'export des notices au format rdf se fait avec la commande ``dump_record`` (cf :ref:`admin-dump-record`). +Chaque objet ``Record`` concerné par l'export est transformé en graphe rdf par un serialiseur. Le graphe rdf est ensuite sérialisé en xml. + +Le serializer est défini dans le fichier ``src/p4l/mapping/__init__.py`` et fait appel à des resources se trouvant dans ``src/p4l/mapping/serializers.py``. + +Les interfaces définies dans ce modules sont inspirées de celle proposée par le module ``Rest framework`` que nous utilisons par ailleurs (cf. :ref:`evol-rest-serializer`). +En particulier on pourra lire la documentation des ``serializer``: http://django-rest-framework.org/api-guide/serializers.html . + - - settings : SPARQL_REF_QUERIES, RDF_SCHEMES - - base de données : utilisation de south - - description import - - modification export - - modification écran d'affichage - +.. _evol-rest-serializer: + +Modification du serialiseur REST +-------------------------------- + +Une partie de l'application (l'édition des notices) dépend d'interface REST proposant du JSON. +Pour cela nous utilisons le module "Django REST Framework". +La documentation de ce module se trouve à l'adresse suivante : http://django-rest-framework.org/ . + +La classe à modifier est ``RecordSerializer`` qui se trouve dans le fichier ``src/p4l/api/serializers.py``. +La documentation sur les ``serializer`` du Rest Framework est à l'adresses suivante : http://django-rest-framework.org/tutorial/1-serialization.html. +La documentation de l'api des serializer se trouve aux url suivantes : http://django-rest-framework.org/api-guide/serializers.html, http://django-rest-framework.org/api-guide/fields.html, http://django-rest-framework.org/api-guide/relations.html. + +Nous utilisons les mécanismes standarts de sérialisation du ``REST Framework``. Nous avons juste adaptee les points suivants: + + * Pour les champs contrôlés par un référentiel, le mécanisme standart du ``REST Framework`` est d'accepter les valeurs que si elle sont déjà présente dans la base. + Nous avons changé ce comportement pour accepter toute les valeurs et de créer les nouvelles à la demande. Ceci a été fait pour simplifier la gestion des référentiels et la centraliser en amont du back office. + Ceci est implémenté dans la classe ``p4l.api.serializers.ThesaurusSerializer``. + * Pour les champs multiples et les sous-objets, l'ID de l'objet en base n'est pas sérialisée. Ceci se trouve dans la classe ``p4l.api.serializers.P4lModelSerializer``. + * Lors d'un update, les sous-objets sont effacés puis recréés. cela a pour conséquence qu'un update partiel n'est pas possible. A chaque requête de mise à jour, l'ensemble de l'objet ``Record`` et de tous ses sous-objets doit être envoyé à l'API REST d'update. + * Une modification du seerializer REST n'est nécessaire que si le nouveau champ est contrôlé par un référentiel (bien sur si ce nouveau champs est d'un type déjà supporté par l'application). + + +.. _evol-ref-labels: + +Modification de la récupération des labels des champs contrôlés par référentiel +------------------------------------------------------------------------------- + +L'application ne gère pas les labels des valeurs des champs contrôlés par référentiel. +Pour l'affichage dews notices il est donc nécessaire de préalablement requêter tous ces labels. + +Ce requêtage se fait dans la méthode ``p4l.views.fill_label_for_model`` (dans le fichier ``src/p4l/views.py``). +Cette méthode retourne un dictionnaire où les clefs sont les uri des termes, et les valeurs les labels correspondants dans la langue demandées. + +Bien sur aucune modification est nécessaire si le champ ajouté ou modifié n'introduit pas un nouveau référentiel. + + +.. _evol-detail: + +Modification de l'écran de détail +--------------------------------- + +L'écran de détail d'une notice (c.f. :ref:`interface-detail`) utilise le couple classique vue/template Django. + +La documentation Django sur les vues est à l'url suivante : https://docs.djangoproject.com/en/1.5/topics/class-based-views/. +La documentation Django sur les template est ici : https://docs.djangoproject.com/en/1.5/topics/templates/. + +La vue d'affichage du détail d'une notice est générée par la classe suivante : ``p4l.views.RecordDetailView`` (dans le fichier ``src/p4l/views.py``). +Le template d'affichage du détail est le suivant : ``src/templates/p4l/record_view.html``. + +Normalement seul le template a besoin d'être modifié. Les champs déjà présents pourront être pris comme exemple pour introduire le nouveau champ. + + +.. _evol-edition: + +Modification de l'écran d'édition +--------------------------------- + +Comme pour l'écran de détail, l'écran d'édition d'une notice (c.f. :ref:`interface-edit`) utilise un couple vue/template Django. (c.f. :ref:`evol-detail` pour les url de documentation Django) +Par contre les fonctionnalités de cette page sont nettement plus complexes dans leur mise en oeuvre. + +La vue d'édition d'une notice est générée par la classe suivante : ``p4l.views.RecordEditView`` (dans le fichier ``src/p4l/views.py``). +Le template d'affichage du détail est le suivant : ``src/templates/p4l/record_update_form.html``. +Par ailleurs la vue d'édition est en fait une véritable application web ("webapp") basée sur la librairie Angularjs (http://angularjs.org/). +Elle est implémentée dans le fichier ``src/p4l/static/p4l/js/p4l.js``. +La page fait aussi appel à des resources (des templates) dans le reepertoire ``src/p4l/static/p4l/template``. + +Normalement, seul les fichiers template Django ``src/templates/p4l/record_update_form.html`` ou bien angular ``src/p4l/static/p4l/templates`` auront besoin d'être modifiés pour ajouter ou modifier un champs d'un type déjà existant. + +Lors du chargement de la page d'édition, les données de la notice sont chargée à partir de la couche d'API REST sous forme d'objets sérialisés en JSON. +Ces données viennent remplir le "modèle" de l'appli web. +Ce modèle est ensuite exploité dans une série de directives Angularjs (c.f. http://docs.angularjs.org/guide/directive) qui permettent l'éditions des différents champs et sous-objets de la notice. +Lors de la sauvegarde, ce modèle est sérialisé en JSON et soumis par requête http à la couche d'API REST de l'application. + +Le formulaire d'édition utilise 4 types d'éléments pour gérer les différents champs et sous-objets de l'objet notice. + + * Pour les champs simples: des contôles html (``input``, ``textarea``...) liés au modèle dans un formulaire Angularjs (http://docs.angularjs.org/guide/forms) + * Pour les champs simples liés à un référentiel : la directive :ref:`simple-sem-uri `. + * Pour les champs complexes liés à un référentiel : la directive :ref:`add-sem-uri `. + * Pour les champs complexes autres (sous-objets) : la directive :ref:`object-list `. + +Les contrôles html et l'usage qu'Angularjs en fait sont documentés dans la référence d'API : http://docs.angularjs.org/api/. +Le reste des directives est documenté ci-après et on pourra se basé sur les champs existant pour aveoir des exemple d'utilisation. + +.. _evol-edition-simple-sem-uri: + +Directive ``simple-sem-uri`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + * ``val`` : le champ du modèle lié à cette directive. + * ``listname`` : Une des clefs du paramètre de configuration ``SPARQL_REF_QUERIES`` (c.f. :ref:`evol-config-SPARQL-REF-QUERIES`) + * ``placeholder`` : texte d'aide du champs de saisie pour le référentiel. + + +.. _evol-edition-add-sem-uri: + +Directive ``add-sem-uri`` +^^^^^^^^^^^^^^^^^^^^^^^^^ + + * ``list`` : le champ du modèle lié à cette directive, ce doit être une liste (champ multivalué). + * ``listname`` : Une des clefs du paramètre de configuration ``SPARQL_REF_QUERIES`` (c.f. :ref:`evol-config-SPARQL-REF-QUERIES`) + * ``placeholder`` : texte d'aide du champs de saisie pour le référentiel. + + +.. _evol-edition-object-list: + +Directive ``object-list`` +^^^^^^^^^^^^^^^^^^^^^^^^^ + + * ``form-template`` : nom d'un template pour l'édition des sous-objets. + * ``disp-template`` : nom d'un template pour gérer l'affichage des sous-objets. Ce paramêtre est optionnel en mode table. + Si ce paramêtre est vide, un template est automatiquement généré. + * ``object-list`` : le champ du modèle lié à cette directive, ce doit être une liste (champ multivalué). + * ``object-fields`` : Liste des champs du sous-objet à afficher en mode table. + * ``table`` : Affiche les sous objets en table ou pas. + * ``size-fields`` : Largeur des colonnes pour le mode table. L'ordre des colonnes est le même que pour ``object-fields``. + L'unité est une colonne définie par le système de grille Bootstrap : http://getbootstrap.com/css/#grid. + * ``label-fields`` : Label des colonnes pour le mode table. Ces labels sont traduits. L'ordre des colonnes est le même que pour ``object-fields``. + +Les templates définis par les paramêtres ``form-template`` et ``disp-template`` se trouvent dans le répertoire ``src/p4l/static/p4l/templates``. +Ce sont des templates Angularjs (c.f. http://docs.angularjs.org/guide/dev_guide.templates). +Pour les template ``form-template``, l'objet édité est dans la variable ``editedObj``. +Pour les template ``disp-template``, l'objet édité est dans la variable ``obj``. +Les templates existant donneront des exemples d'utilisation et pourront servir de base pour l'ajout d'un nouveau champ. +