# HG changeset patch # User Nicolas Chauvat # Date 1227209763 -3600 # Node ID 9ecd54ea0634ce6d81d735d7da3e1c6b023ada48 # Parent 1091d8d63f51b886ded029581976e05970bd4b02 [doc] more chapters diff -r 1091d8d63f51 -r 9ecd54ea0634 doc/book/en/02-01-registry.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/02-01-registry.en.txt Thu Nov 20 20:36:03 2008 +0100 @@ -0,0 +1,9 @@ +.. -*- coding: utf-8 -*- + +The Registry +============ + +[WRITE ME] + +* talk about the vreg singleton, appobjects, registration and selection + diff -r 1091d8d63f51 -r 9ecd54ea0634 doc/book/en/02-02-configuration.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/02-02-configuration.en.txt Thu Nov 20 20:36:03 2008 +0100 @@ -0,0 +1,9 @@ +.. -*- coding: utf-8 -*- + +Configuration +============= + +[WRITE ME] + +* the config object. adding configuration option + diff -r 1091d8d63f51 -r 9ecd54ea0634 doc/book/en/03-00-definition-schema.en.txt --- a/doc/book/en/03-00-definition-schema.en.txt Thu Nov 20 20:14:23 2008 +0100 +++ b/doc/book/en/03-00-definition-schema.en.txt Thu Nov 20 20:36:03 2008 +0100 @@ -16,5 +16,5 @@ schema. -.. include:: 03-sect-stdlib-schemas.en.txt -.. include:: 03-sect-definition-schema.en.txt +.. include:: 03-10-stdlib-schemas.en.txt +.. include:: 03-11-definition-schema.en.txt diff -r 1091d8d63f51 -r 9ecd54ea0634 doc/book/en/03-00-sect-definition-schema.en.txt --- a/doc/book/en/03-00-sect-definition-schema.en.txt Thu Nov 20 20:14:23 2008 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,344 +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, -by 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 `LAX` application. - -* all built-in types are available: `String`, `Int`, `Float`, - `Boolean`, `Date`, `Datetime`, `Time`, `Byte`. - -* each entity 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 entities non meta - - "@" : all types of meta entities but not system entities (e.g. used for - the basis 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. - [PAS CLAIR] - -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 - [PAS CLAIR] - - -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, as well as 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)[PAS CLAIR] by 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 own 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. - -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 define in the precreate -of the application (``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 - [WHAT IS A NON FINALE 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 thatm 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 assumes/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 [??] `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 checks 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. -[PAS CLAIR] diff -r 1091d8d63f51 -r 9ecd54ea0634 doc/book/en/03-00-sect-stdlib-schemas.en.txt --- a/doc/book/en/03-00-sect-stdlib-schemas.en.txt Thu Nov 20 20:14:23 2008 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,86 +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 `LAX` applications. -Of course, you can extend those schemas if necessarry. - -System schemas -`````````````` -Those are defined in:: - - ./myapp/ginco/schemas/ - ./myapp/ginco/entities/ - -``schemas/`` defines the data model you will use in your application. -It allows you to describre the entities and the relations you will need. - -``entities/`` deifnes the methods you might need on the entities you -defined in your schema. - -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 - - -Components in the library -````````````````````````` - -Those are defined in:: - - ./myapp/ginco-apps/ - -An application is based on several basic components. In the set of available -basic components we can find by example: - -* `ecomment`, provides an entity type for `Comment` allowing us to comment others - site's entities - -* `emailinglist`, provides an entity type for `Mailinglist` which groups informations - in a discussion list - -* `efile`, provides entity types for `File` et `Image` used to represent - files (text or binary) with additionnal informations such as MIME type or - encoding. - -* `elink`, provides an entity type for hypertext link (`Link`) - -* `eblog`, provides an entity type weblog (`Blog`) - -* `eperson`, provides an entity type for a person (`Person`) - -* `eaddressbook`, provides an entity type used to represent phone - numbers (`PhoneNumber`) and mailing address (`PostalAddress`) - -* `eclasstags`, categorization system based on tags (`Tag`) - -* `eclassfolders`, categorization system based on folders hierarchy in order - to create navigation sections (`Folder`) - -* `eemail`, archiving management for emails (`Email`, `Emailpart`, - `Emailthread`) - -* `ebasket`, 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. - diff -r 1091d8d63f51 -r 9ecd54ea0634 doc/book/en/03-10-stdlib-schemas.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/03-10-stdlib-schemas.en.txt Thu Nov 20 20:36:03 2008 +0100 @@ -0,0 +1,86 @@ +.. -*- 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 `LAX` applications. +Of course, you can extend those schemas if necessarry. + +System schemas +`````````````` +Those are defined in:: + + ./myapp/ginco/schemas/ + ./myapp/ginco/entities/ + +``schemas/`` defines the data model you will use in your application. +It allows you to describre the entities and the relations you will need. + +``entities/`` deifnes the methods you might need on the entities you +defined in your schema. + +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 + + +Components in the library +````````````````````````` + +Those are defined in:: + + ./myapp/ginco-apps/ + +An application is based on several basic components. In the set of available +basic components we can find by example: + +* `ecomment`, provides an entity type for `Comment` allowing us to comment others + site's entities + +* `emailinglist`, provides an entity type for `Mailinglist` which groups informations + in a discussion list + +* `efile`, provides entity types for `File` et `Image` used to represent + files (text or binary) with additionnal informations such as MIME type or + encoding. + +* `elink`, provides an entity type for hypertext link (`Link`) + +* `eblog`, provides an entity type weblog (`Blog`) + +* `eperson`, provides an entity type for a person (`Person`) + +* `eaddressbook`, provides an entity type used to represent phone + numbers (`PhoneNumber`) and mailing address (`PostalAddress`) + +* `eclasstags`, categorization system based on tags (`Tag`) + +* `eclassfolders`, categorization system based on folders hierarchy in order + to create navigation sections (`Folder`) + +* `eemail`, archiving management for emails (`Email`, `Emailpart`, + `Emailthread`) + +* `ebasket`, 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. + diff -r 1091d8d63f51 -r 9ecd54ea0634 doc/book/en/03-11-definition-schema.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/03-11-definition-schema.en.txt Thu Nov 20 20:36:03 2008 +0100 @@ -0,0 +1,344 @@ +.. -*- 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, +by 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 `LAX` application. + +* all built-in types are available: `String`, `Int`, `Float`, + `Boolean`, `Date`, `Datetime`, `Time`, `Byte`. + +* each entity 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 entities non meta + - "@" : all types of meta entities but not system entities (e.g. used for + the basis 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. + [PAS CLAIR] + +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 + [PAS CLAIR] + + +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, as well as 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)[PAS CLAIR] by 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 own 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. + +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 define in the precreate +of the application (``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 + [WHAT IS A NON FINALE 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 thatm 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 assumes/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 [??] `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 checks 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. +[PAS CLAIR] diff -r 1091d8d63f51 -r 9ecd54ea0634 doc/book/en/XX-XX-actions.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/XX-XX-actions.en.txt Thu Nov 20 20:36:03 2008 +0100 @@ -0,0 +1,9 @@ +.. -*- coding: utf-8 -*- + +Actions +========= + +[WRITE ME] + +* talk about actions that appear in the action box + diff -r 1091d8d63f51 -r 9ecd54ea0634 doc/book/en/XX-XX-boxes.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/XX-XX-boxes.en.txt Thu Nov 20 20:36:03 2008 +0100 @@ -0,0 +1,9 @@ +.. -*- coding: utf-8 -*- + +Boxes +========= + +[WRITE ME] + +* boxes in the web interface + diff -r 1091d8d63f51 -r 9ecd54ea0634 doc/book/en/XX-XX-dbapi.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/XX-XX-dbapi.en.txt Thu Nov 20 20:36:03 2008 +0100 @@ -0,0 +1,9 @@ +.. -*- coding: utf-8 -*- + +DB-API +========= + +[WRITE ME] + +* direct connection to the repository + diff -r 1091d8d63f51 -r 9ecd54ea0634 doc/book/en/XX-XX-embedding-external-page.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/XX-XX-embedding-external-page.en.txt Thu Nov 20 20:36:03 2008 +0100 @@ -0,0 +1,9 @@ +.. -*- coding: utf-8 -*- + +Embedding external pages +======================== + +[WRITE ME] + +* including external content + diff -r 1091d8d63f51 -r 9ecd54ea0634 doc/book/en/XX-XX-repository-operations.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/XX-XX-repository-operations.en.txt Thu Nov 20 20:36:03 2008 +0100 @@ -0,0 +1,9 @@ +.. -*- coding: utf-8 -*- + +Repository operations +====================== + +[WRITE ME] + +* repository operations + diff -r 1091d8d63f51 -r 9ecd54ea0634 doc/book/en/XX-XX-repository-session.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/XX-XX-repository-session.en.txt Thu Nov 20 20:36:03 2008 +0100 @@ -0,0 +1,9 @@ +.. -*- coding: utf-8 -*- + +Repository sessions +=================== + +[WRITE ME] + +* repository sessions + diff -r 1091d8d63f51 -r 9ecd54ea0634 doc/book/en/XX-XX-repository-tasks.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/XX-XX-repository-tasks.en.txt Thu Nov 20 20:36:03 2008 +0100 @@ -0,0 +1,9 @@ +.. -*- coding: utf-8 -*- + +Tasks +========= + +[WRITE ME] + +* repository tasks + diff -r 1091d8d63f51 -r 9ecd54ea0634 doc/book/en/XX-XX-request.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/XX-XX-request.en.txt Thu Nov 20 20:36:03 2008 +0100 @@ -0,0 +1,9 @@ +.. -*- coding: utf-8 -*- + +request +======= + +[WRITE ME] + +* the request object + diff -r 1091d8d63f51 -r 9ecd54ea0634 doc/book/en/XX-XX-sessions.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/XX-XX-sessions.en.txt Thu Nov 20 20:36:03 2008 +0100 @@ -0,0 +1,9 @@ +.. -*- coding: utf-8 -*- + +sessions +======== + +[WRITE ME] + +* authentication and management of sessions + diff -r 1091d8d63f51 -r 9ecd54ea0634 doc/book/en/XX-XX-templates.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/XX-XX-templates.en.txt Thu Nov 20 20:36:03 2008 +0100 @@ -0,0 +1,9 @@ +.. -*- coding: utf-8 -*- + +Templates +========= + +[WRITE ME] + +* talk about main templates, etc. + diff -r 1091d8d63f51 -r 9ecd54ea0634 doc/book/en/index.txt --- a/doc/book/en/index.txt Thu Nov 20 20:14:23 2008 +0100 +++ b/doc/book/en/index.txt Thu Nov 20 20:36:03 2008 +0100 @@ -38,28 +38,28 @@ .. toctree:: :maxdepth: 1 - 01-introduction.en.txt - 02-foundation.en.txt - 03-setup.en.txt - 04-define-schema.en.txt - 05-define-views.en.txt - 06-define-workflows.en.txt - 07-data-as-objects.en.txt - 08-site-config.en.txt - 09-instance-config.en.txt - 10-form-management.en.txt - 11-ajax-json.en.txt - 12-ui-components.en.txt - 13-security.en.txt - 14-hooks.en.txt - 15-notifications.en.txt - 16-rql.en.txt - 17-migration.en.txt - 18-tests.en.txt - 19-i18n.en.txt - 20-google-appengine.en.txt - 21-appendix.en.txt - 22-faq.en.txt + 01-00-introduction.en.txt + 02-00-foundation.en.txt + 03-00-setup.en.txt + 04-00-define-schema.en.txt + 05-00-define-views.en.txt + 06-00-define-workflows.en.txt + 07-00-data-as-objects.en.txt + 08-00-site-config.en.txt + 09-00-instance-config.en.txt + 10-00-form-management.en.txt + 11-00-ajax-json.en.txt + 12-00-ui-components.en.txt + 13-00-security.en.txt + 14-00-hooks.en.txt + 15-00-notifications.en.txt + 16-00-rql.en.txt + 17-00-migration.en.txt + 18-00-tests.en.txt + 19-00-i18n.en.txt + 20-00-google-appengine.en.txt + 21-00-appendix.en.txt + 22-00-faq.en.txt Indices and tables