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

Parametrization and specific extensions
---------------------------------------

Dynamic default values
``````````````````````
It is possible to define *static* default values in the schema.
It is also possible to define *dynamic* default values
by defining in the entity class a method `default_<attribut name>` for
a given attribute.


Loaded attributes and default sorting management
````````````````````````````````````````````````

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

For example: ::

  class Transition(AnyEntity):
    """..."""
    id = 'Transition'
    fetch_attrs, fetch_order = fetch_config(['name'])

Indicates that for the entity type "Transition", you have to pre-load
the attribute `name` and sort by default on this attribute.


Editing forms management
````````````````````````
It is possible to manage attributes/relations in the simple or multiple
editing form thanks to the following *rtags*: 

* `primary`, indicates that an attribute or a relation has to be
  inserted **in the simple or multiple editing forms**. In the case of
  a relation, the related entity editing form will be included in the
  editing form and represented as a combobox. Each item of the
  combobox is a link to an existing entity.

* `secondary`, indicates that an attribute or a relation has to be
  inserted **in the simple editing form only**. In the case of a
  relation, the related entity editing form will be included in the
  editing form and represented as a combobox. Each item of the combobox
  is a link to an existing entity.

* `inlineview`, includes the target entity's form in the editing form
  of the current entity. It allows to create the target entity in the
  same time as the current entity.

* `generic`, indicates that a relation has to be inserted in the simple
  editing form, in the generic box of relation creation.

* `generated`, indicates that an attribute is dynamically computed
  or other,  and that it should not be displayed in the editing form.

If necessary, it is possible to overwrite the method  
`relation_category(rtype, x='subject')` to dynamically compute
a relation editing category.

``add_related`` box management
``````````````````````````````

The box ``add_related`` is an automatic box that allows to create
an entity automatically related to the initial entity (context in
which the box is displayed). By default, the links generated in this
box are computed from the schema properties of the displayed entity,
but it is possible to explicitely specify them thanks to the
following *rtags*:

* `link`, indicates that a relation is in general created pointing
  to an existing entity and that we should not to display a link
  for this relation

* `create`, indicates that a relation is in general created pointing
  to new entities and that we should display a link to create a new
  entity and link to it automatically


If necessary, it is possible to overwrite the method  
`relation_mode(rtype, targettype, x='subject')` to dynamically
compute a relation creation category.

Please note that if at least one action belongs to the `addrelated` category,
the automatic behavior is desactivated in favor of an explicit behavior
(e.g. display of `addrelated` category actions only).


Filtering table forms management
````````````````````````````````

By default, the view ``table`` manages automatically a filtering
form of its content. The algorithm is as follows:

1. we consider that the first column contains the entities to constraint
2. we collect the first entity of the table (row 0) to represent all the 
   others
3. for all the other variables defined in the original request:
   
   1. if the variable is related to the main variable by at least one relation
   2. we call the method ``filterform_vocabulary(rtype, x)`` on the entity,
      if nothing is returned (meaning a tuple `Non`, see below), we go to the
      next variable, otherwise a form filtering element is created based on
      the vocabulary values returned

4. there are no other limitations to the `RQL`, it can include sorting, grouping
   conditions... JavaScript functions are used to regenerate a request based on the
   initial request and on the selected values from the filtering form.

The method ``filterform_vocabulary(rtype, x, var, rqlst, args, cachekey)`` takes 
the name of a relation and the target as parameters,
[XXX what does it mean ?]
 which indicates of the
entity on which we apply the method is subject or object of the relation. It
has to return:

* a 2-uple of None if it does not know how to handle the relation

* a type and a list containing the vocabulary
  
  * the list has to contain couples (value, label)
  * the type indicates if the value designate an integer (`type == 'int'`),
    a string (`type =='string'` or a non-final relation (`type == 'eid'`)

For example in our application managing tickets, we want to be able to filter
them by :

* type
* priority
* state (in_state)
* tag (tags)
* version (done_in)

For that we define the following method: ::


    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::
  Filtering on state and tags is automatically installed, no need to handle it.