.. -*- coding: utf-8 -*-

Paramétrages et extensions spécifiques

--------------------------------------

Valeurs par défaut dynamiques

`````````````````````````````

Il est possible de définir dans le schéma des valeurs par défaut *statiques*.

Il est également possible de définir des valeurs par défaut *dynamiques* en 

définissant sur la classe d'entité une méthode `default_<nom attribut>` pour

un attribut donnée.

Contrôle des attributs chargés et du tri par défaut

```````````````````````````````````````````````````

* l'attribut de classe `fetch_attrs` permet de définir sur une classe d'entité

  la liste des noms des attributs ou relations devant être chargés 

  automatiquement lors de la récupération d'entité(s) de ce type. Dans le cas 

  des relations, on est limité aux relations *sujets de cardinalité `?` ou `1`*.

* la méthode de classe `fetch_order(attr, var)` prend en argument un nom 

  d'attribut (ou de relation) et un nom de variable et doit retourner une chaine

  à utiliser dans la close "ORDERBY" d'une requête RQL pour trier 

  automatiquement les listes d'entités de ce type selon cet attribut, ou `None`

  si l'on ne veut pas de tri sur l'attribut passé en argument. Par défaut les 

  entités sont triées selon leur date de création

* la méthode de classe `fetch_unrelated_order(attr, var)` est similaire à la 

  méthode `fetch_order` mais est utilisée essentiellement pour contrôler le tri

  des listes déroulantes permettant de créer des relations dans la vue d'édition

  d'une entité

La fonction `fetch_config(fetchattrs, mainattr=None)` permet de simplifier la 

définition des attributs à précharger et du tri en retournant une liste des 

attributs à précharger (en considérant ceux de la classe  `AnyEntity`

automatiquement) et une fonction de tri sur l'attribut "principal" (le 2eme 

argument si spécifié ou sinon le premier attribut de la liste `fetchattrs`).

Cette fonction est définie dans le package `ginco.entities`.

Par exemple : ::

  class Transition(AnyEntity):

    """..."""

    id = 'Transition'

    fetch_attrs, fetch_order = fetch_config(['name'])

Indique que pour le type d'entité "Transition" il faut précharger l'attribut

"name" et trier par défaut selon cet attribut.

Contrôle des formulaires d'édition

``````````````````````````````````

Il est possible de contrôler les attributs/relations dans la vue d'édition

simple ou multiple à l'aide des *rtags* suivants :

* `primary`, indique qu'un attribut ou une relation doit être incorporé dans

  les formulaires d'édition simple et multiple. Dans le cas d'une relation,

  le formulaire d'édition de l'entité liée sera inclus dans le formulaire

* `secondary`, indique qu'un attribut ou une relation doit être incorporé dans

  le formulaire d'édition simple uniquement. Dans le cas d'une relation,

  le formulaire d'édition de l'entité liée sera inclus dans le formulaire

* `generic`, indique qu'une relation doit être incorporé dans le formulaire 

  d'édition simple dans la boite générique d'ajout de relation

* `generated`, indique qu'un attribut est caculé dynamiquement ou autre, et 

  qu'il ne doit donc pas être présent dans les formulaires d'édition

Au besoin il est possible de surcharger la méthode 

`relation_category(rtype, x='subject')` pour calculer dynamiquement la catégorie

d'édition d'une relation.

Contrôle de la boîte "add_related"

``````````````````````````````````

La boite `add related` est une boite automatique proposant de créer une entité

qui sera automatiquement liée à l'entité de départ (le contexte dans lequel 

s'affiche la boite). Par défaut, les liens présents dans cette boite sont 

calculés en fonction des propriétés du schéma de l'entité visualisée, mais il

est possible de les spécifier explicitement à l'aide des *rtags* suivants :

* `link`, indique qu'une relation est généralement créée vers une entité

  existante et qu'il ne faut donc pas faire apparaitre de lien pour cette 

  relation

* `create`, indique qu'une relation est généralement créée vers de nouvelles

  entités et qu'il faut donc faire apparaitre un lien pour créer une nouvelle

  entité et la lier automatiquement

Au besoin il est possible de surcharger la méthode  

`relation_mode(rtype, targettype, x='subject')` pour caculer dynamiquement la

catégorie de création d'une relation.

A noter également que si au moins une action dans la catégorie "addrelated" est

trouvée pour le contexte courant, le fonctionnement automatique est désactivé

en faveur du fonctionnement explicite (i.e. affichage des actions de la

catégorie "addrelated" uniquement).

Contrôle des formulaires de filtrage de table

`````````````````````````````````````````````

La vue "table" par défaut gère dynamiquement un formulaire de filtrage du

contenu de celle-ci. L'algorithme est le suivant : 

1. on considère que la première colonne contient les entités à restreindre

2. on recupère la première entité de la table (ligne 0) pour "représenter"

   toutes les autres

3. pour toutes les autres variables définies dans la requête originale :

   1. si la variable est liée à la variable principale par au moins une

      n'importe quelle relation

   2. on appelle la méthode `filterform_vocabulary(rtype, x)` sur l'entité

      et si rien est retourné (ou plus exactement un tuple de valeur `None`,

      voir ci-dessous) on passe à la variable suivante, sinon un élément de

      formulaire de filtrage sera créé avec les valeurs de vocabulaire

      retournées

4. il n'y a pas d'autres limitations sur le rql, il peut comporter des clauses

   de tris, de groupes... Des fonctions javascripts sont utilisées pour

   regénérer une requête à partir de la requête de départ et des valeurs

   séléctionnées dans les filtres de formulaire.

La méthode `filterform_vocabulary(rtype, x, var, rqlst, args, cachekey)` prend

en argument le nom d'une relation et la "cible", qui indique si l'entité sur

laquelle la méthode est appellée est sujet ou objet de la relation. Elle doit

retourner :

* un 2-uple de None si elle ne sait pas gérer cette relation

* un type et une liste contenant le vocabulaire

  * la liste doit contenir des couples (valeur, label)

  * le type indique si la valeur désigne un nombre entier (`type == 'int'`), une

    chaîne de  caractères (`type == 'string'`) ou une entité non finale (`type

    == 'eid'`)

Par exemple dans notre application de gestion de tickets, on veut pouvoir

filtrés ceux-ci par : 

* type

* priorité

* état (in_state)

* étiquette (tags)

* version (done_in)

On définit donc la méthode suivante : ::

    class Ticket(AnyEntity):

	...

	def filterform_vocabulary(self, rtype, x, var, rqlst, args, cachekey):

	    _ = self.req._

	    if rtype == 'type':

		return 'string', [(x, _(x)) for x in ('bug', 'story')]

	    if rtype == 'priority':

		return 'string', [(x, _(x)) for x in ('minor', 'normal', 'important')]

	    if rtype == 'done_in':

		rql = insert_attr_select_relation(rqlst, var, rtype, 'num')

		return 'eid', self.req.execute(rql, args, cachekey)

	    return super(Ticket, self).filterform_vocabulary(rtype, x, var, rqlst,

							     args, cachekey)

NOTE: Le support du filtrage sur les étiquettes et l'état est installé

automatiquement, pas besoin de le gérer ici.