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

Parametrization and specific extensions

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

Dynamic default values

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

It is possible to define in the schema *static* default values.

It is also possible to define in the schema *dynamic* default values

by defining in the entity class a method `default_<attribut name>` for

a given attribute.

Control of loaded attributes and default sorting

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

* The class attribute `fetch_attrs` allows to defined in an entity class

  a list of names of attributes or relations that should be automatically

  loaded when we recover the entities of this type. In the case of relations,

  we are limited to *subject of cardinality `?` or `1`* relations.

* The class method `fetch_order(attr, var)` expects an attribute (or relation)

  name as a parameter and a variable name, and it should return a string

  to use in the requirement `ORDER BY` of an RQL query to automatically

  sort the list of entities of such type according to this attribute, or

  `None` if we do not want to sort on the attribute given in the parameter.

  By default, the entities are sorted according to their creation date.

* The class method `fetch_unrelated_order(attr, var)` is similar to the 

  method `fetch_order` except that it is essentially used to control

  the sorting of drop-down lists enabling relations creation in 

  the editing view of an entity.

The function `fetch_config(fetchattrs, mainattr=None)` simplifies the

definition of the attributes to load and the sorting by returning a 

list of attributes to pre-load (considering automatically the attributes

of `AnyEntity`) and a sorting function based on the main attribute

(the second parameter if specified otherwisethe first attribute from

the list `fetchattrs`).

This function is defined in `cubicweb.entities`.

By example: ::

  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.