# HG changeset patch # User Emile Anclin # Date 1238607651 -7200 # Node ID 33d0e08a931a872fd08891db64d0cb93090dc1fb # Parent 6db7addc28690abcee8f0bbc6b4d0de4709aa7ed [doc] trying to get it a little bit more readable diff -r 6db7addc2869 -r 33d0e08a931a doc/book/en/B0030-data-as-objects.en.txt --- a/doc/book/en/B0030-data-as-objects.en.txt Wed Apr 01 19:39:11 2009 +0200 +++ b/doc/book/en/B0030-data-as-objects.en.txt Wed Apr 01 19:40:51 2009 +0200 @@ -4,15 +4,15 @@ Data as objects =============== -We will in this chapter introduce the objects that are used to handle +In this chapter, we will introduce the objects that are used to handle the data stored in the database. Classes `Entity` and `AnyEntity` -------------------------------- -To provide a specific behavior for each entity, we just need to define -a class inheriting from `cubicweb.entities.AnyEntity`. In general, we have -to defined those classes in a module of `entities` package of an application +To provide a specific behavior for each entity, we have to define +a class inheriting from `cubicweb.entities.AnyEntity`. In general, we +define this class in a module of `entities` package of an application so that it will be available on both server and client side. The class `AnyEntity` is loaded dynamically from the class `Entity` @@ -22,7 +22,7 @@ Descriptors are added when classes are registered in order to initialize the class according to its schema: -* we can access the defined attributes in the schema thanks the attributes of +* we can access the defined attributes in the schema thanks to the attributes of the same name on instances (typed value) * we can access the defined relations in the schema thanks to the relations of @@ -33,12 +33,12 @@ * `has_eid()`, returns true is the entity has an definitive eid (e.g. not in the creation process) -* `check_perm(action)`, checks if the user has the permission to execcute the +* `check_perm(action)`, checks if the user has the permission to execute the requested action on the entity :Formatting and output generation: - * `view(vid, **kwargs)`, apply the given view to the entity + * `view(vid, **kwargs)`, applies the given view to the entity * `absolute_url(**kwargs)`, returns an absolute URL to access the primary view of an entity @@ -118,30 +118,31 @@ *rtags* ------- -*rtags* allows to specify certain behaviors of relations relative to a given +*rtags* allow to specify certain behaviors of relations relative to a given entity type (see later). They are defined on the entity class by the attribute -`rtags` which is a dictionnary with as its keys the triplet :: +`rtags` which is a dictionnary with as keys the triplets :: , , -and as the values a `set` or a tuple of markers defining the properties that +and as values a `set` or a tuple of markers defining the properties that apply to this relation. It is possible to simplify this dictionnary: * if we want to specifiy a single marker, it is not necessary to - use a tuple as the value, the marker by itself (characters string) + use a tuple as value, the marker by itself (character string) is enough * if we only care about a single type of relation and not about the target and the context position (or when this one is not ambigous), we can simply - use the name of the relation type as the key + use the name of the relation type as key * if we want a marker to apply independently from the target entity type, - we have to use the string `*` as the target entity type + we have to use the string `*` as target entity type Please note that this dictionnary is *treated at the time the class is created*. It is automatically merged with the parent class(es) (no need to copy the -dictionnary from the parent class to modify it). Also, modify it after the +dictionnary from the parent class to modify it). Also, modifying it after the class is created will not have any effect... .. include:: B0031-define-entities.en.txt + diff -r 6db7addc2869 -r 33d0e08a931a doc/book/en/B0031-define-entities.en.txt --- a/doc/book/en/B0031-define-entities.en.txt Wed Apr 01 19:39:11 2009 +0200 +++ b/doc/book/en/B0031-define-entities.en.txt Wed Apr 01 19:40:51 2009 +0200 @@ -5,8 +5,8 @@ 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 +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_` for a given attribute. @@ -118,20 +118,22 @@ 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 others variables defined in the original request: +3. for all the other variables defined in the original request: - 1. if the varaible is related to the main variable by at least one relation + 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 is no others limitations to the `RQL`, it can include sorting, grouping - conditions... Javascripts functions are used to regenerate a request based on the +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, which indicates of the +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: @@ -157,18 +159,18 @@ 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, + 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::