--- a/doc/book/en/A000-introduction.en.txt Tue Apr 14 12:14:59 2009 +0200
+++ b/doc/book/en/A000-introduction.en.txt Wed Apr 15 18:16:12 2009 +0200
@@ -6,8 +6,8 @@
Part I - Introduction to `CubicWeb`
===================================
-This first part of the book will offer different reading path to
-present you with the `CubicWeb` framework, provide a tutorial to get a quick
+This first part of the book will present different reading path to
+discover the `CubicWeb` framework, provide a tutorial to get a quick
overview of its features and list its key concepts.
--- a/doc/book/en/B0-data-model.en.txt Tue Apr 14 12:14:59 2009 +0200
+++ b/doc/book/en/B0-data-model.en.txt Wed Apr 15 18:16:12 2009 +0200
@@ -7,6 +7,7 @@
:maxdepth: 1
B0010-define-schema.en.txt
+ B0015-define-permissions.en.txt
B0020-define-workflows.en.txt
B0030-data-as-objects.en.txt
B0040-migration.en.txt
--- a/doc/book/en/B0012-schema-definition.en.txt Tue Apr 14 12:14:59 2009 +0200
+++ b/doc/book/en/B0012-schema-definition.en.txt Wed Apr 15 18:16:12 2009 +0200
@@ -188,194 +188,9 @@
`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
-``````````````````````
-
-Setting permissions is done with the attribute `permissions` of entities and
-relation types. It defines a dictionary 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_<ACTION>_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 <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_<ACTION>_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
-``````````````````````````````````````````````
+----------------------------------------------
If you modified your schema, the update is not automatic; indeed, this is
in general not a good idea.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/B0015-define-permissions.en.txt Wed Apr 15 18:16:12 2009 +0200
@@ -0,0 +1,188 @@
+.. -*- coding: utf-8 -*-
+
+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
+``````````````````````
+
+Setting permissions is done with the attribute `permissions` of entities and
+relation types. It defines a dictionary 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_<ACTION>_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 <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_<ACTION>_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.
+
--- a/doc/book/en/B2052-install.en.txt Tue Apr 14 12:14:59 2009 +0200
+++ b/doc/book/en/B2052-install.en.txt Wed Apr 15 18:16:12 2009 +0200
@@ -97,7 +97,7 @@
Generating translation files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------
`CubicWeb` is fully internationalized. Translation catalogs are found in
``myapp/i18n``. To compile the translation files, use the `gettext` tools
@@ -120,7 +120,7 @@
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::
@@ -128,7 +128,7 @@
$ 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
@@ -136,11 +136,8 @@
$ python myapp/bin/laxctl genschema
-Application configuration
--------------------------
-
-Authentication
-~~~~~~~~~~~~~~
+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``.
@@ -178,9 +175,9 @@
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 <http://localhost:8080/?vid=authinfo>`_ .
+Visit `http://MYAPP_URL/?vid=authinfo <http://localhost:8080/?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
--- a/doc/book/en/Z013-blog-less-ten-minutes.en.txt Tue Apr 14 12:14:59 2009 +0200
+++ b/doc/book/en/Z013-blog-less-ten-minutes.en.txt Wed Apr 15 18:16:12 2009 +0200
@@ -37,7 +37,7 @@
cubicweb-ctl start -D myblog
-This is it. Your blog is ready to you. Go to http://localhost:8080 and enjoy!!
+This is it. Your blog is ready to you. Go to http://localhost:8080 and enjoy!
A little code snapshot from behind the scene