doc/devmanual_fr/chap_manipulation_donnees.txt
changeset 0 b97547f5f1fa
equal deleted inserted replaced
-1:000000000000 0:b97547f5f1fa
       
     1 .. -*- coding: utf-8 -*-
       
     2 
       
     3 
       
     4 Manipulation des données stockées
       
     5 =================================
       
     6 
       
     7 Les classes `Entity` et `AnyEntity`
       
     8 -----------------------------------
       
     9 Pour fournir un comportement spécifique à un type d'entité, il suffit de définir
       
    10 une classe héritant de la class `ginco.entities.AnyEntity`. En général il faut
       
    11 définir ces classes dans un module du package `entities` d'une application pour 
       
    12 qu'elle soit disponible à la fois coté serveur et coté client.
       
    13 
       
    14 La classe `AnyEntity` est une classe chargée dynamiquement héritant de la classe
       
    15 de base `Entity` (`ginco.common.entity`). On définit une sous-classe pour
       
    16 ajouter des méthodes ou spécialiser les comportements d'un type d'entité donné.
       
    17 
       
    18 Des descripteurs sont ajoutés à l'enregistrement pour initialiser la classe en
       
    19 fonction du schéma :
       
    20 
       
    21 * on peut accéder aux attributs définis dans le schéma via les attributs de même
       
    22   nom sur les instances (valeur typée)
       
    23 
       
    24 * on peut accéder aux relations définies dans le schéma via les attributs de même
       
    25   nom sur les instances (liste d'instances d'entité)
       
    26 
       
    27 Les méthodes définies sur la classe `AnyEntity` ou `Entity` sont les suivantes :
       
    28 
       
    29 * `has_eid()`, retourne vrai si l'entité à un eid affecté (i.e. pas en cours de
       
    30   création) 
       
    31         
       
    32 * `check_perm(action)`, vérifie que l'utilisateur à le droit d'effectuer
       
    33   l'action demandée sur l'entité
       
    34 
       
    35 :Formattage et génération de la sortie:
       
    36 
       
    37   * `view(vid, **kwargs)`, applique la vue donnée à l'entité
       
    38 
       
    39   * `absolute_url(**kwargs)`, retourne une URL absolue permettant d'accéder à la
       
    40     vue primaire d'une entité
       
    41 
       
    42   * `rest_path()`, renvoie une l'URL REST relative permettant d'obtenir l'entité
       
    43 
       
    44   * `format(attr)`, retourne le format (type MIME) du champ passé en argument
       
    45 
       
    46   * `printable_value(attr, value=_marker, attrtype=None, format='text/html')`, 
       
    47     retourne une chaine permettant l'affichage dans un format donné de la valeur
       
    48     d'un attribut (la valeur est automatiquement récupérée au besoin)
       
    49 
       
    50   * `display_name(form='')`, retourne une chaîne pour afficher le type de
       
    51     l'entité, en spécifiant éventuellement la forme désirée ('plural' pour la
       
    52     forme plurielle)
       
    53 
       
    54 :Gestion de données:
       
    55 
       
    56   * `as_rset()`, transforme l'entité en un resultset équivalent simulant
       
    57      le résultat de la requête `Any X WHERE X eid _eid_`
       
    58 
       
    59   * `complete(skip_bytes=True)`, effectue une requête permettant de récupérer d'un
       
    60     coup toutes les valeurs d'attributs manquant sur l'entité
       
    61 
       
    62   * `get_value(name)`, récupere la valeur associée à l'attribut passé en argument
       
    63 
       
    64   * `related(rtype, x='subject', limit=None, entities=False)`, retourne une liste
       
    65     des entités liées à l'entité courant par la relation donnée en argument
       
    66 
       
    67   * `unrelated(rtype, targettype, x='subject', limit=None)`, retourne un result set
       
    68     des entités not liées à l'entité courante par la relation donnée en argument
       
    69     et satisfaisants les contraintes de celle-ci
       
    70 
       
    71   * `set_attributes(**kwargs)`, met à jour la liste des attributs avec
       
    72     les valeurs correspondantes passées sous forme d'arguments nommés
       
    73 
       
    74   * `copy_relations(ceid)`, copie les relations de l'entité ayant l'eid passé en
       
    75     argument sur l'entité courante
       
    76 
       
    77   * `last_modified(view)`, retourne la date à laquelle on doit considérer
       
    78     l'objet comme modifié (utiliser par la gestion de cache HTTP)
       
    79 
       
    80   * `delete()` permet de supprimer l'entité représentée
       
    81   
       
    82 :Meta-données standard (Dublin Core):
       
    83 
       
    84   * `dc_title()`, retourne une chaine unicode correspondant à la méta-donnée
       
    85     'Title' (utilise par défaut le premier attribut non 'meta' du schéma de
       
    86     l'entité) 
       
    87 
       
    88   * `dc_long_title()`, comme dc_title mais peut retourner un titre plus détaillé
       
    89 
       
    90   * `dc_description(format='text/plain')`, retourne une chaine unicode
       
    91      correspondant à la méta-donnée 'Description' (cherche un attribut
       
    92      'description' par défaut)
       
    93 
       
    94   * `dc_authors()`, retourne une chaine unicode correspondant à la méta-donnée
       
    95     'Authors' (propriétaires par défaut)
       
    96 
       
    97   * `dc_date(date_format=None)`, retourne une chaine unicode
       
    98      correspondant à la méta-donnée 'Date' (date de modification par défaut)
       
    99             
       
   100 :Contrôle du vocabulaire pour les relations:
       
   101 
       
   102   * `vocabulary(rtype, x='subject', limit=None)`, appelée notamment
       
   103     par les vues d'édition d'erudi, elle renvoie une liste de couple
       
   104     (label, eid) des entités qui pourraient être liées à l'entité
       
   105     via la relation `rtype`
       
   106   * `subject_relation_vocabulary(rtype, limit=None)`, appelée
       
   107     en interne par `vocabulary` dans le cas d'une relation sujet
       
   108   * `object_relation_vocabulary(rtype, limit=None)`, appelée
       
   109     en interne par `vocabulary` dans le cas d'une relation objet
       
   110   * `relation_vocabulary(rtype, targettype, x, limit=None)`, appelé
       
   111     en interne par `subject_relation_vocabulary` et `object_relation_vocabulary`
       
   112 
       
   113 
       
   114 Les *rtags*
       
   115 -----------
       
   116 Les *rtags* permettent de spécifier certains comportements propres aux relations
       
   117 d'un type d'entité donné (voir plus loin). Ils sont définis sur la classe 
       
   118 d'entité via l'attribut `rtags` qui est un dictionnaire dont les clés sont un 
       
   119 triplet ::
       
   120 
       
   121   <type de relation>, <type d'entité cible>, <position du contexte ("subject" ou "object"
       
   122 
       
   123 et les valeurs un `set` ou un tuple de marqueurs définissant des propriétés 
       
   124 s'appliquant à cette relation. 
       
   125 
       
   126 Il est possible de simplifier ce dictionnaire :
       
   127 
       
   128 * si l'on veut spécifier un seul marqueur, il n'est pas nécessaire d'utiliser
       
   129   un tuple comme valeur, le marqueur seul (chaine de caractères) suffit
       
   130 * si l'on s'intéresse uniquement à un type de relation et non à la cible et à la
       
   131   position du contexte (ou que celui-ci n'est pas ambigüe), on peut simplement
       
   132   utiliser le nom du type de relation comme clé
       
   133 * si l'on veut qu'un marqueur s'applique quelque soit le type d'entité cible, il
       
   134   faut utiliser la chaine `*` comme type d'entité cible
       
   135 
       
   136 A noter également que ce dictionnaire est *traité à la création de la classe*. 
       
   137 Il est automatiquement fusionné avec celui de la ou des classe(s) parentes (pas
       
   138 besoin de copier celui de la classe parent pour le modifier). De même modifier
       
   139 celui-ci après création de la classe n'aura aucun effet...
       
   140 
       
   141 
       
   142 .. include:: sect_definition_entites.txt