--- a/doc/book/en/B000-development.en.txt Tue Mar 02 15:11:11 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,19 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-=====================
-Part II - Development
-=====================
-
-This part is about developing web applications with the *CubicWeb* framework.
-
-.. toctree::
- :maxdepth: 1
-
- B0-data-model.en.txt
- B1-web-interface.en.txt
- B2-repository-customization.en.txt
- B3-test.en.txt
- B4-advanced.en.txt
-
-
-
--- a/doc/book/en/B0015-define-permissions.en.txt Tue Mar 02 15:11:11 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,208 +0,0 @@
-.. -*- 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 `RRQLExpression` 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 define rights on attributes of an entity (non-final
- relation), knowing that :
-
- - to define 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
-allows to build very complex and dynamic security architecture. The schema of
-this entity type is as follow : ::
-
- class CWPermission(EntityType):
- """entity type that may be used to construct some advanced security configuration
- """
- permissions = META_ETYPE_PERMS
-
- name = String(required=True, indexed=True, internationalizable=True, maxsize=100,
- description=_('name or identifier of the permission'))
- label = String(required=True, internationalizable=True, maxsize=100,
- description=_('distinct label to distinguate between other permission entity of the same name'))
- require_group = SubjectRelation('CWGroup',
- description=_('groups to which the permission is granted'))
-
- # explicitly add X require_permission CWPermission for each entity that should have
- # configurable security
- class require_permission(RelationType):
- """link a permission to the entity. This permission should be used in the
- security definition of the entity's type to be useful.
- """
- permissions = {
- 'read': ('managers', 'users', 'guests'),
- 'add': ('managers',),
- 'delete': ('managers',),
- }
-
- class require_group(RelationType):
- """used to grant a permission to a group"""
- permissions = {
- 'read': ('managers', 'users', 'guests'),
- 'add': ('managers',),
- 'delete': ('managers',),
- }
-
-
-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 `CWPermission` 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 genericity of the entity type `CWPermission`, 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/B4040-rss-xml.en.txt Tue Mar 02 15:11:11 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,48 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-.. _rss:
-
-RSS Channel
------------
-
-Assuming you have several blog entries, click on the title of the
-search box in the left column. A larger search box should appear. Enter::
-
- Any X ORDERBY D WHERE X is BlogEntry, X creation_date D
-
-and you get a list of blog entries.
-
-Click on your login at the top right corner. Chose "user preferences",
-then "boxes", then "possible views box" and check "visible = yes"
-before validating your changes.
-
-Enter the same query in the search box and you will see the same list,
-plus a box titled "possible views" in the left column. Click on
-"entityview", then "RSS".
-
-You just applied the "RSS" view to the RQL selection you requested.
-
-That's it, you have a RSS channel for your blog.
-
-Try again with::
-
- Any X ORDERBY D WHERE X is BlogEntry, X creation_date D,
- X entry_of B, B title "MyLife"
-
-Another RSS channel, but a bit more focused.
-
-A last one for the road::
-
- Any C ORDERBY D WHERE C is Comment, C creation_date D LIMIT 15
-
-displayed with the RSS view, that's a channel for the last fifteen
-comments posted.
-
-[WRITE ME]
-
-* show that the RSS view can be used to display an ordered selection
- of blog entries, thus providing a RSS channel
-
-* show that a different selection (by category) means a different channel
-
-
--- a/doc/book/en/Z010-beginners.en.txt Tue Mar 02 15:11:11 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,11 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-.. _QuickInstall:
-
-Quick Installation of a *CubicWeb* instance
-===========================================
-
-# .. include:: C010-setup.en.txt
-.. include:: Z012-create-instance.en.txt
-
-
--- a/doc/book/en/Z012-create-instance.en.txt Tue Mar 02 15:11:11 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,80 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-===============================
-Creation of your first instance
-===============================
-
-What is an instance?
---------------------
-
-A *CubicWeb* instance is a container that
-refers to cubes and configuration parameters for your web instance.
-Each instance is stored as a directory in ``~/etc/cubicweb.d`` which enables
-us to run your instance.
-
-What is a cube?
----------------
-
-Cubes represent data and basic building bricks of your web instances :
-blogs, person, date, addressbook and a lot more.
-
-.. XXX They related to each other by a 'Schema' which is also the PostGres representation.
-
-Each cube defines entities, their views, their schemas and workflows
-in an independant directory located in ``/path/to/forest/cubicweb/cubes/``
-for a Mercurial installation or in ``/usr/share/cubicweb/cubes`` for
-a debian package installation. For example, the 'blog' cube defines the entities
-blogs and blogentries.
-
-When an *CubicWeb* instance is created, you list the cubes that you want to use.
-Using a cube means having the entities defined in your cube's schema
-available in your instance as well as their views and workflows.
-
-
-Creating a basic *CubicWeb* Instance
-------------------------------------
-
-We can create an instance to view our
-instance in a web browser. ::
-
- cubicweb-ctl create blog myblog
-
-.. XXX or ::
-
-.. XXX cubicweb-ctl create forge myforge
-
-
-.. note::
- The commands used below are more detailled in the section dedicated to
- :ref:`cubicweb-ctl`.
-
-A series of questions will be prompted to you, the default answer is usually
-sufficient. You can allways modify the parameters later by editing
-configuration files. When a user/psswd is requested to access the database
-please use the login you create at the time you configured the database
-(:ref:`ConfigurationPostgresql`).
-
-It is important to distinguish here the user used to access the database and
-the user used to login to the cubicweb instance. When a *CubicWeb* instance
-starts, it uses the login/psswd for the database to get the schema and handle
-low level transaction. But, when ``cubicweb-ctl create`` asks for
-a manager login/psswd of *CubicWeb*, it refers to an instance user
-to administrate your web instance.
-The configuration files are stored in *~/etc/cubicweb.d/myblog/*.
-
-To launch the web instance, you just type ::
-
- cubicweb-ctl start myblog
-
-You can see how it looks by
-visiting the URL `http://localhost:8080`.
-To login, please use the cubicweb administrator login/psswd you
-defined when you created the instance.
-
-To shutdown the instance ::
-
- cubicweb-ctl stop myinstance
-
-.. XXX something like `cubicweb-ctl live-server intra` would be nice
-
-
--- a/doc/book/en/development/datamodel/definition.rst Tue Mar 02 15:11:11 2010 +0100
+++ b/doc/book/en/development/datamodel/definition.rst Tue Mar 02 15:37:45 2010 +0100
@@ -266,8 +266,11 @@
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``).
+It is also possible to use specific groups if they are defined in the
+precreate of the cube (``migration/precreate.py``). Defining groups in
+postcreate or even later makes them NOT available for security
+purposes (in this case, an `sync_schema_props_perms` command have to
+be issued in a CubicWeb shell).
Use of RQL expression for write permissions
--- a/doc/book/en/development/webstdlib/xmlrss.rst Tue Mar 02 15:11:11 2010 +0100
+++ b/doc/book/en/development/webstdlib/xmlrss.rst Tue Mar 02 15:37:45 2010 +0100
@@ -3,6 +3,9 @@
XML and RSS views (:mod:`cubicweb.web.views.xmlrss`)
----------------------------------------------------
+Overview
++++++++++
+
*rss*
Creates a RSS/XML view and call the view `rssitem` for each entity of
the result set.
@@ -10,3 +13,50 @@
*rssitem*
Create a RSS/XML view for each entity based on the results of the dublin core
methods of the entity (`dc_*`)
+
+
+RSS Channel Example
+++++++++++++++++++++
+
+Assuming you have several blog entries, click on the title of the
+search box in the left column. A larger search box should appear. Enter::
+
+ Any X ORDERBY D WHERE X is BlogEntry, X creation_date D
+
+and you get a list of blog entries.
+
+Click on your login at the top right corner. Chose "user preferences",
+then "boxes", then "possible views box" and check "visible = yes"
+before validating your changes.
+
+Enter the same query in the search box and you will see the same list,
+plus a box titled "possible views" in the left column. Click on
+"entityview", then "RSS".
+
+You just applied the "RSS" view to the RQL selection you requested.
+
+That's it, you have a RSS channel for your blog.
+
+Try again with::
+
+ Any X ORDERBY D WHERE X is BlogEntry, X creation_date D,
+ X entry_of B, B title "MyLife"
+
+Another RSS channel, but a bit more focused.
+
+A last one for the road::
+
+ Any C ORDERBY D WHERE C is Comment, C creation_date D LIMIT 15
+
+displayed with the RSS view, that's a channel for the last fifteen
+comments posted.
+
+[WRITE ME]
+
+* show that the RSS view can be used to display an ordered selection
+ of blog entries, thus providing a RSS channel
+
+* show that a different selection (by category) means a different channel
+
+
+