# HG changeset patch # User Sandrine Ribeau # Date 1230069056 28800 # Node ID 2d9e83c34b23def0901411d46c2c4ee6b190213c # Parent 87c8d96f6173a83cca801bb94f0790e993b1607a [doc] Renaming of part II sub-sections accordingly. diff -r 87c8d96f6173 -r 2d9e83c34b23 doc/book/en/B0010-define-schema.en.txt --- a/doc/book/en/B0010-define-schema.en.txt Tue Dec 23 13:38:02 2008 -0800 +++ b/doc/book/en/B0010-define-schema.en.txt Tue Dec 23 13:50:56 2008 -0800 @@ -17,6 +17,6 @@ relation definition of the schema. -.. include:: B021-schema-stdlib.en.txt -.. include:: B022-schema-definition.en.txt +.. include:: B0011-schema-stdlib.en.txt +.. include:: B0012-schema-definition.en.txt diff -r 87c8d96f6173 -r 2d9e83c34b23 doc/book/en/B0011-schema-stdlib.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/B0011-schema-stdlib.en.txt Tue Dec 23 13:50:56 2008 -0800 @@ -0,0 +1,75 @@ +.. -*- coding: utf-8 -*- + +Pre-defined schemas in the library +---------------------------------- + +The library defines a set of entities schemas that are required by the system +or commonly used in `CubicWeb` applications. +Of course, you can extend those schemas if necessarry. + + +System schemas +`````````````` +The system entities available are : + +* `EUser`, system users +* `EGroup`, users groups +* `EEType`, entity type +* `ERType`, relation type + +* `State`, workflow state +* `Transition`, workflow transition +* `TrInfo`, record of a transition trafic for an entity + +* `EmailAddress`, email address, used by the system to send notifications + to the users and also used by others optionnals schemas + +* `EProperty`, used to configure the application +* `EPermission`, used to configure the security of the application + +* `Card`, generic documenting card +* `Bookmark`, an entity type used to allow a user to customize his links within + the application + +Cubes available +``````````````` + +An application is based on several basic cubes. In the set of available +basic cubes we can find for example : + +* `comment`, provides an entity type for `Comment` allowing us to comment others + site's entities + +* `mailinglist`, provides an entity type for `Mailinglist` which groups informations + in a discussion list + +* `file`, provides entity types for `File` et `Image` used to represent + files (text or binary) with additionnal informations such as MIME type or + encoding. + +* `link`, provides an entity type for hypertext link (`Link`) + +* `blog`, provides an entity type weblog (`Blog`) + +* `person`, provides an entity type for a person (`Person`) + +* `addressbook`, provides an entity type used to represent phone + numbers (`PhoneNumber`) and mailing address (`PostalAddress`) + +* `classtags`, categorization system based on tags (`Tag`) + +* `classfolders`, categorization system based on folders hierarchy in order + to create navigation sections (`Folder`) + +* `email`, archiving management for emails (`Email`, `Emailpart`, + `Emailthread`) + +* `basket`, basket management (`Basket`) allowing to group entities + +To declare the use of a component, once installed, add the name of the component +to the variable `__use__` in the file `__pkginfo__.py` of your own component. + +.. note:: + The listed cubes above are available as debian-packages on `CubicWeb's forge`_. + +.. _`CubicWeb's forge`: http://www.cubicweb.org/project?vtitle=All%20cubicweb%20projects diff -r 87c8d96f6173 -r 2d9e83c34b23 doc/book/en/B0012-schema-definition.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/B0012-schema-definition.en.txt Tue Dec 23 13:50:56 2008 -0800 @@ -0,0 +1,386 @@ +.. -*- coding: utf-8 -*- + +Entity type definition +---------------------- + +An entity type is defined by a Python class which inherits `EntityType`. The +class name correponds to the type name. Then the content of the class contains +the description of attributes and relations for the defined entity type, +for example :: + + class Personne(EntityType): + """A person with the properties and the relations necessarry for my + application""" + + last_name = String(required=True, fulltextindexed=True) + first_name = String(required=True, fulltextindexed=True) + title = String(vocabulary=('M', 'Mme', 'Mlle')) + date_of_birth = Date() + works_for = SubjectRelation('Company', cardinality='?*') + +* the name of the Python attribute corresponds to the name of the attribute + or the relation in `CubicWeb` application. + +* all built-in types are available : `String`, `Int`, `Float`, + `Boolean`, `Date`, `Datetime`, `Time`, `Byte`. + +* each entity type has at least the following meta-relations : + + - `eid` (`Int`) + + - `creation_date` (`Datetime`) + + - `modification_date` (`Datetime`) + + - `created_by` (`EUser`) (which user created the entity) + + - `owned_by` (`EUser`) (who does the entity belongs to, by default the + creator but not necessarry and it could have multiple owners) + + - `is` (`EEType`) + + +* it is also possible to define relations of type object by using `ObjectRelation` + instead of `SubjectRelation` + +* the first argument of `SubjectRelation` and `ObjectRelation` gives respectively + the object/subject entity type of the relation. This could be : + + * a string corresponding to an entity type + + * a tuple of string correponding to multiple entities types + + * special string such as follows : + + - "**" : all types of entities + - "*" : all types of non-meta entities + - "@" : all types of meta entities but not system entities (e.g. used for + the basic schema description) + +* it is possible to use the attribute `meta` to flag an entity type as a `meta` + (e.g. used to describe/categorize other entities) + +* optional properties for attributes and relations : + + - `description` : string describing an attribute or a relation. By default + this string will be used in the editing form of the entity, which means + that it is supposed to help the end-user and should be flagged by the + function `_` to be properly internationalized. + + - `constraints` : list of conditions/constraints that the relation needs to + satisfy (c.f. `Contraints`_) + + - `cardinality` : two characters string which specify the cardinality of the + relation. The first character defines the cardinality of the relation on + the subject, the second on the object of the relation. When a relation + has multiple possible subjects or objects, the cardinality applies to all + and not on a one to one basis (so it must be consistent...). The possible + values are inspired from regular expressions syntax : + + * `1`: 1..1 + * `?`: 0..1 + * `+`: 1..n + * `*`: 0..n + + - `meta` : boolean indicating that the relation is a meta-relation (false by + default) + +* optionnal properties for attributes : + + - `required` : boolean indicating if the attribute is required (false by default) + + - `unique` : boolean indicating if the value of the attribute has to be unique + or not within all entities of the same type (false by default) + + - `indexed` : boolean indicating if an index needs to be created for this + attribute in the database (false by default). This is usefull only if + you know that you will have to run numerous searches on the value of this + attribute. + + - `default` : default value of the attribute. In case of date types, the values + which could be used correpond to the RQL keywords `TODAY` and `NOW`. + + - `vocabulary` : specify static possible values of an attribute + +* optionnal properties of type `String` : + + - `fulltextindexed` : boolean indicating if the attribute is part of + the full text index (false by default) (*applicable on the type `Byte` + as well*) + + - `internationalizable` : boolean indicating if the value of the attribute + is internationalizable (false by default) + + - `maxsize` : integer providing the maximum size of the string (no limit by default) + +* optionnal properties for relations : + + - `composite` : string indicating that the subject (composite == 'subject') + is composed of the objects of the relations. For the opposite case (when + the object is composed of the subjects of the relation), we just need + to set 'object' as the value. The composition implies that when the relation + is deleted (so when the composite is deleted), the composed are also deleted. + +Contraints +`````````` +By default, the available constraints types are : + +* `SizeConstraint` : allows to specify a minimum and/or maximum size on + string (generic case of `maxsize`) + +* `BoundConstraint` : allows to specify a minimum and/or maximum value on + numeric types + +* `UniqueConstraint` : identical to "unique=True" + +* `StaticVocabularyConstraint` : identical to "vocabulary=(...)" + +* `RQLConstraint` : allows to specify a RQL query that needs to be satisfied + by the subject and/or the object of the relation. In this query the variables + `S` and `O` are reserved for the entities subject and object of the + relation. + +* `RQLVocabularyConstraint` : similar to the previous type of constraint except + that it does not express a "strong" constraint, which means it is only used to + restrict the values listed in the drop-down menu of editing form, but it does + not prevent another entity to be selected + + +Relation definition +------------------- + +XXX add note about defining relation type / definition + +A relation is defined by a Python class heriting `RelationType`. The name +of the class corresponds to the name of the type. The class then contains +a description of the properties of this type of relation, and could as well +contains a string for the subject and a string for the object. This allows to create +new definition of associated relations, (so that the class can have the +definition properties from the relation) for example :: + + class locked_by(RelationType): + """relation on all entities indicating that they are locked""" + inlined = True + cardinality = '?*' + subject = '*' + object = 'EUser' + +In addition to the permissions, the properties of the relation types +(shared also by all definition of relation of this type) are : + + +* `inlined` : boolean handling the physical optimization for archiving + the relation in the subject entity table, instead of creating a specific + table for the relation. This applies to the relation when the cardinality + of subject->relation->object is 0..1 (`?`) or 1..1 (`1`) + +* `symetric` : boolean indication that the relation is symetrical, which + means `X relation Y` implies `Y relation X` + +In the case of simultaneous relations definitions, `subject` and `object` +can both be equal to the value of the first argument of `SubjectRelation` +and `ObjectRelation`. + +When a relation is not inlined and not symetrical, and it does not require +specific permissions, its definition (by using `SubjectRelation` and +`ObjectRelation`) is all we need. + + +The security model +------------------ + +The security model of `cubicWeb` is based on `Access Control List`. +The main principles are: + +* users and groups of users +* a user belongs to at least one group of user +* permissions (read, update, create, delete) +* permissions are assigned to groups (and not to users) + +For `CubicWeb` in particular: + +* we associate rights at the enttities/relations schema level +* for each entity, we distinguish four kind of permissions: read, + add, update and delete +* for each relation, we distinguish three king of permissions: read, + add and delete (we can not modify a relation) +* the basic groups are: Administrators, Users and Guests +* by default, users belongs to the group Users +* there is a virtual group called `Owners users` to which we + can associate only deletion and update permissions +* we can not add users to the `Owners users` group, they are + implicetely added to it according to the context of the objects + they own +* the permissions of this group are only be checked on update/deletion + actions if all the other groups the user belongs does not provide + those permissions + + +Permissions definition +`````````````````````` + +Define permissions is set through to the attribute `permissions` of entities and +relations types. It defines a dictionnary where the keys are the access types +(action), and the values are the authorized groups or expressions. + +For an entity type, the possible actions are `read`, `add`, `update` and +`delete`. + +For a relation type, the possible actions are `read`, `add`, and `delete`. + +For each access type, a tuple indicates the name of the authorized groups and/or +one or multiple RQL expressions to satisfy to grant access. The access is +provided once the user is in the listed groups or one of the RQL condition is +satisfied. + +The standard groups are : + +* `guests` + +* `users` + +* `managers` + +* `owners` : virtual group corresponding to the entity's owner. + This can only be used for the actions `update` and `delete` of an entity + type. + +It is also possible to use specific groups if they are defined in the precreate +of the cube (``migration/precreate.py``). + + +Use of RQL expression for writing rights +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +It is possible to define RQL expression to provide update permission +(`add`, `delete` and `update`) on relation and entity types. + +RQL expression for entity type permission : + +* you have to use the class `ERQLExpression` + +* the used expression corresponds to the WHERE statement of an RQL query + +* in this expression, the variables X and U are pre-defined references + respectively on the current entity (on which the action is verified) and + on the user who send the request + +* it is possible to use, in this expression, a special relation + "has__permission" where the subject is the user and the + object is a any variable, meaning that the user needs to have + permission to execute the action on the entities related + to this variable + +For RQL expressions on a relation type, the principles are the same except +for the following : + +* you have to use the class `RQLExpression` in the case of a non-final relation + +* in the expression, the variables S, O and U are pre-defined references + to respectively the subject and the object of the current relation (on + which the action is being verified) and the user who executed the query + +* we can also defined rights on attributes of an entity (non-final relation), + knowing that : + + - to defines RQL expression, we have to use the class `ERQLExpression` + in which X represents the entity the attribute belongs to + + - the permissions `add` and `delete` are equivalent. Only `add`/`read` + are actually taken in consideration. + +In addition to that the entity type `EPermission` from the standard library +allow to build very complex and dynamic security architecture. The schema of +this entity type is as follow : :: + + class EPermission(MetaEntityType): + """entity type that may be used to construct some advanced security configuration + """ + name = String(required=True, indexed=True, internationalizable=True, maxsize=100) + require_group = SubjectRelation('EGroup', cardinality='+*', + description=_('groups to which the permission is granted')) + require_state = SubjectRelation('State', + description=_("entity'state in which the permission is applyable")) + # can be used on any entity + require_permission = ObjectRelation('**', cardinality='*1', composite='subject', + description=_("link a permission to the entity. This " + "permission should be used in the security " + "definition of the entity's type to be useful.")) + + +Example of configuration :: + + + ... + + class Version(EntityType): + """a version is defining the content of a particular project's release""" + + permissions = {'read': ('managers', 'users', 'guests',), + 'update': ('managers', 'logilab', 'owners',), + 'delete': ('managers', ), + 'add': ('managers', 'logilab', + ERQLExpression('X version_of PROJ, U in_group G,' + 'PROJ require_permission P, P name "add_version",' + 'P require_group G'),)} + + ... + + class version_of(RelationType): + """link a version to its project. A version is necessarily linked to one and only one project. + """ + permissions = {'read': ('managers', 'users', 'guests',), + 'delete': ('managers', ), + 'add': ('managers', 'logilab', + RRQLExpression('O require_permission P, P name "add_version",' + 'U in_group G, P require_group G'),) + } + inlined = True + +This configuration indicates that an entity `EPermission` named +"add_version" can be associated to a project and provides rights to create +new versions on this project to specific groups. It is important to notice that : + +* in such case, we have to protect both the entity type "Version" and the relation + associating a version to a project ("version_of") + +* because of the genricity of the entity type `EPermission`, we have to execute + a unification with the groups and/or the states if necessary in the expression + ("U in_group G, P require_group G" in the above example) + +Use of RQL expression for reading rights +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The principles are the same but with the following restrictions : + +* we can not use `RRQLExpression` on relation types for reading + +* special relations "has__permission" can not be used + + +Note on the use of RQL expression for `add` permission +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Potentially, the use of an RQL expression to add an entity or a relation +can cause problems for the user interface, because if the expression uses +the entity or the relation to create, then we are not able to verify the +permissions before we actually add the entity (please note that this is +not a problem for the RQL server at all, because the permissions checks are +done after the creation). In such case, the permission check methods +(check_perm, has_perm) can indicate that the user is not allowed to create +this entity but can obtain the permission. +To compensate this problem, it is usually necessary, for such case, +to use an action that reflects the schema permissions but which enables +to check properly the permissions so that it would show up if necessary. + + +Updating your application with your new schema +`````````````````````````````````````````````` + +You have to get a shell on your application :: + + cubicweb-ctl shell moninstance + +and type :: + + add_entity_type('Personne') + +And restart your application! diff -r 87c8d96f6173 -r 2d9e83c34b23 doc/book/en/B0030-data-as-objects.en.txt --- a/doc/book/en/B0030-data-as-objects.en.txt Tue Dec 23 13:38:02 2008 -0800 +++ b/doc/book/en/B0030-data-as-objects.en.txt Tue Dec 23 13:50:56 2008 -0800 @@ -141,4 +141,4 @@ dictionnary from the parent class to modify it). Also, modify it after the class is created will not have any effect... -.. include:: B051-define-entities.en.txt +.. include:: B0031-define-entities.en.txt diff -r 87c8d96f6173 -r 2d9e83c34b23 doc/book/en/B0031-define-entities.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/B0031-define-entities.en.txt Tue Dec 23 13:50:56 2008 -0800 @@ -0,0 +1,168 @@ +.. -*- 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_` 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. + +* `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 sill be included in the editing form. + +* `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 necessarry, 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 necessarry, 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 others variables defined in the original request: + + 1. if the varaible 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 + 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 +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. + diff -r 87c8d96f6173 -r 2d9e83c34b23 doc/book/en/B021-schema-stdlib.en.txt --- a/doc/book/en/B021-schema-stdlib.en.txt Tue Dec 23 13:38:02 2008 -0800 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,75 +0,0 @@ -.. -*- coding: utf-8 -*- - -Pre-defined schemas in the library ----------------------------------- - -The library defines a set of entities schemas that are required by the system -or commonly used in `CubicWeb` applications. -Of course, you can extend those schemas if necessarry. - - -System schemas -`````````````` -The system entities available are : - -* `EUser`, system users -* `EGroup`, users groups -* `EEType`, entity type -* `ERType`, relation type - -* `State`, workflow state -* `Transition`, workflow transition -* `TrInfo`, record of a transition trafic for an entity - -* `EmailAddress`, email address, used by the system to send notifications - to the users and also used by others optionnals schemas - -* `EProperty`, used to configure the application -* `EPermission`, used to configure the security of the application - -* `Card`, generic documenting card -* `Bookmark`, an entity type used to allow a user to customize his links within - the application - -Cubes available -``````````````` - -An application is based on several basic cubes. In the set of available -basic cubes we can find for example : - -* `comment`, provides an entity type for `Comment` allowing us to comment others - site's entities - -* `mailinglist`, provides an entity type for `Mailinglist` which groups informations - in a discussion list - -* `file`, provides entity types for `File` et `Image` used to represent - files (text or binary) with additionnal informations such as MIME type or - encoding. - -* `link`, provides an entity type for hypertext link (`Link`) - -* `blog`, provides an entity type weblog (`Blog`) - -* `person`, provides an entity type for a person (`Person`) - -* `addressbook`, provides an entity type used to represent phone - numbers (`PhoneNumber`) and mailing address (`PostalAddress`) - -* `classtags`, categorization system based on tags (`Tag`) - -* `classfolders`, categorization system based on folders hierarchy in order - to create navigation sections (`Folder`) - -* `email`, archiving management for emails (`Email`, `Emailpart`, - `Emailthread`) - -* `basket`, basket management (`Basket`) allowing to group entities - -To declare the use of a component, once installed, add the name of the component -to the variable `__use__` in the file `__pkginfo__.py` of your own component. - -.. note:: - The listed cubes above are available as debian-packages on `CubicWeb's forge`_. - -.. _`CubicWeb's forge`: http://www.cubicweb.org/project?vtitle=All%20cubicweb%20projects diff -r 87c8d96f6173 -r 2d9e83c34b23 doc/book/en/B022-schema-definition.en.txt --- a/doc/book/en/B022-schema-definition.en.txt Tue Dec 23 13:38:02 2008 -0800 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,386 +0,0 @@ -.. -*- coding: utf-8 -*- - -Entity type definition ----------------------- - -An entity type is defined by a Python class which inherits `EntityType`. The -class name correponds to the type name. Then the content of the class contains -the description of attributes and relations for the defined entity type, -for example :: - - class Personne(EntityType): - """A person with the properties and the relations necessarry for my - application""" - - last_name = String(required=True, fulltextindexed=True) - first_name = String(required=True, fulltextindexed=True) - title = String(vocabulary=('M', 'Mme', 'Mlle')) - date_of_birth = Date() - works_for = SubjectRelation('Company', cardinality='?*') - -* the name of the Python attribute corresponds to the name of the attribute - or the relation in `CubicWeb` application. - -* all built-in types are available : `String`, `Int`, `Float`, - `Boolean`, `Date`, `Datetime`, `Time`, `Byte`. - -* each entity type has at least the following meta-relations : - - - `eid` (`Int`) - - - `creation_date` (`Datetime`) - - - `modification_date` (`Datetime`) - - - `created_by` (`EUser`) (which user created the entity) - - - `owned_by` (`EUser`) (who does the entity belongs to, by default the - creator but not necessarry and it could have multiple owners) - - - `is` (`EEType`) - - -* it is also possible to define relations of type object by using `ObjectRelation` - instead of `SubjectRelation` - -* the first argument of `SubjectRelation` and `ObjectRelation` gives respectively - the object/subject entity type of the relation. This could be : - - * a string corresponding to an entity type - - * a tuple of string correponding to multiple entities types - - * special string such as follows : - - - "**" : all types of entities - - "*" : all types of non-meta entities - - "@" : all types of meta entities but not system entities (e.g. used for - the basic schema description) - -* it is possible to use the attribute `meta` to flag an entity type as a `meta` - (e.g. used to describe/categorize other entities) - -* optional properties for attributes and relations : - - - `description` : string describing an attribute or a relation. By default - this string will be used in the editing form of the entity, which means - that it is supposed to help the end-user and should be flagged by the - function `_` to be properly internationalized. - - - `constraints` : list of conditions/constraints that the relation needs to - satisfy (c.f. `Contraints`_) - - - `cardinality` : two characters string which specify the cardinality of the - relation. The first character defines the cardinality of the relation on - the subject, the second on the object of the relation. When a relation - has multiple possible subjects or objects, the cardinality applies to all - and not on a one to one basis (so it must be consistent...). The possible - values are inspired from regular expressions syntax : - - * `1`: 1..1 - * `?`: 0..1 - * `+`: 1..n - * `*`: 0..n - - - `meta` : boolean indicating that the relation is a meta-relation (false by - default) - -* optionnal properties for attributes : - - - `required` : boolean indicating if the attribute is required (false by default) - - - `unique` : boolean indicating if the value of the attribute has to be unique - or not within all entities of the same type (false by default) - - - `indexed` : boolean indicating if an index needs to be created for this - attribute in the database (false by default). This is usefull only if - you know that you will have to run numerous searches on the value of this - attribute. - - - `default` : default value of the attribute. In case of date types, the values - which could be used correpond to the RQL keywords `TODAY` and `NOW`. - - - `vocabulary` : specify static possible values of an attribute - -* optionnal properties of type `String` : - - - `fulltextindexed` : boolean indicating if the attribute is part of - the full text index (false by default) (*applicable on the type `Byte` - as well*) - - - `internationalizable` : boolean indicating if the value of the attribute - is internationalizable (false by default) - - - `maxsize` : integer providing the maximum size of the string (no limit by default) - -* optionnal properties for relations : - - - `composite` : string indicating that the subject (composite == 'subject') - is composed of the objects of the relations. For the opposite case (when - the object is composed of the subjects of the relation), we just need - to set 'object' as the value. The composition implies that when the relation - is deleted (so when the composite is deleted), the composed are also deleted. - -Contraints -`````````` -By default, the available constraints types are : - -* `SizeConstraint` : allows to specify a minimum and/or maximum size on - string (generic case of `maxsize`) - -* `BoundConstraint` : allows to specify a minimum and/or maximum value on - numeric types - -* `UniqueConstraint` : identical to "unique=True" - -* `StaticVocabularyConstraint` : identical to "vocabulary=(...)" - -* `RQLConstraint` : allows to specify a RQL query that needs to be satisfied - by the subject and/or the object of the relation. In this query the variables - `S` and `O` are reserved for the entities subject and object of the - relation. - -* `RQLVocabularyConstraint` : similar to the previous type of constraint except - that it does not express a "strong" constraint, which means it is only used to - restrict the values listed in the drop-down menu of editing form, but it does - not prevent another entity to be selected - - -Relation definition -------------------- - -XXX add note about defining relation type / definition - -A relation is defined by a Python class heriting `RelationType`. The name -of the class corresponds to the name of the type. The class then contains -a description of the properties of this type of relation, and could as well -contains a string for the subject and a string for the object. This allows to create -new definition of associated relations, (so that the class can have the -definition properties from the relation) for example :: - - class locked_by(RelationType): - """relation on all entities indicating that they are locked""" - inlined = True - cardinality = '?*' - subject = '*' - object = 'EUser' - -In addition to the permissions, the properties of the relation types -(shared also by all definition of relation of this type) are : - - -* `inlined` : boolean handling the physical optimization for archiving - the relation in the subject entity table, instead of creating a specific - table for the relation. This applies to the relation when the cardinality - of subject->relation->object is 0..1 (`?`) or 1..1 (`1`) - -* `symetric` : boolean indication that the relation is symetrical, which - means `X relation Y` implies `Y relation X` - -In the case of simultaneous relations definitions, `subject` and `object` -can both be equal to the value of the first argument of `SubjectRelation` -and `ObjectRelation`. - -When a relation is not inlined and not symetrical, and it does not require -specific permissions, its definition (by using `SubjectRelation` and -`ObjectRelation`) is all we need. - - -The security model ------------------- - -The security model of `cubicWeb` is based on `Access Control List`. -The main principles are: - -* users and groups of users -* a user belongs to at least one group of user -* permissions (read, update, create, delete) -* permissions are assigned to groups (and not to users) - -For `CubicWeb` in particular: - -* we associate rights at the enttities/relations schema level -* for each entity, we distinguish four kind of permissions: read, - add, update and delete -* for each relation, we distinguish three king of permissions: read, - add and delete (we can not modify a relation) -* the basic groups are: Administrators, Users and Guests -* by default, users belongs to the group Users -* there is a virtual group called `Owners users` to which we - can associate only deletion and update permissions -* we can not add users to the `Owners users` group, they are - implicetely added to it according to the context of the objects - they own -* the permissions of this group are only be checked on update/deletion - actions if all the other groups the user belongs does not provide - those permissions - - -Permissions definition -`````````````````````` - -Define permissions is set through to the attribute `permissions` of entities and -relations types. It defines a dictionnary where the keys are the access types -(action), and the values are the authorized groups or expressions. - -For an entity type, the possible actions are `read`, `add`, `update` and -`delete`. - -For a relation type, the possible actions are `read`, `add`, and `delete`. - -For each access type, a tuple indicates the name of the authorized groups and/or -one or multiple RQL expressions to satisfy to grant access. The access is -provided once the user is in the listed groups or one of the RQL condition is -satisfied. - -The standard groups are : - -* `guests` - -* `users` - -* `managers` - -* `owners` : virtual group corresponding to the entity's owner. - This can only be used for the actions `update` and `delete` of an entity - type. - -It is also possible to use specific groups if they are defined in the precreate -of the cube (``migration/precreate.py``). - - -Use of RQL expression for writing rights -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -It is possible to define RQL expression to provide update permission -(`add`, `delete` and `update`) on relation and entity types. - -RQL expression for entity type permission : - -* you have to use the class `ERQLExpression` - -* the used expression corresponds to the WHERE statement of an RQL query - -* in this expression, the variables X and U are pre-defined references - respectively on the current entity (on which the action is verified) and - on the user who send the request - -* it is possible to use, in this expression, a special relation - "has__permission" where the subject is the user and the - object is a any variable, meaning that the user needs to have - permission to execute the action on the entities related - to this variable - -For RQL expressions on a relation type, the principles are the same except -for the following : - -* you have to use the class `RQLExpression` in the case of a non-final relation - -* in the expression, the variables S, O and U are pre-defined references - to respectively the subject and the object of the current relation (on - which the action is being verified) and the user who executed the query - -* we can also defined rights on attributes of an entity (non-final relation), - knowing that : - - - to defines RQL expression, we have to use the class `ERQLExpression` - in which X represents the entity the attribute belongs to - - - the permissions `add` and `delete` are equivalent. Only `add`/`read` - are actually taken in consideration. - -In addition to that the entity type `EPermission` from the standard library -allow to build very complex and dynamic security architecture. The schema of -this entity type is as follow : :: - - class EPermission(MetaEntityType): - """entity type that may be used to construct some advanced security configuration - """ - name = String(required=True, indexed=True, internationalizable=True, maxsize=100) - require_group = SubjectRelation('EGroup', cardinality='+*', - description=_('groups to which the permission is granted')) - require_state = SubjectRelation('State', - description=_("entity'state in which the permission is applyable")) - # can be used on any entity - require_permission = ObjectRelation('**', cardinality='*1', composite='subject', - description=_("link a permission to the entity. This " - "permission should be used in the security " - "definition of the entity's type to be useful.")) - - -Example of configuration :: - - - ... - - class Version(EntityType): - """a version is defining the content of a particular project's release""" - - permissions = {'read': ('managers', 'users', 'guests',), - 'update': ('managers', 'logilab', 'owners',), - 'delete': ('managers', ), - 'add': ('managers', 'logilab', - ERQLExpression('X version_of PROJ, U in_group G,' - 'PROJ require_permission P, P name "add_version",' - 'P require_group G'),)} - - ... - - class version_of(RelationType): - """link a version to its project. A version is necessarily linked to one and only one project. - """ - permissions = {'read': ('managers', 'users', 'guests',), - 'delete': ('managers', ), - 'add': ('managers', 'logilab', - RRQLExpression('O require_permission P, P name "add_version",' - 'U in_group G, P require_group G'),) - } - inlined = True - -This configuration indicates that an entity `EPermission` named -"add_version" can be associated to a project and provides rights to create -new versions on this project to specific groups. It is important to notice that : - -* in such case, we have to protect both the entity type "Version" and the relation - associating a version to a project ("version_of") - -* because of the genricity of the entity type `EPermission`, we have to execute - a unification with the groups and/or the states if necessary in the expression - ("U in_group G, P require_group G" in the above example) - -Use of RQL expression for reading rights -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The principles are the same but with the following restrictions : - -* we can not use `RRQLExpression` on relation types for reading - -* special relations "has__permission" can not be used - - -Note on the use of RQL expression for `add` permission -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Potentially, the use of an RQL expression to add an entity or a relation -can cause problems for the user interface, because if the expression uses -the entity or the relation to create, then we are not able to verify the -permissions before we actually add the entity (please note that this is -not a problem for the RQL server at all, because the permissions checks are -done after the creation). In such case, the permission check methods -(check_perm, has_perm) can indicate that the user is not allowed to create -this entity but can obtain the permission. -To compensate this problem, it is usually necessary, for such case, -to use an action that reflects the schema permissions but which enables -to check properly the permissions so that it would show up if necessary. - - -Updating your application with your new schema -`````````````````````````````````````````````` - -You have to get a shell on your application :: - - cubicweb-ctl shell moninstance - -and type :: - - add_entity_type('Personne') - -And restart your application! diff -r 87c8d96f6173 -r 2d9e83c34b23 doc/book/en/B031-views-stdlib.en.txt --- a/doc/book/en/B031-views-stdlib.en.txt Tue Dec 23 13:38:02 2008 -0800 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,65 +0,0 @@ -.. -*- coding: utf-8 -*- - -Predefined views in the library -------------------------------- - -A certain number of views are used to build the web interface, which apply -to one or more entities. Their identifier is what distinguish them from -each others and the main ones are: - -:primary: - primary view of an entity, this is the view called by default when a single - entity is in the result set and needs to be displayed. This view is supposed - to render a maximum of informations about the entity. -:secondary: - secondary view of an entity. By default it renders the two first attributes - of the entity as a clickable link redirecting to the primary view. -:oneline: - similar to the `secondary` view, but called when we want the view to stand - on a single line, or just get a brief view. By default this view uses the - parameter `MAX_LINE_CHAR` to control the result size. -:text: - similar to the `oneline` view, but should not contain HTML. -:incontext, outofcontext: - similar to the `secondary` view, but called when an entity is considered - as in or out of context. By default it respectively returns the result of - `textincontext` and `textoutofcontext` wrapped in a link leading to - the primary view of the entity. -:textincontext, textoutofcontext: - similar to the `text` view, but called is an entity is considered out or - in context. By default it returns respectively the result of the - methods `.dc_title` and `.dc_long_title` of the entity. -:list: - creates a HTML list (`
    `) and call the view `listitem` for each entity - of the result set -:listitem: - redirects by default to the `outofcontext` view -:rss: - creates a RSS/XML view and call the view `rssitem` for each entity of - the result set -:rssitem: - create a RSS/XML view for each entity based on the results of the dunblin core - methods of the entity (`dc_*`) - -Start view: - -:index: - home page -:schema: - display the schema of the application - -Special views: - -:noresult: - called if the result set is empty -:finall: - display the value of a cell without trasnformation (in case of a non final - entity, we see the eid). Applicable on any result set. -:table: - creates a HTML table (``) and call the view `cell` for each cell of - the result set. Applicable on any result set. -:cell: - by default redirects to the `final` view if this is a final entity or - `outofcontext` view otherwise -:null: - view always applicable and which does not return anything diff -r 87c8d96f6173 -r 2d9e83c34b23 doc/book/en/B051-define-entities.en.txt --- a/doc/book/en/B051-define-entities.en.txt Tue Dec 23 13:38:02 2008 -0800 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,168 +0,0 @@ -.. -*- 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_` 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. - -* `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 sill be included in the editing form. - -* `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 necessarry, 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 necessarry, 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 others variables defined in the original request: - - 1. if the varaible 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 - 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 -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. - diff -r 87c8d96f6173 -r 2d9e83c34b23 doc/book/en/B1020-define-views.en.txt --- a/doc/book/en/B1020-define-views.en.txt Tue Dec 23 13:38:02 2008 -0800 +++ b/doc/book/en/B1020-define-views.en.txt Tue Dec 23 13:50:56 2008 -0800 @@ -210,7 +210,7 @@ the dictionnary of the forms parameters, before going the classic way (through step 1 and 2 described juste above) -.. include:: B031-views-stdlib.en.txt +.. include:: B1021-views-stdlib.en.txt XML views, binaries... diff -r 87c8d96f6173 -r 2d9e83c34b23 doc/book/en/B1021-views-stdlib.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/B1021-views-stdlib.en.txt Tue Dec 23 13:50:56 2008 -0800 @@ -0,0 +1,65 @@ +.. -*- coding: utf-8 -*- + +Predefined views in the library +------------------------------- + +A certain number of views are used to build the web interface, which apply +to one or more entities. Their identifier is what distinguish them from +each others and the main ones are: + +:primary: + primary view of an entity, this is the view called by default when a single + entity is in the result set and needs to be displayed. This view is supposed + to render a maximum of informations about the entity. +:secondary: + secondary view of an entity. By default it renders the two first attributes + of the entity as a clickable link redirecting to the primary view. +:oneline: + similar to the `secondary` view, but called when we want the view to stand + on a single line, or just get a brief view. By default this view uses the + parameter `MAX_LINE_CHAR` to control the result size. +:text: + similar to the `oneline` view, but should not contain HTML. +:incontext, outofcontext: + similar to the `secondary` view, but called when an entity is considered + as in or out of context. By default it respectively returns the result of + `textincontext` and `textoutofcontext` wrapped in a link leading to + the primary view of the entity. +:textincontext, textoutofcontext: + similar to the `text` view, but called is an entity is considered out or + in context. By default it returns respectively the result of the + methods `.dc_title` and `.dc_long_title` of the entity. +:list: + creates a HTML list (`
      `) and call the view `listitem` for each entity + of the result set +:listitem: + redirects by default to the `outofcontext` view +:rss: + creates a RSS/XML view and call the view `rssitem` for each entity of + the result set +:rssitem: + create a RSS/XML view for each entity based on the results of the dunblin core + methods of the entity (`dc_*`) + +Start view: + +:index: + home page +:schema: + display the schema of the application + +Special views: + +:noresult: + called if the result set is empty +:finall: + display the value of a cell without trasnformation (in case of a non final + entity, we see the eid). Applicable on any result set. +:table: + creates a HTML table (`
    `) and call the view `cell` for each cell of + the result set. Applicable on any result set. +:cell: + by default redirects to the `final` view if this is a final entity or + `outofcontext` view otherwise +:null: + view always applicable and which does not return anything diff -r 87c8d96f6173 -r 2d9e83c34b23 doc/book/en/B141-intro.en.txt --- a/doc/book/en/B141-intro.en.txt Tue Dec 23 13:38:02 2008 -0800 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,44 +0,0 @@ -.. -*- coding: utf-8 -*- - -Introduction -============ - -What is `Google AppEngine` ? ------------------------------- - -`Google AppEngine`_ is provided with a partial port of the `Django` -framework, but Google stated at Google IO 2008 that it would not -support a specific Python web framework and that all -community-supported frameworks would be more than welcome [1]_. - -Therefore `Logilab`_ ported `CubicWeb` to run on top of `Google AppEngine`'s -datastore. - -.. _`Google AppEngine`: http://code.google.com/appengine/docs/whatisgoogleappengine.html -.. _Logilab: http://www.logilab.fr/ -.. [1] for more on this matter, read our blog at http://www.logilab.org/blogentry/5216 - - -Essentials ----------- - -To build a web application for `Google App Engine`'s datastore, you -need to have a good understanding of the main concepts of our -`CubicWeb` framework. - -The main concepts are: - - - *schema* - - - *query language* - - - *result set* - - - *views* - - - *generated user interface* - - - *cube* - -You can find detailled explanation of those concepts in :ref:`TermsVocabulary`. - diff -r 87c8d96f6173 -r 2d9e83c34b23 doc/book/en/B142-install.en.txt --- a/doc/book/en/B142-install.en.txt Tue Dec 23 13:38:02 2008 -0800 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,221 +0,0 @@ -.. -*- coding: utf-8 -*- - -.. _installation: - -Installation -============ - -Download the source -------------------- - -- The `Google AppEngine SDK` can be downloaded from: - http://code.google.com/appengine/downloads.html - -- `LAX` is available as an extension of `CubicWeb` under the GPLv2 - license which can be downloaded from : http://cubicweb.org/ - -Please follow instructions on how to install `CubicWeb` framework -(:ref:`CubicWebInstallation`). - -Once ``cubicweb-ctl`` is installed, then you can create a Google -App Engine extension of our framework by running the command :: - - cubicweb-ctl newgapp - -This will create a directory containing :: - - `-- myapp/ - |-- app.conf - |-- app.yaml - |-- bin/ - | `-- laxctl - |-- boostrap_cubes - |-- cubes/ - | |-- addressbook/ - | .. - | |-- comment - | .. - | `-- zone/ - |-- cubicweb/ - |-- custom.py - |-- cw-cubes/ - |-- dateutil/ - |-- docutils/ - |-- fckeditor/ - |-- i18n/ - |-- index.yaml - |-- loader.py - |-- logilab/ - |-- main.py - |-- migration.py - |-- mx/ - |-- roman.py - |-- rql/ - |-- schema.py - |-- simplejson/ - |-- tools/ - |-- views.py - |-- vobject/ - |-- yams/ - `-- yapps/ - - -This skeleton directory is a working `AppEngine` application. You will -recognize the files ``app.yaml`` and ``main.py``. All the rest is the -`LAX` framework and its third-party libraries. You will notice that -the directory ``cubes`` is a library of reusable cubes. - -The main directories that you should know about are: - - - ``cubes`` : this is a library of reusable yams cubes. To use - those cubes you will list them in the variable - `included-yams-cubes` of ``app.conf``. See also :ref:`cubes`. - - [WHICH OTHER ONES SHOULD BE LISTED HERE?] - -Dependencies ------------- - -Before starting anything, please make sure the following packages are installed: - - yaml : by default google appengine is providing yaml; make sure you can - import it. We recommend you create a symbolic link yaml instead of installing - and using python-yaml: - yaml -> full/path/to/google_appengine/lib/yaml/lib/yaml/ - - gettext - -Setup ------ - -Once you executed ``cubicweb-ctl newgapp ``, you can use that ``myapp/`` -as an application directory and do as follows. - -This installation directory provides a configuration for an instance of `CubicWeb` -ported for Google App Engine. It is installed with its own command ``laxctl`` -which is a port of the command tool ``cubicweb-ctl`` originally developped for -`CubicWeb`. - -You can have the details of available commands by running :: - - $ python myapp/bin/laxctl --help - - -Generating translation files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -`LAX` is fully internationalized. Translation catalogs are found in -``myapp/i18n``. To compile the translation files, use the `gettext` tools -or the ``laxctl`` command :: - - $ python myapp/bin/laxctl i18nupdate - $ python myapp/bin/laxctl i18ncompile - -Ignore the errors that print "No translation file found for domain -'erudi'". They disappear after the first run of i18ncompile. - -.. note:: The command myapp/bin/laxctl i18nupdate needs to be executed - only if your application is using cubes from ginco-apps. - Otherwise, please skip it. - -You will never need to add new entries in the translation catalog. Instead we would -recommand you to use ``self.req._("msgId")`` in your application code -to flag new message id to add to the catalog, where ``_`` refers to -xgettext that is used to collect new strings to translate. -While running ``laxctl i18nupdate``, new string will be added to the catalogs. - -Generating the data directory -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In order to generate the ``myapp/data`` directory that holds the static -files like stylesheets and icons, you need to run the command:: - - $ python myapp/bin/laxctl populatedata - -Generating the schema diagram -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -There is a view named ``schema`` that displays a diagram of the -entity-relationship graph defined by the schema. This diagram has to -be generated from the command line:: - - $ python myapp/bin/laxctl genschema - -Application configuration -------------------------- - -Authentication -~~~~~~~~~~~~~~ - -You have the option of using or not google authentication for your application. -This has to be define in ``app.conf`` and ``app.yaml``. - -In ``app.conf`` modify the following variable:: -  - # does this application rely on google authentication service or not. - use-google-auth=no - -In ``app.yaml`` comment the `login: required` set by default in the handler:: - - - url: .* - script: main.py - # comment the line below to allow anonymous access or if you don't want to use - # google authentication service - #login: required - - - - -Quickstart : launch the application ------------------------------------ - -On Mac OS X platforms, drag that directory on the -`GoogleAppEngineLauncher`. - -On Unix and Windows platforms, run it with the dev_appserver:: - - $ python /path/to/google_appengine/dev_appserver.py /path/to/myapp/ - -Once the local server is started, visit `http://MYAPP_URL/_load `_ and sign in as administrator. -This will initialize the repository and enable you to log in into -the application and continue the installation. - -You should be redirected to a page displaying a message `content initialized`. - -Initialize the datastore -~~~~~~~~~~~~~~~~~~~~~~~~ - -You, then, want to visit `http://MYAPP_URL/?vid=authinfo `_ . -If you selected not to use google authentication, you will be prompted to a -login form where you should initialize the administrator login (recommended -to use admin/admin at first). You will then be redirected to a page providing -you the value to provide to ``./bin/laxctl --cookie``. - -If you choosed to use google authentication, then you will not need to set up -and administrator login but you will get the cookie value as well. - -This cookie values needs to be provided to ``laxctl`` commands -in order to handle datastore administration requests. - -.. image:: images/lax-book.02-cookie-values.en.png - :alt: displaying the detailed view of the cookie values returned - - -.. note:: In case you are not redirected to a page providing the - option --cookie value, please visit one more time - `http://MYAPP_URL/?vid=authinfo `_ . - -Once, you have this value, then return to the shell and execute :: - - $ python myapp/bin/laxctl db-init --cookie='dev_appserver_login=test@example.com:True; __session=7bbe973a6705bc5773a640f8cf4326cc' localhost:8080 - -.. note:: In the case you are not using google authentication, the value returned - by `http://MYAPP_URL/?vid=authinfo `_ - will look like : - --cookie='__session=2b45d1a9c36c03d2a30cedb04bc37b6d' - -Log out by clicking in the menu at the top right corner -and restart browsing from `http://MYAPP_URL/ `_ -as a normal user. - -Unless you did something to change it, http://MYAPP_URL should be -http://localhost:8080/ - - diff -r 87c8d96f6173 -r 2d9e83c34b23 doc/book/en/B2050-google-appengine.en.txt --- a/doc/book/en/B2050-google-appengine.en.txt Tue Dec 23 13:38:02 2008 -0800 +++ b/doc/book/en/B2050-google-appengine.en.txt Tue Dec 23 13:50:56 2008 -0800 @@ -7,5 +7,5 @@ ========================== -.. include:: B141-intro.en.txt -.. include:: B142-install.en.txt +.. include:: B2051-intro.en.txt +.. include:: B2052-install.en.txt diff -r 87c8d96f6173 -r 2d9e83c34b23 doc/book/en/B2051-intro.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/B2051-intro.en.txt Tue Dec 23 13:50:56 2008 -0800 @@ -0,0 +1,44 @@ +.. -*- coding: utf-8 -*- + +Introduction +============ + +What is `Google AppEngine` ? +------------------------------ + +`Google AppEngine`_ is provided with a partial port of the `Django` +framework, but Google stated at Google IO 2008 that it would not +support a specific Python web framework and that all +community-supported frameworks would be more than welcome [1]_. + +Therefore `Logilab`_ ported `CubicWeb` to run on top of `Google AppEngine`'s +datastore. + +.. _`Google AppEngine`: http://code.google.com/appengine/docs/whatisgoogleappengine.html +.. _Logilab: http://www.logilab.fr/ +.. [1] for more on this matter, read our blog at http://www.logilab.org/blogentry/5216 + + +Essentials +---------- + +To build a web application for `Google App Engine`'s datastore, you +need to have a good understanding of the main concepts of our +`CubicWeb` framework. + +The main concepts are: + + - *schema* + + - *query language* + + - *result set* + + - *views* + + - *generated user interface* + + - *cube* + +You can find detailled explanation of those concepts in :ref:`TermsVocabulary`. + diff -r 87c8d96f6173 -r 2d9e83c34b23 doc/book/en/B2052-install.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/B2052-install.en.txt Tue Dec 23 13:50:56 2008 -0800 @@ -0,0 +1,221 @@ +.. -*- coding: utf-8 -*- + +.. _installation: + +Installation +============ + +Download the source +------------------- + +- The `Google AppEngine SDK` can be downloaded from: + http://code.google.com/appengine/downloads.html + +- `LAX` is available as an extension of `CubicWeb` under the GPLv2 + license which can be downloaded from : http://cubicweb.org/ + +Please follow instructions on how to install `CubicWeb` framework +(:ref:`CubicWebInstallation`). + +Once ``cubicweb-ctl`` is installed, then you can create a Google +App Engine extension of our framework by running the command :: + + cubicweb-ctl newgapp + +This will create a directory containing :: + + `-- myapp/ + |-- app.conf + |-- app.yaml + |-- bin/ + | `-- laxctl + |-- boostrap_cubes + |-- cubes/ + | |-- addressbook/ + | .. + | |-- comment + | .. + | `-- zone/ + |-- cubicweb/ + |-- custom.py + |-- cw-cubes/ + |-- dateutil/ + |-- docutils/ + |-- fckeditor/ + |-- i18n/ + |-- index.yaml + |-- loader.py + |-- logilab/ + |-- main.py + |-- migration.py + |-- mx/ + |-- roman.py + |-- rql/ + |-- schema.py + |-- simplejson/ + |-- tools/ + |-- views.py + |-- vobject/ + |-- yams/ + `-- yapps/ + + +This skeleton directory is a working `AppEngine` application. You will +recognize the files ``app.yaml`` and ``main.py``. All the rest is the +`LAX` framework and its third-party libraries. You will notice that +the directory ``cubes`` is a library of reusable cubes. + +The main directories that you should know about are: + + - ``cubes`` : this is a library of reusable yams cubes. To use + those cubes you will list them in the variable + `included-yams-cubes` of ``app.conf``. See also :ref:`cubes`. + - [WHICH OTHER ONES SHOULD BE LISTED HERE?] + +Dependencies +------------ + +Before starting anything, please make sure the following packages are installed: + - yaml : by default google appengine is providing yaml; make sure you can + import it. We recommend you create a symbolic link yaml instead of installing + and using python-yaml: + yaml -> full/path/to/google_appengine/lib/yaml/lib/yaml/ + - gettext + +Setup +----- + +Once you executed ``cubicweb-ctl newgapp ``, you can use that ``myapp/`` +as an application directory and do as follows. + +This installation directory provides a configuration for an instance of `CubicWeb` +ported for Google App Engine. It is installed with its own command ``laxctl`` +which is a port of the command tool ``cubicweb-ctl`` originally developped for +`CubicWeb`. + +You can have the details of available commands by running :: + + $ python myapp/bin/laxctl --help + + +Generating translation files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +`LAX` is fully internationalized. Translation catalogs are found in +``myapp/i18n``. To compile the translation files, use the `gettext` tools +or the ``laxctl`` command :: + + $ python myapp/bin/laxctl i18nupdate + $ python myapp/bin/laxctl i18ncompile + +Ignore the errors that print "No translation file found for domain +'erudi'". They disappear after the first run of i18ncompile. + +.. note:: The command myapp/bin/laxctl i18nupdate needs to be executed + only if your application is using cubes from ginco-apps. + Otherwise, please skip it. + +You will never need to add new entries in the translation catalog. Instead we would +recommand you to use ``self.req._("msgId")`` in your application code +to flag new message id to add to the catalog, where ``_`` refers to +xgettext that is used to collect new strings to translate. +While running ``laxctl i18nupdate``, new string will be added to the catalogs. + +Generating the data directory +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In order to generate the ``myapp/data`` directory that holds the static +files like stylesheets and icons, you need to run the command:: + + $ python myapp/bin/laxctl populatedata + +Generating the schema diagram +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There is a view named ``schema`` that displays a diagram of the +entity-relationship graph defined by the schema. This diagram has to +be generated from the command line:: + + $ python myapp/bin/laxctl genschema + +Application configuration +------------------------- + +Authentication +~~~~~~~~~~~~~~ + +You have the option of using or not google authentication for your application. +This has to be define in ``app.conf`` and ``app.yaml``. + +In ``app.conf`` modify the following variable:: +  + # does this application rely on google authentication service or not. + use-google-auth=no + +In ``app.yaml`` comment the `login: required` set by default in the handler:: + + - url: .* + script: main.py + # comment the line below to allow anonymous access or if you don't want to use + # google authentication service + #login: required + + + + +Quickstart : launch the application +----------------------------------- + +On Mac OS X platforms, drag that directory on the +`GoogleAppEngineLauncher`. + +On Unix and Windows platforms, run it with the dev_appserver:: + + $ python /path/to/google_appengine/dev_appserver.py /path/to/myapp/ + +Once the local server is started, visit `http://MYAPP_URL/_load `_ and sign in as administrator. +This will initialize the repository and enable you to log in into +the application and continue the installation. + +You should be redirected to a page displaying a message `content initialized`. + +Initialize the datastore +~~~~~~~~~~~~~~~~~~~~~~~~ + +You, then, want to visit `http://MYAPP_URL/?vid=authinfo `_ . +If you selected not to use google authentication, you will be prompted to a +login form where you should initialize the administrator login (recommended +to use admin/admin at first). You will then be redirected to a page providing +you the value to provide to ``./bin/laxctl --cookie``. + +If you choosed to use google authentication, then you will not need to set up +and administrator login but you will get the cookie value as well. + +This cookie values needs to be provided to ``laxctl`` commands +in order to handle datastore administration requests. + +.. image:: images/lax-book.02-cookie-values.en.png + :alt: displaying the detailed view of the cookie values returned + + +.. note:: In case you are not redirected to a page providing the + option --cookie value, please visit one more time + `http://MYAPP_URL/?vid=authinfo `_ . + +Once, you have this value, then return to the shell and execute :: + + $ python myapp/bin/laxctl db-init --cookie='dev_appserver_login=test@example.com:True; __session=7bbe973a6705bc5773a640f8cf4326cc' localhost:8080 + +.. note:: In the case you are not using google authentication, the value returned + by `http://MYAPP_URL/?vid=authinfo `_ + will look like : + --cookie='__session=2b45d1a9c36c03d2a30cedb04bc37b6d' + +Log out by clicking in the menu at the top right corner +and restart browsing from `http://MYAPP_URL/ `_ +as a normal user. + +Unless you did something to change it, http://MYAPP_URL should be +http://localhost:8080/ + +