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 `cubicweb.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.