--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/README Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,43 @@
+====
+Book
+====
+
+----
+Part
+----
+
+Chapter
+=======
+
+Level 1 section
+---------------
+
+Level 2 section
+~~~~~~~~~~~~~~~
+
+Level 3 section
+```````````````
+
+
+
+*CubicWeb*
+
+
+inline directives:
+ :file:
+ :envvar:
+ :command:
+
+ :ref:, :mod:
+
+
+XXX
+* lien vers cw.cwconfig.CW_CUBES_PATH par ex.
+
+
+.. sourcecode:: python
+
+ class SomePythonCode:
+ ...
+
+.. XXX a comment
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/_maybe_to_integrate/D050-architecture.en.txt Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,14 @@
+.. -*- coding: utf-8 -*-
+
+
+Server Architecture
+-------------------
+
+.. image:: images/server-class-diagram.png
+
+`Diagramme ArgoUML`_
+
+[FIXME]
+Make a downloadable source of zargo file.
+
+.. _`Diagramme ArgoUML`: cubicweb.zargo
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/_maybe_to_integrate/rss-xml.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,45 @@
+.. -*- coding: utf-8 -*-
+
+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
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/_maybe_to_integrate/template.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,20 @@
+
+
+Templates
+---------
+
+*Templates* are specific views that do not depend on a result set. The basic
+class `Template` (`cubicweb.common.view`) is derived from the class `View`.
+
+To build a HTML page, a *main template* is used. In general, the template of
+identifier `main` is the one to use (it is not used in case an error is raised or for
+the login form for example). This template uses other templates in addition
+to the views which depends on the content to generate the HTML page to return.
+
+A *template* is responsible for:
+
+1. executing RQL query of data to render if necessary
+2. identifying the view to use to render data if it is not specified
+3. composing the HTML page to return
+
+You will find out more about templates in :ref:`templates`.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/_maybe_to_integrate/treemixin.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,100 @@
+
+Class `TreeMixIn`
+-----------------
+
+This class provides a tree interface. This mixin has to be inherited
+explicitly and configured using the tree_attribute, parent_target and
+children_target class attribute to benefit from this default implementation.
+
+This class provides the following methods:
+
+ * `different_type_children(entities=True)`, returns children entities
+ of different type as this entity. According to the `entities` parameter,
+ returns entity objects (if entity=True) or the equivalent result set.
+
+ * `same_type_children(entities=True)`, returns children entities of
+ the same type as this entity. According to the `entities` parameter,
+ return entity objects (if entity=True) or the equivalent result set.
+
+ * `iterchildren( _done=None)`, iters on the children of the entity.
+
+ * `prefixiter( _done=None)`
+
+ * `path()`, returns the list of eids from the root object to this object.
+
+ * `iterparents()`, iters on the parents of the entity.
+
+ * `notification_references(view)`, used to control References field
+ of email send on notification for this entity. `view` is the notification view.
+ Should return a list of eids which can be used to generate message ids
+ of previously sent email.
+
+`TreeMixIn` implements also the ITree interface (``cubicweb.interfaces``):
+
+ * `parent()`, returns the parent entity if any, else None (e.g. if we are on the
+ root)
+
+ * `children(entities=True, sametype=False)`, returns children entities
+ according to the `entities` parameter, return entity objects or the
+ equivalent result set.
+
+ * `children_rql()`, returns the RQL query corresponding to the children
+ of the entity.
+
+ * `is_leaf()`, returns True if the entity does not have any children.
+
+ * `is_root()`, returns True if the entity does not have any parent.
+
+ * `root()`, returns the root object of the tree representation of
+ the entity and its related entities.
+
+Example of use
+``````````````
+
+Imagine you defined three types of entities in your schema, and they
+relates to each others as follows in ``schema.py``::
+
+ class Entity1(EntityType):
+ title = String()
+ is_related_to = SubjectRelation('Entity2', 'subject')
+
+ class Entity2(EntityType):
+ title = String()
+ belongs_to = SubjectRelation('Entity3', 'subject')
+
+ class Entity3(EntityType):
+ name = String()
+
+You would like to create a view that applies to both entity types
+`Entity1` and `Entity2` and which lists the entities they are related to.
+That means when you view `Entity1` you want to list all `Entity2`, and
+when you view `Entity2` you want to list all `Entity3`.
+
+In ``entities.py``::
+
+ class Entity1(TreeMixIn, AnyEntity):
+ id = 'Entity1'
+ __implements__ = AnyEntity.__implements__ + (ITree,)
+ __rtags__ = {('is_related_to', 'Entity2', 'object'): 'link'}
+ tree_attribute = 'is_related_to'
+
+ def children(self, entities=True):
+ return self.different_type_children(entities)
+
+ class Entity2(TreeMixIn, AnyEntity):
+ id = 'Entity2'
+ __implements__ = AnyEntity.__implements__ + (ITree,)
+ __rtags__ = {('belongs_to', 'Entity3', 'object'): 'link'}
+ tree_attribute = 'belongs_to'
+
+ def children(self, entities=True):
+ return self.different_type_children(entities)
+
+Once this is done, you can define your common view as follows::
+
+ class E1E2CommonView(baseviews.PrimaryView):
+ accepts = ('Entity11, 'Entity2')
+
+ def render_entity_relations(self, entity, siderelations):
+ self.wview('list', entity.children(entities=False))
+
--- a/doc/book/en/A000-introduction.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,19 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-.. _Part1:
-
-===================================
-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
-overview of its features and list its key concepts.
-
-
-.. toctree::
- :maxdepth: 2
-
- A010-book-map.en.txt
- A020-tutorial.en.txt
- A030-foundation.en.txt
--- a/doc/book/en/A010-book-map.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,10 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Book map
-=========
-
-[WRITE ME]
-
-* explain how to use this book and what chapters to read in what order depending on the
- objectives of the reader
-
--- a/doc/book/en/A020-tutorial.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,28 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-.. _Tutorial:
-
-Tutorial
-========
-
-`CubicWeb` is a semantic web application framework that favors reuse and
-object-oriented design.
-
-A `cube` is a component that includes a model defining the data types and a set of
-views to display the data.
-
-An application is a `cube`, but usually an application is built by assembling
-a few smaller cubes.
-
-An `instance` is a specific installation of an application and includes
-configuration files.
-
-
-This tutorial will show how to create a `cube` and how to use it as an
-application to run an `instance`.
-
-.. include:: Z013-blog-less-ten-minutes.en.txt
-.. include:: A02a-create-cube.en.txt
-.. include:: A02b-components.en.txt
-.. include:: A02c-maintemplate.en.txt
-.. include:: A02d-conclusion.en.txt
--- a/doc/book/en/A02a-create-cube.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,269 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Create your cube
-----------------
-
-Once your `CubicWeb` development environment is set up, you can create a new
-cube::
-
- cubicweb-ctl newcube blog
-
-This will create in the cubes directory (``/path/to/forest/cubes`` for Mercurial
-installation, ``/usr/share/cubicweb/cubes`` for debian packages installation)
-a directory named ``blog`` reflecting the structure described in :ref:`cubesConcepts`.
-
-.. _DefineDataModel:
-
-Define your data model
-----------------------
-
-The data model or schema is the core of your `CubicWeb` application.
-It defines the type of content your application will handle.
-
-The data model of your cube ``blog`` is defined in the file ``schema.py``:
-
-::
-
- class Blog(EntityType):
- title = String(maxsize=50, required=True)
- description = String()
-
- class BlogEntry(EntityType):
- title = String(required=True, fulltextindexed=True, maxsize=256)
- publish_date = Date(default='TODAY')
- content = String(required=True, fulltextindexed=True)
- entry_of = SubjectRelation('Blog', cardinality='?*')
-
-
-A Blog has a title and a description. The title is a string that is
-required by the class EntityType and must be less than 50 characters.
-The description is a string that is not constrained.
-
-A BlogEntry has a title, a publish_date and a content. The title is a
-string that is required and must be less than 100 characters. The
-publish_date is a Date with a default value of TODAY, meaning that
-when a BlogEntry is created, its publish_date will be the current day
-unless it is modified. The content is a string that will be indexed in
-the full-text index and has no constraint.
-
-A BlogEntry also has a relationship ``entry_of`` that links it to a
-Blog. The cardinality ``?*`` means that a BlogEntry can be part of
-zero or one Blog (``?`` means `zero or one`) and that a Blog can
-have any number of BlogEntry (``*`` means `any number including
-zero`). For completeness, remember that ``+`` means `one or more`.
-
-
-Create your instance
---------------------
-
-To use this cube as an application and create a new instance named ``blogdemo``, do::
-
- cubicweb-ctl create blog blogdemo
-
-
-This command will create the corresponding database and initialize it.
-
-Welcome to your web application
--------------------------------
-
-Start your application in debug mode with the following command: ::
-
- cubicweb-ctl start -D blogdemo
-
-
-You can now access your web application to create blogs and post messages
-by visiting the URL http://localhost:8080/.
-
-A login form will appear. By default, the application will not allow anonymous
-users to enter the application. To login, you need then use the admin account
-you created at the time you initialized the database with ``cubicweb-ctl
-create``.
-
-.. image:: images/login-form.png
-
-
-Once authenticated, you can start playing with your application
-and create entities.
-
-.. image:: images/blog-demo-first-page.png
-
-Please notice that so far, the `CubicWeb` franework managed all aspects of
-the web application based on the schema provided at first.
-
-
-Add entities
-------------
-
-We will now add entities in our web application.
-
-Add a Blog
-~~~~~~~~~~
-
-Let us create a few of these entities. Click on the `[+]` at the left of the
-link Blog on the home page. Call this new Blog ``Tech-blog`` and type in
-``everything about technology`` as the description, then validate the form by
-clicking on ``Validate``.
-
-.. image:: images/cbw-create-blog.en.png
- :alt: from to create blog
-
-Click on the logo at top left to get back to the home page, then
-follow the Blog link that will list for you all the existing Blog.
-You should be seeing a list with a single item ``Tech-blog`` you
-just created.
-
-.. image:: images/cbw-list-one-blog.en.png
- :alt: displaying a list of a single blog
-
-Clicking on this item will get you to its detailed description except
-that in this case, there is not much to display besides the name and
-the phrase ``everything about technology``.
-
-Now get back to the home page by clicking on the top-left logo, then
-create a new Blog called ``MyLife`` and get back to the home page
-again to follow the Blog link for the second time. The list now
-has two items.
-
-.. image:: images/cbw-list-two-blog.en.png
- :alt: displaying a list of two blogs
-
-Add a BlogEntry
-~~~~~~~~~~~~~~~
-
-Get back to the home page and click on [+] at the left of the link
-BlogEntry. Call this new entry ``Hello World`` and type in some text
-before clicking on ``Validate``. You added a new blog entry without
-saying to what blog it belongs. There is a box on the left entitled
-``actions``, click on the menu item ``modify``. You are back to the form
-to edit the blog entry you just created, except that the form now has
-another section with a combobox titled ``add relation``. Chose
-``entry_of`` in this menu and a second combobox appears where you pick
-``MyLife``.
-
-You could also have, at the time you started to fill the form for a
-new entity BlogEntry, hit ``Apply`` instead of ``Validate`` and the
-combobox titled ``add relation`` would have showed up.
-
-
-.. image:: images/cbw-add-relation-entryof.en.png
- :alt: editing a blog entry to add a relation to a blog
-
-Validate the changes by clicking ``Validate``. The entity BlogEntry
-that is displayed now includes a link to the entity Blog named
-``MyLife``.
-
-.. image:: images/cbw-detail-one-blogentry.en.png
- :alt: displaying the detailed view of a blogentry
-
-Note that all of this was handled by the framework and that the only input
-that was provided so far is the schema. To get a graphical view of the schema,
-point your browser to the URL http://localhost:8080/schema
-
-.. image:: images/cbw-schema.en.png
- :alt: graphical view of the schema (aka data-model)
-
-
-.. _DefineViews:
-
-Define your entity views
-------------------------
-
-Each entity defined in a model inherits default views allowing
-different rendering of the data. You can redefine each of them
-according to your needs and preferences. So let's see how the
-views are defined.
-
-
-The view selection principle
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-A view is defined by a Python class which includes:
-
- - an identifier (all objects in `CubicWeb` are entered in a registry
- and this identifier will be used as a key)
-
- - a filter to select the result sets it can be applied to
-
-A view has a set of methods complying
-with the `View` class interface (`cubicweb.common.view`).
-
-`CubicWeb` provides a lot of standard views for the type `EntityView`;
-for a complete list, read the code in directory ``cubicweb/web/views/``.
-
-A view is applied on a `result set` which contains a set of
-entities we are trying to display. `CubicWeb` uses a selector
-mechanism which computes for each available view a score:
-the view with the highest score is then used to display the given `result set`.
-The standard library of selectors is in
-``cubicweb.common.selector`` and a library of methods used to
-compute scores is available in ``cubicweb.vregistry.vreq``.
-
-It is possible to define multiple views for the same identifier
-and to associate selectors and filters to allow the application
-to find the best way to render the data.
-
-For example, the view named ``primary`` is the one used to display
-a single entity. We will now show you how to customize this view.
-
-
-View customization
-~~~~~~~~~~~~~~~~~~
-
-If you wish to modify the way a `BlogEntry` is rendered, you will have to
-overwrite the `primary` view defined in the module ``views`` of the cube
-``cubes/blog/views.py``.
-
-We can for example add in front of the publication date a prefix specifying
-that the date we see is the publication date.
-
-To do so, please apply the following changes:
-
-::
-
- from cubicweb.web.views import baseviews
-
-
- class BlogEntryPrimaryView(baseviews.PrimaryView):
-
- accepts = ('BlogEntry',)
-
- def render_entity_title(self, entity):
- self.w(u'<h1>%s</h1>' % html_escape(entity.dc_title()))
-
- def content_format(self, entity):
- return entity.view('reledit', rtype='content_format')
-
- def cell_call(self, row, col):
- entity = self.entity(row, col)
-
- # display entity attributes with prefixes
- self.w(u'<h1>%s</h1>' % entity.title)
- self.w(u'<p>published on %s</p>' % entity.publish_date.strftime('%Y-%m-%d'))
- self.w(u'<p>%s</p>' % entity.content)
-
- # display relations
- siderelations = []
- if self.main_related_section:
- self.render_entity_relations(entity, siderelations)
-
-.. note::
- When a view is modified, it is not required to restart the application
- server. Save the Python file and reload the page in your web browser
- to view the changes.
-
-You can now see that the publication date has a prefix.
-
-.. image:: images/cbw-update-primary-view.en.png
- :alt: modified primary view
-
-
-The above source code defines a new primary view for ``BlogEntry``.
-
-Since views are applied to result sets and result sets can be tables of
-data, we have to recover the entity from its (row,col)-coordinates.
-The view has a ``self.w()`` method that is used to output data, in our
-example HTML output.
-
-You can find more details about views and selectors in :ref:`ViewDefinition`.
-
-
--- a/doc/book/en/A02b-components.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,81 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-.. _cubes:
-
-Cubes
------
-
-Standard library
-~~~~~~~~~~~~~~~~
-
-A library of standard cubes are available from `CubicWeb Forge`_
-Cubes provide entities and views.
-
-The available application entities are:
-
-* addressbook: PhoneNumber and PostalAddress
-
-* basket: Basket (like a shopping cart)
-
-* blog: Blog (a *very* basic blog)
-
-* classfolder: Folder (to organize things but grouping them in folders)
-
-* classtags: Tag (to tag anything)
-
-* file: File (to allow users to upload and store binary or text files)
-
-* link: Link (to collect links to web resources)
-
-* mailinglist: MailingList (to reference a mailing-list and the URLs
- for its archives and its admin interface)
-
-* person: Person (easily mixed with addressbook)
-
-* task: Task (something to be done between start and stop date)
-
-* zone: Zone (to define places within larger places, for example a
- city in a state in a country)
-
-The available system entities are:
-
-* comment: Comment (to attach comment threads to entities)
-
-
-Adding comments to BlogDemo
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To import a cube in your application just change the line in the
-``__pkginfo__.py`` file and verify that the cube you are planning
-to use is listed by the command ``cubicweb-ctl list``.
-For example::
-
- __use__ = ('comment',)
-
-will make the ``Comment`` entity available in your ``BlogDemo``
-application.
-
-Change the schema to add a relationship between ``BlogEntry`` and
-``Comment`` and you are done. Since the comment cube defines the
-``comments`` relationship, adding the line::
-
- comments = ObjectRelation('Comment', cardinality='1*', composite='object')
-
-to the definition of a ``BlogEntry`` will be enough.
-
-Synchronize the data model
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Once you modified your data model, you need to synchronize the
-database with your model. For this purpose, `CubicWeb` provides
-a very useful command ``cubicweb-ctl shell blogdemo`` which
-launches an interactive migration Python shell. (see
-:ref:`cubicweb-ctl-shell` for more details))
-As you modified a relation from the `BlogEntry` schema,
-run the following command:
-::
-
- synchronize_rschema('BlogEntry')
-
-You can now start your application and add comments to each
-`BlogEntry`.
--- a/doc/book/en/A02c-maintemplate.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,127 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Templates
----------
-
-Look at ``cubicweb/web/views/basetemplates.py`` and you will
-find the base templates used to generate HTML for your application.
-
-A page is composed as indicated on the schema below:
-
-.. image:: images/lax-book.06-main-template-layout.en.png
-
-In this section we will demonstrate a change in one of the main
-interesting template from the three you will look for,
-that is to say, the HTMLPageHeader, the HTMLPageFooter
-and the TheMainTemplate.
-
-
-Customize a template
-~~~~~~~~~~~~~~~~~~~~
-
-Based on the diagram below, each template can be overriden
-by your customized template. To do so, we recommand you create
-a Python module ``blog.views.templates`` to keep it organized.
-In this module you will have to import the parent class you are
-interested as follows: ::
-
- from cubicweb.web.views.basetemplates import HTMLPageHeader, \
- HTMLPageFooter, TheMainTemplate
-
-and then create your sub-class::
-
- class MyBlogHTMLPageHeader(HTMLPageHeader):
- ...
-
-Customize header
-`````````````````
-
-Let's now move the search box in the header and remove the login form
-from the header. We'll show how to move it to the left column of the application.
-
-Let's say we do not want anymore the login menu to be in the header
-
-First, to remove the login menu, we just need to comment out the display of the
-login graphic component such as follows: ::
-
- class MyBlogHTMLPageHeader(HTMLPageHeader):
-
- def main_header(self, view):
- """build the top menu with authentification info and the rql box"""
- self.w(u'<table id="header"><tr>\n')
- self.w(u'<td id="firstcolumn">')
- self.vreg.select_component('logo', self.req, self.rset).dispatch(w=self.w)
- self.w(u'</td>\n')
- # appliname and breadcrumbs
- self.w(u'<td id="headtext">')
- comp = self.vreg.select_component('appliname', self.req, self.rset)
- if comp and comp.propval('visible'):
- comp.dispatch(w=self.w)
- comp = self.vreg.select_component('breadcrumbs', self.req, self.rset, view=view)
- if comp and comp.propval('visible'):
- comp.dispatch(w=self.w, view=view)
- self.w(u'</td>')
- # logged user and help
- #self.w(u'<td>\n')
- #comp = self.vreg.select_component('loggeduserlink', self.req, self.rset)
- #comp.dispatch(w=self.w)
- #self.w(u'</td><td>')
-
- self.w(u'<td>')
- helpcomp = self.vreg.select_component('help', self.req, self.rset)
- if helpcomp: # may not be available if Card is not defined in the schema
- helpcomp.dispatch(w=self.w)
- self.w(u'</td>')
- # lastcolumn
- self.w(u'<td id="lastcolumn">')
- self.w(u'</td>\n')
- self.w(u'</tr></table>\n')
- self.template('logform', rset=self.rset, id='popupLoginBox', klass='hidden',
- title=False, message=False)
-
-
-
-.. image:: images/lax-book.06-header-no-login.en.png
-
-Customize footer
-````````````````
-
-If you want to change the footer for example, look
-for HTMLPageFooter and override it in your views file as in: ::
-
- from cubicweb.web.views.basetemplates import HTMLPageFooter
-
- class MyHTMLPageFooter(HTMLPageFooter):
-
- def call(self, **kwargs):
- self.w(u'<div class="footer">')
- self.w(u'This website has been created with <a href="http://cubicweb.org">CubicWeb</a>.')
- self.w(u'</div>')
-
-Updating a view does not require any restart of the server. By reloading
-the page you can see your new page footer.
-
-
-TheMainTemplate
-```````````````
-
-.. _TheMainTemplate:
-
-The MainTemplate is a bit complex as it tries to accomodate many
-different cases. We are now about to go through it and cutomize entirely
-our application.
-
-TheMainTemplate is responsible for the general layout of the entire application.
-It defines the template of ``id = main`` that is used by the application. Is
-also defined in ``cubicweb/web/views/basetemplates.py`` another template that can
-be used based on TheMainTemplate called SimpleMainTemplate which does not have
-a top section.
-
-.. image:: images/lax-book.06-simple-main-template.en.png
-
-XXX
-[WRITE ME]
-
-* customize MainTemplate and show that everything in the user
- interface can be changed
-
--- a/doc/book/en/A02d-conclusion.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,17 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-What's next?
-------------
-
-We demonstrated how from a straight out of the box `CubicWeb`
-installation, you can build your web-application based on a
-schema. It's all already there: views, templates, permissions,
-etc. The step forward is now for you to customize according
-to your needs.
-
-More than a web application, many features are available to
-extend your application, for example: RSS channel integration
-(:ref:`rss`), hooks (:ref:`hooks`), support of sources such as
-Google App Engine (:ref:`gaecontents`) and lots of others to
-discover through our book.
-
--- a/doc/book/en/A02d-rss-xml.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,45 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-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/A030-foundation.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,34 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-`CubicWeb` Foundations
-======================
-
-A little history...
--------------------
-
-`CubicWeb` is a web application framework developped by Logilab_ since 2001.
-
-Entirely written in Python, `CubicWeb` publishes data from all sorts
-of sources such as SQL database, LDAP directory and versioning system such
-as subversion.
-
-`CubicWeb` user interface was designed to let the final user a huge flexibility
-on how to select and how to display content. It allows to browse the knowledge
-database and to display the results with the best rendering according to
-the context.
-This interface flexibility gives back the user the control of the
-rendering parameters that are usually reserved for developpers.
-
-
-We can list a couple of web applications developped with `CubicWeb`, an online
-public phone directory (see http://www.118000.fr/), a system for managing
-digital studies and simulations for a research lab, a tool for shared children
-babysitting (see http://garde-partagee.atoukontact.fr/), a tool to manage
-software developpment (see http://www.logilab.org), an application for
-managing museums collections (see
-http://collections.musees-haute-normandie.fr/collections/), etc.
-
-In 2008, `CubicWeb` was ported for a new type of source : the datastore
-from `GoogleAppEngine`_.
-
-.. include:: A03a-concepts.en.txt
--- a/doc/book/en/A03a-concepts.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,536 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Concepts
---------
-
-This section aims to provide you the keys of success with `CubicWeb`
-by clarifying the terms specific to our framework.
-
-Global architecture
-~~~~~~~~~~~~~~~~~~~
-.. image:: images/archi_globale.en.png
-
-
-`CubicWeb` framework is a server/client application framework. Those two
-parts communicate through RQL (`CubicWeb` query language implementation)
-and ResultSet (which will be explained in :ref:`TermsVocabulary`).
-
-The server manages all interactions with sources.
-
-
-.. note::
- Usually, the client and server sides are integrated in the same
- process and interact directly, without the need for distant
- calls using Pyro. But, it is important to note that those two
- sides, client/server, are disjointed and it is possible to execute
- a couple of calls in distinct processes to balance the load of
- your web site on one or more machines.
-
-.. _TermsVocabulary:
-
-Terms and vocabulary
-~~~~~~~~~~~~~~~~~~~~~
-
-`CubicWeb` defines its own terminology. To make sure there is no confusion
-while reading this book, we strongly recommand you take time to go through
-the following definitions that are the basics to understand while
-developing with `CubicWeb`.
-
-*schema*
- The schema defines the data model of an application based on entities
- and relations, modeled with a comprehensive language made of Python
- classes based on `yams`_ library. This is the core piece
- of an application. It is initially defined in the file system and is
- stored in the database at the time an instance is created. `CubicWeb`
- provides a certain number of system entities included automatically
- (necessary for the core of `CubicWeb`) and a library of
- cubes (which defined application entities) that can be explicitely
- included if necessary.
-
-*entity type*
- An entity type is a set of attributes; the essential attribute of
- an entity is its key, named eid.
-
-*relation type*
- Entities are linked to each others by relations. In `CubicWeb`
- relations are binary: by convention we name the first item of
- a relation the `subject` and the second the `object`.
-
-*final entity type*
- Final types correspond to the basic types such as string of characters,
- integers... Those types have a main property which is that they can
- only be used as `object` of a relation. The attributes of an entity
- (non final) are entities (finals).
-
-*final relation type*
- A relation is said final if its `object` is a final type. This is equivalent
- to an entity attribute.
-
-*relation definition*
- A relation definition is a 3-uple (subject entity type, relation type, object
- entity type), with an associated set of property such as cardinality, constraints...
-
-*repository*
- This is the RQL server side of `CubicWeb`. Be carefull not to get
- confused with a Mercurial repository or a debian repository.
-
-*source*
- A data source is a container of data (SGBD, LDAP directory, `Google
- App Engine`'s datastore ...) integrated in the
- `CubicWeb` repository. This repository has at least one source, `system` which
- contains the schema of the application, plain-text index and other
- vital informations for the system.
-
-*configuration*
- It is possible to create different configurations for an instance:
-
- - ``repository`` : repository only, accessible for clients using Pyro
- - ``twisted`` : web interface only, access the repository using Pyro
- - ``all-in-one`` : web interface and repository in a single process.
- The repository could be or not accessible using Pyro.
-
-*cube*
- A cube is a model grouping one or multiple data types and/or views
- to provide a specific functionality or a complete `CubicWeb` application
- potentially using other cubes. The available cubes are located in the file
- system at `/path/to/forest/cubicweb/cubes` for a Mercurial forest installation.
- For a debian packages installation they will be located in
- `/usr/share/cubicweb/cubes`.
- Larger applications can be built quite fast by importing cubes,
- adding entities and relationships, overriding the
- *views* that display the cubes or by editing informations not provided by
- the cubes.
-
-*instance*
- An instance is a specific installation of one or multiple cubes. All the required
- configuration files necessary for the well being of your web application
- are grouped in an instance. This will refer to the cube(s) your application
- is based on.
- For example logilab.org and our intranet are two instances of a single
- cube "jpl", developped internally.
- The instances are defined in the directory `/etc/cubicweb.d`.
-
-*application*
- The term application is sometimes used to talk about an instance
- and sometimes to talk of a cube depending on the context.
- So we would like to avoid using this term and try to use *cube* and
- *instance* instead.
-
-*result set*
- This object contains the results of an RQL query sent to the source
- and informations on the query.
-
-*Pyro*
- `Python Remote Object`_, distributed objects system similar to Java's RMI
- (Remote Method Invocation), which can be used for the dialog between the web
- side of the framework and the RQL repository.
-
-*query language*
- A full-blown query language named RQL is used to formulate requests
- to the database or any sources such as LDAP or `Google App Engine`'s
- datastore.
-
-*views*
- A view is applied to a `result set` to present it as HTML, XML,
- JSON, CSV, etc. Views are implemented as Python classes. There is no
- templating language.
-
-*generated user interface*
- A user interface is generated on-the-fly from the schema definition:
- entities can be created, displayed, updated and deleted. As display
- views are not very fancy, it is usually necessary to develop your
- own. Any generated view can be overridden by defining a new one with
- the same identifier.
-
-*rql*
- Relation Query Language in order to emphasize the way of browsing relations.
- This query language is inspired by SQL but is on a higher level;
- its implementation generates SQL.
-
-
-.. _`Python Remote Object`: http://pyro.sourceforge.net/
-.. _`yams`: http://www.logilab.org/project/yams/
-
-
-`CubicWeb` engine
-~~~~~~~~~~~~~~~~~
-
-The engine in `CubicWeb` is a set of classes managing a set of objects loaded
-dynamically at the startup of `CubicWeb` (*appobjects*). Those dynamic objects,
-based on the schema or the library, are building the final application.
-The different dynamic components are for example:
-
-* client and server side
-
- - entities definition, containing the logic which enables application data manipulation
-
-* client side
-
- - *views*, or more specifically
-
- - boxes
- - header and footer
- - forms
- - page templates
-
- - *actions*
- - *controllers*
-
-* server side
-
- - notification hooks
- - notification views
-
-The components of the engine are:
-
-* a frontal web (only twisted is available so far), transparent for dynamic objects
-* an object that encapsulates the configuration
-* a `registry` (`cubicweb.cwvreg`) containing the dynamic objects loaded automatically
-
-Every *appobject* may access to the instance configuration using its *config* attribute
-and to the registry using its *vreg* attribute.
-
-API Python/RQL
-~~~~~~~~~~~~~~
-
-The Python API developped to interface with RQL is inspired from the standard db-api,
-with a Connection object having the methods cursor, rollback and commit essentially.
-The most important method is the `execute` method of a cursor :
-
-`execute(rqlstring, args=None, eid_key=None, build_descr=True)`
-
-:rqlstring: the RQL query to execute (unicode)
-:args: if the query contains substitutions, a dictionary containing the values to use
-:eid_key:
- an implementation detail of the RQL cache implies that if a substitution
- is used to introduce an eid *susceptible to raise the ambiguities in the query
- type resolution*, then we have to specify the corresponding key in the dictionary
- through this argument
-
-
-The `Connection` object owns the methods `commit` and `rollback`. You *should
-never need to use them* during the development of the web interface based on
-the `CubicWeb` framework as it determines the end of the transaction depending
-on the query execution success.
-
-.. note::
- While executing update queries (SET, INSERT, DELETE), if a query generates
- an error related to security, a rollback is automatically done on the current
- transaction.
-
-
-The `Request` class (`cubicweb.web`)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-A request instance is created when an HTTP request is sent to the web server.
-It contains informations such as form parameters, user authenticated, etc.
-
-**Globally, a request represents a user query, either through HTTP or not
-(we also talk about RQL queries on the server side for example).**
-
-An instance of `Request` has the following attributes:
-
-* `user`, instance of `cubicweb.common.utils.User` corresponding to the authenticated
- user
-* `form`, dictionary containing the values of a web form
-* `encoding`, character encoding to use in the response
-
-But also:
-
-:Session data handling:
- * `session_data()`, returns a dictionary containing all the session data
- * `get_session_data(key, default=None)`, returns a value associated to the given
- key or the value `default` if the key is not defined
- * `set_session_data(key, value)`, assign a value to a key
- * `del_session_data(key)`, suppress the value associated to a key
-
-
-:Cookies handling:
- * `get_cookie()`, returns a dictionary containing the value of the header
- HTTP 'Cookie'
- * `set_cookie(cookie, key, maxage=300)`, adds a header HTTP `Set-Cookie`,
- with a minimal 5 minutes length of duration by default (`maxage` = None
- returns a *session* cookie which will expire when the user closes the browser
- window)
- * `remove_cookie(cookie, key)`, forces a value to expire
-
-:URL handling:
- * `url()`, returns the full URL of the HTTP request
- * `base_url()`, returns the root URL of the web application
- * `relative_path()`, returns the relative path of the request
-
-:And more...:
- * `set_content_type(content_type, filename=None)`, adds the header HTTP
- 'Content-Type'
- * `get_header(header)`, returns the value associated to an arbitrary header
- of the HTTP request
- * `set_header(header, value)`, adds an arbitrary header in the response
- * `cursor()` returns a RQL cursor on the session
- * `execute(*args, **kwargs)`, shortcut to ``.cursor().execute()``
- * `property_value(key)`, properties management (`CWProperty`)
- * dictionary `data` to store data to share informations between components
- *while a request is executed*
-
-Please note that this class is abstract and that a concrete implementation
-will be provided by the *frontend* web used (in particular *twisted* as of
-today). For the views or others that are executed on the server side,
-most of the interface of `Request` is defined in the session associated
-to the client.
-
-The `AppObject` class
-~~~~~~~~~~~~~~~~~~~~~
-
-In general:
-
-* we do not inherit directly from this class but from a more specific
- class such as `AnyEntity`, `EntityView`, `AnyRsetView`,
- `Action`...
-
-* to be recordable, a subclass has to define its own register (attribute
- `__registry__`) and its identifier (attribute `id`). Usually we do not have
- to take care of the register, only the identifier `id`.
-
-We can find a certain number of attributes and methods defined in this class
-and common to all the application objects.
-
-At the recording, the following attributes are dynamically added to
-the *subclasses*:
-
-* `vreg`, the `vregistry` of the application
-* `schema`, the application schema
-* `config`, the application configuration
-
-We also find on instances, the following attributes:
-
-* `req`, `Request` instance
-* `rset`, the *result set* associated to the object if necessary
-* `cursor`, rql cursor on the session
-
-
-:URL handling:
- * `build_url(method=None, **kwargs)`, returns an absolute URL based on
- the given arguments. The *controller* supposed to handle the response,
- can be specified through the special parameter `method` (the connection
- is theoretically done automatically :).
-
- * `datadir_url()`, returns the directory of the application data
- (contains static files such as images, css, js...)
-
- * `base_url()`, shortcut to `req.base_url()`
-
- * `url_quote(value)`, version *unicode safe* of the function `urllib.quote`
-
-:Data manipulation:
-
- * `etype_rset(etype, size=1)`, shortcut to `vreg.etype_rset()`
-
- * `eid_rset(eid, rql=None, descr=True)`, returns a *result set* object for
- the given eid
- * `entity(row, col=0)`, returns the entity corresponding to the data position
- in the *result set* associated to the object
-
- * `complete_entity(row, col=0, skip_bytes=True)`, is equivalent to `entity` but
- also call the method `complete()` on the entity before returning it
-
-:Data formatting:
- * `format_date(date, date_format=None, time=False)` returns a string for a
- mx date time according to application's configuration
- * `format_time(time)` returns a string for a mx date time according to
- application's configuration
-
-:And more...:
-
- * `external_resource(rid, default=_MARKER)`, access to a value defined in the
- configuration file `external_resource`
-
- * `tal_render(template, variables)`, renders a precompiled page template with
- variables in the given dictionary as context
-
-.. note::
- When we inherit from `AppObject` (even not directly), you *always* have to use
- **super()** to get the methods and attributes of the superclasses, and not
- use the class identifier.
- For example, instead of writting: ::
-
- class Truc(PrimaryView):
- def f(self, arg1):
- PrimaryView.f(self, arg1)
-
- You'd better write: ::
-
- class Truc(PrimaryView):
- def f(self, arg1):
- super(Truc, self).f(arg1)
-
-.. _cubesConcepts:
-
-Cubes
-~~~~~
-
-What is a cube ?
-````````````````
-
-A cube is a model grouping one or more entity types and/or views associated
-in order to provide a specific feature or even a complete application using
-other cubes.
-
-You can decide to write your own set of cubes if you wish to re-use the
-entity types you develop. Lots of cubes are available from the `CubicWeb
-Forge`_ under a free software license.
-
-.. _`CubicWeb Forge`: http://www.cubicweb.org/project/
-
-.. _foundationsCube:
-
-Standard structure for a cube
-`````````````````````````````
-
-A cube is structured as follows:
-
-::
-
- mycube/
- |
- |-- data/
- | |-- cubes.mycube.css
- | |-- cubes.mycube.js
- | `-- external_resources
- |
- |-- debian/
- | |-- changelog
- | |-- compat
- | |-- control
- | |-- copyright
- | |-- cubicweb-mycube.prerm
- | `-- rules
- |
- |-- entities.py
- |
- |-- i18n/
- | |-- en.po
- | `-- fr.po
- |
- |-- __init__.py
- |
- |-- MANIFEST.in
- |
- |-- migration/
- | |-- postcreate.py
- | `-- precreate.py
- |
- |-- __pkginfo__.py
- |
- |-- schema.py
- |
- |-- setup.py
- |
- |-- site_cubicweb.py
- |
- |-- hooks.py
- |
- |-- test/
- | |-- data/
- | | `-- bootstrap_cubes
- | |-- pytestconf.py
- | |-- realdb_test_mycube.py
- | `-- test_mycube.py
- |
- `-- views.py
-
-
-We can use subpackages instead of python modules for ``views.py``, ``entities.py``,
-``schema.py`` or ``hooks.py``. For example, we could have:
-
-::
-
- mycube/
- |
- |-- entities.py
- |-- hooks.py
- `-- views/
- |-- forms.py
- |-- primary.py
- `-- widgets.py
-
-
-where :
-
-* ``schema`` contains the schema definition (server side only)
-* ``entities`` contains the entities definition (server side and web interface)
-* ``sobjects`` contains hooks and/or views notifications (server side only)
-* ``views`` contains the web interface components (web interface only)
-* ``test`` contains tests related to the application (not installed)
-* ``i18n`` contains message catalogs for supported languages (server side and
- web interface)
-* ``data`` contains data files for static content (images, css, javascripts)
- ...(web interface only)
-* ``migration`` contains initialization file for new instances (``postcreate.py``)
- and a file containing dependencies of the component depending on the version
- (``depends.map``)
-* ``debian`` contains all the files managing debian packaging (you will find
- the usual files ``control``, ``rules``, ``changelog``... not installed)
-* file ``__pkginfo__.py`` provides component meta-data, especially the distribution
- and the current version (server side and web interface) or sub-cubes used by
- the cube.
-
-
-At least you should have:
-
-* the file ``__pkginfo__.py``
-* the schema definition
- XXX false, we may want to have cubes which are only adding a service,
- no persistent data (eg embedding for instance)
-
-
-Standard library
-````````````````
-
-A library of standard cubes are available from `CubicWeb Forge`_
-Cubes provide entities and views.
-
-The available application entities are:
-
-* addressbook_: PhoneNumber and PostalAddress
-
-* basket_: Basket (like a shopping cart)
-
-* blog_: Blog (a *very* basic blog)
-
-* comment_: Comment (to attach comment threads to entities)
-
-* event_: Event (define events, display them in calendars)
-
-* file_: File (to allow users to upload and store binary or text files)
-
-* folder_: Folder (to organize things but grouping them in folders)
-
-* keyword_: Keyword (to define classification schemes)
-
-* link_: Link (to collect links to web resources)
-
-* mailinglist_: MailingList (to reference a mailing-list and the URLs
- for its archives and its admin interface)
-
-* person_: Person (easily mixed with addressbook)
-
-* tag_: Tag (to tag anything)
-
-* task_: Task (something to be done between start and stop date)
-
-* zone_: Zone (to define places within larger places, for example a
- city in a state in a country)
-
-.. _addressbook: http://www.cubicweb.org/project/cubicweb-addressbook
-.. _basket: http://www.cubicweb.org/project/cubicweb-basket
-.. _blog: http://www.cubicweb.org/project/cubicweb-blog
-.. _comment: http://www.cubicweb.org/project/cubicweb-comment
-.. _event: http://www.cubicweb.org/project/cubicweb-event
-.. _file: http://www.cubicweb.org/project/cubicweb-file
-.. _folder: http://www.cubicweb.org/project/cubicweb-folder
-.. _keyword: http://www.cubicweb.org/project/cubicweb-keyword
-.. _link: http://www.cubicweb.org/project/cubicweb-link
-.. _mailinglist: http://www.cubicweb.org/project/cubicweb-mailinglist
-.. _person: http://www.cubicweb.org/project/cubicweb-person
-.. _tag: http://www.cubicweb.org/project/cubicweb-tag
-.. _task: http://www.cubicweb.org/project/cubicweb-task
-.. _zone: http://www.cubicweb.org/project/cubicweb-zone
--- a/doc/book/en/B0-data-model.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,13 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-The data model
-++++++++++++++
-
-.. toctree::
- :maxdepth: 1
-
- B0010-define-schema.en.txt
- B0020-define-workflows.en.txt
- B0030-data-as-objects.en.txt
- B0040-migration.en.txt
-
--- a/doc/book/en/B0010-define-schema.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,23 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Data model definition: the *schema*
-===================================
-
-The **schema** is the core piece of a `CubicWeb` application as it defines
-the handled data model. It is based on entity types that are either already
-defined in the `CubicWeb` standard library; or more specific types, that
-`CubicWeb` expects to find in one or more Python files under the directory
-`schema`.
-
-At this point, it is important to make clear the difference between
-*relation type* and *relation definition*: a *relation type* is only a relation
-name with potentially other additionnal properties (see XXXX), whereas a
-*relation definition* is a complete triplet
-"<subject entity type> <relation type> <object entity type>".
-A relation type could have been implied if none is related to a
-relation definition of the schema.
-
-
-.. include:: B0011-schema-stdlib.en.txt
-.. include:: B0012-schema-definition.en.txt
-
--- a/doc/book/en/B0011-schema-stdlib.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,98 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Pre-defined schemas in the library
-----------------------------------
-
-The library defines a set of entity schemas that are required by the system
-or commonly used in `CubicWeb` applications.
-Of course, you can extend those schemas if necessary.
-
-
-System schemas
-``````````````
-The available system entities are:
-
-* `CWUser`, system users
-* `CWGroup`, users groups
-* `CWEType`, entity type
-* `CWRType`, 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
-
-* `CWProperty`, used to configure the application
-* `CWPermission`, 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
-
-(The first 'E' in some of the names is the first letter of 'Erudi',
-`CubicWeb`'s old name; it might be changed/removed some day.)
-
-Available cubes
-```````````````
-
-An application is based on several basic cubes. In the set of available
-basic cubes we can find for example :
-
-* addressbook_: PhoneNumber and PostalAddress
-
-* basket_: Basket (like a shopping cart)
-
-* blog_: Blog (a *very* basic blog)
-
-* comment_: Comment (to attach comment threads to entities)
-
-* email_: archiving management for emails (`Email`, `Emailpart`,
- `Emailthread`)
-
-* event_: Event (define events, display them in calendars)
-
-* file_: File (to allow users to upload and store binary or text files)
-
-* folder_: Folder (to organize things but grouping them in folders)
-
-* keyword_: Keyword (to define classification schemes)
-
-* link_: Link (to collect links to web resources)
-
-* mailinglist_: MailingList (to reference a mailing-list and the URLs
- for its archives and its admin interface)
-
-* person_: Person (easily mixed with addressbook)
-
-* tag_: Tag (to tag anything)
-
-* task_: Task (something to be done between start and stop date)
-
-* zone_: Zone (to define places within larger places, for example a
- city in a state in a country)
-
-.. _addressbook: http://www.cubicweb.org/project/cubicweb-addressbook
-.. _basket: http://www.cubicweb.org/project/cubicweb-basket
-.. _blog: http://www.cubicweb.org/project/cubicweb-blog
-.. _comment: http://www.cubicweb.org/project/cubicweb-comment
-.. _email: http://www.cubicweb.org/project/cubicweb-email
-.. _event: http://www.cubicweb.org/project/cubicweb-event
-.. _file: http://www.cubicweb.org/project/cubicweb-file
-.. _folder: http://www.cubicweb.org/project/cubicweb-folder
-.. _keyword: http://www.cubicweb.org/project/cubicweb-keyword
-.. _link: http://www.cubicweb.org/project/cubicweb-link
-.. _mailinglist: http://www.cubicweb.org/project/cubicweb-mailinglist
-.. _person: http://www.cubicweb.org/project/cubicweb-person
-.. _tag: http://www.cubicweb.org/project/cubicweb-tag
-.. _task: http://www.cubicweb.org/project/cubicweb-task
-.. _zone: http://www.cubicweb.org/project/cubicweb-zone
-
-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
--- a/doc/book/en/B0012-schema-definition.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,421 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Entity type definition
-----------------------
-
-An entity type is defined by a Python class which inherits from `EntityType`.
-The class definition contains the description of attributes and relations
-for the defined entity type.
-The class name corresponds to the entity type name. It is exepected to be
-defined in the module ``mycube.schema``.
-
-
-For example ::
-
- class Person(EntityType):
- """A person with the properties and the relations necessary for my
- application"""
-
- last_name = String(required=True, fulltextindexed=True)
- first_name = String(required=True, fulltextindexed=True)
- title = String(vocabulary=('Mr', 'Mrs', 'Miss'))
- date_of_birth = Date()
- works_for = SubjectRelation('Company', cardinality='?*')
-
-
-The entity described above defines three attributes of type String,
-last_name, first_name and title, an attribute of type Date for the date of
-birth and a relation that connects a `Person` to another entity of type
-`Company` through the semantic `works_for`.
-
-The name of the Python attribute corresponds to the name of the attribute
-or the relation in `CubicWeb` application.
-
-Built-in types for attributes
-`````````````````````````````
-
-All `CubicWeb` built-in types are available : `String`, `Int`, `Float`,
-`Decimal`, `Boolean`, `Date`, `Datetime`, `Time`, `Interval`, `Byte`
-and `Password`.
-They are implicitely imported (as well as the special the function "_"
-for translation :ref:`internationalization`).
-
-An attribute is defined in the schema as follows::
-
- attr_name = attr_type(properties*)
-
-where `attr_type` is one of the type listed above and `properties` is
-a list of the attribute needs to statisfy (see :ref:`properties`
-for more details).
-
-
-Meta-data
-`````````
-
-Each entity type has at least the following meta-relations :
-
- - `eid` (`Int`)
-
- - `creation_date` (`Datetime`)
-
- - `modification_date` (`Datetime`)
-
- - `created_by` (`CWUser`) (which user created the entity)
-
- - `owned_by` (`CWUser`) (to whom the entity belongs; by default the
- creator but not necessary, and it could have multiple owners)
-
- - `is` (`CWEType`) (of which type the entity is)
-
-
-* relations can be defined by using `ObjectRelation` or `SubjectRelation`.
- The first argument of `SubjectRelation` or `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 corresponding to multiple entity 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)
-
-Optionnal properties
-````````````````````
-.. _properties:
-
-
-* optional properties for attributes and relations :
-
- - `description` : a 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` : a list of conditions/constraints that the relation has to
- satisfy (c.f. `Contraints`_)
-
- - `cardinality` : a two character string which specify the cardinality of the
- relation. The first character defines the cardinality of the relation on
- the subject, and the second on the object. When a relation can have
- multiple subjects or objects, the cardinality applies to all,
- not on a one-to-one basis (so it must be consistent...). The possible
- values are inspired from regular expression syntax :
-
- * `1`: 1..1
- * `?`: 0..1
- * `+`: 1..n
- * `*`: 0..n
-
- - `meta` : boolean indicating that the relation is a meta-relation (false by
- default)
-
-* optional 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 useful 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 correspond to the RQL keywords `TODAY` and `NOW`.
-
- - `vocabulary` : specify static possible values of an attribute
-
-* optional 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)
-
-* optional 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 set
- 'object' as 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 constraint 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 has 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.
-
-
-Definition of relations
------------------------
-
-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
-contain 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 = 'CWUser'
-
-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`)
-
-* `symmetric` : boolean indicating that the relation is symmetrical, 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 symmetrical, 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
-``````````````````````
-
-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 `CWPermission` from the standard library
-allow to build very complex and dynamic security architecture. The schema of
-this entity type is as follow : ::
-
- class CWPermission(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('CWGroup', 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 `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 genricity 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.
-
-
-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.
-Instead, you call a shell on your application, which is a
-an interactive python shell, with an appropriate
-cubicweb environment ::
-
- cubicweb-ctl shell myinstance
-
-and type ::
-
- add_entity_type('Person')
-
-And restart your application!
--- a/doc/book/en/B0020-define-workflows.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,159 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-.. _Workflow:
-
-An Example: Workflow definition
-===============================
-
-General
--------
-
-A workflow describes how certain entities have to evolve between
-different states. Hence we have a set of states, and a "transition graph",
-i.e. a list of possible transitions from one state to another state.
-
-We will define a simple workflow for a blog, with only the following
-two states: `submitted` and `published`. So first, we create a simple
-`CubicWeb` in ten minutes (see :ref:`BlogTenMinutes`).
-
-Set-up a workflow
------------------
-
-We want to create a workflow to control the quality of the BlogEntry
-submitted on your application. When a BlogEntry is created by a user
-its state should be `submitted`. To be visible to all, it has to
-be in the state `published`. To move it from `submitted` to `published`,
-we need a transition that we can call `approve_blogentry`.
-
-A BlogEntry state should not be modifiable by every user.
-So we have to define a group of users, `moderators`, and
-this group will have appropriate permissions to publish a BlogEntry.
-
-There are two ways to create a workflow: from the user interface,
-or by defining it in ``migration/postcreate.py``.
-This script is executed each time a new ``cubicweb-ctl db-init`` is done.
-We strongly recommand to create the workflow in ``migration/postcreate.py``
-and we will now show you how. Read `Under the hood`_ to understand why.
-
-Update the schema
-~~~~~~~~~~~~~~~~~
-If we want a State for our BlogEntry, we have to define a relation
-``in_state`` in the schema of BlogEntry. So we add
-the line ``in_state (...)``::
-
- class BlogEntry(EntityType):
- title = String(maxsize=100, required=True)
- publish_date = Date(default='TODAY')
- text_format = String(meta=True, internationalizable=True, maxsize=50,
- default='text/rest', constraints=[format_constraint])
- text = String(fulltextindexed=True)
- category = String(vocabulary=('important','business'))
- entry_of = SubjectRelation('Blog', cardinality='?*')
- in_state = SubjectRelation('State', cardinality='1*')
-
-As you updated the schema, you have to re-execute ``cubicweb-ctl db-init``
-to initialize the database and migrate your existing entities.
-
-[WRITE ABOUT MIGRATION]
-
-Create states, transitions and group permissions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The ``postcreate.py`` script is executed in a special environment, adding
-several `CubicWeb` primitives that can be used.
-They are all defined in the ``class ServerMigrationHelper``.
-We will only discuss the methods we use to create a workflow in this example.
-
-To define our workflow for BlogDemo, please add the following lines
-to ``migration/postcreate.py``::
-
- _ = unicode
-
- moderators = add_entity('CWGroup', name=u"moderators")
-
-This adds the `moderators` user group.
-
-::
-
- submitted = add_state(_('submitted'), 'BlogEntry', initial=True)
- published = add_state(_('published'), 'BlogEntry')
-
-``add_state`` expects as first argument the name of the state you want
-to create, then the entity type on which the state can be applied,
-and an optional argument to say if it is supposed to be the initial state
-of the entity type.
-
-::
-
- add_transition(_('approve_blogentry'), 'BlogEntry', (submitted,), published, ('moderators', 'managers'),)
-
-
-``add_transition`` expects
-
- * as the first argument the name of the
- transition, then the entity type on which the transition can be applied,
- * then the list of states on which the transition can be trigged,
- * the target state of the transition,
- * and the permissions
- (e.g. a list of user groups who can apply the transition; the user
- has to belong to at least one of the listed group to perform the action).
-
-::
-
- checkpoint()
-
-.. note::
- Do not forget to add the `_()` in front of all states and transitions names while creating
- a workflow so that they will be identified by the i18n catalog scripts.
-
-In addition to the user group condition, we could have added a RQL condition.
-In this case, the user can only perform the action if
-the two conditions are satisfied.
-
-If we use a RQL condition on a transition, we can use the following
-variables:
-
-* `%(eid)s`, object's eid
-* `%(ueid)s`, user executing the query eid
-* `%(seid)s`, the object's current state eid
-
-
-.. image:: images/lax-book.03-transitions-view.en.png
-
-You can notice that in the action box of a BlogEntry, the state
-is now listed as well as the possible transitions defined by the workflow.
-The transitions will only be displayed for users having the right permissions.
-In our example, the transition `approve_blogentry` will only be displayed
-for the users belonging to the group `moderators` or `managers`.
-
-
-Under the hood
-~~~~~~~~~~~~~~
-
-A workflow is a collection of entities of type ``State`` and of type ``Transition``
-which are standard `CubicWeb` entity types.
-For instance, the following lines::
-
- submitted = add_state(_('submitted'), 'BlogEntry', initial=True)
- published = add_state(_('published'), 'BlogEntry')
-
-will create two entities of type ``State``, one with name 'submitted', and the other
-with name 'published'. Whereas::
-
- add_transition(_('approve_blogentry'), 'BlogEntry', (submitted,), published, ('moderators', 'managers'),)
-
-will create an entity of type ``Transition`` with name 'approve_blogentry' which will
-be linked to the ``State`` entities created before.
-As a consequence, we could use the administration interface to do these operations.
-But it is not recommanded because it will be uselessly complicated
-and will be only local to your instance.
-
-
-Indeed, if you create the states and transitions through the user interface,
-next time you initialize the database
-you will have to re-create all the entities.
-The user interface should only be a reference for you to view the states
-and transitions, but is not the appropriate interface to define your
-application workflow.
-
-
--- a/doc/book/en/B0030-data-as-objects.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,247 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-
-Data as objects
-===============
-
-In this chapter, we will introduce the objects that are used to handle
-the data stored in the database.
-
-Class `Entity` and `AnyEntity`
-------------------------------
-
-To provide a specific behavior for each entity, we have to define
-a class inheriting from `cubicweb.entities.AnyEntity`. In general, we
-define this class in a module of `mycube.entities` package of an application
-so that it will be available on both server and client side.
-
-The class `AnyEntity` is loaded dynamically from the class `Entity`
-(`cubciweb.common.entity`). We define a sub-class to add methods or to
-specialize the handling of a given entity type
-
-Descriptors are added when classes are registered in order to initialize the class
-according to its schema:
-
-* we can access the defined attributes in the schema thanks to the attributes of
- the same name on instances (typed value)
-
-* we can access the defined relations in the schema thanks to the relations of
- the same name on instances (entities instances list)
-
-The methods defined for `AnyEntity` or `Entity` are the following ones:
-
-* `has_eid()`, returns true is the entity has an definitive eid (e.g. not in the
- creation process)
-
-* `check_perm(action)`, checks if the user has the permission to execute the
- requested action on the entity
-
-:Formatting and output generation:
-
- * `view(vid, **kwargs)`, applies the given view to the entity
-
- * `absolute_url(**kwargs)`, returns an absolute URL to access the primary view
- of an entity
-
- * `rest_path()`, returns a relative REST URL to get the entity
-
- * `format(attr)`, returns the format (MIME type) of the field given un parameter
-
- * `printable_value(attr, value=_marker, attrtype=None, format='text/html')`,
- returns a string enabling the display of an attribute value in a given format
- (the value is automatically recovered if necessary)
-
- * `display_name(form='')`, returns a string to display the entity type by
- specifying the preferred form (`plural` for a plural form)
-
-:Data handling:
-
- * `as_rset()`, converts the entity into an equivalent result set simulating the
- request `Any X WHERE X eid _eid_`
-
- * `complete(skip_bytes=True)`, executes a request that recovers in one time
- all the missing attributes of an entity
-
- * `get_value(name)`, returns the value associated to the attribute name given
- in parameter
-
- * `related(rtype, x='subject', limit=None, entities=False)`, returns a list
- of entities related to the current entity by the relation given in parameter
-
- * `unrelated(rtype, targettype, x='subject', limit=None)`, returns a result set
- corresponding to the entities not related to the current entity by the
- relation given in parameter and satisfying its constraints
-
- * `set_attributes(**kwargs)`, updates the attributes list with the corresponding
- values given named parameters
-
- * `copy_relations(ceid)`, copies the relations of the entities having the eid
- given in the parameters on the current entity
-
- * `last_modified(view)`, returns the date the object has been modified
- (used by HTTP cache handling)
-
- * `delete()` allows to delete the entity
-
-:Standard meta-data (Dublin Core):
-
- * `dc_title()`, returns a unicode string corresponding to the meta-data
- `Title` (used by default the first attribute non-meta of the entity
- schema)
-
- * `dc_long_title()`, same as dc_title but can return a more
- detailled title
-
- * `dc_description(format='text/plain')`, returns a unicode string
- corresponding to the meta-data `Description` (look for a description
- attribute by default)
-
- * `dc_authors()`, returns a unicode string corresponding to the meta-data
- `Authors` (owners by default)
-
- * `dc_date(date_format=None)`, returns a unicode string corresponding to
- the meta-data `Date` (update date by default)
-
-:Vocabulary control on relations:
-
- * `vocabulary(rtype, x='subject', limit=None)`, called by the
- editing views, it returns a list of couples (label, eid) of entities
- that could be related to the entity by the relation `rtype`
- * `subject_relation_vocabulary(rtype, limit=None)`, called internally
- by `vocabulary` in the case of a subject relation
- * `object_relation_vocabulary(rtype, limit=None)`, called internally
- by `vocabulary` in the case of an object relation
- * `relation_vocabulary(rtype, targettype, x, limit=None)`, called
- internally by `subject_relation_vocabulary` and `object_relation_vocabulary`
-
-Class `TreeMixIn`
------------------
-
-This class provides a tree interface. This mixin has to be inherited
-explicitly and configured using the tree_attribute, parent_target and
-children_target class attribute to benefit from this default implementation.
-
-This class provides the following methods:
-
- * `different_type_children(entities=True)`, returns children entities
- of different type as this entity. According to the `entities` parameter,
- returns entity objects (if entity=True) or the equivalent result set.
-
- * `same_type_children(entities=True)`, returns children entities of
- the same type as this entity. According to the `entities` parameter,
- return entity objects (if entity=True) or the equivalent result set.
-
- * `iterchildren( _done=None)`, iters on the children of the entity.
-
- * `prefixiter( _done=None)`
-
- * `path()`, returns the list of eids from the root object to this object.
-
- * `iterparents()`, iters on the parents of the entity.
-
- * `notification_references(view)`, used to control References field
- of email send on notification for this entity. `view` is the notification view.
- Should return a list of eids which can be used to generate message ids
- of previously sent email.
-
-`TreeMixIn` implements also the ITree interface (``cubicweb.interfaces``):
-
- * `parent()`, returns the parent entity if any, else None (e.g. if we are on the
- root)
-
- * `children(entities=True, sametype=False)`, returns children entities
- according to the `entities` parameter, return entity objects or the
- equivalent result set.
-
- * `children_rql()`, returns the RQL query corresponding to the children
- of the entity.
-
- * `is_leaf()`, returns True if the entity does not have any children.
-
- * `is_root()`, returns True if the entity does not have any parent.
-
- * `root()`, returns the root object of the tree representation of
- the entity and its related entities.
-
-Example of use
-``````````````
-
-Imagine you defined three types of entities in your schema, and they
-relates to each others as follows in ``schema.py``::
-
- class Entity1(EntityType):
- title = String()
- is_related_to = SubjectRelation('Entity2', 'subject')
-
- class Entity2(EntityType):
- title = String()
- belongs_to = SubjectRelation('Entity3', 'subject')
-
- class Entity3(EntityType):
- name = String()
-
-You would like to create a view that applies to both entity types
-`Entity1` and `Entity2` and which lists the entities they are related to.
-That means when you view `Entity1` you want to list all `Entity2`, and
-when you view `Entity2` you want to list all `Entity3`.
-
-In ``entities.py``::
-
- class Entity1(TreeMixIn, AnyEntity):
- id = 'Entity1'
- __implements__ = AnyEntity.__implements__ + (ITree,)
- __rtags__ = {('is_related_to', 'Entity2', 'object'): 'link'}
- tree_attribute = 'is_related_to'
-
- def children(self, entities=True):
- return self.different_type_children(entities)
-
- class Entity2(TreeMixIn, AnyEntity):
- id = 'Entity2'
- __implements__ = AnyEntity.__implements__ + (ITree,)
- __rtags__ = {('belongs_to', 'Entity3', 'object'): 'link'}
- tree_attribute = 'belongs_to'
-
- def children(self, entities=True):
- return self.different_type_children(entities)
-
-Once this is done, you can define your common view as follows::
-
- class E1E2CommonView(baseviews.PrimaryView):
- accepts = ('Entity11, 'Entity2')
-
- def render_entity_relations(self, entity, siderelations):
- self.wview('list', entity.children(entities=False))
-
-
-*rtags*
--------
-
-*rtags* allow to specify certain behaviors of relations relative to a given
-entity type (see later). They are defined on the entity class by the attribute
-`rtags` which is a dictionary with as keys the triplets ::
-
- <relation type>, <target entity type>, <context position ("subject" ou "object")>
-
-and as values a `set` or a tuple of markers defining the properties that
-apply to this relation.
-
-It is possible to simplify this dictionary:
-
-* if we want to specifiy a single marker, it is not necessary to
- use a tuple as value, the marker by itself (character string)
- is enough
-* if we only care about a single type of relation and not about the target
- and the context position (or when this one is not ambigous), we can simply
- use the name of the relation type as key
-* if we want a marker to apply independently from the target entity type,
- we have to use the string `*` as target entity type
-
-
-Please note that this dictionary is *treated at the time the class is created*.
-It is automatically merged with the parent class(es) (no need to copy the
-dictionary from the parent class to modify it). Also, modifying it after the
-class is created will not have any effect...
-
-.. include:: B0031-define-entities.en.txt
-
--- a/doc/book/en/B0031-define-entities.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,178 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Parametrization and specific extensions
----------------------------------------
-
-Dynamic default values
-``````````````````````
-It is possible to define *static* default values in the schema.
-It is also possible to define *dynamic* default values
-by defining in the entity class a method `default_<attribut name>` 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 and represented as a combobox. Each item of the
- combobox is a link to an existing entity.
-
-* `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 will be included in the
- editing form and represented as a combobox. Each item of the combobox
- is a link to an existing entity.
-
-* `inlineview`, includes the target entity's form in the editing form
- of the current entity. It allows to create the target entity in the
- same time as the current entity.
-
-* `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 necessary, 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 necessary, 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 other variables defined in the original request:
-
- 1. if the variable is related to the main variable by at least one relation
- 2. we call the method ``filterform_vocabulary(rtype, x)`` on the entity,
- if nothing is returned (meaning a tuple `Non`, see below), we go to the
- next variable, otherwise a form filtering element is created based on
- the vocabulary values returned
-
-4. there are no other limitations to the `RQL`, it can include sorting, grouping
- conditions... JavaScript functions are used to regenerate a request based on the
- initial request and on the selected values from the filtering form.
-
-The method ``filterform_vocabulary(rtype, x, var, rqlst, args, cachekey)`` takes
-the name of a relation and the target as parameters,
-[XXX what does it mean ?]
-which indicates of the
-entity on which we apply the method is subject or object of the relation. It
-has to return:
-
-* 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.
-
--- a/doc/book/en/B0040-migration.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,213 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-.. _migration:
-
-Migration
-=========
-
-One of the main concept in `CubicWeb` is to create incremental applications.
-For this purpose, multiple actions are provided to facilitate the improvement
-of an application, and in particular to handle the changes to be applied
-to the data model, without loosing existing data.
-
-The current version of an application model is provided in the file
-`__pkginfo__.py` as a tuple of 3 integers.
-
-Migration scripts management
-----------------------------
-
-Migration scripts has to be located in the directory `migration` of your
-application and named accordingly:
-
-::
-
- <version n° X.Y.Z>[_<description>]_<mode>.py
-
-in which :
-
-* X.Y.Z is the model version number to which the script enables to migrate.
-
-* *mode* (between the last "_" and the extension ".py") is used for
- distributed installation. It indicates to which part
- of the application (RQL server, web server) the script applies.
- Its value could be :
-
- * `common`, applies to the RQL server as well as the web server and updates
- files on the hard drive (configuration files migration for example).
-
- * `web`, applies only to the web server and updates files on the hard drive.
-
- * `repository`, applies only to the RQL server and updates files on the
- hard drive.
-
- * `Any`, applies only to the RQL server and updates data in the database
- (schema and data migration for example).
-
-Again in the directory `migration`, the file `depends.map` allows to indicate
-that for the migration to a particular model version, you always have to first
-migrate to a particular `CubicWeb` version. This file can contain comments (lines
-starting by `#`) and a dependancy is listed as follows: ::
-
- <model version n° X.Y.Z> : <cubicweb version n° X.Y.Z>
-
-For example: ::
-
- 0.12.0: 2.26.0
- 0.13.0: 2.27.0
- # 0.14 works with 2.27 <= cubicweb <= 2.28 at least
- 0.15.0: 2.28.0
-
-Base context
-------------
-
-The following identifiers are pre-defined in migration scripts:
-
-* `config`, instance configuration
-
-* `interactive_mode`, boolean indicating that the script is executed in
- an interactive mode or not
-
-* `appltemplversion`, application model version of the instance
-
-* `templversion`, installed application model version
-
-* `cubicwebversion`, installed cubicweb version
-
-* `confirm(question)`, function asking the user and returning true
- if the user answers yes, false otherwise (always returns true in
- non-interactive mode)
-
-* the function `_`, it is equivalent to `unicode` allowing to flag the strings
- to internationalize in the migration scripts.
-
-In the `repository` scripts, the following identifiers are also defined:
-
-* `checkpoint`, request confirming and executing a "commit" at checking point
-
-* `repo_schema`, instance persisting schema (e.g. instance schema of the
- current migration)
-
-* `newschema`, installed schema on the file system (e.g. schema of
- the updated model and cubicweb)
-
-* `sqlcursor`, SQL cursor for very rare cases where it is really
- necessary or beneficial to go through the sql
-
-* `repo`, repository object
-
-
-Schema migration
-----------------
-The following functions for schema migration are available in `repository`
-scripts:
-
-* `add_attribute(etype, attrname, attrtype=None, commit=True)`, adds a new
- attribute to an existing entity type. If the attribute type is not specified,
- then it is extracted from the updated schema.
-
-* `drop_attribute(etype, attrname, commit=True)`, removes an attribute from an
- existing entity type.
-
-* `rename_attribute(etype, oldname, newname, commit=True)`, renames an attribute
-
-* `add_entity_type(etype, auto=True, commit=True)`, adds a new entity type.
- If `auto` is True, all the relations using this entity type and having a known
- entity type on the other hand will automatically be added.
-
-* `drop_entity_type(etype, commit=True)`, removes an entity type and all the
- relations using it.
-
-* `rename_entity_type(oldname, newname, commit=True)`, renames an entity type
-
-* `add_relation_type(rtype, addrdef=True, commit=True)`, adds a new relation
- type. If `addrdef` is True, all the relations definitions of this type will
- be added.
-
-* `drop_relation_type(rtype, commit=True)`, removes a relation type and all the
- definitions of this type.
-
-* `rename_relation(oldname, newname, commit=True)`, renames a relation.
-
-* `add_relation_definition(subjtype, rtype, objtype, commit=True)`, adds a new
- relation definition.
-
-* `drop_relation_definition(subjtype, rtype, objtype, commit=True)`, removes
- a relation definition.
-
-* `synchronize_permissions(ertype, commit=True)`, synchronizes permissions on
- an entity type or relation type.
-
-* `synchronize_rschema(rtype, commit=True)`, synchronizes properties and permissions
- on a relation type.
-
-* `synchronize_eschema(etype, commit=True)`, synchronizes properties and persmissions
- on an entity type.
-
-* `synchronize_schema(commit=True)`, synchronizes the persisting schema with the
- updated schema (but without adding or removing new entity types, relations types
- or even relations definitions).
-
-* `change_relation_props(subjtype, rtype, objtype, commit=True, **kwargs)`, changes
- properties of a relation definition by using the named parameters of the properties
- to change.
-
-* `set_widget(etype, rtype, widget, commit=True)`, changes the widget used for the
- relation <rtype> of entity type <etype>.
-
-* `set_size_constraint(etype, rtype, size, commit=True)`, changes the size constraints
- for the relation <rtype> of entity type <etype>.
-
-Data migration
---------------
-The following functions for data migration are available in `repository` scripts:
-
-* `rql(rql, kwargs=None, cachekey=None, ask_confirm=True)`, executes an arbitrary RQL
- query, either to interrogate or update. A result set object is returned.
-
-* `add_entity(etype, *args, **kwargs)`, adds a nes entity type of the given
- type. The attribute and relation values are specified using the named and
- positionned parameters.
-
-Workflow creation
------------------
-
-The following functions for workflow creation are available in `repository`
-scripts:
-
-* `add_state(name, stateof, initial=False, commit=False, **kwargs)`, adds a new state
- in the workflow.
-
-* `add_transition(name, transitionof, fromstates, tostate, requiredgroups=(), commit=False, **kwargs)`,
- adds a new transition in the workflow.
-
-You can find more details about workflows in the chapter :ref:`Workflow` .
-
-Configuration migration
------------------------
-
-The following functions for configuration migration are available in all
-scripts:
-
-* `option_renamed(oldname, newname)`, indicates that an option has been renamed
-
-* `option_group_change(option, oldgroup, newgroup)`, indicates that an option does not
- belong anymore to the same group.
-
-* `option_added(oldname, newname)`, indicates that an option has been added.
-
-* `option_removed(oldname, newname)`, indicates that an option has been deleted.
-
-
-Others migration functions
---------------------------
-Those functions are only used for low level operations that could not be
-accomplished otherwise or to repair damaged databases during interactive
-session. They are available in `repository` scripts:
-
-* `sqlexec(sql, args=None, ask_confirm=True)`, executes an arbitrary SQL query
-* `add_entity_type_table(etype, commit=True)`
-* `add_relation_type_table(rtype, commit=True)`
-* `uninline_relation(rtype, commit=True)`
-
-
-[FIXME] Add explanation on how to use cubicweb-ctl shell
--- a/doc/book/en/B081-i18n.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,71 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-.. _Internationalisation:
-
-
-Internationalisation
-====================
-
-Le système d'internationalisation de l'interface web de CubicWeb est basé sur le
-système `GNU gettext`_.
-
-.. _`GNU gettext`: http://www.gnu.org/software/gettext/
-
-Messages à internationaliser
-----------------------------
-
-Marquage des messages à internaliser
-````````````````````````````````````
-Les chaines de caractères à internationaliser sont marqués par l'appel à la
-fonction `_` *OU* par la méthode équivalent de la requête dans le code python ou
-dans les expressions python de template TAL.
-
-Dans les templates cubicweb-tal, il est également possible d'insérer une chaine Ã
-traduire via les balises `i18n:content` et `i18n:replace`.
-
-De plus des messages correspondant aux entités/relations utilisés par le schéma
-de l'application seront automatiquement ajoutés.
-
-Renvoi d'un message internationalisé lors de la construction d'une page
-```````````````````````````````````````````````````````````````````````
-La fonction *built-in* `_` ne doit servir qu'**Ã marquer les messages Ã
-traduire**, non pas à récupérer une traduction. Il faut pour cela utiliser la
-méthode `_` de l'objet requête, sans quoi vous récupérerez l'identifiant de
-message au lieu de sa traduction dans la langue propre à la requête.1
-
-
-Gestion des catalogues de traduction
-------------------------------------
-Une fois l'application rendu internationalisable coté code, reste à gérer les
-catalogues de traductions. cubicweb-ctl intègre pour cela les commandes suivantes :
-
-* `i18nlibupdate`, met à jour les catalogues de messages *de la librairie
- cubicweb*. Sauf si vous développez sur le framework (et non votre propre
- application), vous ne devriez pas avoir à utiliser cette commande
-
-* `i18nupdate`, met à jour les catalogues de messages *du composant* (ou de tous
- les composants). A la suite de cette commande, vous devez mettre à jour les
- fichiers de traduction *.po* dans le sous-répertoire "i18n" de votre
- template. Évidemment les traductions précédentes toujours utilisées ont été
- conservées.
-
-* `i18ncompile`, recompile les catalogues de messages *d'une instance* (ou de
- toutes les instances) après mise à jour des catalogues de son composant. Cela
- est effectué automatiquement lors d'une création ou d'une mise à jour. Les
- catalogues de messages compilés se trouvent dans le répertoire
- "i18n/<lang>/LC_MESSAGES/cubicweb.mo" de l'application où `lang` est
- l'identifiant de la langue sur 2 lettres ('en' ou 'fr' par exemple)
-
-
-Le cas classique
-````````````````
-Vous avez ajouté et/ou modifié des messages d'un composant utilisé par votre
-application (en ajoutant une nouvelle vue ou en ayant modifié le schéma par
-exemple) :
-
-1. `cubicweb-ctl i18nupdate <composant>`
-2. éditer les fichiers <composant>/xxx.po dans pour y rajouter les traductions
- manquantes (`msgstr` vide)
-3. `hg ci -m "updated i18n catalogs"`
-4. `cubicweb-ctl i18n compile <monapplication>`
-
--- a/doc/book/en/B1-web-interface.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,20 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Web interface
-+++++++++++++
-.. toctree::
- :maxdepth: 1
-
- B1010-request.en.txt
- B1020-define-views.en.txt
- B1030-form-management.en.txt
- B1040-actions.en.txt
- B1050-boxes.en.txt
- B1060-templates.en.txt
- B1070-ui-components.en.txt
- B1080-ajax-json.en.txt
- B1090-internationalization.en.txt
- B1100-online-doc.en.txt
- B1110-embedding-external-page.en.txt
- B1120-urlrewrite.en.txt
- B1130-css.en.txt
--- a/doc/book/en/B1010-request.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,9 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Request
-=======
-
-[WRITE ME]
-
-* the request object
-
--- a/doc/book/en/B1020-define-views.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,414 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-.. _ViewDefinition:
-
-Views definition
-================
-
-This chapter aims to describe the concept of a `view` used all along
-the development of a web application and how it has been implemented
-in `CubicWeb`.
-
-We'll start with a description of the interface providing you with a basic
-understanding of the classes and methods available, then detail the view
-selection principle which makes `CubicWeb` web interface very flexible.
-
-A `View` is an object applied to another object such as an entity.
-
-Basic class for views
----------------------
-
-Class `View` (`cubicweb.common.view`)
-`````````````````````````````````````
-
-This class is an abstraction of a view class, used as a base class for every
-renderable object such as views, templates, graphic components, etc.
-
-A `View` is instantiated to render a result set or part of a result set. `View`
-subclasses may be parametrized using the following class attributes:
-
- * `templatable` indicates if the view may be embeded in a main
- template or if it has to be rendered standalone (i.e. XML views
- must not be embeded in the main template for HTML pages)
- * if the view is not templatable, it should set the `content_type` class
- attribute to the correct MIME type (text/xhtml by default)
- * the `category` attribute may be used in the interface to regroup related
- objects together
-
-At instantiation time, the standard `req`, `rset`, and `cursor`
-attributes are added and the `w` attribute will be set at rendering
-time.
-
-A view writes to its output stream thanks to its attribute `w` (`UStreamIO`).
-
-The basic interface for views is as follows (remember that the result set has a
-tabular structure with rows and columns, hence cells):
-
-* `dispatch(**context)`, render the view by calling `call` or
- `cell_call` depending on the given parameters
-* `call(**kwargs)`, call the view for a complete result set or null (default
- implementation calls `cell_call()` on each cell of the result set)
-* `cell_call(row, col, **kwargs)`, call the view for a given cell of a result set
-* `url()`, returns the URL enabling us to get the view with the current
- result set
-* `view(__vid, rset, __fallback_vid=None, **kwargs)`, call the view of identifier
- `__vid` on the given result set. It is possible to give a view identifier
- of fallback that will be used if the view requested is not applicable to the
- result set
-
-* `wview(__vid, rset, __fallback_vid=None, **kwargs)`, similar to `view` except
- the flow is automatically passed in the parameters
-
-* `html_headers()`, returns a list of HTML headers to set by the main template
-
-* `page_title()`, returns the title to use in the HTML header `title`
-
-
-Other basic view classes
-````````````````````````
-Here are some of the subclasses of `View` defined in `cubicweb.common.view`
-that are more concrete as they relate to data rendering within the application:
-
-* `EntityView`, view applying to lines or cell containing an entity (e.g. an eid)
-* `StartupView`, start view that does not require a result set to apply to
-* `AnyRsetView`, view applied to any result set
-* `EmptyRsetView`, view applied to an empty result set
-
-
-The selection view principle
-----------------------------
-
-A view is essentially defined by:
-
-- an identifier (all objects in `CubicWeb` are entered in a registry
- and this identifier will be used as a key). This is defined in the class
- attribute ``id``.
-
-- a filter to select the result sets it can be applied to. This is defined in
- the class attribute ``__selectors__``, which expects a tuple of selectors
- as its value.
-
-
-For a given identifier, multiple views can be defined. `CubicWeb` uses
-a selector which computes scores to identify and select the
-best view to apply in the given context. The selectors library is in
-``cubicweb.common.selector`` and a library of the methods used to
-compute scores is in ``cubicweb.vregistry.vreq``.
-
-.. include:: B1021-views-selectors.en.txt
-
-Registerer
-``````````
-[Registerers are deprecated: they will soon disappear for explicite
-registration...]
-
-A view is also customizable through its attribute ``__registerer__``.
-This is used at the time the application is launched to manage how
-objects (views, graphic components, actions, etc.)
-are registered in the `cubicWeb` registry.
-
-A `registerer` can, for example, identify when we register an
-object that is equivalent to an already registered object, which
-could happen when we define two `primary` views for an entity type.
-
-The purpose of a `registerer` is to control object registry
-at the application startup whereas `selectors` control objects
-when they are selected for display.
-
-
-.. include:: B1022-views-stdlib.en.txt
-
-
-Examples of views class
------------------------
-
-- Using the attribute `templatable`
-
- ::
-
-
- class RssView(XmlView):
- id = 'rss'
- title = _('rss')
- templatable = False
- content_type = 'text/xml'
- http_cache_manager = MaxAgeHTTPCacheManager
- cache_max_age = 60*60*2 # stay in http cache for 2 hours by default
-
-
-
-- Using the attribute `__selectors__`
-
- ::
-
-
- class SearchForAssociationView(EntityView):
- """view called by the edition view when the user asks
- to search for something to link to the edited eid
- """
- id = 'search-associate'
- title = _('search for association')
- __selectors__ = (one_line_rset, match_search_state, accept_selector)
- accepts = ('Any',)
- search_states = ('linksearch',)
-
-
-Rendering methods and attributes for ``PrimaryView``
-----------------------------------------------------
-
-By default, `CubicWeb` provides a primary view for each new entity type
-you create. The first view you might be interested in modifying.
-
-Let's have a quick look at the EntityView ``PrimaryView`` as well as
-its rendering method::
-
- class PrimaryView(EntityView):
- """the full view of an non final entity"""
- id = 'primary'
- title = _('primary')
- show_attr_label = True
- show_rel_label = True
- skip_none = True
- skip_attrs = ('eid', 'creation_date', 'modification_date')
- skip_rels = ()
- main_related_section = True
-
- ...
-
- def cell_call(self, row, col):
- self.row = row
- self.render_entity(self.complete_entity(row, col))
-
- def render_entity(self, entity):
- """return html to display the given entity"""
- siderelations = []
- self.render_entity_title(entity)
- self.render_entity_metadata(entity)
- # entity's attributes and relations, excluding meta data
- # if the entity isn't meta itself
- self.w(u'<div>')
- self.w(u'<div class="mainInfo">')
- self.render_entity_attributes(entity, siderelations)
- self.w(u'</div>')
- self.content_navigation_components('navcontenttop')
- if self.main_related_section:
- self.render_entity_relations(entity, siderelations)
- self.w(u'</div>')
- # side boxes
- self.w(u'<div class="primaryRight">')
- self.render_side_related(entity, siderelations)
- self.w(u'</div>')
- self.w(u'<div class="clear"></div>')
- self.content_navigation_components('navcontentbottom')
-
- ...
-
-``cell_call`` is executed for each entity of a result set and apply ``render_entity``.
-
-The methods you want to modify while customizing a ``PrimaryView`` are:
-
-*render_entity_title(self, entity)*
- Renders the entity title based on the assumption that the method
- ``def content_title(self)`` is implemented for the given entity type.
-
-*render_entity_metadata(self, entity)*
- Renders the entity metadata based on the assumption that the method
- ``def summary(self)`` is implemented for the given entity type.
-
-*render_entity_attributes(self, entity, siderelations)*
- Renders all the attribute of an entity with the exception of attribute
- of type `Password` and `Bytes`.
-
-*content_navigation_components(self, context)*
- This method is applicable only for entity type implementing the interface
- `IPrevNext`. This interface is for entities which can be linked to a previous
- and/or next entity. This methods will render the navigation links between
- entities of this type, either at the top or at the bottom of the page
- given the context (navcontent{top|bottom}).
-
-*render_entity_relations(self, entity, siderelations)*
- Renders all the relations of the entity in the main section of the page.
-
-*render_side_related(self, entity, siderelations)*
- Renders all the relations of the entity in a side box. This is equivalent
- to *render_entity_relations* in addition to render the relations
- in a box.
-
-Also, please note that by setting the following attributes in you class,
-you can already customize some of the rendering:
-
-*show_attr_label*
- Renders the attribute label next to the attribute value if set to True.
- Otherwise, does only display the attribute value.
-
-*show_rel_label*
- Renders the relation label next to the relation value if set to True.
- Otherwise, does only display the relation value.
-
-*skip_none*
- Does not render an attribute value that is None if set to True.
-
-*skip_attrs*
- Given a list of attributes name, does not render the value of the attributes listed.
-
-*skip_rels*
- Given a list of relations name, does not render the relations listed.
-
-*main_related_section*
- Renders the relations of the entity if set to True.
-
-A good practice is for you to identify the content of your entity type for which
-the default rendering does not answer your need so that you can focus on the specific
-method (from the list above) that needs to be modified. We do not recommand you to
-overwrite ``render_entity`` as you might potentially loose the benefits of the side
-boxes handling.
-
-Example of a view customization
--------------------------------
-
-[FIXME] XXX Example needs to be rewritten as it shows how to modify cell_call which
-contredicts our advise of not modifying it.
-
-We'll show you now an example of a ``primary`` view and how to customize it.
-
-If you want to change the way a ``BlogEntry`` is displayed, just override
-the method ``cell_call()`` of the view ``primary`` in ``BlogDemo/views.py`` ::
-
- 01. from cubicweb.web.views import baseviews
- 02.
- 03. class BlogEntryPrimaryView(baseviews.PrimaryView):
- 04.
- 05. accepts = ('BlogEntry',)
- 06.
- 07. def cell_call(self, row, col):
- 08. entity = self.entity(row, col)
- 09. self.w(u'<h1>%s</h1>' % entity.title)
- 10. self.w(u'<p>published on %s in category %s</p>' % \
- 11. (entity.publish_date.strftime('%Y-%m-%d'), entity.category))
- 12. self.w(u'<p>%s</p>' % entity.text)
-
-The above source code defines a new primary view (`line 03`) for
-``BlogEntry`` (`line 05`).
-
-Since views are applied to result sets which can be tables of
-data, we have to recover the entity from its (row,col)-coordinates (`line 08`).
-We will get to this in more detail later.
-
-The view method ``self.w()`` is used to output data. Here `lines
-09-12` output HTML tags and values of the entity's attributes.
-
-When displaying the same blog entry as before, you will notice that the
-page is now looking much nicer. [FIXME: it is not clear to what this refers.]
-
-.. image:: images/lax-book.09-new-view-blogentry.en.png
- :alt: blog entries now look much nicer
-
-Let us now improve the primary view of a blog ::
-
- 01. class BlogPrimaryView(baseviews.PrimaryView):
- 02.
- 03. accepts = ('Blog',)
- 04.
- 05. def cell_call(self, row, col):
- 06. entity = self.entity(row, col)
- 07. self.w(u'<h1>%s</h1>' % entity.title)
- 08. self.w(u'<p>%s</p>' % entity.description)
- 09. rset = self.req.execute('Any E WHERE E entry_of B, B eid "%s"' % entity.eid)
- 10. self.wview('primary', rset)
-
-In the above source code, `lines 01-08` are similar to the previous
-view we defined. [FIXME: defined where ?]
-
-At `line 09`, a simple request is made to build a result set with all
-the entities linked to the current ``Blog`` entity by the relationship
-``entry_of``. The part of the framework handling the request knows
-about the schema and infer that such entities have to be of the
-``BlogEntry`` kind and retrieves them.
-
-The request returns a selection of data called a result set. At
-`line 10` the view 'primary' is applied to this result set to output
-HTML.
-
-**This is to be compared to interfaces and protocols in object-oriented
-languages. Applying a given view called 'a_view' to all the entities
-of a result set only requires to have for each entity of this result set,
-an available view called 'a_view' which accepts the entity.**
-
-Assuming we added entries to the blog titled `MyLife`, displaying it
-now allows to read its description and all its entries.
-
-.. image:: images/lax-book.10-blog-with-two-entries.en.png
- :alt: a blog and all its entries
-
-**Before we move forward, remember that the selection/view principle is
-at the core of `CubicWeb`. Everywhere in the engine, data is requested
-using the RQL language, then HTML/XML/text/PNG is output by applying a
-view to the result set returned by the query. That is where most of the
-flexibility comes from.**
-
-[WRITE ME]
-
-* implementing interfaces, calendar for blog entries
-* show that a calendar view can export data to ical
-
-We will implement the `cubicweb.interfaces.ICalendarable` interfaces on
-entities.BlogEntry and apply the OneMonthCalendar and iCalendar views
-to result sets like "Any E WHERE E is BlogEntry"
-
-* create view "blogentry table" with title, publish_date, category
-
-We will show that by default the view that displays
-"Any E,D,C WHERE E publish_date D, E category C" is the table view.
-Of course, the same can be obtained by calling
-self.wview('table',rset)
-
-* in view blog, select blogentries and apply view "blogentry table"
-* demo ajax by filtering blogentry table on category
-
-we did the same with 'primary', but with tables we can turn on filters
-and show that ajax comes for free.
-[FILLME]
-
-
-Templates
----------
-
-*Templates* are specific views that do not depend on a result set. The basic
-class `Template` (`cubicweb.common.view`) is derived from the class `View`.
-
-To build a HTML page, a *main template* is used. In general, the template of
-identifier `main` is the one to use (it is not used in case an error is raised or for
-the login form for example). This template uses other templates in addition
-to the views which depends on the content to generate the HTML page to return.
-
-A *template* is responsible for:
-
-1. executing RQL query of data to render if necessary
-2. identifying the view to use to render data if it is not specified
-3. composing the HTML page to return
-
-You will find out more about templates in :ref:`templates`.
-
-XML views, binaries...
-----------------------
-For views generating other formats than HTML (an image generated dynamically
-for example), and which can not simply be included in the HTML page generated
-by the main template (see above), you have to:
-
-* set the attribute `templatable` of the class to `False`
-* set, through the attribute `content_type` of the class, the MIME type generated
- by the view to `application/octet-stream`
-
-For views dedicated to binary content creation (like dynamically generated
-images), we have to set the attribute `binary` of the class to `True` (which
-implies that `templatable == False`, so that the attribute `w` of the view could be
-replaced by a binary flow instead of unicode).
-
-(X)HTML tricks to apply
------------------------
-
-Some web browser (Firefox for example) are not happy with empty `<div>`
-(by empty we mean that there is no content in the tag, but there
-could be attributes), so we should always use `<div></div>` even if
-it is empty and not use `<div/>`.
-
--- a/doc/book/en/B1021-views-selectors.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,56 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Selectors
-`````````
-
-Selectors are scoring functions that are called by the view
-dispatcher to tell whenever a view can be applied to a given result
-set of a request. Selector sets are the glue that tie views to the data
-model. Using them appropriately is an essential part of the
-construction of well behaved cubes.
-
-When no score is higher than the others, an exception is raised
-``NoSelectableObject`` to let you know that the engine was not able to
-identify the view to apply. In such case you would need to review your
-design and make sure your views are properly defined.
-
-`CubicWeb` provides its own set of selectors that you can use and here
-is a description of some of the most common used:
-
-*yes*
- This selector accepts everything which basically means to any result
- set.
-
-*none_rset*
- This selector accepts no result set, so it can be applied to any
- object.
-
-*rset*
- This selector accepts any result set, whatever the number of objects
- in the result set.
-
-*nonempty_rset*
- This selector accepts any non empty result set.
-
-*empty_rset*
- This selector accepts empty (only) result set.
-
-*one_line_rset*
- This selector accepts result set with a single line of result.
-
-*two_lines_rset*
- This selector accepts result set with *at least* two lines of result.
-
-*two_cols_rset*
- This selector accepts result set with *at least* one line and two columns of result.
-
-*anonymous_user*
- This selector accepts if user is anonymous.
-
-*authenticated_user*
- This selector accepts if user is authenticated.
-
-
-Of course you will write your own set of selectors as you get familiar with the
-framework.
-
--- a/doc/book/en/B1022-views-stdlib.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,93 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Predefined views in the library
-```````````````````````````````
-
-`CubicWeb` provides a lot of standard views. You can find them in
-``cubicweb/web/views/``.
-
-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
- non final entity is in the result set and needs to be displayed.
- This view is supposed to render a maximum of informations about the entity.
-
-*text*
- This is the simplest text view for an entity. It displays the
- title of an entity. It should not contain HTML.
-
-*oneline*
- This is a hyper linked *text* view. 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.
-
-*secondary*
- This is a combinaison of an icon and a *oneline* view.
- By default it renders the two first attributes of the entity as a
- clickable link redirecting to the primary view.
-
-*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 when 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*
- This view displays a list of entities by creating a HTML list (`<ul>`)
- and call the view `listitem` for each entity of the result set.
-
-*listitem*
- This view 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 dublin core
- methods of the entity (`dc_*`)
-
-*sidebox*
- This view displays usually a side box of some related entities
- in a primary view.
-
-
-Start view (e.g. views that don't apply to a result set):
-
-*index*
- This view defines the home page of your application. It does not require
- a result set to apply to.
-
-*schema*
- A view dedicated to the display of the schema of the application
-
-Special views:
-
-*noresult*
- This view is the default view used when no result has been found
- (e.g. empty result set).
-
-*final*
- 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 (`<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*
- This view is the default view used when nothing needs to be rendered.
- It is always applicable and it does not return anything
--- a/doc/book/en/B1030-form-management.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,137 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Forms handling
-==============
-
-Automatically generated forms management for handled entities
--------------------------------------------------------------
-
-XXX FILLME
-
-* forms ``edition`` and ``creation``
-
-The form generated by default does not fit your needs? You are not
-required to re-do all by hands! :)
-
-* rtags primary, secondary, generated, generic,
- `Entity.relation_category(rtype, x='subject')`
-* inline_view (now a rtag?)
-* widget specification
-
-Editing controller behavior by default (id: `edit`)
----------------------------------------------------
-
-Editing control
-```````````````
-
-Re-requisites: the parameters related to entities to edit are
-specified as follows ::
-
- <field name>:<entity eid>
-
-where entity eid could be a letter in case of an entity to create. We
-name those parameters as *qualified*.
-
-1. Retrieval of entities to edit by looking for the forms parameters
- starting by `eid:` and also having a parameter `__type` associated
- (also *qualified* by eid)
-
-2. For all the attributes and the relations of an entity to edit:
-
- 1. search for a parameter `edits-<relation name>` or `edito-<relation name>`
- qualified in the case of a relation where the entity is object
- 2. if found, the value returned is considered as the initial value
- for this relaiton and we then look for the new value(s) in the parameter
- <relation name> (qualified)
- 3. if the value returned is different from the initial value, an database update
- request is done
-
-3. For each entity to edit:
-
- 1. if a qualified parameter `__linkto` is specified, its value has to be
- a string (or a list of string) such as: ::
-
- <relation type>:<eids>:<target>
-
- where <target> is either `subject` or `object` and each eid could be
- separated from the others by a `_`. Target specifies if the *edited entity*
- is subject or object of the relation and each relation specified will
- be inserted.
-
- 2. if a qualified parameter `__clone_eid` is specified for an entity, the
- relations of the specified entity passed as value of this parameter are
- copied on the edited entity.
-
- 3. if a qualified parameter `__delete` is specified, its value must be
- a string or a list of string such as follows: ::
-
- <ssubjects eids>:<relation type>:<objects eids>
-
- where each eid subject or object can be seperated from the other
- by `_`. Each relation specified will be deleted.
-
- 4. if a qualified parameter `__insert` is specified, its value should
- follow the same pattern as `__delete`, but each relation specified is
- inserted.
-
-4. If the parameters `__insert` and/or `__delete` are found not qualified,
- they are interpreted as explained above (independantly from the number
- of entities edited).
-
-5. If no entity is edited but the form contains the parameters `__linkto`
- and `eid`, this one is interpreted by using the value specified for `eid`
- to designate the entity on which to add the relations.
-
-
-.. note::
-
- * If the parameter `__action_delete` is found, all the entities specified
- as to be edited will be deleted.
-
- * If the parameter`__action_cancel` is found, no action is completed.
-
- * If the parameter `__action_apply` is found, the editing is applied
- normally but the redirection is done on the form
- (see :ref:`RedirectionControl`).
-
- * The parameter `__method` is also supported as for the main template
- (XXX not very consistent, maybe __method should be dealed in the view
- controller).
-
- * If no entity is found to be edited and if there is no parameter
- `__action_delete`, `__action_cancel`, `__linkto`, `__delete` or
- `__insert`, an error is raised.
-
- * Using the parameter `__message` in the form will allow to use its value
- as a message to provide the user once the editing is completed.
-
-
-.. _RedirectionControl:
-
-Redirection control
-```````````````````
-Once editing is completed, there is still an issue left: where should we go
-now? If nothing is specified, the controller will do his job but it does not
-mean we will be happy with the result. We can control that by using the
-following parameters:
-
-* `__redirectpath`: path of the URL (relative to the root URL of the site,
- no form parameters
-
-* `__redirectparams`: forms parameters to add to the path
-
-* `__redirectrql`: redirection RQL request
-
-* `__redirectvid`: redirection view identifier
-
-* `__errorurl`: initial form URL, used for redirecting in case a validation
- error is raised during editing. If this one is not specified, an error page
- is displayed instead of going back to the form (which is, if necessary,
- responsible for displaying the errors)
-
-* `__form_id`: initial view form identifier, used if `__action_apply` is
- found
-
-In general we use either `__redirectpath` and `__redirectparams` or
-`__redirectrql` and `__redirectvid`.
-
--- a/doc/book/en/B1040-actions.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,9 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Actions
-=========
-
-[WRITE ME]
-
-* talk about actions that appear in the action box
-
--- a/doc/book/en/B1050-boxes.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,9 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Boxes
-=========
-
-[WRITE ME]
-
-* boxes in the web interface
-
--- a/doc/book/en/B1060-templates.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,215 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-.. _templates:
-
-Templates
-=========
-
-[WRITE ME]
-
-* talk about main templates, etc.
-
-
-
-Look at ``cubicweb/web/views/basetemplates.py`` and you will
-find the base templates used to generate HTML for your application.
-
-A page is composed as indicated on the schema below :
-
-.. image:: images/lax-book.06-main-template-layout.en.png
-
-In this section we will go through a couple of the primary templates
-you must be interested in, that is to say, the HTMLPageHeader,
-the HTMLPageFooter and the TheMainTemplate.
-
-
-HTMLPageHeader
---------------
-
-Customize header
-~~~~~~~~~~~~~~~~
-
-Let's now move the search box in the header and remove the login form
-from the header. We'll show how to move it to the left column of the application.
-
-Let's say we do not want anymore the login menu to be in the header, but we
-prefer it to be in the left column just below the logo. As the left column is
-rendered by ``TheMainTemplate``, we will show how to do it in TheMainTemplate_.
-
-First, to remove the login menu, we just need to comment out the display of the
-login component such as follows : ::
-
- class MyHTMLPageHeader(HTMLPageHeader):
-
- def main_header(self, view):
- """build the top menu with authentification info and the rql box"""
- self.w(u'<table id="header"><tr>\n')
- self.w(u'<td id="firstcolumn">')
- self.vreg.select_component('logo', self.req, self.rset).dispatch(w=self.w)
- self.w(u'</td>\n')
- # appliname and breadcrumbs
- self.w(u'<td id="headtext">')
- comp = self.vreg.select_component('appliname', self.req, self.rset)
- if comp and comp.propval('visible'):
- comp.dispatch(w=self.w)
- comp = self.vreg.select_component('breadcrumbs', self.req, self.rset, view=view)
- if comp and comp.propval('visible'):
- comp.dispatch(w=self.w, view=view)
- self.w(u'</td>')
- # logged user and help
- #self.w(u'<td>\n')
- #comp = self.vreg.select_component('loggeduserlink', self.req, self.rset)
- #comp.dispatch(w=self.w)
- #self.w(u'</td><td>')
-
- self.w(u'<td>')
- helpcomp = self.vreg.select_component('help', self.req, self.rset)
- if helpcomp: # may not be available if Card is not defined in the schema
- helpcomp.dispatch(w=self.w)
- self.w(u'</td>')
- # lastcolumn
- self.w(u'<td id="lastcolumn">')
- self.w(u'</td>\n')
- self.w(u'</tr></table>\n')
- self.template('logform', rset=self.rset, id='popupLoginBox', klass='hidden',
- title=False, message=False)
-
-
-
-.. image:: images/lax-book.06-header-no-login.en.png
-
-Let's now move the search box in the top-right header area. To do so, we will
-first create a method to get the search box display and insert it in the header
-table.
-
-::
-
- from cubicweb.web.views.basetemplates import HTMLPageHeader
- class MyHTMLPageHeader(HTMLPageHeader):
- def main_header(self, view):
- """build the top menu with authentification info and the rql box"""
- self.w(u'<table id="header"><tr>\n')
- self.w(u'<td id="firstcolumn">')
- self.vreg.select_component('logo', self.req, self.rset).dispatch(w=self.w)
- self.w(u'</td>\n')
- # appliname and breadcrumbs
- self.w(u'<td id="headtext">')
- comp = self.vreg.select_component('appliname', self.req, self.rset)
- if comp and comp.propval('visible'):
- comp.dispatch(w=self.w)
- comp = self.vreg.select_component('breadcrumbs', self.req, self.rset, view=view)
- if comp and comp.propval('visible'):
- comp.dispatch(w=self.w, view=view)
- self.w(u'</td>')
-
- # logged user and help
- #self.w(u'<td>\n')
- #comp = self.vreg.select_component('loggeduserlink', self.req, self.rset)
- #comp.dispatch(w=self.w)
- #self.w(u'</td><td>')
-
- # search box
- self.w(u'<td>')
- self.get_searchbox(view, 'left')
- self.w(u'</td>')
-
- self.w(u'<td>')
- helpcomp = self.vreg.select_component('help', self.req, self.rset)
- if helpcomp: # may not be available if Card is not defined in the schema
- helpcomp.dispatch(w=self.w)
- self.w(u'</td>')
- # lastcolumn
- self.w(u'<td id="lastcolumn">')
- self.w(u'</td>\n')
- self.w(u'</tr></table>\n')
- self.template('logform', rset=self.rset, id='popupLoginBox', klass='hidden',
- title=False, message=False)
-
- def get_searchbox(self, view, context):
- boxes = list(self.vreg.possible_vobjects('boxes', self.req, self.rset,
- view=view, context=context))
- if boxes:
- for box in boxes:
- if box.id == 'search_box':
- box.dispatch(w=self.w, view=view)
-
-
-
-
-HTMLPageFooter
---------------
-
-If you want to change the footer for example, look
-for HTMLPageFooter and override it in your views file as in :
-::
-
- form cubicweb.web.views.basetemplates import HTMLPageFooter
- class MyHTMLPageFooter(HTMLPageFooter):
- def call(self, **kwargs):
- self.w(u'<div class="footer">')
- self.w(u'This website has been created with <a href="http://cubicweb.org">CubicWeb</a>.')
- self.w(u'</div>')
-
-Updating a view does not require any restart of the server. By reloading
-the page you can see your new page footer.
-
-
-TheMainTemplate
----------------
-.. _TheMainTemplate:
-
-TheMainTemplate is responsible for the general layout of the entire application.
-It defines the template of ``id = main`` that is used by the application.
-
-The default main template (`cubicweb.web.views.basetemplates.TheMainTemplate`)
-builds the page based on the following pattern:
-
-.. image:: images/main_template_layout.png
-
-The rectangle containing `view.dispatch()` represents the area where the content
-view has to be displayed. The others represents sub-templates called to complete
-the page. A default implementation of those is provided in
-`cubicweb.views.basetemplates`. You can, of course, overload those sub-templates
-to implement your own customization of the HTML page.
-
-We can also control certain aspects of the main template thanks to the following
-forms parameters:
-
-* `__notemplate`, if present (whatever the value assigned), only the content view
- is returned
-* `__force_display`, if present and its value is not null, no navigation
- whatever the number of entities to display
-* `__method`, if the result set to render contains only one entity and this
- parameter is set, it refers to a method to call on the entity by passing it
- the dictionary of the forms parameters, before going the classic way (through
- step 1 and 2 described juste above)
-
-The MainTemplate is a bit complex as it tries to accomodate many
-different cases. We are now about to go through it and cutomize entirely
-our application.
-
-
-CSS changes
------------
-
-We cannot modify the order in which the application is reading the CSS. In
-the case we want to create new CSS style, the best is to define it a in a new
-CSS located under ``myapp/data/``.
-
-
-.. [TRANSLATE ME FROM FRENCH]
-.. 03-XX-external_resources.fr.txt
-
-[TODO]
-Add login menu in left column
-
-
-[WRITE ME]
-
-* customize MainTemplate and show that everything in the user
- interface can be changed
-
-[TODO]
-Rajouter une section pour definir la terminologie utilisee.
-Dans cubicweb-doc rajouter une section pour cubciweb-ctl shell ou
-on liste les commandes dispos.
--- a/doc/book/en/B1070-ui-components.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,14 +0,0 @@
-Others web interface components
-===============================
-
-Actions
--------
-XXXFILLME
-
-Component, VComponent
----------------------
-XXXFILLME
-
-CWProperty
----------
-XXXFILLME
--- a/doc/book/en/B1080-ajax-json.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,16 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-AJAX
-====
-JSON bla bla
-XXX FILLME
-
-
-Le contrôleur 'json'
---------------------
-XXX FILLME
-
-
-API Javascript
---------------
-XXX FILLME
--- a/doc/book/en/B1090-internationalization.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,100 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-.. _internationalisation:
-
-
-Internationalisation
-====================
-
-Cubicweb fully supports the internalization of it's content and interface.
-
-Cubicweb's interface internationalization is based on the translation project `GNU gettext`_.
-
-.. _`GNU gettext`: http://www.gnu.org/software/gettext/
-
-Cubicweb' internalization involves two steps:
-
-* in your Python code and cubicweb-tal templates : mark translatable strings
-
-* in your application : handle the translation catalog
-
-String internationalization
----------------------------
-
-In the Python code and cubicweb-tal templates translatable strings can be
-marked in one of the following ways :
-
- * by using the *built-in* function `_` ::
-
- class PrimaryView(EntityView):
- """the full view of an non final entity"""
- id = 'primary'
- title = _('primary')
-
- OR
-
- * by using the equivalent request's method ::
-
- class NoResultView(EmptyRsetView):
- """default view when no result has been found"""
- id = 'noresult'
-
- def call(self, **kwargs):
- self.w(u'<div class="searchMessage"><strong>%s</strong></div>\n'
- % self.req._('No result matching query'))
-
-The goal of the *built-in* function `_` is only **to mark the
-translatable strings**, it will only return the string to translate
-it-self, but not its translation.
-
-In the other hand the request's method `self.req._` is meant to retrieve the
-proper translation of translation strings in the requested language.
-
-Translations in cubicweb-tal template can also be done with TAL tags
-`i18n:content` and `i18n:replace`.
-
-.. note::
-
- We dont need to mark the translation strings of entities/relations
- used by a particular application's schema as they are generated
- automatically.
-
-
-Handle the translation catalog
-------------------------------
-
-Once the internationalization is done in your application's code, you need
-to populate and update the translation catalog. Cubicweb provides the
-following commands for this purpose:
-
-
-* `i18nlibupdate` updates Cubicweb framework's translation
- catalogs. Unless you work on the framework development, you don't
- need to use this command.
-
-* `i18nupdate` updates the translation catalogs of *one particular
- component* (or of all components). After this command is
- executed you must update the translation files *.po* in the "i18n"
- directory of your template. This command will of course not remove
- existing translations still in use.
-
-* `i18ncompile` recompile the translation catalogs of *one particular
- instance* (or of all instances) after the translation catalogs of
- its components have been updated. This command is automatically
- called every time you create or update your instance. The compiled
- catalogs (*.mo*) are stored in the i18n/<lang>/LC_MESSAGES of
- application where `lang` is the language identifier ('en' or 'fr'
- for exemple).
-
-
-Example
-```````
-You have added and/or modified some translation strings in your application
-(after creating a new view or modifying the application's schema for exemple).
-To update the translation catalogs you need to do:
-
-1. `cubicweb-ctl i18nupdate <component>`
-2. Edit the <component>/xxx.po files and add missing translations (empty `msgstr`)
-3. `hg ci -m "updated i18n catalogs"`
-4. `cubicweb-ctl i18ncompile <myapplication>`
-
--- a/doc/book/en/B1100-online-doc.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,9 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Online documentation system
-===========================
-
-[WRITE ME]
-
-* describe the on-line documentation system
-
--- a/doc/book/en/B1110-embedding-external-page.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,9 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Embedding external pages
-========================
-
-[WRITE ME]
-
-* including external content
-
--- a/doc/book/en/B1120-urlrewrite.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,10 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-URL Rewriting
-=============
-
-
-[WRITE ME]
-
-* show how urls are mapped to selections and views and explain URLRewriting
-
--- a/doc/book/en/B1130-css.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,16 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-CSS changes
-===========
-
-XXX FIXME explain CSS used by cubciweb
-
-We cannot modify the order in which the application is reading the CSS. In
-the case we want to create new CSS style, the best is to define it a in a new
-CSS located under ``myapp/data/`` and use those new styles while writing
-customized views and templates.
-
-If you want to modify an existing CSS styling property, you will have to use
-``!important`` declaration to override the existing property. The application
-apply a higher priority on the default CSS and you can not change that.
-Customized CSS will not be read first.
--- a/doc/book/en/B2-repository-customization.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,15 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Repository customization
-++++++++++++++++++++++++
-.. toctree::
- :maxdepth: 1
-
- B2010-sessions.en.txt
- B2020-hooks.en.txt
- B2030-notifications.en.txt
- B2040-repository-operations.en.txt
- B2050-google-appengine.en.txt
- B2060-repository-tasks.en.txt
-
-
--- a/doc/book/en/B2010-sessions.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,9 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Sessions
-========
-
-[WRITE ME]
-
-* authentication and management of sessions
-
--- a/doc/book/en/B2020-hooks.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,32 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-.. _hooks:
-
-Hooks
-=====
-
-XXX FILLME
-
-*Hooks* are executed before or after updating an entity or a relation in the
-repository.
-
-Their prototypes are as follows:
-
- * after_add_entity (session, entity)
- * after_update_entity (session, entity)
- * after_delete_entity (session, eid)
- * before_add_entity (session, entity)
- * before_update_entity (session, entity)
- * before_delete_entity (session, eid)
-
- * after_add_relation (session, fromeid, rtype, toeid)
- * after_delete_relation (session, fromeid, rtype, toeid)
- * before_add_relation (session, fromeid, rtype, toeid)
- * before_delete_relation (session, fromeid, rtype, toeid)
-
- * server_startup
- * server_shutdown
-
- * session_open
- * session_close
-
--- a/doc/book/en/B2030-notifications.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,6 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Notifications management
-========================
-
-XXX FILLME
--- a/doc/book/en/B2040-repository-operations.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,9 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Repository operations
-======================
-
-[WRITE ME]
-
-* repository operations
-
--- a/doc/book/en/B2050-google-appengine.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,11 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-.. _gaecontents:
-
-==========================
-Google AppEngine Datastore
-==========================
-
-
-.. include:: B2051-intro.en.txt
-.. include:: B2052-install.en.txt
--- a/doc/book/en/B2051-intro.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /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`.
-
--- a/doc/book/en/B2052-install.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,219 +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
-
-
-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 <myapp>
-
-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
-`CubicWeb` 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 <myapp>``, 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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-`CubicWeb` 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
-'cubicweb'". 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 cubicweb-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 <http://localhost:8080/_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 <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
-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 <http://localhost:8080/?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 <http://localhost:8080/?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/ <http://localhost:8080>`_
-as a normal user.
-
-Unless you did something to change it, http://MYAPP_URL should be
-http://localhost:8080/
-
-
--- a/doc/book/en/B2060-repository-tasks.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,9 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Tasks
-=========
-
-[WRITE ME]
-
-* repository tasks
-
--- a/doc/book/en/B3-test.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,9 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Tests
-+++++
-.. toctree::
- :maxdepth: 1
-
- B3010-tests.en.txt
-
--- a/doc/book/en/B3010-tests.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,38 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Tests
-=====
-
-Unit tests
-----------
-
-`CubicWeb` framework provides essentially two Python test classes in the
-module `cubicweb.devtools.apptest`:
-
-* `EnvBasedTC`, to simulate a complete environment (web + repository)
-* `RepositoryBasedTC`, to simulate a repository environment only
-
-Thos two classes almost have the same interface and offers numerous methods to
-write tests rapidely and efficiently.
-
-XXX FILLME describe API
-
-In most of the cases, you will inherit `EnvBasedTC` to write Unittest or
-functional tests for your entities, views, hooks, etc...
-
-Email notifications tests
--------------------------
-When running tests potentially generated e-mails are not really
-sent but is found in the list `MAILBOX` of module `cubicweb.devtools.apptest`.
-This list is reset at each test *setUp* (by the setUp of classes `EnvBasedTC`
-and `RepositoryBasedTC`).
-
-
-You can test your notifications by analyzing the contents of this list, which
-contains objects with two attributes:
-* `recipients`, the list of recipients
-* `msg`, object email.Message
-
-Automatic testing
------------------
-XXXFILLME
--- a/doc/book/en/B4-advanced.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,11 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Advanced
-++++++++
-.. toctree::
- :maxdepth: 1
-
- B4010-configuration.en.txt
- B4020-dbapi.en.txt
- B4030-registry.en.txt
- B4040-rss-xml.en.txt
--- a/doc/book/en/B4010-configuration.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,9 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Configuration
--------------
-
-[WRITE ME]
-
-* the config object. adding configuration option
-
--- a/doc/book/en/B4020-dbapi.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,9 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-DB-API
-=========
-
-[WRITE ME]
-
-* direct connection to the repository
-
--- a/doc/book/en/B4030-registry.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,148 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-The Registry
-------------
-
-[WRITE ME]
-
-* talk about the vreg singleton, appobjects, registration and selection
-
-
-Details of the recording process
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-At startup, the `registry` or registers base, inspects a number of directories
-looking for compatible classes definition. After a recording process, the objects
-are assigned to registers so that they can be selected dynamically while the
-application is running.
-
-The base class of those objects is `AppRsetObject` (module `cubicweb.common.appobject`).
-
-XXX registers example
-XXX actual details of the recording process!
-
-Runtime objects selection
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-XXX tell why it's a cw foundation!
-
-Application objects are stored in the registry using a two level hierarchy :
-
- object's `__registry__` : object's `id` : [list of app objects]
-
-The following rules are applied to select an object given a register and an id and an input context:
-* each object has a selector which may be built from a set of basic (or not :)
-
- selectors using `chainall` or `chainfirst` combinators
-
-* a selector return a score >= 0
-* a score of 0 means the objects can't be applied to the input context
-* the object with the greatest score is selected. If multiple objects have an
- identical score, one of them is selected randomly (this is usually a bug)
-
-The object's selector is the `__select__` class method on the object's class.
-
-The score is used to choose the most pertinent objects where there are more than
-one selectable object. For instance, if you're selecting the primary
-(eg `id = 'primary'`) view (eg `__registry__ = 'view'`) for a result set containing
-a `Card` entity, 2 objects will probably be selectable:
-
-* the default primary view (`accepts = 'Any'`)
-* the specific `Card` primary view (`accepts = 'Card'`)
-
-This is because primary views are using the `accept_selector` which is considering the
-`accepts` class attribute of the object's class. Other primary views specific to other
-entity types won't be selectable in this case. And among selectable objects, the
-accept selector will return a higher score the the second view since it's more
-specific, so it will be selected as expected.
-
-Usually, you won't define it directly but by defining the `__selectors__` tuple
-on the class, with ::
-
- __selectors__ = (sel1, sel2)
-
-which is equivalent to ::
-
- __select__ = classmethod(chainall(sel1, sel2))
-
-The former is prefered since it's shorter and it's ease overriding in
-subclasses (you have access to sub-selectors instead of the wrapping function).
-
-:chainall(selectors...): if one selector return 0, return 0, else return the sum of scores
-
-:chainfirst(selectors...): return the score of the first selector which has a non zero score
-
-XXX describe standard selector (link to generated api doc!)
-
-Example
-````````
-
-Le but final : quand on est sur un Blog, on veut que le lien rss de celui-ci pointe
-vers les entrées de ce blog, non vers l'entité blog elle-même.
-
-L'idée générale pour résoudre ça : on définit une méthode sur les classes d'entité
-qui renvoie l'url du flux rss pour l'entité en question. Avec une implémentation
-par défaut sur AnyEntity et une implémentation particulière sur Blog qui fera ce
-qu'on veut.
-
-La limitation : on est embêté dans le cas ou par ex. on a un result set qui contient
-plusieurs entités Blog (ou autre chose), car on ne sait pas sur quelle entité appeler
-la méthode sus-citée. Dans ce cas, on va conserver le comportement actuel (eg appel
-Ã limited_rql)
-
-Donc : on veut deux cas ici, l'un pour un rset qui contient une et une seule entité,
-l'autre pour un rset qui contient plusieurs entité.
-
-Donc... On a déja dans web/views/boxes.py la classe RSSIconBox qui fonctionne. Son
-sélecteur ::
-
- class RSSIconBox(ExtResourcesBoxTemplate):
- """just display the RSS icon on uniform result set"""
- __selectors__ = ExtResourcesBoxTemplate.__selectors__ + (nfentity_selector,)
-
-
-indique qu'il prend en compte :
-
-* les conditions d'apparition de la boite (faut remonter dans les classes parentes
- pour voir le détail)
-* nfentity_selector, qui filtre sur des rset contenant une liste d'entité non finale
-
-ça correspond donc à notre 2eme cas. Reste à fournir un composant plus spécifique
-pour le 1er cas ::
-
- class EntityRSSIconBox(RSSIconBox):
- """just display the RSS icon on uniform result set for a single entity"""
- __selectors__ = RSSIconBox.__selectors__ + (onelinerset_selector,)
-
-
-Ici, on ajoute onelinerset_selector, qui filtre sur des rset de taille 1. Il faut
-savoir que quand on chaine des selecteurs, le score final est la somme des scores
-renvoyés par chaque sélecteur (sauf si l'un renvoie zéro, auquel cas l'objet est
-non sélectionnable). Donc ici, sur un rset avec plusieurs entités, onelinerset_selector
-rendra la classe EntityRSSIconBox non sélectionnable, et on obtiendra bien la
-classe RSSIconBox. Pour un rset avec une entité, la classe EntityRSSIconBox aura un
-score supérieur à RSSIconBox et c'est donc bien elle qui sera sélectionnée.
-
-Voili voilou, il reste donc pour finir tout ça :
-
-* à définir le contenu de la méthode call de EntityRSSIconBox
-* fournir l'implémentation par défaut de la méthode renvoyant l'url du flux rss sur
- AnyEntity
-* surcharger cette methode dans blog.Blog
-
-
-When to use selectors?
-```````````````````````
-
-Il faut utiliser les sélecteurs pour faire des choses différentes en
-fonction de ce qu'on a en entrée. Dès qu'on a un "if" qui teste la
-nature de `self.rset` dans un objet, il faut très sérieusement se
-poser la question s'il ne vaut pas mieux avoir deux objets différent
-avec des sélecteurs approprié.
-
-If this is so fundamental, why don't I see them more often?
-```````````````````````````````````````````````````````````
-
-Because you're usually using base classes which are hiding the plumbing
-of __registry__ (almost always), id (often when using "standard" object),
-register and selector.
--- a/doc/book/en/C000-administration.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,20 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-.. _Part3:
-
-==========================
-Part III - Administration
-==========================
-
-This part is for installation and administration of the `CubicWeb` framework and
-applications based on that framework.
-
-.. toctree::
- :maxdepth: 1
-
- C010-setup.en.txt
- C020-create-instance.en.txt
- C030-site-config.en.txt
- C040-instance-config.en.txt
- C050-rql.en.txt
-
--- a/doc/book/en/C010-setup.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,207 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-.. _SetUpEnv:
-
-===================================================
-Installation and set-up of a `CubicWeb` environment
-===================================================
-
-Installation of `Cubicweb` and its dependencies
------------------------------------------------
-
-`CubicWeb` is packaged for Debian and Ubuntu, but can be installed from source
-using a tarball or the Mercurial version control system.
-
-.. _DebianInstallation:
-
-Debian and Ubuntu packages
-```````````````````````````
-
-Depending on the distribution you are using, add the appropriate line to your list
-of sources (for example by editing ``/etc/apt/sources.list``).
-
-For Debian Lenny::
-
- deb http://ftp.logilab.org/dists/ lenny/
-
-For Debian Sid::
-
- deb http://ftp.logilab.org/dists/ sid/
-
-For Ubuntu Hardy::
-
- deb http://ftp.logilab.org/dists/ hardy/
-
-
-You can now install the required packages with the following command::
-
- apt-get update
- apt-get install cubicweb cubicweb-dev
-
-`cubicweb` installs the framework itself, allowing you to create
-new applications.
-
-`cubicweb-dev` installs the development environment allowing you to
-develop new cubes.
-
-There is also a wide variety of cubes listed on http://www.cubicweb.org/Project available as debian packages and tarball.
-
-
-Install from source
-```````````````````
-
-You can download the archive containing the sources from our `ftp site`_ at::
-
- http://ftp.logilab.org/pub/cubicweb/
-
-.. _`ftp site`: http://ftp.logilab.org/pub/cubicweb/
-
-or keep up to date with on-going development by using Mercurial and its forest
-extension::
-
- hg fclone http://www.logilab.org/hg/forests/cubicweb
-
-See :ref:`MercurialPresentation` for more details about Mercurial.
-
-Postgres installation
-`````````````````````
-
-Please refer to the `Postgresql project online documentation`_.
-
-.. _`Postgresql project online documentation`: http://www.postgresql.org/
-
-You need to install the three following packages: `postgres-8.3`,
-`postgres-contrib-8.3` and `postgresql-plpython-8.3`.
-
-
-Then you can install:
-
-* `pyro` if you wish the repository to be accessible through Pyro
- or if the client and the server are not running on the same machine
- (in which case the packages will have to be installed on both
- machines)
-
-* `python-ldap` if you plan to use a LDAP source on the server
-
-.. _ConfigurationEnv:
-
-Environment configuration
--------------------------
-
-If you installed `CubicWeb` by cloning the Mercurial forest, then you
-will need to update the environment variable PYTHONPATH by adding
-the path to the forest ``cubicweb``:
-
-Add the following lines to either `.bashrc` or `.bash_profile` to configure
-your development environment ::
-
- export PYTHONPATH=/full/path/to/cubicweb-forest
-
-If you installed the debian packages, no configuration is required.
-Your new cubes will be placed in `/usr/share/cubicweb/cubes` and
-your applications will be placed in `/etc/cubicweb.d`.
-
-To use others directories then you will have to configure the
-following environment variables as follows::
-
- export CW_CUBES_PATH=~/lib/cubes
- export CW_REGISTRY=~/etc/cubicweb.d/
- export CW_INSTANCE_DATA=$CW_REGISTRY
- export CW_RUNTIME=/tmp
-
-.. note::
- The values given above are our suggestions but of course
- can be different.
-
-
-Databases configuration
------------------------
-
-
-
-.. _ConfigurationPostgres:
-
-Postgres configuration
-``````````````````````
-
-.. note::
- If you already have an existing cluster and postgres server
- running, you do not need to execute the initilization step
- of your Postgres database.
-
-* First, initialize the database Postgres with the command ``initdb``.
- ::
-
- $ initdb -D /path/to/pgsql
-
- Once initialized, start the database server Postgres
- with the command::
-
- $ postgres -D /path/to/psql
-
- If you cannot execute this command due to permission issues, please
- make sure that your username has write access on the database.
- ::
-
- $ chown username /path/to/pgsql
-
-* The database authentication can be either set to `ident sameuser`
- or `md5`.
- If set to `md5`, make sure to use an existing user
- of your database.
- If set to `ident sameuser`, make sure that your
- client's operating system user name has a matching user in
- the database. If not, please do as follow to create a user::
-
- $ su
- $ su - postgres
- $ createuser -s -P username
-
- The option `-P` (for password prompt), will encrypt the password with
- the method set in the configuration file ``pg_hba.conf``.
- If you do not use this option `-P`, then the default value will be null
- and you will need to set it with::
-
- $ su postgres -c "echo ALTER USER username WITH PASSWORD 'userpasswd' | psql"
-
- This login/password will be requested when you will create an
- instance with `cubicweb-ctl create` to initialize the database of
- your application.
-
-.. note::
- The authentication method can be configured in ``pg_hba.conf``.
-
-
-.. FIXME Are these steps really necessary? It seemed to work without.
-
-* Installation of plain-text index extension ::
-
- cat /usr/share/postgresql/8.3/contrib/tsearch2.sql | psql -U username template1
-
-* Installation of plpythonu language by default ::
-
- createlang -U pgadmin plpythonu template1
-
-MySql configuration
-```````````````````
-Yout must add the following lines in /etc/mysql/my.cnf file::
-
- transaction-isolation = READ-COMMITTED
- default-storage-engine=INNODB
- default-character-set=utf8
- max_allowed_packet = 128M
-
-Pyro configuration
-------------------
-
-If you use Pyro, it is required to have a name server Pyro running on your
-network (by default it is detected by a broadcast request).
-
-To do so, you need to :
-
-* launch the server manually before starting cubicweb as a server with
- `pyro-nsd start`
-
-* edit the file ``/etc/default/pyro-nsd`` so that the name server pyro
- will be launched automatically when the machine fire up
-
--- a/doc/book/en/C020-create-instance.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,132 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Creation of your first instance
-===============================
-
-What is an instance?
---------------------
-
-A `CubicWeb` instance is a directory in ``~/etc/cubicweb.d``
-which enables us to run a web application. An instance is based on
-a cube.
-
-An instance is a container that refers to cubes and configuration
-parameters for your web application.
-
-We recommand not to define schema, entities or views in the instance
-file system itself but in the cube, in order to maintain re-usability of
-entities and their views. We strongly recommand to develop cubes which
-could be used in other instances (modular approach).
-
-
-What is a cube?
----------------
-
-A 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.
-
-When an instance is created, you list one or more cubes that your instance
-will 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.
-
-.. note::
- The commands used below are more detailled in the section dedicated to
- :ref:`cubicweb-ctl`.
-
-
-Create a cube
--------------
-
-Let's start by creating the cube environment in which we will develop ::
-
- cd ~/hg
-
- cubicweb-ctl newcube mycube
-
- # answer questions
- hg init moncube
- cd mycube
- hg add .
- hg ci
-
-If all went well, you should see the cube you just create in the list
-returned by `cubicweb-ctl list` in the section *Available components*,
-and if it is not the case please refer to :ref:`ConfigurationEnv`.
-
-To use a cube, you have to list it in the variable ``__use__``
-of the file ``__pkginfo__.py`` of the instance.
-This variable is used for the instance packaging (dependencies
-handled by system utility tools such as APT) and the usable cubes
-at the time the base is created (import_erschema('MyCube') will
-not properly work otherwise).
-
-.. note::
- Please note that if you do not wish to use default directory
- for your cubes library, then you want to use the option
- --directory to specify where you would like to place
- the source code of your cube:
- ``cubicweb-ctl newcube --directory=/path/to/cubes/library cube_name``
-
-Instance creation
------------------
-
-Now that we created our cube, we can create an instance to view our
-application in a web browser. To do so we will use a `all-in-on`
-configuration to simplify things ::
-
- cubicweb-ctl create -c all-in-one mycube myinstance
-
-.. note::
- Please note that we created a new cube for a demo purpose but
- you could have use an existing cube available in our standard library
- such as blog or person for example.
-
-A serie of questions will be prompted to you, the default answer is usually
-sufficient. You can anyway modify the configuration later on 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:`ConfigurationPostgres`).
-
-It is important to distinguish here the user used to access the database and
-the user used to login to the cubicweb application. When a `CubicWeb` application
-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 application user you will
-use during the development to administrate your web application. It will be
-possible, later on, to create others users for your final web application.
-
-When this command is completed, the definition of your instance is
-located in *~/etc/cubicweb.d/myinstance/*. To launch it, you just type ::
-
- cubicweb-ctl start -D myinstance
-
-The option `-D` specify the *debug mode* : the instance is not running in
-server mode and does not disconnect from the termnial, which simplifies debugging
-in case the instance is not properly launched. You can see how it looks by
-visiting the URL `http://localhost:8080` (the port number depends of your
-configuration). To login, please use the cubicweb administrator login/psswd you
-defined when you created the instance.
-
-To shutdown the instance, Crtl-C in the terminal window is enough.
-If you did not use the option `-D`, then type ::
-
- cubicweb-ctl stop myinstance
-
-This is it! All is settled down to start developping your data model...
-
-
-Usage of `cubicweb-liveserver`
-``````````````````````````````
-
-To quickly test a new cube, you can also use the script `cubicweb-liveserver`
-which allows to create an application in memory (use of SQLite database by
-default) and make it accessible through a web server ::
-
- cubicweb-ctl live-server mycube
-
-or by using an existing database (SQLite or Postgres)::
-
- cubicweb-ctl live-server -s myfile_sources mycube
-
--- a/doc/book/en/C030-site-config.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,94 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-User interface for web site configuration
-=========================================
-
-.. image:: images/lax-book.03-site-config-panel.en.png
-
-This panel allows you to configure the appearance of your application site.
-Six menus are available and we will go through each of them to explain how
-to use them.
-
-Navigation
-~~~~~~~~~~
-This menu provides you a way to adjust some navigation options depending on
-your needs, such as the number of entities to display by page of results.
-Follows the detailled list of available options :
-
-* navigation.combobox-limit : maximum number of entities to display in related
- combo box (sample format: 23)
-* navigation.page-size : maximum number of objects displayed by page of results
- (sample format: 23)
-* navigation.related-limit : maximum number of related entities to display in
- the primary view (sample format: 23)
-* navigation.short-line-size : maximum number of characters in short description
- (sample format: 23)
-
-UI
-~~
-This menu provides you a way to customize the user interface settings such as
-date format or encoding in the produced html.
-Follows the detailled list of available options :
-
-* ui.date-format : how to format date in the ui ("man strftime" for format description)
-* ui.datetime-format : how to format date and time in the ui ("man strftime" for format
- description)
-* ui.default-text-format : default text format for rich text fields.
-* ui.encoding : user interface encoding
-* ui.fckeditor :should html fields being edited using fckeditor (a HTML WYSIWYG editor).
- You should also select text/html as default text format to actually get fckeditor.
-* ui.float-format : how to format float numbers in the ui
-* ui.language : language of the user interface
-* ui.main-template : id of main template used to render pages
-* ui.site-title : site title, which is displayed right next to the logo in the header
-* ui.time-format : how to format time in the ui ("man strftime" for format description)
-
-
-Actions
-~~~~~~~
-This menu provides a way to configure the context in which you expect the actions
-to be displayed to the user and if you want the action to be visible or not.
-You must have notice that when you view a list of entities, an action box is
-available on the left column which display some actions as well as a drop-down
-menu for more actions.
-
-The context available are :
-
-* mainactions : actions listed in the left box
-* moreactions : actions listed in the `more` menu of the left box
-* addrelated : add actions listed in the left box
-* useractions : actions listed in the first section of drop-down menu
- accessible from the right corner user login link
-* siteactions : actions listed in the second section of drop-down menu
- accessible from the right corner user login link
-* hidden : select this to hide the specific action
-
-Boxes
-~~~~~
-The application has already a pre-defined set of boxes you can use right away.
-This configuration section allows you to place those boxes where you want in the
-application interface to customize it.
-
-The available boxes are :
-
-* actions box : box listing the applicable actions on the displayed data
-
-* boxes_blog_archives_box : box listing the blog archives
-
-* possible views box : box listing the possible views for the displayed data
-
-* rss box : RSS icon to get displayed data as a RSS thread
-
-* search box : search box
-
-* startup views box : box listing the configuration options available for
- the application site, such as `Preferences` and `Site Configuration`
-
-Components
-~~~~~~~~~~
-[WRITE ME]
-
-Contextual components
-~~~~~~~~~~~~~~~~~~~~~
-[WRITE ME]
-
--- a/doc/book/en/C040-instance-config.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,163 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-
-Configure an instance
-=====================
-
-While creating an instance, a configuration file is generated in::
-
- $ (CW_REGISTRY) / <instance> / <configuration name>.conf
-
-For example::
-
- /etc/cubicweb.d/JPL/all-in-one.conf
-
-It is a simple text file format INI. In the following description,
-each option name is prefixed with its own section and followed by its
-default value if necessary, e.g. "`<section>.<option>` [value]."
-
-
-Configuring the Web server
---------------------------
-:`web.auth-model` [cookie]:
- authentication mode, cookie or http
-:`web.realm`:
- realm of the application in http authentication mode
-:`web.http-session-time` [0]:
- period of inactivity of an HTTP session before it closes automatically.
- Duration in seconds, 0 meaning no expiration (or more exactly at the
- closing of the browser client)
-
-:`main.anonymous-user`, `main.anonymous-password`:
- login and password to use to connect to the RQL server with
- HTTP anonymous connection. CWUser account should exist.
-
-:`main.base-url`:
- url base site to be used to generate the urls of web pages
-
-Https configuration
-```````````````````
-It is possible to make a site accessible for anonymous http connections
-and https for authenticated users. This requires to
-use apache (for example) for redirection and the variable `main.https-url`
-of configuration file.
-
-:Example:
-
- For an apache redirection of a site accessible via `http://localhost/demo`
- and `https://localhost/demo` and actually running on port 8080, it
- takes to the http:::
-
- RewriteCond %(REQUEST_URI) ^/demo
- RewriteRule ^/demo$ /demo/
- RewriteRule ^/demo/(.*) http://127.0.0.1:8080/$1 [L,P]
-
- and for the https:::
-
- RewriteCond %(REQUEST_URI) ^/ demo
- RewriteRule ^/demo$/demo/
- RewriteRule ^/demo/(.*) http://127.0.0.1:8080/https/$1 [L,P]
-
-
- and we will file in the all-in-one.conf of the instance:::
-
- base-url = http://localhost/demo
- https-url = `https://localhost/demo`
-
-Setting up the web
---------------------------------
-:`web.embed-allowed`:
- regular expression matching sites which could be "embedded" in
- the site (controllers 'embed')
-:`web.submit-url`:
- url where the bugs encountered in the application can be mailed to
-
-
-RQL server configuration
-------------------------
-:`main.host`:
- host name if it can not be detected correctly
-:`main.pid-file`:
- file where will be written the server pid
-:`main.uid`:
- user account to use for launching the server when it is
- root launched by init
-:`main.session-time [30*60]`:
- timeout of a RQL session
-:`main.query-log-file`:
- file where all requests RQL executed by the server are written
-
-
-Pyro configuration for the instance
------------------------------------
-Web server side:
-
-:`pyro-client.pyro-application-id`:
- pyro identifier of RQL server (e.g. the instance name)
-
-RQL server side:
-
-:`pyro-server.pyro-port`:
- pyro port number. If none is specified, a port is assigned
- automatically.
-
-RQL and web servers side:
-
-:`pyro-name-server.pyro-ns-host`:
- hostname hosting pyro server name. If no value is
- specified, it is located by a request from broadcast
-:`pyro-name-server.pyro-ns-group` [cubicweb]:
- pyro group in which to save the application
-
-
-Configuring e-mail
-------------------
-RQL and web server side:
-
-:`email.mangle-mails [no]`:
- indicates whether the email addresses must be displayed as is or
- transformed
-
-RQL server side:
-
-:`email.smtp-host [mail]`:
- hostname hosting the SMTP server to use for outgoing mail
-:`email.smtp-port [25]`:
- SMTP server port to use for outgoing mail
-:`email.sender-name`:
- name to use for outgoing mail of the application
-:`email.sender-addr`:
- address for outgoing mail of the application
-:`email.default dest-addrs`:
- destination addresses by default, if used by the configuration of the
- dissemination of the model (separated by commas)
-:`email.supervising-addrs`:
- destination addresses of e-mails of supervision (separated by
- commas)
-
-
-Configuring logging
--------------------
-:`main.log-threshold`:
- level of filtering messages (DEBUG, INFO, WARNING, ERROR)
-:`main.log-file`:
- file to write messages
-
-
-Configuring Eproperties
------------------------
-Other configuration settings are in the form of entities `CWProperty`
-in the database. It must be edited via the web interface or by
-RQL queries.
-
-:`ui.encoding`:
- Character encoding to use for the web
-:`navigation.short-line-size`: # XXX should be in ui
- number of characters for "short" display
-:`navigation.page-size`:
- maximum number of entities to show per results page
-:`navigation.related-limit`:
- number of related entities to show up on primary entity view
-:`navigation.combobox-limit`:
- number of entities unrelated to show up on the drop-down lists of
- the sight on an editing entity view
--- a/doc/book/en/C050-rql.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,655 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-.. _RQL:
-
-======================================
-RQL language (Relation Query Language)
-======================================
-
-Introduction
-============
-
-Goals of RQL
-------------
-
-The goal is to have a language emphasizing the way of browsing
-relations. As such, attributes will be regarded as cases of
-special relations (in terms of implementation, the language
-user should see virtually no difference between an attribute and a
-relation).
-
-RQL is inspired by SQL but is the highest level. A knowledge of the
-`CubicWeb` schema defining the application is necessary.
-
-Comparison with existing languages
-----------------------------------
-
-SQL
-```
-RQL builds on the features of SQL but is at a higher level
-(the current implementation of RQL generates SQL). For that it is limited
-to the way of browsing relations and introduces variables.
-The user does not need to know the model underlying SQL, but the `CubicWeb`
-schema defining the application.
-
-Versa
-`````
-We should look in more detail, but here are already some ideas for
-the moment ... Versa_ is the language most similar to what we wanted
-to do, but the model underlying data being RDF, there is some
-number of things such as namespaces or handling of the RDF types which
-does not interest us. On the functionality level, Versa_ is very comprehensive
-including through many functions of conversion and basic types manipulation,
-which may need to be guided at one time or another.
-Finally, the syntax is a little esoteric.
-
-Sparql
-``````
-
-The query language most similar to RQL is SPARQL_, defined by the W3C to serve
-for the semantic web.
-
-
-The different types of queries
-------------------------------
-
-Search (`Any`)
- Extract entities and attributes of entities.
-
-Insert entities (`INSERT`)
- Insert new entities or relations in the database.
- It can also directly create relationships for the newly created entities.
-
-Update entities, create relations (`SET`)
- Update existing entities in the database,
- or create relations between existing entities.
-
-Delete entities or relationship (`DELETE`)
- Remove entities or relations existing in the database.
-
-Search Query
-------------
-
- [ `DISTINCT`] <entity type> V1 (V2) \ *
- [ `GROUPBY` V1 (V2) \*] [ `ORDERBY` <orderterms>]
- [ `WHERE` <restriction>]
- [ `LIMIT` <value>] [ `OFFSET` <value>]
-
-:entity type:
- Type of selected variables.
- The special type `Any` is equivalent to not specify a type.
-:restriction:
- list of conditions to test successively
- `V1 relation V2 | <static value>`
-:orderterms:
- Definition of the selection order: variable or column number followed by
- sorting method ( `ASC`, `DESC`), ASC is the default.
-:note for grouped queries:
- For grouped queries (e.g., a clause `GROUPBY`), all
- selected variables must be aggregated or grouped.
-
-
-
-- *Search for the object of identifier 53*
- ::
-
- Any WHERE X
- X eid 53
-
-- *Search material such as comics, owned by syt and available*
- ::
-
- WHERE X Document
- X occurence_of F, F class C, C name 'Comics'
- X owned_by U, U login 'syt'
- X available true
-
-- *Looking for people working for eurocopter interested in training*
- ::
-
- Any P WHERE
- P is Person, P work_for S, S name 'Eurocopter'
- P interested_by T, T name 'training'
-
-- *Search note less than 10 days old written by jphc or ocy*
- ::
-
- Any N WHERE
- N is Note, N written_on D, D day> (today -10),
- N written_by P, P name 'jphc' or P name 'ocy'
-
-- *Looking for people interested in training or living in Paris*
- ::
-
- Any P WHERE
- P is Person, (P interested_by T, T name 'training') OR
- (P city 'Paris')
-
-- *The name and surname of all people*
- ::
-
- Any N, P WHERE
- X is Person, X name N, X first_name P
-
- Note that the selection of several entities generally force
- the use of "Any" because the type specification applies otherwise
- to all the selected variables. We could write here
- ::
-
- String N, P WHERE
- X is Person, X name N, X first_name P
-
-
- Note: You can not specify several types with * ... where X is FirstType or X is SecondType*.
- To specify several types explicitely, you have to do
-
- ::
-
- Any X where X is in (FirstType, SecondType)
-
-
-Insertion query
----------------
-
- `INSERT` <entity type> V1 (, <entity type> V2) \ * `:` <assignments>
- [ `WHERE` <restriction>]
-
-:assignments:
- list of relations to assign in the form `V1 relationship V2 | <static value>`
-
-The restriction can define variables used in assignments.
-
-Caution, if a restriction is specified, the insertion is done for
-*each line result returned by the restriction*.
-
-- *Insert a new person named 'foo'*
- ::
-
- INSERT Person X: X name 'foo'
-
-- *Insert a new person named 'foo', another called 'nice' and a 'friend' relation
- between them*
- ::
-
- INSERT Person X, Person Y: X name 'foo', Y name 'nice', X friend Y
-
-- *Insert a new person named 'foo' and a 'friend' relation with an existing
- person called 'nice'*
- ::
-
- INSERT Person X: X name 'foo', X friend Y WHERE name 'nice'
-
-Update and relation creation queries
-------------------------------------
- `SET` <assignements>
- [ `WHERE` <restriction>]
-
-Caution, if a restriction is specified, the update is done *for
-each result line returned by the restriction*.
-
-- *Renaming of the person named 'foo' to 'bar' with the first name changed*
- ::
-
- SET X name 'bar', X first_name 'original' WHERE X is Person, X name 'foo'
-
-- *Insert a relation of type 'know' between objects linked by
- the relation of type 'friend'*
- ::
-
- SET X know Y WHERE X friend Y
-
-
-Deletion query
---------------
- `DELETE` (<entity type> V) | (V1 relation v2 ),...
- [ `WHERE` <restriction>]
-
-Caution, if a restriction is specified, the deletion is made *for
-each line result returned by the restriction*.
-
-- *Deletion of the person named 'foo'*
- ::
-
- DELETE Person X WHERE X name 'foo'
-
-- *Removal of all relations of type 'friend' from the person named 'foo'*
- ::
-
- DELETE X friend Y WHERE X is Person, X name 'foo'
-
-
-(yet) Undocumented types of queries
------------------------------------
-
-**Limit / offset**
-::
-
- Any P ORDERBY N LIMIT 5 OFFSET 10 WHERE P is Person, P firstname N
-
-**Function calls**
-::
-
- Any UPPER(N) WHERE P firstname N
-
-**Exists**
-::
-
- Any X ORDERBY PN,N
- WHERE X num N, X version_of P, P name PN,
- EXISTS(X in_state S, S name IN ("dev", "ready"))
- OR EXISTS(T tags X, T name "priority")
-
-**Left outer join**
-::
-
- Any T,P,V WHERE T is Ticket, T concerns P, T done_in V?
-
-
-**Having**
-::
-
- Any X GROUPBY X WHERE X knows Y HAVING COUNT(Y) > 10
-
-**Simple union**
-::
-
- (Any X WHERE X is Person) UNION (Any X WHERE X is Company)
-
-**Complex union**
-::
-
- DISTINCT Any W, REF
- WITH W, REF BEING
- (
- (Any W, REF WHERE W is Workcase, W ref REF,
- W concerned_by D, D name "Logilab")
- UNION
- (Any W, REF WHERE W is Workcase, W ref REF, '
- W split_into WP, WP name "WP1")
- )
-
-
-Language definition
-===================
-
-Reserved keywords
------------------
-The keywords are not case sensitive.
-
-::
-
- DISTINCT, INSERT, SET, DELETE,
- WHERE, AND, OR, NOT, EXISTS,
- IN, LIKE, UNION, WITH, BEING,
- TRUE, FALSE, NULL, TODAY, NOW,
- LIMIT, OFFSET,
- HAVING, GROUPBY, ORDERBY, ASC, DESC
-
-
-Variables and Typing
---------------------
-
-With RQL, we do not distinguish between entities and attributes. The
-value of an attribute is considered an entity of a particular type (see
-below), linked to one (real) entity by a relation called the name of
-the attribute.
-
-Entities and values to browse and/or select are represented in
-the query by *variables* that must be written in capital letters.
-
-There is a special type **Any**, referring to a non specific type.
-
-We can restrict the possible types for a variable using the
-special relation **is**.
-The possible type(s) for each variable is derived from the schema
-according to the constraints expressed above and thanks to the relations between
-each variable.
-
-Built-in types
-``````````````
-
-The base types supported are string (between double or single quotes),
-integers or floats (the separator is '.'), dates and
-boolean. We expect to receive a schema in which types String,
-Int, Float, Date and Boolean are defined.
-
-* `String` (literal: between double or single quotes).
-* `Int`, `Float` (separator being'.').
-* `Date`, `Datetime`, `Time` (literal: string YYYY/MM/DD [hh:mm] or keywords
- `TODAY` and `NOW`).
-* `Boolean` (keywords `TRUE` and `FALSE`).
-* `Keyword` NULL.
-
-
-Operators
----------
-
-Logical Operators
-`````````````````
-::
-
- AND, OR, NOT, ','
-
-',' is equivalent to 'AND' but with the smallest among the priority
-of logical operators (see :ref:`PriorityOperators`).
-
-Mathematical Operators
-``````````````````````
-::
-
- +, -, *, /
-
-Comparison operators
-````````````````````
-::
-
- =, <, <=, >=, >, ~=, IN, LIKE
-
-* The operator `=` is the default operator.
-
-* The operator `LIKE` equivalent to `~=` can be used with the
- special character `%` in a string to indicate that the chain
- must start or finish by a prefix/suffix:
- ::
-
- Any X WHERE X name ~= 'Th%'
- Any X WHERE X name LIKE '%lt'
-
-* The operator `IN` provides a list of possible values:
- ::
-
- Any X WHERE X name IN ( 'chauvat', 'fayolle', 'di mascio', 'thenault')
-
-
-XXX nico: "A trick <> 'bar'" wouldn't it be more convenient than
-"NOT A trick 'bar'" ?
-
-.. _PriorityOperators:
-
-Operator priority
-`````````````````
-
-1. '*', '/'
-
-2. '+', '-'
-
-3. 'not'
-
-4 'and'
-
-5 'or'
-
-6 ','
-
-
-Advanced Features
------------------
-
-Aggregate Functions
-```````````````````
-::
-
- COUNT, MIN, MAX, AVG, SUM
-
-Functions on string
-```````````````````
-::
-
- UPPER, LOWER
-
-Optional relations
-``````````````````
-
-* They allow you to select entities related or not to another.
-
-* You must use the `?` behind the variable to specify that the relation
- toward it is optional:
-
- - Anomalies of a project attached or not to a version ::
-
- Any X, V WHERE X concerns P, P eid 42, X corrected_in V?
-
- - All cards and the project they document if necessary ::
-
- Any C, P WHERE C is Card, P? documented_by C
-
-
-
-BNF grammar
------------
-
-The terminal elements are in capital letters, non-terminal in lowercase.
-The value of the terminal elements (between quotes) is a Python regular
-expression.
-::
-
- statement:: = (select | delete | insert | update) ';'
-
-
- # select specific rules
- select ::= 'DISTINCT'? E_TYPE selected_terms restriction? group? sort?
-
- selected_terms ::= expression ( ',' expression)*
-
- group ::= 'GROUPBY' VARIABLE ( ',' VARIABLE)*
-
- sort ::= 'ORDERBY' sort_term ( ',' sort_term)*
-
- sort_term ::= VARIABLE sort_method =?
-
- sort_method ::= 'ASC' | 'DESC'
-
-
- # delete specific rules
- delete ::= 'DELETE' (variables_declaration | relations_declaration) restriction?
-
-
- # insert specific rules
- insert ::= 'INSERT' variables_declaration ( ':' relations_declaration)? restriction?
-
-
- # update specific rules
- update ::= 'SET' relations_declaration restriction
-
-
- # common rules
- variables_declaration ::= E_TYPE VARIABLE (',' E_TYPE VARIABLE)*
-
- relations_declaration ::= simple_relation (',' simple_relation)*
-
- simple_relation ::= VARIABLE R_TYPE expression
-
- restriction ::= 'WHERE' relations
-
- relations ::= relation (LOGIC_OP relation)*
- | '(' relations')'
-
- relation ::= 'NOT'? VARIABLE R_TYPE COMP_OP? expression
- | 'NOT'? R_TYPE VARIABLE 'IN' '(' expression (',' expression)* ')'
-
- expression ::= var_or_func_or_const (MATH_OP var_or_func_or_const) *
- | '(' expression ')'
-
- var_or_func_or_const ::= VARIABLE | function | constant
-
- function ::= FUNCTION '(' expression ( ',' expression) * ')'
-
- constant ::= KEYWORD | STRING | FLOAT | INT
-
- # tokens
- LOGIC_OP ::= ',' | 'OR' | 'AND'
- MATH_OP ::= '+' | '-' | '/' | '*'
- COMP_OP ::= '>' | '>=' | '=' | '<=' | '<' | '~=' | 'LIKE'
-
- FUNCTION ::= 'MIN' | 'MAX' | 'SUM' | 'AVG' | 'COUNT' | 'UPPER' | 'LOWER'
-
- VARIABLE ::= '[A-Z][A-Z0-9]*'
- E_TYPE ::= '[A-Z]\w*'
- R_TYPE ::= '[a-z_]+'
-
- KEYWORD ::= 'TRUE' | 'FALSE' | 'NULL' | 'TODAY' | 'NOW'
- STRING ::= "'([^'\]|\\.)*'" |'"([^\"]|\\.)*\"'
- FLOAT ::= '\d+\.\d*'
- INT ::= '\d+'
-
-
-Remarks
--------
-
-Sorting and groups
-``````````````````
-
-- For grouped queries (e.g. with a GROUPBY clause), all
- selected variables should be grouped.
-
-- To group and/or sort by attributes, we can do: "X,L user U, U
- login L GROUPBY L, X ORDERBY L"
-
-- If the sorting method (SORT_METHOD) is not specified, then the sorting is
- ascendant.
-
-Negation
-````````
-
-* A query such as `Document X WHERE NOT X owned_by U` means "the
- documents have no relation `owned_by`".
-* But the query `Document X WHERE NOT X owned_by U, U login "syt"`
- means "the documents have no relation `owned_by` with the user
- syt". They may have a relation "owned_by" with another user.
-
-Identity
-````````
-
-You can use the special relation `identity` in a query to
-add an identity constraint between two variables. This is equivalent
-to ``is`` in python::
-
- Any A WHERE A comments B, A identity B
-
-return all objects that comment themselves. The relation
-`identity` is especially useful when defining the rules for securities
-with `RQLExpressions`.
-
-Implementation
-==============
-
-Internal representation (syntactic tree)
-----------------------------------------
-
-The tree research does not contain the selected variables
-(e.g. there is only what follows "WHERE").
-
-The insertion tree does not contain the variables inserted or relations
-defined on these variables (e.g. there is only what follows "WHERE").
-
-The removal tree does not contain the deleted variables and relations
-(e.g. there is only what follows the "WHERE").
-
-The update tree does not contain the variables and relations updated
-(e.g. there is only what follows the "WHERE").
-
-::
-
- Select ((Relationship | And | Or)?, Group?, Sort?)
- Insert (Relations | And | Or)?
- Delete (Relationship | And | Or)?
- Update (Relations | And | Or)?
-
- And ((Relationship | And | Or), (Relationship | And | Or))
- Or ((Relationship | And | Or), (Relationship | And | Or))
-
- Relationship ((VariableRef, Comparison))
-
- Comparison ((Function | MathExpression | Keyword | Constant | VariableRef) +)
-
- Function (())
- MathExpression ((MathExpression | Keyword | Constant | VariableRef), (MathExpression | Keyword | Constant | VariableRef))
-
- Group (VariableRef +)
- Sort (SortTerm +)
- SortTerm (VariableRef +)
-
- VariableRef ()
- Variable ()
- Keyword ()
- Constant ()
-
-
-Remarks
--------
-
-- The current implementation does not support linking two relations of type
- 'is' with a OR. I do not think that the negation is supported on this type
- of relation (XXX FIXME to be confirmed).
-
-- Relations defining the variables must be left to those using them.
- For example::
-
- Point P where P abs X, P ord Y, P value X+Y
-
- is valid, but::
-
- Point P where P abs X, P value X+Y, P ord Y
-
- is not.
-
-RQL logs
---------
-
-You can configure the `CubicWeb` application to keep a log
-of the queries executed against your database. To do so,
-edit the configuration file of your application
-``.../etc/cubicweb.d/myapp/all-in-one.conf`` and uncomment the
-variable ``query-log-file``::
-
- # web application query log file
- query-log-file=/tmp/rql-myapp.log
-
-
-Conclusion
-==========
-
-Limitations
------------
-
-It lacks at the moment:
-
-- COALESCE
-
-- restrictions on groups (HAVING)
-
-and certainly other things ...
-
-A disadvantage is that to use this language we must know the
-format used (with real relation names and entities, not those viewing
-in the user interface). On the other hand, we can not really bypass
-that, and it is the job of a user interface to hide the RQL.
-
-
-Topics
-------
-
-It would be convenient to express the schema matching
-relations (non-recursive rules)::
-
- Document class Type <-> Document occurence_of Fiche class Type
- Sheet class Type <-> Form collection Collection class Type
-
-Therefore 1. becomes::
-
- Document X where
- X class C, C name 'Cartoon'
- X owned_by U, U login 'syt'
- X available true
-
-I'm not sure that we should handle this at RQL level ...
-
-There should also be a special relation 'anonymous'.
-
-
-
-.. _Versa: http://uche.ogbuji.net/tech/rdf/versa/
-.. _SPARQL: http://www.w3.org/TR/rdf-sparql-query/
-
-
-[FIXME] see also RQL documentation in source rql/doc.
--- a/doc/book/en/D000-annex.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,21 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-.. _Part4:
-
-====================
-Part IV - Appendixes
-====================
-
-The following chapters are reference material.
-
-.. toctree::
- :maxdepth: 1
-
- D010-faq.en.txt
- D020-cookbook.en.txt
- D030-cubicweb-ctl.en.txt
- D040-api-reference.en.txt
- D050-architecture.en.txt
- D060-modules-stdlib.en.txt
- D070-modules-cbw-api.en.txt
- D080-mercurial.en.txt
--- a/doc/book/en/D010-faq.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,244 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Frequently Asked Questions
-==========================
-
-[XXX 'copy answer from forum' means reusing text from
-http://groups.google.com/group/google-appengine/browse_frm/thread/c9476925f5f66ec6
-and
-http://groups.google.com/group/google-appengine/browse_frm/thread/d791ce17e2716147/eb078f8cfe8426e0
-and
-http://groups.google.com/group/google-appengine/browse_frm/thread/f48cf6099973aef5/c28cd6934dd72457
-]
-
-* Why does not CubicWeb have a template language ?
-
- There are enough template languages out there. You can use your
- preferred template language if you want. [explain how to use a
- template language]
-
- `CubicWeb` does not define its own templating language as this was
- not our goal. Based on our experience, we realized that
- we could gain productivity by letting designers use design tools
- and developpers develop without the use of the templating language
- as an intermediary that could not be anyway efficient for both parties.
- Python is the templating language that we use in `CubicWeb`, but again,
- it does not prevent you from using a templating language.
-
- The reason template languages are not used in this book is that
- experience has proved us that using pure python was less cumbersome.
-
-* Why do you think using pure python is better than using a template language ?
-
- Python is an Object Oriented Programming language and as such it
- already provides a consistent and strong architecture and syntax
- a templating language would not reach.
-
- When doing development, you need a real language and template
- languages are not real languages.
-
- Using Python enables developing applications for which code is
- easier to maintain with real functions/classes/contexts
- without the need of learning a new dialect. By using Python,
- we use standard OOP techniques and this is a key factor in a
- robust application.
-
-* Why do you use the GPL license to prevent me from doing X ?
-
- GPL means that *if* you redistribute your application, you need to
- redistribute it *and* the changes you made *and* the code _linked_
- to it under the GPL licence.
-
- Publishing a web site has nothing to do with redistributing
- source code. A fair amount of companies use modified GPL code
- for internal use. And someone could publish a `CubicWeb` component
- under a BSD licence for others to plug into a GPL framework without
- any problem. The only thing we are trying to prevent here is someone
- taking the framework and packaging it as closed source to his own
- clients.
-
-
-* CubicWeb looks pretty recent. Is it stable ?
-
- It is constantly evolving, piece by piece. The framework has
- evolved over the past seven years and data has been migrated from
- one schema to the other ever since. There is a well-defined way to
- handle data and schema migration.
-
-* Why is the RQL query language looking similar to X ?
-
- It may remind you of SQL but it is higher level than SQL, more like
- SPARQL. Except that SPARQL did not exist when we started the project.
- Having SPARQL has a query language has been in our backlog for years.
-
- That RQL language is what is going to make a difference with django-
- like frameworks for several reasons.
-
- 1. accessing data is *much* easier with it. One can write complex
- queries with RQL that would be tedious to define and hard to maintain
- using an object/filter suite of method calls.
-
- 2. it offers an abstraction layer allowing your applications to run
- on multiple back-ends. That means not only various SQL backends
- (postgresql, sqlite, mysql), but also multiple databases at the
- same time, and also non-SQL data stores like LDAP directories and
- subversion/mercurial repositories (see the `vcsfile`
- component). Google App Engine is yet another supported target for
- RQL.
-
-[copy answer from forum, explain why similar to sparql and why better
- than django and SQL]
-
-* which ajax library
-
- [we use jquery and things on top of that]
-
-* `Error while publishing rest text ...`
-
- While modifying the description of an entity, you get an error message in
- the application `Error while publishing ...` for Rest text and plain text.
- The server returns a traceback like as follows ::
-
- 2008-10-06 15:05:08 - (cubicweb.rest) ERROR: error while publishing ReST text
- Traceback (most recent call last):
- File "/home/user/src/blogdemo/cubicweb/common/rest.py", line 217, in rest_publish
- File "/usr/lib/python2.5/codecs.py", line 817, in open
- file = __builtin__.open(filename, mode, buffering)
- TypeError: __init__() takes at most 3 arguments (4 given)
-
-
- This can be fixed by applying the patch described in :
- http://code.google.com/p/googleappengine/issues/detail?id=48
-
-* What are hooks used for?
-
- Hooks are executed around (actually before or after) events. The
- most common events are data creation, update and deletion. They
- permit additional constraint checking (those not expressible at the
- schema level), pre and post computations depending on data
- movements.
-
- As such, they are a vital part of the framework.
-
- Other kinds of hooks, called Operations, are available
- for execution just before commit.
-
-* When should you define an HTML template rather than define a graphical component?
-
- An HTML template cannot contain code, hence it is only about static
- content. A component is made of code and operations that apply on a
- well defined context (request, result set). It enables much more
- dynamic views.
-
-* What is the difference between `AppRsetObject` and `AppObject` ?
-
- `AppRsetObject` instances are selected on a request and a result
- set. `AppObject` instances are directly selected by id.
-
-* How to update a database after a schema modification?
-
- It depends on what has been modified in the schema.
-
- * Update of an attribute permissions and properties:
- ``synchronize_eschema('MyEntity')``.
-
- * Update of a relation permissions and properties:
- ``synchronize_rschema('MyRelation')``.
-
- * Add an attribute: ``add_attribute('MyEntityType', 'myattr')``.
-
- * Add a relation: ``add_relation_definition('SubjRelation', 'MyRelation', 'ObjRelation')``.
-
-
-* How to create an anonymous user?
-
- This allows to bypass authentication for your site. In the
- ``all-in-one.conf`` file of your instance, define the anonymous user
- as follows ::
-
- # login of the CubicWeb user account to use for anonymous user (if you want to
- # allow anonymous)
- anonymous-user=anon
-
- # password of the CubicWeb user account matching login
- anonymous-password=anon
-
- You also must ensure that this `anon` user is a registered user of
- the DB backend. If not, you can create through the administation
- interface of your instance by adding a user with the role `guests`.
- This could be the admin account (for development
- purposes, of course).
-
-.. note::
- While creating a new instance, you can decide to allow access
- to anonymous user, which will automatically execute what is
- decribed above.
-
-
-* How to change the application logo?
-
- There are two ways of changing the logo.
-
- 1. The easiest way to use a different logo is to replace the existing
- ``logo.png`` in ``myapp/data`` by your prefered icon and refresh.
- By default all application will look for a ``logo.png`` to be
- rendered in the logo section.
-
- .. image:: images/lax-book.06-main-template-logo.en.png
-
- 2. In your cube directory, you can specify which file to use for the logo.
- This is configurable in ``mycube/data/external_resources``: ::
-
- LOGO = DATADIR/path/to/mylogo.gif
-
- where DATADIR is ``mycubes/data``.
-
-* How to configure LDAP source?
-
- Your instance's sources are defined in ``/etc/cubicweb.d/myapp/sources``.
- Configuring an LDAP source is about declaring that source in your
- instance configuration file such as: ::
-
- [ldapuser]
- adapter=ldapuser
- # ldap host
- host=myhost
- # base DN to lookup for usres
- user-base-dn=ou=People,dc=mydomain,dc=fr
- # user search scope
- user-scope=ONELEVEL
- # classes of user
- user-classes=top,posixAccount
- # attribute used as login on authentication
- user-login-attr=uid
- # name of a group in which ldap users will be by default
- user-default-group=users
- # map from ldap user attributes to cubicweb attributes
- user-attrs-map=gecos:email,uid:login
-
- Any change applied to configuration file requires to restart your
- application.
-
-* I get NoSelectableObject exceptions: how do I debug selectors ?
-
- You just need to put the appropriate context manager around view/component
- selection: ::
-
- from cubicweb.common.selectors import traced_selection
- with traced_selection():
- comp = self.vreg.select_object('contentnavigation', 'wfhistory',
- self.req, rset, context='navcontentbottom')
-
- This will yield additional WARNINGs, like this: ::
-
- 2009-01-09 16:43:52 - (cubicweb.selectors) WARNING: selector one_line_rset returned 0 for <class 'cubicweb.web.views.basecomponents.WFHistoryVComponent'>
-
-* How to format an entity date attribute?
-
- If your schema has an attribute of type Date or Datetime, you might
- want to format it. First, you should define your preferred format using
- the site configuration panel ``http://appurl/view?vid=systemepropertiesform``
- and then set ``ui.date`` and/or ``ui.datetime``.
- Then in the view code, use::
-
- self.format_date(entity.date_attribute)
--- a/doc/book/en/D020-cookbook.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,64 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Cook book
-=========
-
-We gathered together some of our tricks and scripts that could make
-life easier.
-
-
-* How to import LDAP users in `CubicWeb`?
-
- Here is a very useful script which enables you to import LDAP users
- into your `CubicWeb` application by running the following: ::
-
-
- import os
- import pwd
- import sys
-
- from logilab.common.db import get_connection
-
- def getlogin():
- """avoid usinng os.getlogin() because of strange tty / stdin problems
- (man 3 getlogin)
- Another solution would be to use $LOGNAME, $USER or $USERNAME
- """
- return pwd.getpwuid(os.getuid())[0]
-
-
- try:
- database = sys.argv[1]
- except IndexError:
- print 'USAGE: python ldap2system.py <database>'
- sys.exit(1)
-
- if raw_input('update %s db ? [y/n]: ' % database).strip().lower().startswith('y'):
- cnx = get_connection(user=getlogin(), database=database)
- cursor = cnx.cursor()
-
- insert = ('INSERT INTO euser (creation_date, eid, modification_date, login, firstname, surname, last_login_time, upassword) '
- "VALUES (%(mtime)s, %(eid)s, %(mtime)s, %(login)s, %(firstname)s, %(surname)s, %(mtime)s, './fqEz5LeZnT6');")
- update = "UPDATE entities SET source='system' WHERE eid=%(eid)s;"
- cursor.execute("SELECT eid,type,source,extid,mtime FROM entities WHERE source!='system'")
- for eid, type, source, extid, mtime in cursor.fetchall():
- if type != 'CWUser':
- print "don't know what to do with entity type", type
- continue
- if source != 'ldapuser':
- print "don't know what to do with source type", source
- continue
- ldapinfos = dict(x.strip().split('=') for x in extid.split(','))
- login = ldapinfos['uid']
- firstname = ldapinfos['uid'][0].upper()
- surname = ldapinfos['uid'][1:].capitalize()
- if login != 'jcuissinat':
- args = dict(eid=eid, type=type, source=source, login=login,
- firstname=firstname, surname=surname, mtime=mtime)
- print args
- cursor.execute(insert, args)
- cursor.execute(update, args)
-
- cnx.commit()
- cnx.close()
-
--- a/doc/book/en/D030-cubicweb-ctl.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,122 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-.. _cubicweb-ctl:
-
-``cubicweb-ctl`` tool
-=====================
-
-`cubicweb-ctl` is the swiss knife to manage `CubicWeb` instances.
-The general syntax is ::
-
- cubicweb-ctl <command> [options command] <arguments commands>
-
-To view available commands ::
-
- cubicweb-ctl
- cubicweb-ctl --help
-
-Please note that the commands available depends on the `CubicWeb` packages
-and cubes that have been installed.
-
-To view the help menu on specific command ::
-
- cubicweb-ctl <command> --help
-
-Command to create a cube
-------------------------
-
-* ``newcube``, create a new cube on the file system based on the name
- given in the parameters. This command create a cube from an application
- skeleton that includes default files required for debian packaging.
-
-
-Command to create an instance
------------------------------
-* ``create``, creates the files for the instance configuration
-* ``db-create``, creates the system database of an instance (tables and
- extensions only)
-* ``db-init``, initializes the system database of an instance
- (schema, groups, users, workflows...)
-
-By default, those three commandes are encapsulated in ``create`` so
-that they can be executed consecutively.
-
-Command to create an instance for Google AppEngine datastore source
--------------------------------------------------------------------
-* ``newgapp``, creates the configuration files for an instance
-
-This command needs to be followed by the commands responsible for
-the database initialization. As those are specific to the `datastore`,
-specific Google AppEgine database, they are not available for now
-in cubicweb-ctl, but they are available in the instance created.
-
-For more details, please see :ref:`gaecontents` .
-
-Commands to control instances
------------------------------
-* ``start``, starts one or more or all instances
-* ``stop``, stops one or more or all instances
-* ``restart``, restarts one or more or all instances
-* ``status``, returns the status of the instance
-
-Commands to maintain instances
-------------------------------
-* ``upgrade``, launches the existing instances migration when a new version
- of `CubicWeb` or the cubes installed is available
-* ``shell``, opens a migration shell for manual maintenance of the instance
-* ``db-dump``, creates a dump of the system database
-* ``db-restore``, restores a dump of the system database
-* ``db-check``, checks data integrity of an instance. If the automatic correction
- is activated, it is recommanded to create a dump before this operation.
-* ``schema-sync``, synchronizes the persistent schema of an instance with
- the application schema. It is recommanded to create a dump before this operation.
-
-Commands to maintain i18n catalogs
-----------------------------------
-* ``i18nlibupdate``, regenerates messages catalogs of the `CubicWeb` library
-* ``i18nupdate``, regenerates the messages catalogs of a cube
-* ``i18ncompile``, recompiles the messages catalogs of an instance.
- This is automatically done while upgrading.
-
-See also chapter :ref:`internationalisation`.
-
-Other commands
---------------
-* ``list``, provides a list of the available configuration, cubes
- and instances.
-* ``delete``, deletes an instance (configuration files and database)
-
-
-Create an instance from an existing cube
-````````````````````````````````````````
-
-To create an instance from an existing cube, execute the following
-command ::
-
- cubicweb-ctl create <cube_name> <instance_name>
-
-This command will create the configuration files of an instance in
-``~/etc/cubicweb.d/<instance_name>``.
-The tool ``cubicweb-ctl`` allows you to execute the command ``db-create``
-and ``db-init`` when you run ``create`` so that you can complete an
-instance creation in a single command.
-
-If you decide not to execut those commands while ``cubicweb-ctl create``,
-then you will have to execute them seperately(``cubicweb-ctl db-create``,
-``cubicweb-ctl db-init`` ) otherwise your installation will not be complete
-and you will not be able to launch your instance.
-
-
-Creation of an instance from a new cube
-```````````````````````````````````````
-
-Create first your new cube cube ::
-
- cubicweb-ctl newcube <mycube>
-
-This will create a new cube in ``/path/to/forest/cubicweb/cubes/<mycube>``
-for a Mercurial forest installation, or in ``/usr/share/cubicweb/cubes``
-for a debian packages installation, and then create an instance as
-explained just above.
-
-
--- a/doc/book/en/D040-api-reference.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,33 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-API Reference
-=============
-
-Schema API
-----------
-
-Base Types
-~~~~~~~~~~
-
-Base types are defined as a set in yams.BASE_TYPES that includes:
-`String`, `Int`, `Float`, `Boolean`, `Date`, `Time`, `Datetime`,
-`Interval`, `Password`, `Bytes`.
-
-See `yams' API <http://www.cubicweb.org/doc/en/modindex.html>`_
-
-Constraints
-~~~~~~~~~~~
-
-Constraints are defined in yams.constraints and include:
-`UniqueConstraint`, `SizeConstraint`, `RegexpConstraint`,
-`BoundConstraint`, `IntervalBoundConstraint`,
-`StaticVocabularyConstraint`, `MultipleStaticVocabularyConstraint`.
-
-See `yams' API <http://www.cubicweb.org/doc/en/modindex.html>`_
-
-Views API
----------
-
-See `yams' API <http://www.cubicweb.org/doc/en/modindex.html>`_
-[WRITE ME]
-
--- a/doc/book/en/D050-architecture.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,14 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-
-Server Architecture
--------------------
-
-.. image:: images/server-class-diagram.png
-
-`Diagramme ArgoUML`_
-
-[FIXME]
-Make a downloadable source of zargo file.
-
-.. _`Diagramme ArgoUML`: cubicweb.zargo
--- a/doc/book/en/D080-mercurial.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,133 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-.. _MercurialPresentation:
-
-Introducing Mercurial
-=====================
-
-Introduction
-````````````
-Mercurial_ manages a distributed repository containing revisions
-trees (each revision indicates the changes required to obtain the
-next, and so on). Locally, we have a repository containing revisions
-tree, and a working directory. It is possible
-to put in its working directory, one of the versions of its local repository,
-modify and then push it in its repository.
-It is also possible to get revisions from another repository or to export
-its own revisions from the local repository to another repository.
-
-.. _Mercurial: http://www.selenic.com/mercurial/
-
-In contrast to CVS/Subversion, we usually create a repository by
-project to manage.
-
-In a collaborative development, we usually create a central repository
-accessible to all developers of the project. These central repository is used
-as a reference. According to its needs, then everyone can have a local repository,
-that you will have to synchronize with the central repository from time to time.
-
-
-Major commands
-``````````````
-* Create a local repository::
-
- hg clone ssh://myhost//home/src/repo
-
-* See the contents of the local repository (graphical tool in Tk)::
-
- hgview
-
-* Add a sub-directory or file in the current directory::
-
- hg add subdir
-
-* Move to the working directory a specific revision (or last
- revision) from the local repository::
-
- hg update [identifier-revision]
- hg up [identifier-revision]
-
-* Get in its local repository, the tree of revisions contained in a
- remote repository (this does not change the local directory)::
-
- hg pull ssh://myhost//home/src/repo
- hg pull -u ssh://myhost//home/src/repo # equivalent to pull + update
-
-* See what are the heads of branches of the local repository if a `pull`
- returned a new branch::
-
- hg heads
-
-* Submit the working directory in the local repository (and create a new
- revision)::
-
- hg commit
- hg ci
-
-* Merge with the mother revision of local directory, another revision from
- the local respository (the new revision will be then two mothers
- revisions)::
-
- hg merge identifier-revision
-
-* Export to a remote repository, the tree of revisions in its content
- local respository (this does not change the local directory)::
-
- hg push ssh://myhost//home/src/repo
-
-* See what local revisions are not in another repository::
-
- hg outgoing ssh://myhost//home/src/repo
-
-* See what are the revisions of a repository not found locally::
-
- hg incoming ssh://myhost//home/src/repo
-
-* See what is the revision of the local repository which has been taken out
- from the working directory and amended::
-
- hg parent
-
-* See the differences between the working directory and the mother revision
- of the local repository, possibly to submit them in the local repository::
-
- hg diff
- hg commit-tool
- hg ct
-
-
-Best Practices
-``````````````
-* Remember to `hg pull -u` regularly, and particularly before
- a `hg commit`.
-
-* Remember to `hg push` when your repository contains a version
- relatively stable of your changes.
-
-* If a `hg pull -u` created a new branch head:
-
- 1. find its identifier with `hg head`
- 2. merge with `hg merge`
- 3. `hg ci`
- 4. `hg push`
-
-Installation of the forest extension
-````````````````````````````````````
-
-Set up the forest extension by getting a copy of the sources
-from http://hg.akoha.org/hgforest/ and adding the following
-lines to your ``~/.hgrc``: ::
-
- [extensions]
- hgext.forest=
- # or, if forest.py is not in the hgext dir:
- # forest=/path/to/forest.py
-
-
-More information
-````````````````
-
-For more information about Mercurial, please refer to the Mercurial project online documentation_.
-
-.. _documentation: http://www.selenic.com/mercurial/wiki/
-
--- a/doc/book/en/Z013-blog-less-ten-minutes.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,26 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-.. _BlogTenMinutes:
-
-Get a Blog running in less than ten minutes!
---------------------------------------------
-
-You need to install the following packages (:ref:`DebianInstallation`)::
-
- cubicweb, cubicweb-dev, cubicweb-blog
-
-Creation and initialization of your application by running::
-
- cubicweb-ctl create blog myblog
-
-Your application is now ready to go::
-
- cubicweb-ctl start -D myblog
-
-This is it. Your blog is ready to you. Go to http://localhost:8080 and enjoy!!
-
-As a developper, you'll want to know more about how to develop new
-cubes and cutomize the look of your application and this is what we
-talk about now.
-
-
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/admin/create-instance.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,63 @@
+.. -*- coding: utf-8 -*-
+
+Creation of your first instance
+===============================
+
+Instance creation
+-----------------
+
+Now that we created our cube, we can create an instance to view our
+application in a web browser. To do so we will use a `all-in-one`
+configuration to simplify things ::
+
+ cubicweb-ctl create -c all-in-one mycube myinstance
+
+.. note::
+ Please note that we created a new cube for a demo purpose but
+ you could have use an existing cube available in our standard library
+ such as blog or person for example.
+
+A serie of questions will be prompted to you, the default answer is usually
+sufficient. You can anyway modify the configuration later on 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:`ConfigurationPostgres`).
+
+It is important to distinguish here the user used to access the database and the
+user used to login to the cubicweb application. When an instance starts, it uses
+the login/psswd for the database to get the schema and handle low level
+transaction. But, when :command:`cubicweb-ctl create` asks for a manager
+login/psswd of `CubicWeb`, it refers to the user you will use during the
+development to administrate your web application. It will be possible, later on,
+to use this user to create others users for your final web application.
+
+
+Instance administration
+-----------------------
+
+start / stop
+~~~~~~~~~~~~
+When this command is completed, the definition of your instance is
+located in :file:`~/etc/cubicweb.d/myinstance/*`. To launch it, you just type ::
+
+ cubicweb-ctl start -D myinstance
+
+The option `-D` specify the *debug mode* : the instance is not running in
+server mode and does not disconnect from the termnial, which simplifies debugging
+in case the instance is not properly launched. You can see how it looks by
+visiting the URL `http://localhost:8080` (the port number depends of your
+configuration). To login, please use the cubicweb administrator login/psswd you
+defined when you created the instance.
+
+To shutdown the instance, Crtl-C in the terminal window is enough.
+If you did not use the option `-D`, then type ::
+
+ cubicweb-ctl stop myinstance
+
+This is it! All is settled down to start developping your data model...
+
+
+upgrade
+~~~~~~~
+XXX feed me
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/admin/gae.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,233 @@
+.. -*- coding: utf-8 -*-
+
+CubicWeb in Google AppEngine
+============================
+
+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
+
+Download the source
+-------------------
+
+- The `Google AppEngine SDK` can be downloaded from:
+ http://code.google.com/appengine/downloads.html
+
+
+Please follow instructions on how to install `CubicWeb` framework
+(:ref:`CubicWebInstallation`).
+
+Installation
+------------
+
+Once ``cubicweb-ctl`` is installed, then you can create a Google
+App Engine extension of our framework by running the command ::
+
+ cubicweb-ctl newgapp <myapp>
+
+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
+`CubicWeb` 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 <myapp>``, 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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`CubicWeb` 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
+'cubicweb'". 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 cubicweb-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 <http://localhost:8080/_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 <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
+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 <http://localhost:8080/?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 <http://localhost:8080/?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/ <http://localhost:8080>`_
+as a normal user.
+
+Unless you did something to change it, http://MYAPP_URL should be
+http://localhost:8080/
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/admin/index.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,35 @@
+.. -*- coding: utf-8 -*-
+
+.. _Part3:
+
+-------------------------
+Part III - Administration
+-------------------------
+
+This part is for installation and administration of the `CubicWeb` framework and
+applications based on that framework.
+
+.. toctree::
+ :maxdepth: 1
+
+ setup
+ create-instance
+ instance-config
+ site-config
+ multisources
+ ldap
+ gae
+
+
+
+RQL logs
+--------
+
+You can configure the `CubicWeb` application to keep a log
+of the queries executed against your database. To do so,
+edit the configuration file of your application
+``.../etc/cubicweb.d/myapp/all-in-one.conf`` and uncomment the
+variable ``query-log-file``::
+
+ # web application query log file
+ query-log-file=/tmp/rql-myapp.log
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/admin/instance-config.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,163 @@
+.. -*- coding: utf-8 -*-
+
+
+Configure an instance
+=====================
+
+While creating an instance, a configuration file is generated in::
+
+ $ (CW_REGISTRY) / <instance> / <configuration name>.conf
+
+For example::
+
+ /etc/cubicweb.d/JPL/all-in-one.conf
+
+It is a simple text file format INI. In the following description,
+each option name is prefixed with its own section and followed by its
+default value if necessary, e.g. "`<section>.<option>` [value]."
+
+
+Configuring the Web server
+--------------------------
+:`web.auth-model` [cookie]:
+ authentication mode, cookie or http
+:`web.realm`:
+ realm of the application in http authentication mode
+:`web.http-session-time` [0]:
+ period of inactivity of an HTTP session before it closes automatically.
+ Duration in seconds, 0 meaning no expiration (or more exactly at the
+ closing of the browser client)
+
+:`main.anonymous-user`, `main.anonymous-password`:
+ login and password to use to connect to the RQL server with
+ HTTP anonymous connection. CWUser account should exist.
+
+:`main.base-url`:
+ url base site to be used to generate the urls of web pages
+
+Https configuration
+```````````````````
+It is possible to make a site accessible for anonymous http connections
+and https for authenticated users. This requires to
+use apache (for example) for redirection and the variable `main.https-url`
+of configuration file.
+
+:Example:
+
+ For an apache redirection of a site accessible via `http://localhost/demo`
+ and `https://localhost/demo` and actually running on port 8080, it
+ takes to the http:::
+
+ RewriteCond %(REQUEST_URI) ^/demo
+ RewriteRule ^/demo$ /demo/
+ RewriteRule ^/demo/(.*) http://127.0.0.1:8080/$1 [L,P]
+
+ and for the https:::
+
+ RewriteCond %(REQUEST_URI) ^/ demo
+ RewriteRule ^/demo$/demo/
+ RewriteRule ^/demo/(.*) http://127.0.0.1:8080/https/$1 [L,P]
+
+
+ and we will file in the all-in-one.conf of the instance:::
+
+ base-url = http://localhost/demo
+ https-url = `https://localhost/demo`
+
+Setting up the web
+--------------------------------
+:`web.embed-allowed`:
+ regular expression matching sites which could be "embedded" in
+ the site (controllers 'embed')
+:`web.submit-url`:
+ url where the bugs encountered in the application can be mailed to
+
+
+RQL server configuration
+------------------------
+:`main.host`:
+ host name if it can not be detected correctly
+:`main.pid-file`:
+ file where will be written the server pid
+:`main.uid`:
+ user account to use for launching the server when it is
+ root launched by init
+:`main.session-time [30*60]`:
+ timeout of a RQL session
+:`main.query-log-file`:
+ file where all requests RQL executed by the server are written
+
+
+Pyro configuration for the instance
+-----------------------------------
+Web server side:
+
+:`pyro-client.pyro-application-id`:
+ pyro identifier of RQL server (e.g. the instance name)
+
+RQL server side:
+
+:`pyro-server.pyro-port`:
+ pyro port number. If none is specified, a port is assigned
+ automatically.
+
+RQL and web servers side:
+
+:`pyro-name-server.pyro-ns-host`:
+ hostname hosting pyro server name. If no value is
+ specified, it is located by a request from broadcast
+:`pyro-name-server.pyro-ns-group` [cubicweb]:
+ pyro group in which to save the application
+
+
+Configuring e-mail
+------------------
+RQL and web server side:
+
+:`email.mangle-mails [no]`:
+ indicates whether the email addresses must be displayed as is or
+ transformed
+
+RQL server side:
+
+:`email.smtp-host [mail]`:
+ hostname hosting the SMTP server to use for outgoing mail
+:`email.smtp-port [25]`:
+ SMTP server port to use for outgoing mail
+:`email.sender-name`:
+ name to use for outgoing mail of the application
+:`email.sender-addr`:
+ address for outgoing mail of the application
+:`email.default dest-addrs`:
+ destination addresses by default, if used by the configuration of the
+ dissemination of the model (separated by commas)
+:`email.supervising-addrs`:
+ destination addresses of e-mails of supervision (separated by
+ commas)
+
+
+Configuring logging
+-------------------
+:`main.log-threshold`:
+ level of filtering messages (DEBUG, INFO, WARNING, ERROR)
+:`main.log-file`:
+ file to write messages
+
+
+Configuring persistent properties
+---------------------------------
+Other configuration settings are in the form of entities `CWProperty`
+in the database. It must be edited via the web interface or by
+RQL queries.
+
+:`ui.encoding`:
+ Character encoding to use for the web
+:`navigation.short-line-size`: # XXX should be in ui
+ number of characters for "short" display
+:`navigation.page-size`:
+ maximum number of entities to show per results page
+:`navigation.related-limit`:
+ number of related entities to show up on primary entity view
+:`navigation.combobox-limit`:
+ number of entities unrelated to show up on the drop-down lists of
+ the sight on an editing entity view
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/admin/ldap.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,4 @@
+LDAP integration
+================
+
+XXX feed me
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/admin/multisources.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,4 @@
+Integrating some data from another instance
+===========================================
+
+XXX feed me
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/admin/setup.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,207 @@
+.. -*- coding: utf-8 -*-
+
+.. _SetUpEnv:
+
+===================================================
+Installation and set-up of a `CubicWeb` environment
+===================================================
+
+Installation of `Cubicweb` and its dependencies
+-----------------------------------------------
+
+`CubicWeb` is packaged for Debian and Ubuntu, but can be installed from source
+using a tarball or the Mercurial version control system.
+
+.. _DebianInstallation:
+
+Debian and Ubuntu packages
+```````````````````````````
+
+Depending on the distribution you are using, add the appropriate line to your list
+of sources (for example by editing ``/etc/apt/sources.list``).
+
+For Debian Lenny::
+
+ deb http://ftp.logilab.org/dists/ lenny/
+
+For Debian Sid::
+
+ deb http://ftp.logilab.org/dists/ sid/
+
+For Ubuntu Hardy::
+
+ deb http://ftp.logilab.org/dists/ hardy/
+
+
+You can now install the required packages with the following command::
+
+ apt-get update
+ apt-get install cubicweb cubicweb-dev
+
+`cubicweb` installs the framework itself, allowing you to create
+new applications.
+
+`cubicweb-dev` installs the development environment allowing you to
+develop new cubes.
+
+There is also a wide variety of cubes listed on http://www.cubicweb.org/Project available as debian packages and tarball.
+
+
+Install from source
+```````````````````
+
+You can download the archive containing the sources from our `ftp site`_ at::
+
+ http://ftp.logilab.org/pub/cubicweb/
+
+.. _`ftp site`: http://ftp.logilab.org/pub/cubicweb/
+
+or keep up to date with on-going development by using Mercurial and its forest
+extension::
+
+ hg fclone http://www.logilab.org/hg/forests/cubicweb
+
+See :ref:`MercurialPresentation` for more details about Mercurial.
+
+Postgres installation
+`````````````````````
+
+Please refer to the `Postgresql project online documentation`_.
+
+.. _`Postgresql project online documentation`: http://www.postgresql.org/
+
+You need to install the three following packages: `postgres-8.3`,
+`postgres-contrib-8.3` and `postgresql-plpython-8.3`.
+
+
+Then you can install:
+
+* `pyro` if you wish the repository to be accessible through Pyro
+ or if the client and the server are not running on the same machine
+ (in which case the packages will have to be installed on both
+ machines)
+
+* `python-ldap` if you plan to use a LDAP source on the server
+
+.. _ConfigurationEnv:
+
+Environment configuration
+-------------------------
+
+If you installed `CubicWeb` by cloning the Mercurial forest, then you
+will need to update the environment variable PYTHONPATH by adding
+the path to the forest ``cubicweb``:
+
+Add the following lines to either `.bashrc` or `.bash_profile` to configure
+your development environment ::
+
+ export PYTHONPATH=/full/path/to/cubicweb-forest
+
+If you installed the debian packages, no configuration is required.
+Your new cubes will be placed in `/usr/share/cubicweb/cubes` and
+your applications will be placed in `/etc/cubicweb.d`.
+
+To use others directories then you will have to configure the
+following environment variables as follows::
+
+ export CW_CUBES_PATH=~/lib/cubes
+ export CW_REGISTRY=~/etc/cubicweb.d/
+ export CW_INSTANCE_DATA=$CW_REGISTRY
+ export CW_RUNTIME=/tmp
+
+.. note::
+ The values given above are our suggestions but of course
+ can be different.
+
+
+Databases configuration
+-----------------------
+
+
+
+.. _ConfigurationPostgres:
+
+Postgres configuration
+``````````````````````
+
+.. note::
+ If you already have an existing cluster and postgres server
+ running, you do not need to execute the initilization step
+ of your Postgres database.
+
+* First, initialize the database Postgres with the command ``initdb``.
+ ::
+
+ $ initdb -D /path/to/pgsql
+
+ Once initialized, start the database server Postgres
+ with the command::
+
+ $ postgres -D /path/to/psql
+
+ If you cannot execute this command due to permission issues, please
+ make sure that your username has write access on the database.
+ ::
+
+ $ chown username /path/to/pgsql
+
+* The database authentication can be either set to `ident sameuser`
+ or `md5`.
+ If set to `md5`, make sure to use an existing user
+ of your database.
+ If set to `ident sameuser`, make sure that your
+ client's operating system user name has a matching user in
+ the database. If not, please do as follow to create a user::
+
+ $ su
+ $ su - postgres
+ $ createuser -s -P username
+
+ The option `-P` (for password prompt), will encrypt the password with
+ the method set in the configuration file ``pg_hba.conf``.
+ If you do not use this option `-P`, then the default value will be null
+ and you will need to set it with::
+
+ $ su postgres -c "echo ALTER USER username WITH PASSWORD 'userpasswd' | psql"
+
+ This login/password will be requested when you will create an
+ instance with `cubicweb-ctl create` to initialize the database of
+ your application.
+
+.. note::
+ The authentication method can be configured in ``pg_hba.conf``.
+
+
+.. FIXME Are these steps really necessary? It seemed to work without.
+
+* Installation of plain-text index extension ::
+
+ cat /usr/share/postgresql/8.3/contrib/tsearch2.sql | psql -U username template1
+
+* Installation of plpythonu language by default ::
+
+ createlang -U pgadmin plpythonu template1
+
+MySql configuration
+```````````````````
+Yout must add the following lines in /etc/mysql/my.cnf file::
+
+ transaction-isolation = READ-COMMITTED
+ default-storage-engine=INNODB
+ default-character-set=utf8
+ max_allowed_packet = 128M
+
+Pyro configuration
+------------------
+
+If you use Pyro, it is required to have a name server Pyro running on your
+network (by default it is detected by a broadcast request).
+
+To do so, you need to :
+
+* launch the server manually before starting cubicweb as a server with
+ `pyro-nsd start`
+
+* edit the file ``/etc/default/pyro-nsd`` so that the name server pyro
+ will be launched automatically when the machine fire up
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/admin/site-config.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,94 @@
+.. -*- coding: utf-8 -*-
+
+User interface for web site configuration
+=========================================
+
+.. image:: ../images/lax-book.03-site-config-panel.en.png
+
+This panel allows you to configure the appearance of your application site.
+Six menus are available and we will go through each of them to explain how
+to use them.
+
+Navigation
+~~~~~~~~~~
+This menu provides you a way to adjust some navigation options depending on
+your needs, such as the number of entities to display by page of results.
+Follows the detailled list of available options :
+
+* navigation.combobox-limit : maximum number of entities to display in related
+ combo box (sample format: 23)
+* navigation.page-size : maximum number of objects displayed by page of results
+ (sample format: 23)
+* navigation.related-limit : maximum number of related entities to display in
+ the primary view (sample format: 23)
+* navigation.short-line-size : maximum number of characters in short description
+ (sample format: 23)
+
+UI
+~~
+This menu provides you a way to customize the user interface settings such as
+date format or encoding in the produced html.
+Follows the detailled list of available options :
+
+* ui.date-format : how to format date in the ui ("man strftime" for format description)
+* ui.datetime-format : how to format date and time in the ui ("man strftime" for format
+ description)
+* ui.default-text-format : default text format for rich text fields.
+* ui.encoding : user interface encoding
+* ui.fckeditor :should html fields being edited using fckeditor (a HTML WYSIWYG editor).
+ You should also select text/html as default text format to actually get fckeditor.
+* ui.float-format : how to format float numbers in the ui
+* ui.language : language of the user interface
+* ui.main-template : id of main template used to render pages
+* ui.site-title : site title, which is displayed right next to the logo in the header
+* ui.time-format : how to format time in the ui ("man strftime" for format description)
+
+
+Actions
+~~~~~~~
+This menu provides a way to configure the context in which you expect the actions
+to be displayed to the user and if you want the action to be visible or not.
+You must have notice that when you view a list of entities, an action box is
+available on the left column which display some actions as well as a drop-down
+menu for more actions.
+
+The context available are :
+
+* mainactions : actions listed in the left box
+* moreactions : actions listed in the `more` menu of the left box
+* addrelated : add actions listed in the left box
+* useractions : actions listed in the first section of drop-down menu
+ accessible from the right corner user login link
+* siteactions : actions listed in the second section of drop-down menu
+ accessible from the right corner user login link
+* hidden : select this to hide the specific action
+
+Boxes
+~~~~~
+The application has already a pre-defined set of boxes you can use right away.
+This configuration section allows you to place those boxes where you want in the
+application interface to customize it.
+
+The available boxes are :
+
+* actions box : box listing the applicable actions on the displayed data
+
+* boxes_blog_archives_box : box listing the blog archives
+
+* possible views box : box listing the possible views for the displayed data
+
+* rss box : RSS icon to get displayed data as a RSS thread
+
+* search box : search box
+
+* startup views box : box listing the configuration options available for
+ the application site, such as `Preferences` and `Site Configuration`
+
+Components
+~~~~~~~~~~
+[WRITE ME]
+
+Contextual components
+~~~~~~~~~~~~~~~~~~~~~
+[WRITE ME]
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/annexes/cookbook.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,64 @@
+.. -*- coding: utf-8 -*-
+
+Cook book
+=========
+
+We gathered together some of our tricks and scripts that could make
+life easier.
+
+
+* How to import LDAP users in `CubicWeb`?
+
+ Here is a very useful script which enables you to import LDAP users
+ into your `CubicWeb` application by running the following: ::
+
+
+ import os
+ import pwd
+ import sys
+
+ from logilab.common.db import get_connection
+
+ def getlogin():
+ """avoid usinng os.getlogin() because of strange tty / stdin problems
+ (man 3 getlogin)
+ Another solution would be to use $LOGNAME, $USER or $USERNAME
+ """
+ return pwd.getpwuid(os.getuid())[0]
+
+
+ try:
+ database = sys.argv[1]
+ except IndexError:
+ print 'USAGE: python ldap2system.py <database>'
+ sys.exit(1)
+
+ if raw_input('update %s db ? [y/n]: ' % database).strip().lower().startswith('y'):
+ cnx = get_connection(user=getlogin(), database=database)
+ cursor = cnx.cursor()
+
+ insert = ('INSERT INTO euser (creation_date, eid, modification_date, login, firstname, surname, last_login_time, upassword) '
+ "VALUES (%(mtime)s, %(eid)s, %(mtime)s, %(login)s, %(firstname)s, %(surname)s, %(mtime)s, './fqEz5LeZnT6');")
+ update = "UPDATE entities SET source='system' WHERE eid=%(eid)s;"
+ cursor.execute("SELECT eid,type,source,extid,mtime FROM entities WHERE source!='system'")
+ for eid, type, source, extid, mtime in cursor.fetchall():
+ if type != 'CWUser':
+ print "don't know what to do with entity type", type
+ continue
+ if source != 'ldapuser':
+ print "don't know what to do with source type", source
+ continue
+ ldapinfos = dict(x.strip().split('=') for x in extid.split(','))
+ login = ldapinfos['uid']
+ firstname = ldapinfos['uid'][0].upper()
+ surname = ldapinfos['uid'][1:].capitalize()
+ if login != 'jcuissinat':
+ args = dict(eid=eid, type=type, source=source, login=login,
+ firstname=firstname, surname=surname, mtime=mtime)
+ print args
+ cursor.execute(insert, args)
+ cursor.execute(update, args)
+
+ cnx.commit()
+ cnx.close()
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/annexes/cubicweb-ctl.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,122 @@
+.. -*- coding: utf-8 -*-
+
+.. _cubicweb-ctl:
+
+``cubicweb-ctl`` tool
+=====================
+
+`cubicweb-ctl` is the swiss knife to manage `CubicWeb` instances.
+The general syntax is ::
+
+ cubicweb-ctl <command> [options command] <arguments commands>
+
+To view available commands ::
+
+ cubicweb-ctl
+ cubicweb-ctl --help
+
+Please note that the commands available depends on the `CubicWeb` packages
+and cubes that have been installed.
+
+To view the help menu on specific command ::
+
+ cubicweb-ctl <command> --help
+
+Command to create a cube
+------------------------
+
+* ``newcube``, create a new cube on the file system based on the name
+ given in the parameters. This command create a cube from an application
+ skeleton that includes default files required for debian packaging.
+
+
+Command to create an instance
+-----------------------------
+* ``create``, creates the files for the instance configuration
+* ``db-create``, creates the system database of an instance (tables and
+ extensions only)
+* ``db-init``, initializes the system database of an instance
+ (schema, groups, users, workflows...)
+
+By default, those three commandes are encapsulated in ``create`` so
+that they can be executed consecutively.
+
+Command to create an instance for Google AppEngine datastore source
+-------------------------------------------------------------------
+* ``newgapp``, creates the configuration files for an instance
+
+This command needs to be followed by the commands responsible for
+the database initialization. As those are specific to the `datastore`,
+specific Google AppEgine database, they are not available for now
+in cubicweb-ctl, but they are available in the instance created.
+
+For more details, please see :ref:`gaecontents` .
+
+Commands to control instances
+-----------------------------
+* ``start``, starts one or more or all instances
+* ``stop``, stops one or more or all instances
+* ``restart``, restarts one or more or all instances
+* ``status``, returns the status of the instance
+
+Commands to maintain instances
+------------------------------
+* ``upgrade``, launches the existing instances migration when a new version
+ of `CubicWeb` or the cubes installed is available
+* ``shell``, opens a migration shell for manual maintenance of the instance
+* ``db-dump``, creates a dump of the system database
+* ``db-restore``, restores a dump of the system database
+* ``db-check``, checks data integrity of an instance. If the automatic correction
+ is activated, it is recommanded to create a dump before this operation.
+* ``schema-sync``, synchronizes the persistent schema of an instance with
+ the application schema. It is recommanded to create a dump before this operation.
+
+Commands to maintain i18n catalogs
+----------------------------------
+* ``i18nlibupdate``, regenerates messages catalogs of the `CubicWeb` library
+* ``i18nupdate``, regenerates the messages catalogs of a cube
+* ``i18ncompile``, recompiles the messages catalogs of an instance.
+ This is automatically done while upgrading.
+
+See also chapter :ref:`internationalisation`.
+
+Other commands
+--------------
+* ``list``, provides a list of the available configuration, cubes
+ and instances.
+* ``delete``, deletes an instance (configuration files and database)
+
+
+Create an instance from an existing cube
+````````````````````````````````````````
+
+To create an instance from an existing cube, execute the following
+command ::
+
+ cubicweb-ctl create <cube_name> <instance_name>
+
+This command will create the configuration files of an instance in
+``~/etc/cubicweb.d/<instance_name>``.
+The tool ``cubicweb-ctl`` allows you to execute the command ``db-create``
+and ``db-init`` when you run ``create`` so that you can complete an
+instance creation in a single command.
+
+If you decide not to execut those commands while ``cubicweb-ctl create``,
+then you will have to execute them seperately(``cubicweb-ctl db-create``,
+``cubicweb-ctl db-init`` ) otherwise your installation will not be complete
+and you will not be able to launch your instance.
+
+
+Creation of an instance from a new cube
+```````````````````````````````````````
+
+Create first your new cube cube ::
+
+ cubicweb-ctl newcube <mycube>
+
+This will create a new cube in ``/path/to/forest/cubicweb/cubes/<mycube>``
+for a Mercurial forest installation, or in ``/usr/share/cubicweb/cubes``
+for a debian packages installation, and then create an instance as
+explained just above.
+
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/annexes/faq.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,244 @@
+.. -*- coding: utf-8 -*-
+
+Frequently Asked Questions
+==========================
+
+[XXX 'copy answer from forum' means reusing text from
+http://groups.google.com/group/google-appengine/browse_frm/thread/c9476925f5f66ec6
+and
+http://groups.google.com/group/google-appengine/browse_frm/thread/d791ce17e2716147/eb078f8cfe8426e0
+and
+http://groups.google.com/group/google-appengine/browse_frm/thread/f48cf6099973aef5/c28cd6934dd72457
+]
+
+* Why does not CubicWeb have a template language ?
+
+ There are enough template languages out there. You can use your
+ preferred template language if you want. [explain how to use a
+ template language]
+
+ `CubicWeb` does not define its own templating language as this was
+ not our goal. Based on our experience, we realized that
+ we could gain productivity by letting designers use design tools
+ and developpers develop without the use of the templating language
+ as an intermediary that could not be anyway efficient for both parties.
+ Python is the templating language that we use in `CubicWeb`, but again,
+ it does not prevent you from using a templating language.
+
+ The reason template languages are not used in this book is that
+ experience has proved us that using pure python was less cumbersome.
+
+* Why do you think using pure python is better than using a template language ?
+
+ Python is an Object Oriented Programming language and as such it
+ already provides a consistent and strong architecture and syntax
+ a templating language would not reach.
+
+ When doing development, you need a real language and template
+ languages are not real languages.
+
+ Using Python enables developing applications for which code is
+ easier to maintain with real functions/classes/contexts
+ without the need of learning a new dialect. By using Python,
+ we use standard OOP techniques and this is a key factor in a
+ robust application.
+
+* Why do you use the GPL license to prevent me from doing X ?
+
+ GPL means that *if* you redistribute your application, you need to
+ redistribute it *and* the changes you made *and* the code _linked_
+ to it under the GPL licence.
+
+ Publishing a web site has nothing to do with redistributing
+ source code. A fair amount of companies use modified GPL code
+ for internal use. And someone could publish a `CubicWeb` component
+ under a BSD licence for others to plug into a GPL framework without
+ any problem. The only thing we are trying to prevent here is someone
+ taking the framework and packaging it as closed source to his own
+ clients.
+
+
+* CubicWeb looks pretty recent. Is it stable ?
+
+ It is constantly evolving, piece by piece. The framework has
+ evolved over the past seven years and data has been migrated from
+ one schema to the other ever since. There is a well-defined way to
+ handle data and schema migration.
+
+* Why is the RQL query language looking similar to X ?
+
+ It may remind you of SQL but it is higher level than SQL, more like
+ SPARQL. Except that SPARQL did not exist when we started the project.
+ Having SPARQL has a query language has been in our backlog for years.
+
+ That RQL language is what is going to make a difference with django-
+ like frameworks for several reasons.
+
+ 1. accessing data is *much* easier with it. One can write complex
+ queries with RQL that would be tedious to define and hard to maintain
+ using an object/filter suite of method calls.
+
+ 2. it offers an abstraction layer allowing your applications to run
+ on multiple back-ends. That means not only various SQL backends
+ (postgresql, sqlite, mysql), but also multiple databases at the
+ same time, and also non-SQL data stores like LDAP directories and
+ subversion/mercurial repositories (see the `vcsfile`
+ component). Google App Engine is yet another supported target for
+ RQL.
+
+[copy answer from forum, explain why similar to sparql and why better
+ than django and SQL]
+
+* which ajax library
+
+ [we use jquery and things on top of that]
+
+* `Error while publishing rest text ...`
+
+ While modifying the description of an entity, you get an error message in
+ the application `Error while publishing ...` for Rest text and plain text.
+ The server returns a traceback like as follows ::
+
+ 2008-10-06 15:05:08 - (cubicweb.rest) ERROR: error while publishing ReST text
+ Traceback (most recent call last):
+ File "/home/user/src/blogdemo/cubicweb/common/rest.py", line 217, in rest_publish
+ File "/usr/lib/python2.5/codecs.py", line 817, in open
+ file = __builtin__.open(filename, mode, buffering)
+ TypeError: __init__() takes at most 3 arguments (4 given)
+
+
+ This can be fixed by applying the patch described in :
+ http://code.google.com/p/googleappengine/issues/detail?id=48
+
+* What are hooks used for?
+
+ Hooks are executed around (actually before or after) events. The
+ most common events are data creation, update and deletion. They
+ permit additional constraint checking (those not expressible at the
+ schema level), pre and post computations depending on data
+ movements.
+
+ As such, they are a vital part of the framework.
+
+ Other kinds of hooks, called Operations, are available
+ for execution just before commit.
+
+* When should you define an HTML template rather than define a graphical component?
+
+ An HTML template cannot contain code, hence it is only about static
+ content. A component is made of code and operations that apply on a
+ well defined context (request, result set). It enables much more
+ dynamic views.
+
+* What is the difference between `AppRsetObject` and `AppObject` ?
+
+ `AppRsetObject` instances are selected on a request and a result
+ set. `AppObject` instances are directly selected by id.
+
+* How to update a database after a schema modification?
+
+ It depends on what has been modified in the schema.
+
+ * Update of an attribute permissions and properties:
+ ``synchronize_eschema('MyEntity')``.
+
+ * Update of a relation permissions and properties:
+ ``synchronize_rschema('MyRelation')``.
+
+ * Add an attribute: ``add_attribute('MyEntityType', 'myattr')``.
+
+ * Add a relation: ``add_relation_definition('SubjRelation', 'MyRelation', 'ObjRelation')``.
+
+
+* How to create an anonymous user?
+
+ This allows to bypass authentication for your site. In the
+ ``all-in-one.conf`` file of your instance, define the anonymous user
+ as follows ::
+
+ # login of the CubicWeb user account to use for anonymous user (if you want to
+ # allow anonymous)
+ anonymous-user=anon
+
+ # password of the CubicWeb user account matching login
+ anonymous-password=anon
+
+ You also must ensure that this `anon` user is a registered user of
+ the DB backend. If not, you can create through the administation
+ interface of your instance by adding a user with the role `guests`.
+ This could be the admin account (for development
+ purposes, of course).
+
+.. note::
+ While creating a new instance, you can decide to allow access
+ to anonymous user, which will automatically execute what is
+ decribed above.
+
+
+* How to change the application logo?
+
+ There are two ways of changing the logo.
+
+ 1. The easiest way to use a different logo is to replace the existing
+ ``logo.png`` in ``myapp/data`` by your prefered icon and refresh.
+ By default all application will look for a ``logo.png`` to be
+ rendered in the logo section.
+
+ .. image:: ../images/lax-book.06-main-template-logo.en.png
+
+ 2. In your cube directory, you can specify which file to use for the logo.
+ This is configurable in ``mycube/data/external_resources``: ::
+
+ LOGO = DATADIR/path/to/mylogo.gif
+
+ where DATADIR is ``mycubes/data``.
+
+* How to configure LDAP source?
+
+ Your instance's sources are defined in ``/etc/cubicweb.d/myapp/sources``.
+ Configuring an LDAP source is about declaring that source in your
+ instance configuration file such as: ::
+
+ [ldapuser]
+ adapter=ldapuser
+ # ldap host
+ host=myhost
+ # base DN to lookup for usres
+ user-base-dn=ou=People,dc=mydomain,dc=fr
+ # user search scope
+ user-scope=ONELEVEL
+ # classes of user
+ user-classes=top,posixAccount
+ # attribute used as login on authentication
+ user-login-attr=uid
+ # name of a group in which ldap users will be by default
+ user-default-group=users
+ # map from ldap user attributes to cubicweb attributes
+ user-attrs-map=gecos:email,uid:login
+
+ Any change applied to configuration file requires to restart your
+ application.
+
+* I get NoSelectableObject exceptions: how do I debug selectors ?
+
+ You just need to put the appropriate context manager around view/component
+ selection: ::
+
+ from cubicweb.common.selectors import traced_selection
+ with traced_selection():
+ comp = self.vreg.select_object('contentnavigation', 'wfhistory',
+ self.req, rset, context='navcontentbottom')
+
+ This will yield additional WARNINGs, like this: ::
+
+ 2009-01-09 16:43:52 - (cubicweb.selectors) WARNING: selector one_line_rset returned 0 for <class 'cubicweb.web.views.basecomponents.WFHistoryVComponent'>
+
+* How to format an entity date attribute?
+
+ If your schema has an attribute of type Date or Datetime, you might
+ want to format it. First, you should define your preferred format using
+ the site configuration panel ``http://appurl/view?vid=systemepropertiesform``
+ and then set ``ui.date`` and/or ``ui.datetime``.
+ Then in the view code, use::
+
+ self.format_date(entity.date_attribute)
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/annexes/index.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,26 @@
+.. -*- coding: utf-8 -*-
+
+.. _Part4:
+
+--------------------
+Part IV - Appendixes
+--------------------
+
+The following chapters are reference material.
+
+.. toctree::
+ :maxdepth: 1
+
+ faq
+ cookbook
+ cubicweb-ctl
+ rql/index
+ mercurial
+
+(X)HTML tricks to apply
+-----------------------
+
+Some web browser (Firefox for example) are not happy with empty `<div>`
+(by empty we mean that there is no content in the tag, but there
+could be attributes), so we should always use `<div></div>` even if
+it is empty and not use `<div/>`.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/annexes/mercurial.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,133 @@
+.. -*- coding: utf-8 -*-
+
+.. _MercurialPresentation:
+
+Introducing Mercurial
+=====================
+
+Introduction
+````````````
+Mercurial_ manages a distributed repository containing revisions
+trees (each revision indicates the changes required to obtain the
+next, and so on). Locally, we have a repository containing revisions
+tree, and a working directory. It is possible
+to put in its working directory, one of the versions of its local repository,
+modify and then push it in its repository.
+It is also possible to get revisions from another repository or to export
+its own revisions from the local repository to another repository.
+
+.. _Mercurial: http://www.selenic.com/mercurial/
+
+In contrast to CVS/Subversion, we usually create a repository by
+project to manage.
+
+In a collaborative development, we usually create a central repository
+accessible to all developers of the project. These central repository is used
+as a reference. According to its needs, then everyone can have a local repository,
+that you will have to synchronize with the central repository from time to time.
+
+
+Major commands
+``````````````
+* Create a local repository::
+
+ hg clone ssh://myhost//home/src/repo
+
+* See the contents of the local repository (graphical tool in Tk)::
+
+ hgview
+
+* Add a sub-directory or file in the current directory::
+
+ hg add subdir
+
+* Move to the working directory a specific revision (or last
+ revision) from the local repository::
+
+ hg update [identifier-revision]
+ hg up [identifier-revision]
+
+* Get in its local repository, the tree of revisions contained in a
+ remote repository (this does not change the local directory)::
+
+ hg pull ssh://myhost//home/src/repo
+ hg pull -u ssh://myhost//home/src/repo # equivalent to pull + update
+
+* See what are the heads of branches of the local repository if a `pull`
+ returned a new branch::
+
+ hg heads
+
+* Submit the working directory in the local repository (and create a new
+ revision)::
+
+ hg commit
+ hg ci
+
+* Merge with the mother revision of local directory, another revision from
+ the local respository (the new revision will be then two mothers
+ revisions)::
+
+ hg merge identifier-revision
+
+* Export to a remote repository, the tree of revisions in its content
+ local respository (this does not change the local directory)::
+
+ hg push ssh://myhost//home/src/repo
+
+* See what local revisions are not in another repository::
+
+ hg outgoing ssh://myhost//home/src/repo
+
+* See what are the revisions of a repository not found locally::
+
+ hg incoming ssh://myhost//home/src/repo
+
+* See what is the revision of the local repository which has been taken out
+ from the working directory and amended::
+
+ hg parent
+
+* See the differences between the working directory and the mother revision
+ of the local repository, possibly to submit them in the local repository::
+
+ hg diff
+ hg commit-tool
+ hg ct
+
+
+Best Practices
+``````````````
+* Remember to `hg pull -u` regularly, and particularly before
+ a `hg commit`.
+
+* Remember to `hg push` when your repository contains a version
+ relatively stable of your changes.
+
+* If a `hg pull -u` created a new branch head:
+
+ 1. find its identifier with `hg head`
+ 2. merge with `hg merge`
+ 3. `hg ci`
+ 4. `hg push`
+
+Installation of the forest extension
+````````````````````````````````````
+
+Set up the forest extension by getting a copy of the sources
+from http://hg.akoha.org/hgforest/ and adding the following
+lines to your ``~/.hgrc``: ::
+
+ [extensions]
+ hgext.forest=
+ # or, if forest.py is not in the hgext dir:
+ # forest=/path/to/forest.py
+
+
+More information
+````````````````
+
+For more information about Mercurial, please refer to the Mercurial project online documentation_.
+
+.. _documentation: http://www.selenic.com/mercurial/wiki/
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/annexes/rql/implementation.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,169 @@
+
+
+Implementation
+--------------
+BNF grammar
+~~~~~~~~~~~
+
+The terminal elements are in capital letters, non-terminal in lowercase.
+The value of the terminal elements (between quotes) is a Python regular
+expression.
+::
+
+ statement:: = (select | delete | insert | update) ';'
+
+
+ # select specific rules
+ select ::= 'DISTINCT'? E_TYPE selected_terms restriction? group? sort?
+
+ selected_terms ::= expression ( ',' expression)*
+
+ group ::= 'GROUPBY' VARIABLE ( ',' VARIABLE)*
+
+ sort ::= 'ORDERBY' sort_term ( ',' sort_term)*
+
+ sort_term ::= VARIABLE sort_method =?
+
+ sort_method ::= 'ASC' | 'DESC'
+
+
+ # delete specific rules
+ delete ::= 'DELETE' (variables_declaration | relations_declaration) restriction?
+
+
+ # insert specific rules
+ insert ::= 'INSERT' variables_declaration ( ':' relations_declaration)? restriction?
+
+
+ # update specific rules
+ update ::= 'SET' relations_declaration restriction
+
+
+ # common rules
+ variables_declaration ::= E_TYPE VARIABLE (',' E_TYPE VARIABLE)*
+
+ relations_declaration ::= simple_relation (',' simple_relation)*
+
+ simple_relation ::= VARIABLE R_TYPE expression
+
+ restriction ::= 'WHERE' relations
+
+ relations ::= relation (LOGIC_OP relation)*
+ | '(' relations')'
+
+ relation ::= 'NOT'? VARIABLE R_TYPE COMP_OP? expression
+ | 'NOT'? R_TYPE VARIABLE 'IN' '(' expression (',' expression)* ')'
+
+ expression ::= var_or_func_or_const (MATH_OP var_or_func_or_const) *
+ | '(' expression ')'
+
+ var_or_func_or_const ::= VARIABLE | function | constant
+
+ function ::= FUNCTION '(' expression ( ',' expression) * ')'
+
+ constant ::= KEYWORD | STRING | FLOAT | INT
+
+ # tokens
+ LOGIC_OP ::= ',' | 'OR' | 'AND'
+ MATH_OP ::= '+' | '-' | '/' | '*'
+ COMP_OP ::= '>' | '>=' | '=' | '<=' | '<' | '~=' | 'LIKE'
+
+ FUNCTION ::= 'MIN' | 'MAX' | 'SUM' | 'AVG' | 'COUNT' | 'UPPER' | 'LOWER'
+
+ VARIABLE ::= '[A-Z][A-Z0-9]*'
+ E_TYPE ::= '[A-Z]\w*'
+ R_TYPE ::= '[a-z_]+'
+
+ KEYWORD ::= 'TRUE' | 'FALSE' | 'NULL' | 'TODAY' | 'NOW'
+ STRING ::= "'([^'\]|\\.)*'" |'"([^\"]|\\.)*\"'
+ FLOAT ::= '\d+\.\d*'
+ INT ::= '\d+'
+
+
+Internal representation (syntactic tree)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The tree research does not contain the selected variables
+(e.g. there is only what follows "WHERE").
+
+The insertion tree does not contain the variables inserted or relations
+defined on these variables (e.g. there is only what follows "WHERE").
+
+The removal tree does not contain the deleted variables and relations
+(e.g. there is only what follows the "WHERE").
+
+The update tree does not contain the variables and relations updated
+(e.g. there is only what follows the "WHERE").
+
+::
+
+ Select ((Relationship | And | Or)?, Group?, Sort?)
+ Insert (Relations | And | Or)?
+ Delete (Relationship | And | Or)?
+ Update (Relations | And | Or)?
+
+ And ((Relationship | And | Or), (Relationship | And | Or))
+ Or ((Relationship | And | Or), (Relationship | And | Or))
+
+ Relationship ((VariableRef, Comparison))
+
+ Comparison ((Function | MathExpression | Keyword | Constant | VariableRef) +)
+
+ Function (())
+ MathExpression ((MathExpression | Keyword | Constant | VariableRef), (MathExpression | Keyword | Constant | VariableRef))
+
+ Group (VariableRef +)
+ Sort (SortTerm +)
+ SortTerm (VariableRef +)
+
+ VariableRef ()
+ Variable ()
+ Keyword ()
+ Constant ()
+
+
+Known limitations
+~~~~~~~~~~~~~~~~~
+
+- The current implementation does not support linking two relations of type 'is'
+ with a OR. I do not think that the negation is supported on this type of
+ relation (XXX FIXME to be confirmed).
+
+- Relations defining the variables must be left to those using them. For
+ example::
+
+ Point P where P abs X, P ord Y, P value X+Y
+
+ is valid, but::
+
+ Point P where P abs X, P value X+Y, P ord Y
+
+ is not.
+
+- missing proper explicit type conversion, COALESCE and certainly other things...
+
+- writing a rql query require knowledge of the schema used (with real relation
+ names and entities, not those viewing in the user interface). On the other
+ hand, we can not really bypass that, and it is the job of a user interface to
+ hide the RQL.
+
+
+Topics
+~~~~~~
+
+It would be convenient to express the schema matching
+relations (non-recursive rules)::
+
+ Document class Type <-> Document occurence_of Fiche class Type
+ Sheet class Type <-> Form collection Collection class Type
+
+Therefore 1. becomes::
+
+ Document X where
+ X class C, C name 'Cartoon'
+ X owned_by U, U login 'syt'
+ X available true
+
+I'm not sure that we should handle this at RQL level ...
+
+There should also be a special relation 'anonymous'.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/annexes/rql/index.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,12 @@
+Relation Query Language (RQL)
+=============================
+
+This chapter describes the Relation Query Language syntax and its implementation in CubicWeb.
+
+.. toctree::
+ :maxdepth: 1
+
+ intro
+ language
+ dbapi
+ implementation
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/annexes/rql/intro.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,66 @@
+
+Introduction
+------------
+
+Goals of RQL
+~~~~~~~~~~~~
+
+The goal is to have a language emphasizing the way of browsing
+relations. As such, attributes will be regarded as cases of
+special relations (in terms of implementation, the language
+user should see virtually no difference between an attribute and a
+relation).
+
+RQL is inspired by SQL but is the highest level. A knowledge of the
+`CubicWeb` schema defining the application is necessary.
+
+Comparison with existing languages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+SQL
+```
+RQL builds on the features of SQL but is at a higher level
+(the current implementation of RQL generates SQL). For that it is limited
+to the way of browsing relations and introduces variables.
+The user does not need to know the model underlying SQL, but the `CubicWeb`
+schema defining the application.
+
+Versa
+`````
+We should look in more detail, but here are already some ideas for
+the moment ... Versa_ is the language most similar to what we wanted
+to do, but the model underlying data being RDF, there is some
+number of things such as namespaces or handling of the RDF types which
+does not interest us. On the functionality level, Versa_ is very comprehensive
+including through many functions of conversion and basic types manipulation,
+which may need to be guided at one time or another.
+Finally, the syntax is a little esoteric.
+
+Sparql
+``````
+The query language most similar to RQL is SPARQL_, defined by the W3C to serve
+for the semantic web.
+
+
+The different types of queries
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Search (`Any`)
+ Extract entities and attributes of entities.
+
+Insert entities (`INSERT`)
+ Insert new entities or relations in the database.
+ It can also directly create relationships for the newly created entities.
+
+Update entities, create relations (`SET`)
+ Update existing entities in the database,
+ or create relations between existing entities.
+
+Delete entities or relationship (`DELETE`)
+ Remove entities or relations existing in the database.
+
+
+
+
+.. _Versa: http://uche.ogbuji.net/tech/rdf/versa/
+.. _SPARQL: http://www.w3.org/TR/rdf-sparql-query/
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/annexes/rql/language.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,377 @@
+.. -*- coding: utf-8 -*-
+
+.. _RQL:
+
+RQL syntax
+----------
+
+Reserved keywords
+~~~~~~~~~~~~~~~~~
+The keywords are not case sensitive.
+
+::
+
+ DISTINCT, INSERT, SET, DELETE,
+ WHERE, AND, OR, NOT, EXISTS,
+ IN, LIKE, UNION, WITH, BEING,
+ TRUE, FALSE, NULL, TODAY, NOW,
+ LIMIT, OFFSET,
+ HAVING, GROUPBY, ORDERBY, ASC, DESC
+
+
+Variables and Typing
+~~~~~~~~~~~~~~~~~~~~
+
+With RQL, we do not distinguish between entities and attributes. The
+value of an attribute is considered an entity of a particular type (see
+below), linked to one (real) entity by a relation called the name of
+the attribute.
+
+Entities and values to browse and/or select are represented in
+the query by *variables* that must be written in capital letters.
+
+There is a special type **Any**, referring to a non specific type.
+
+We can restrict the possible types for a variable using the
+special relation **is**.
+The possible type(s) for each variable is derived from the schema
+according to the constraints expressed above and thanks to the relations between
+each variable.
+
+Built-in types
+``````````````
+
+The base types supported are string (between double or single quotes),
+integers or floats (the separator is '.'), dates and
+boolean. We expect to receive a schema in which types String,
+Int, Float, Date and Boolean are defined.
+
+* `String` (literal: between double or single quotes).
+* `Int`, `Float` (separator being'.').
+* `Date`, `Datetime`, `Time` (literal: string YYYY/MM/DD [hh:mm] or keywords
+ `TODAY` and `NOW`).
+* `Boolean` (keywords `TRUE` and `FALSE`).
+* `Keyword` NULL.
+
+
+Operators
+~~~~~~~~~
+
+Logical Operators
+`````````````````
+::
+
+ AND, OR, NOT, ','
+
+ ',' is equivalent to 'AND' but with the smallest among the priority
+ of logical operators (see :ref:`PriorityOperators`).
+
+Mathematical Operators
+````````````````````
+::
+
+ +, -, *, /
+
+Comparison operators
+````````````````````
+::
+
+ =, <, <=, >=, >, ~=, IN, LIKE
+
+* The operator `=` is the default operator.
+
+* The operator `LIKE` equivalent to `~=` can be used with the
+ special character `%` in a string to indicate that the chain
+ must start or finish by a prefix/suffix:
+ ::
+
+ Any X WHERE X name ~= 'Th%'
+ Any X WHERE X name LIKE '%lt'
+
+* The operator `IN` provides a list of possible values:
+ ::
+
+ Any X WHERE X name IN ( 'chauvat', 'fayolle', 'di mascio', 'thenault')
+
+
+XXX nico: "A trick <> 'bar'" wouldn't it be more convenient than
+"NOT A trick 'bar'" ?
+
+.. _PriorityOperators:
+
+Operators priority
+``````````````````
+
+1. '*', '/'
+
+2. '+', '-'
+
+3. 'not'
+
+4 'and'
+
+5 'or'
+
+6 ','
+
+
+Search Query
+~~~~~~~~~~~~
+
+ [ `DISTINCT`] <entity type> V1 (, V2) \ *
+ [ `GROUPBY` V1 (V2) \*] [ `ORDERBY` <orderterms>]
+ [ `LIMIT` <value>] [ `OFFSET` <value>]
+ [ `WHERE` <restriction>]
+ [ `WITH` V1 (, V2) \ * BEING (<query>)]
+ [ `HAVING` <restriction>]
+ [ `UNION` <query>]
+
+:entity type:
+ Type of selected variables.
+ The special type `Any` is equivalent to not specify a type.
+:restriction:
+ list of conditions to test successively
+ `V1 relation V2 | <static value>`
+:orderterms:
+ Definition of the selection order: variable or column number followed by
+ sorting method ( `ASC`, `DESC`), ASC is the default.
+:note for grouped queries:
+ For grouped queries (e.g., a clause `GROUPBY`), all
+ selected variables must be aggregated or grouped.
+
+
+Sorting and groups
+``````````````````
+
+- For grouped queries (e.g. with a GROUPBY clause), all
+ selected variables should be grouped.
+
+- To group and/or sort by attributes, we can do: "X,L user U, U
+ login L GROUPBY L, X ORDERBY L"
+
+- If the sorting method (SORT_METHOD) is not specified, then the sorting is
+ ascendant.
+
+- Aggregate Functions: COUNT, MIN, MAX, AVG, SUM
+
+
+Negation
+````````
+
+* A query such as `Document X WHERE NOT X owned_by U` means "the
+ documents have no relation `owned_by`".
+* But the query `Document X WHERE NOT X owned_by U, U login "syt"`
+ means "the documents have no relation `owned_by` with the user
+ syt". They may have a relation "owned_by" with another user.
+
+Identity
+````````
+
+You can use the special relation `identity` in a query to
+add an identity constraint between two variables. This is equivalent
+to ``is`` in python::
+
+ Any A WHERE A comments B, A identity B
+
+return all objects that comment themselves. The relation
+`identity` is especially useful when defining the rules for securities
+with `RQLExpressions`.
+
+
+Limit / offset
+``````````````
+::
+
+ Any P ORDERBY N LIMIT 5 OFFSET 10 WHERE P is Person, P firstname N
+
+Function calls
+``````````````
+::
+
+ Any UPPER(N) WHERE P firstname N
+
+Functions on string: UPPER, LOWER
+
+Exists
+``````
+::
+
+ Any X ORDERBY PN,N
+ WHERE X num N, X version_of P, P name PN,
+ EXISTS(X in_state S, S name IN ("dev", "ready"))
+ OR EXISTS(T tags X, T name "priority")
+
+
+Optional relations (Left outer join)
+````````````````````````````````````
+
+* They allow you to select entities related or not to another.
+
+* You must use the `?` behind the variable to specify that the relation
+ toward it is optional:
+
+ - Anomalies of a project attached or not to a version ::
+
+ Any X, V WHERE X concerns P, P eid 42, X corrected_in V?
+
+ - All cards and the project they document if necessary ::
+
+ Any C, P WHERE C is Card, P? documented_by C
+
+ Any T,P,V WHERE T is Ticket, T concerns P, T done_in V?
+
+
+Having
+``````
+::
+
+ Any X GROUPBY X WHERE X knows Y HAVING COUNT(Y) > 10
+
+Subqueries
+``````````
+::
+
+ (Any X WHERE X is Person) UNION (Any X WHERE X is Company)
+
+
+ DISTINCT Any W, REF
+ WITH W, REF BEING
+ (
+ (Any W, REF WHERE W is Workcase, W ref REF,
+ W concerned_by D, D name "Logilab")
+ UNION
+ (Any W, REF WHERE W is Workcase, W ref REF, '
+ W split_into WP, WP name "WP1")
+ )
+
+
+Examples
+````````
+
+- *Search for the object of identifier 53*
+ ::
+
+ Any WHERE X
+ X eid 53
+
+- *Search material such as comics, owned by syt and available*
+ ::
+
+ Any X WHERE X is Document
+ X occurence_of F, F class C, C name 'Comics'
+ X owned_by U, U login 'syt'
+ X available TRUE
+
+- *Looking for people working for eurocopter interested in training*
+ ::
+
+ Any P WHERE
+ P is Person, P work_for S, S name 'Eurocopter'
+ P interested_by T, T name 'training'
+
+- *Search note less than 10 days old written by jphc or ocy*
+ ::
+
+ Any N WHERE
+ N is Note, N written_on D, D day> (today -10),
+ N written_by P, P name 'jphc' or P name 'ocy'
+
+- *Looking for people interested in training or living in Paris*
+ ::
+
+ Any P WHERE
+ P is Person, (P interested_by T, T name 'training') OR
+ (P city 'Paris')
+
+- *The name and surname of all people*
+ ::
+
+ Any N, P WHERE
+ X is Person, X name N, X first_name P
+
+ Note that the selection of several entities generally force
+ the use of "Any" because the type specification applies otherwise
+ to all the selected variables. We could write here
+ ::
+
+ String N, P WHERE
+ X is Person, X name N, X first_name P
+
+
+ Note: You can not specify several types with * ... where X is FirstType or X is SecondType*.
+ To specify several types explicitely, you have to do
+
+ ::
+
+ Any X where X is in (FirstType, SecondType)
+
+
+Insertion query
+~~~~~~~~~~~~~~~~
+
+ `INSERT` <entity type> V1 (, <entity type> V2) \ * `:` <assignments>
+ [ `WHERE` <restriction>]
+
+:assignments:
+ list of relations to assign in the form `V1 relationship V2 | <static value>`
+
+The restriction can define variables used in assignments.
+
+Caution, if a restriction is specified, the insertion is done for
+*each line result returned by the restriction*.
+
+- *Insert a new person named 'foo'*
+ ::
+
+ INSERT Person X: X name 'foo'
+
+- *Insert a new person named 'foo', another called 'nice' and a 'friend' relation
+ between them*
+ ::
+
+ INSERT Person X, Person Y: X name 'foo', Y name 'nice', X friend Y
+
+- *Insert a new person named 'foo' and a 'friend' relation with an existing
+ person called 'nice'*
+ ::
+
+ INSERT Person X: X name 'foo', X friend Y WHERE name 'nice'
+
+Update and relation creation queries
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ `SET` <assignements>
+ [ `WHERE` <restriction>]
+
+Caution, if a restriction is specified, the update is done *for
+each result line returned by the restriction*.
+
+- *Renaming of the person named 'foo' to 'bar' with the first name changed*
+ ::
+
+ SET X name 'bar', X first_name 'original' WHERE X is Person, X name 'foo'
+
+- *Insert a relation of type 'know' between objects linked by
+ the relation of type 'friend'*
+ ::
+
+ SET X know Y WHERE X friend Y
+
+
+Deletion query
+~~~~~~~~~~~~~~
+ `DELETE` (<entity type> V) | (V1 relation v2 ),...
+ [ `WHERE` <restriction>]
+
+Caution, if a restriction is specified, the deletion is made *for
+each line result returned by the restriction*.
+
+- *Deletion of the person named 'foo'*
+ ::
+
+ DELETE Person X WHERE X name 'foo'
+
+- *Removal of all relations of type 'friend' from the person named 'foo'*
+ ::
+
+ DELETE X friend Y WHERE X is Person, X name 'foo'
+
--- a/doc/book/en/conf.py Tue Apr 28 11:22:43 2009 +0200
+++ b/doc/book/en/conf.py Thu May 07 16:33:22 2009 +0200
@@ -29,14 +29,14 @@
templates_path = ['.templates']
# The suffix of source filenames.
-source_suffix = '.txt'
+source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# General substitutions.
project = 'Cubicweb'
-copyright = '2008, Logilab'
+copyright = '2008-2009, Logilab'
# The default replacements for |version| and |release|, also used in various
# other places throughout the built documents.
@@ -44,7 +44,7 @@
# The short X.Y version.
version = '0.54'
# The full version, including alpha/beta/rc tags.
-release = '3.0'
+release = '3.2'
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/cubes/available-cubes.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,64 @@
+
+Available cubes
+---------------
+
+An application is based on several basic cubes. In the set of available
+basic cubes we can find for example :
+
+Base entity types
+~~~~~~~~~~~~~~~~~
+* addressbook_: PhoneNumber and PostalAddress
+* card_: Card, generic documenting card
+* event_: Event (define events, display them in calendars)
+* file_: File (to allow users to upload and store binary or text files)
+* link_: Link (to collect links to web resources)
+* mailinglist_: MailingList (to reference a mailing-list and the URLs
+ for its archives and its admin interface)
+* person_: Person (easily mixed with addressbook)
+* task_: Task (something to be done between start and stop date)
+* zone_: Zone (to define places within larger places, for example a
+ city in a state in a country)
+
+
+Classification
+~~~~~~~~~~~~~~
+* folder_: Folder (to organize things but grouping them in folders)
+* keyword_: Keyword (to define classification schemes)
+* tag_: Tag (to tag anything)
+
+Other features
+~~~~~~~~~~~~~~
+* basket_: Basket (like a shopping cart)
+* blog_: a blogging system uxing Blog and BlogEntry entity types
+* comment_: system to attach comment threads to entities)
+* email_: archiving management for emails (`Email`, `Emailpart`,
+ `Emailthread`), trigger action in cubicweb through email
+
+
+
+
+
+.. _addressbook: http://www.cubicweb.org/project/cubicweb-addressbook
+.. _basket: http://www.cubicweb.org/project/cubicweb-basket
+.. _card: http://www.cubicweb.org/project/cubicweb-card
+.. _blog: http://www.cubicweb.org/project/cubicweb-blog
+.. _comment: http://www.cubicweb.org/project/cubicweb-comment
+.. _email: http://www.cubicweb.org/project/cubicweb-email
+.. _event: http://www.cubicweb.org/project/cubicweb-event
+.. _file: http://www.cubicweb.org/project/cubicweb-file
+.. _folder: http://www.cubicweb.org/project/cubicweb-folder
+.. _keyword: http://www.cubicweb.org/project/cubicweb-keyword
+.. _link: http://www.cubicweb.org/project/cubicweb-link
+.. _mailinglist: http://www.cubicweb.org/project/cubicweb-mailinglist
+.. _person: http://www.cubicweb.org/project/cubicweb-person
+.. _tag: http://www.cubicweb.org/project/cubicweb-tag
+.. _task: http://www.cubicweb.org/project/cubicweb-task
+.. _zone: http://www.cubicweb.org/project/cubicweb-zone
+
+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
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/cubes/cc-newcube.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,46 @@
+Creating a new cube from scratch using :command:`cubicweb-ctl newcube`
+----------------------------------------------------------------------
+
+Let's start by creating the cube environment in which we will develop ::
+
+ cd ~/hg
+
+ cubicweb-ctl newcube mycube
+
+ # answer questions
+ hg init moncube
+ cd mycube
+ hg add .
+ hg ci
+
+If all went well, you should see the cube you just create in the list
+returned by `cubicweb-ctl list` in the section *Available components*,
+and if it is not the case please refer to :ref:`ConfigurationEnv`.
+
+To use a cube, you have to list it in the variable ``__use__``
+of the file ``__pkginfo__.py`` of the instance.
+This variable is used for the instance packaging (dependencies
+handled by system utility tools such as APT) and the usable cubes
+at the time the base is created (import_erschema('MyCube') will
+not properly work otherwise).
+
+.. note::
+ Please note that if you do not wish to use default directory
+ for your cubes library, then you want to use the option
+ --directory to specify where you would like to place
+ the source code of your cube:
+ ``cubicweb-ctl newcube --directory=/path/to/cubes/library cube_name``
+
+
+Usage of :command:`cubicweb-ctl liveserver`
+-------------------------------------------
+
+To quickly test a new cube, you can also use the `liveserver` command for cubicweb-ctl
+which allows to create an instance in memory (using an SQLite database by
+default) and make it accessible through a web server ::
+
+ cubicweb-ctl live-server mycube
+
+or by using an existing database (SQLite or Postgres)::
+
+ cubicweb-ctl live-server -s myfile_sources mycube
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/cubes/index.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,11 @@
+Cubes
+=====
+
+This chapter describes how to define your own cubes and reuse already available cubes.
+
+.. toctree::
+ :maxdepth: 1
+
+ layout.rst
+ cc-newcube.rst
+ available-cubes.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/cubes/layout.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,138 @@
+
+.. _foundationsCube:
+
+.. _cubelayout:
+
+Standard structure for a cube
+-----------------------------
+
+A cube is structured as follows:
+
+::
+
+ mycube/
+ |
+ |-- data/
+ | |-- cubes.mycube.css
+ | |-- cubes.mycube.js
+ | `-- external_resources
+ |
+ |-- debian/
+ | |-- changelog
+ | |-- compat
+ | |-- control
+ | |-- copyright
+ | |-- cubicweb-mycube.prerm
+ | `-- rules
+ |
+ |-- entities.py
+ |
+ |-- i18n/
+ | |-- en.po
+ | `-- fr.po
+ |
+ |-- __init__.py
+ |
+ |-- MANIFEST.in
+ |
+ |-- migration/
+ | |-- postcreate.py
+ | `-- precreate.py
+ |
+ |-- __pkginfo__.py
+ |
+ |-- schema.py
+ |
+ |-- setup.py
+ |
+ |-- site_cubicweb.py
+ |
+ |-- hooks.py
+ |
+ |-- test/
+ | |-- data/
+ | | `-- bootstrap_cubes
+ | |-- pytestconf.py
+ | |-- realdb_test_mycube.py
+ | `-- test_mycube.py
+ |
+ `-- views.py
+
+
+We can use subpackages instead of python modules for ``views.py``, ``entities.py``,
+``schema.py`` or ``hooks.py``. For example, we could have:
+
+::
+
+ mycube/
+ |
+ |-- entities.py
+ |-- hooks.py
+ `-- views/
+ |-- forms.py
+ |-- primary.py
+ `-- widgets.py
+
+
+where :
+
+* ``schema`` contains the schema definition (server side only)
+* ``entities`` contains the entities definition (server side and web interface)
+* ``sobjects`` contains hooks and/or views notifications (server side only)
+* ``views`` contains the web interface components (web interface only)
+* ``test`` contains tests related to the application (not installed)
+* ``i18n`` contains message catalogs for supported languages (server side and
+ web interface)
+* ``data`` contains data files for static content (images, css, javascripts)
+ ...(web interface only)
+* ``migration`` contains initialization files for new instances (``postcreate.py``)
+ and a file containing dependencies of the component depending on the version
+ (``depends.map``)
+* ``debian`` contains all the files managing debian packaging (you will find
+ the usual files ``control``, ``rules``, ``changelog``... not installed)
+* file ``__pkginfo__.py`` provides component meta-data, especially the distribution
+ and the current version (server side and web interface) or sub-cubes used by
+ the cube.
+
+
+At least you should have:
+
+* the file ``__pkginfo__.py``
+* the schema definition
+ XXX false, we may want to have cubes which are only adding a service,
+ no persistent data (eg embedding for instance)
+
+
+
+The :file:`__init__.py` and :file:`site_cubicweb.py` files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The :file:`__pkginfo__.py` file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+XXX contains metadata describing your cubes
+ distname / modname
+ version / numversion
+ __use__
+ __recommend__
+
+
+:file:`migration/precreate.py` and :file:`migration/postcreate.py`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+XXX detail steps of instance creation
+
+
+External resources such as image, javascript and css files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+XXX naming convention external_resources file
+
+
+Out-of the box testing
+~~~~~~~~~~~~~~~~~~~~~~
+XXX MANIFEST.in, __pkginfo__.include_dirs, debian
+
+
+
+Packaging and distribution
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+XXX MANIFEST.in, __pkginfo__.include_dirs, debian
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/datamodel/baseschema.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,38 @@
+
+Pre-defined schemas in the library
+----------------------------------
+
+The library defines a set of entity schemas that are required by the system
+or commonly used in `CubicWeb` applications.
+
+
+Entity types used to store the schema
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* `CWEType`, entity type
+* `CWRType`, relation type
+* `CWRelation`, relation definition
+* `CWAttribute`, attribute relation definition
+* `CWConstraint`, `CWConstraintType`, `RQLExpression`
+
+Entity types used to manage users and permissions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* `CWUser`, system users
+* `CWGroup`, users groups
+* `CWPermission`, used to configure the security of the application
+
+Entity types used to manage workflows
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* `State`, workflow state
+* `Transition`, workflow transition
+* `TrInfo`, record of a transition trafic for an entity
+
+Other entity types
+~~~~~~~~~~~~~~~~~~
+* `CWCache`
+* `CWProperty`, used to configure the application
+
+* `EmailAddress`, email address, used by the system to send notifications
+ to the users and also used by others optionnals schemas
+
+* `Bookmark`, an entity type used to allow a user to customize his links within
+ the application
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/datamodel/define-workflows.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,159 @@
+.. -*- coding: utf-8 -*-
+
+.. _Workflow:
+
+An Example: Workflow definition
+===============================
+
+General
+-------
+
+A workflow describes how certain entities have to evolve between
+different states. Hence we have a set of states, and a "transition graph",
+i.e. a list of possible transitions from one state to another state.
+
+We will define a simple workflow for a blog, with only the following
+two states: `submitted` and `published`. So first, we create a simple
+`CubicWeb` in ten minutes (see :ref:`BlogTenMinutes`).
+
+Set-up a workflow
+-----------------
+
+We want to create a workflow to control the quality of the BlogEntry
+submitted on your application. When a BlogEntry is created by a user
+its state should be `submitted`. To be visible to all, it has to
+be in the state `published`. To move it from `submitted` to `published`,
+we need a transition that we can call `approve_blogentry`.
+
+A BlogEntry state should not be modifiable by every user.
+So we have to define a group of users, `moderators`, and
+this group will have appropriate permissions to publish a BlogEntry.
+
+There are two ways to create a workflow: from the user interface,
+or by defining it in ``migration/postcreate.py``.
+This script is executed each time a new ``cubicweb-ctl db-init`` is done.
+We strongly recommand to create the workflow in ``migration/postcreate.py``
+and we will now show you how. Read `Under the hood`_ to understand why.
+
+Update the schema
+~~~~~~~~~~~~~~~~~
+If we want a State for our BlogEntry, we have to define a relation
+``in_state`` in the schema of BlogEntry. So we add
+the line ``in_state (...)``::
+
+ class BlogEntry(EntityType):
+ title = String(maxsize=100, required=True)
+ publish_date = Date(default='TODAY')
+ text_format = String(meta=True, internationalizable=True, maxsize=50,
+ default='text/rest', constraints=[format_constraint])
+ text = String(fulltextindexed=True)
+ category = String(vocabulary=('important','business'))
+ entry_of = SubjectRelation('Blog', cardinality='?*')
+ in_state = SubjectRelation('State', cardinality='1*')
+
+As you updated the schema, you have to re-execute ``cubicweb-ctl db-init``
+to initialize the database and migrate your existing entities.
+
+[WRITE ABOUT MIGRATION]
+
+Create states, transitions and group permissions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``postcreate.py`` script is executed in a special environment, adding
+several `CubicWeb` primitives that can be used.
+They are all defined in the ``class ServerMigrationHelper``.
+We will only discuss the methods we use to create a workflow in this example.
+
+To define our workflow for BlogDemo, please add the following lines
+to ``migration/postcreate.py``::
+
+ _ = unicode
+
+ moderators = add_entity('CWGroup', name=u"moderators")
+
+This adds the `moderators` user group.
+
+::
+
+ submitted = add_state(_('submitted'), 'BlogEntry', initial=True)
+ published = add_state(_('published'), 'BlogEntry')
+
+``add_state`` expects as first argument the name of the state you want
+to create, then the entity type on which the state can be applied,
+and an optional argument to say if it is supposed to be the initial state
+of the entity type.
+
+::
+
+ add_transition(_('approve_blogentry'), 'BlogEntry', (submitted,), published, ('moderators', 'managers'),)
+
+
+``add_transition`` expects
+
+ * as the first argument the name of the
+ transition, then the entity type on which the transition can be applied,
+ * then the list of states on which the transition can be trigged,
+ * the target state of the transition,
+ * and the permissions
+ (e.g. a list of user groups who can apply the transition; the user
+ has to belong to at least one of the listed group to perform the action).
+
+::
+
+ checkpoint()
+
+.. note::
+ Do not forget to add the `_()` in front of all states and transitions names while creating
+ a workflow so that they will be identified by the i18n catalog scripts.
+
+In addition to the user group condition, we could have added a RQL condition.
+In this case, the user can only perform the action if
+the two conditions are satisfied.
+
+If we use a RQL condition on a transition, we can use the following
+variables:
+
+* `%(eid)s`, object's eid
+* `%(ueid)s`, user executing the query eid
+* `%(seid)s`, the object's current state eid
+
+
+.. image:: images/lax-book.03-transitions-view.en.png
+
+You can notice that in the action box of a BlogEntry, the state
+is now listed as well as the possible transitions defined by the workflow.
+The transitions will only be displayed for users having the right permissions.
+In our example, the transition `approve_blogentry` will only be displayed
+for the users belonging to the group `moderators` or `managers`.
+
+
+Under the hood
+~~~~~~~~~~~~~~
+
+A workflow is a collection of entities of type ``State`` and of type ``Transition``
+which are standard `CubicWeb` entity types.
+For instance, the following lines::
+
+ submitted = add_state(_('submitted'), 'BlogEntry', initial=True)
+ published = add_state(_('published'), 'BlogEntry')
+
+will create two entities of type ``State``, one with name 'submitted', and the other
+with name 'published'. Whereas::
+
+ add_transition(_('approve_blogentry'), 'BlogEntry', (submitted,), published, ('moderators', 'managers'),)
+
+will create an entity of type ``Transition`` with name 'approve_blogentry' which will
+be linked to the ``State`` entities created before.
+As a consequence, we could use the administration interface to do these operations.
+But it is not recommanded because it will be uselessly complicated
+and will be only local to your instance.
+
+
+Indeed, if you create the states and transitions through the user interface,
+next time you initialize the database
+you will have to re-create all the entities.
+The user interface should only be a reference for you to view the states
+and transitions, but is not the appropriate interface to define your
+application workflow.
+
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/datamodel/definition.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,440 @@
+.. -*- coding: utf-8 -*-
+
+Yams *schema*
+-------------
+
+The **schema** is the core piece of a `CubicWeb` application as it defines
+the handled data model. It is based on entity types that are either already
+defined in the `CubicWeb` standard library; or more specific types, that
+`CubicWeb` expects to find in one or more Python files under the directory
+`schema`.
+
+At this point, it is important to make clear the difference between
+*relation type* and *relation definition*: a *relation type* is only a relation
+name with potentially other additionnal properties (see XXXX), whereas a
+*relation definition* is a complete triplet
+"<subject entity type> <relation type> <object entity type>".
+A relation type could have been implied if none is related to a
+relation definition of the schema.
+
+
+All `CubicWeb` built-in types are available : `String`, `Int`, `Float`,
+`Decimal`, `Boolean`, `Date`, `Datetime`, `Time`, `Interval`, `Byte`
+and `Password`.
+They are implicitely imported (as well as the special the function "_"
+for translation :ref:`internationalization`).
+
+The instance schema of an application is defined on all appobjects by a .schema
+class attribute set on registration. It's an instance of
+:class:`yams.schema.Schema`.
+
+Entity type
+~~~~~~~~~~~
+It's an instance of :class:`yams.schema.EntitySchema`
+
+XXX meta
+XXX permission
+XXX yams inheritance
+
+Relation type
+~~~~~~~~~~~~~
+It's an instance of :class:`yams.schema.RelationSchema`
+
+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`)
+
+* `symmetric` : boolean indicating that the relation is symmetrical, which
+ means `X relation Y` implies `Y relation X`
+
+XXX meta
+XXX permission
+
+
+Relation definition
+~~~~~~~~~~~~~~~~~~~
+Relation definition are represented in yams using an internal structure only exposed through the :mod:`api <yams.schema>`.
+
+Properties
+``````````
+Properties defined below are accessible through the following api:
+
+ RelationSchema.rproperties()
+ RelationSchema.rproperty(subjtype, objtype, property name)
+
+* Optional properties for attributes and relations :
+
+ - `description` : a 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` : a list of conditions/constraints that the relation has to
+ satisfy (c.f. `Contraints`_)
+
+ - `cardinality` : a two character string which specify the cardinality of the
+ relation. The first character defines the cardinality of the relation on
+ the subject, and the second on the object. When a relation can have
+ multiple subjects or objects, the cardinality applies to all,
+ not on a one-to-one basis (so it must be consistent...). The possible
+ values are inspired from regular expression syntax :
+
+ * `1`: 1..1
+ * `?`: 0..1
+ * `+`: 1..n
+ * `*`: 0..n
+
+ - `meta` : boolean indicating that the relation is a meta-relation (false by
+ default)
+
+* optional 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 useful 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 correspond to the RQL keywords `TODAY` and `NOW`.
+
+ - `vocabulary` : specify static possible values of an attribute
+
+* optional 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)
+
+* optional 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 set
+ 'object' as value. The composition implies that when the relation
+ is deleted (so when the composite is deleted), the composed are also deleted.
+
+ - `fti_container`: XXX feed me
+
+Constraints
+```````````
+By default, the available constraint 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 has 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.
+
+XXX note about how to add new constraint
+
+
+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
+
+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 user groups
+````````````````````````
+
+* `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 `RQLExpression`
+
+* 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 `RQLExpression`
+ 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.
+
+: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.
+
+
+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
+
+
+
+
+Defining your schema using yams
+-------------------------------
+
+Entity type definition
+~~~~~~~~~~~~~~~~~~~~~~
+
+An entity type is defined by a Python class which inherits from `EntityType`.
+The class definition contains the description of attributes and relations
+for the defined entity type.
+The class name corresponds to the entity type name. It is exepected to be
+defined in the module ``mycube.schema``.
+
+
+For example ::
+
+ class Person(EntityType):
+ """A person with the properties and the relations necessary for my
+ application"""
+
+ last_name = String(required=True, fulltextindexed=True)
+ first_name = String(required=True, fulltextindexed=True)
+ title = String(vocabulary=('Mr', 'Mrs', 'Miss'))
+ date_of_birth = Date()
+ works_for = SubjectRelation('Company', cardinality='?*')
+
+
+The entity described above defines three attributes of type String,
+last_name, first_name and title, an attribute of type Date for the date of
+birth and a relation that connects a `Person` to another entity of type
+`Company` through the semantic `works_for`.
+
+The name of the Python attribute corresponds to the name of the attribute
+or the relation in `CubicWeb` application.
+
+An attribute is defined in the schema as follows::
+
+ attr_name = attr_type(properties*)
+
+where `attr_type` is one of the type listed above and `properties` is
+a list of the attribute needs to statisfy (see :ref:`properties`
+for more details).
+
+
+* relations can be defined by using `ObjectRelation` or `SubjectRelation`.
+ The first argument of `SubjectRelation` or `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 corresponding to multiple entity 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)
+
+Inheritance
+```````````
+XXX feed me
+
+
+Definition of relations
+~~~~~~~~~~~~~~~~~~~~~~~
+
+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
+contain 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 = 'CWUser'
+
+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 symmetrical, and it does not require
+specific permissions, its definition (by using `SubjectRelation` and
+`ObjectRelation`) is all we need.
+
+
+Definition of permissions
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In addition to that the entity type `CWPermission` from the standard library
+allow to build very complex and dynamic security architecture. The schema of
+this entity type is as follow : ::
+
+ class CWPermission(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('CWGroup', 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 `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 genricity 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)
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/datamodel/index.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,13 @@
+Data model
+==========
+
+This chapter describes how you define a schema and how to make it evolves as the time goes.
+
+.. toctree::
+ :maxdepth: 1
+
+ definition
+ metadata
+ baseschema
+
+.. comment: define-workflows
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/datamodel/inheritance.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,1 @@
+XXX WRITME
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/datamodel/metadata.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,43 @@
+
+Meta-data
+----------
+
+Each entity type has at least the following meta-relations:
+
+eid
+~~~
+Each entity in *CubicWeb* has an associated identifier which is unique
+in an instance. We usually call this identifier `eid`.
+
+`creation_date` and `modification_date`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Date and time of the creation / lastest modification of an entity.
+
+
+`created_by`
+~~~~~~~~~~~~
+relation to the :ref:`users <CWUser>` who has created the entity
+
+`owned_by`
+~~~~~~~~~~
+relation to :ref:`users <CWUser>` whom the entity belongs; usually the creator but not
+necessary, and it could have multiple owners notably for permission control
+
+`is`
+~~~~~
+relation to the :ref:`entity type <CWEType>` of which type the entity is.
+
+`is_instance`
+~~~~~~~~~~~~~
+relation to the :ref:`entity types <CWEType>` of which type the entity is an instance of.
+
+
+Special relations
+-----------------
+`has_text`
+~~~~~~~~~~
+query the full text index (only for entities having fulltextindexed attributes)
+
+`identity`
+~~~~~~~~~~
+XXX
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/devcore/appobject.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,86 @@
+
+
+The `AppObject` class
+~~~~~~~~~~~~~~~~~~~~~
+
+In general:
+
+* we do not inherit directly from this class but from a more specific
+ class such as `AnyEntity`, `EntityView`, `AnyRsetView`,
+ `Action`...
+
+* to be recordable, a subclass has to define its own register (attribute
+ `__registry__`) and its identifier (attribute `id`). Usually we do not have
+ to take care of the register, only the identifier `id`.
+
+We can find a certain number of attributes and methods defined in this class
+and common to all the application objects.
+
+At the recording, the following attributes are dynamically added to
+the *subclasses*:
+
+* `vreg`, the `vregistry` of the application
+* `schema`, the application schema
+* `config`, the application configuration
+
+We also find on instances, the following attributes:
+
+* `req`, `Request` instance
+* `rset`, the *result set* associated to the object if necessary
+* `cursor`, rql cursor on the session
+
+
+:URL handling:
+ * `build_url(method=None, **kwargs)`, returns an absolute URL based on
+ the given arguments. The *controller* supposed to handle the response,
+ can be specified through the special parameter `method` (the connection
+ is theoretically done automatically :).
+
+ * `datadir_url()`, returns the directory of the application data
+ (contains static files such as images, css, js...)
+
+ * `base_url()`, shortcut to `req.base_url()`
+
+ * `url_quote(value)`, version *unicode safe* of the function `urllib.quote`
+
+:Data manipulation:
+
+ * `etype_rset(etype, size=1)`, shortcut to `vreg.etype_rset()`
+
+ * `eid_rset(eid, rql=None, descr=True)`, returns a *result set* object for
+ the given eid
+ * `entity(row, col=0)`, returns the entity corresponding to the data position
+ in the *result set* associated to the object
+
+ * `complete_entity(row, col=0, skip_bytes=True)`, is equivalent to `entity` but
+ also call the method `complete()` on the entity before returning it
+
+:Data formatting:
+ * `format_date(date, date_format=None, time=False)` returns a string for a
+ mx date time according to application's configuration
+ * `format_time(time)` returns a string for a mx date time according to
+ application's configuration
+
+:And more...:
+
+ * `external_resource(rid, default=_MARKER)`, access to a value defined in the
+ configuration file `external_resource`
+
+ * `tal_render(template, variables)`, renders a precompiled page template with
+ variables in the given dictionary as context
+
+.. note::
+ When we inherit from `AppObject` (even not directly), you *always* have to use
+ **super()** to get the methods and attributes of the superclasses, and not
+ use the class identifier.
+ For example, instead of writting: ::
+
+ class Truc(PrimaryView):
+ def f(self, arg1):
+ PrimaryView.f(self, arg1)
+
+ You'd better write: ::
+
+ class Truc(PrimaryView):
+ def f(self, arg1):
+ super(Truc, self).f(arg1)
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/devcore/dbapi.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,29 @@
+
+
+API Python/RQL
+~~~~~~~~~~~~~~
+
+The Python API developped to interface with RQL is inspired from the standard db-api,
+with a Connection object having the methods cursor, rollback and commit essentially.
+The most important method is the `execute` method of a cursor :
+
+`execute(rqlstring, args=None, eid_key=None, build_descr=True)`
+
+:rqlstring: the RQL query to execute (unicode)
+:args: if the query contains substitutions, a dictionary containing the values to use
+:eid_key:
+ an implementation detail of the RQL cache implies that if a substitution
+ is used to introduce an eid *susceptible to raise the ambiguities in the query
+ type resolution*, then we have to specify the corresponding key in the dictionary
+ through this argument
+
+
+The `Connection` object owns the methods `commit` and `rollback`. You *should
+never need to use them* during the development of the web interface based on
+the `CubicWeb` framework as it determines the end of the transaction depending
+on the query execution success.
+
+.. note::
+ While executing update queries (SET, INSERT, DELETE), if a query generates
+ an error related to security, a rollback is automatically done on the current
+ transaction.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/devcore/index.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,18 @@
+Core APIs
+=========
+
+.. toctree::
+ :maxdepth: 1
+
+ vreg.rst
+ selection.rst
+ appobject.rst
+ selectors.rst
+ dbapi.rst
+
+
+:mod:`Configuration <cubicweb.cwconfig>`
+----------------------------------------
+
+.. automodule:: cubicweb.cwconfig
+ :members:
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/devcore/selectors.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,101 @@
+Base selectors
+--------------
+
+Selectors are scoring functions that are called by the view dispatcher to tell
+whenever a view can be applied to a given result set of a request. Selector sets
+are the glue that tie views to the data model. Using them appropriately is an
+essential part of the construction of well behaved cubes.
+
+
+`CubicWeb` provides its own set of selectors that you can use and here is a
+description of some of the most common used:
+
+Of course you will write your own set of selectors as you get familiar with the
+framework.
+
+
+:yes([score=1]):
+ Return the score given as parameter (default to 1). Usually used for appobjects
+ which can be selected whatever the context, or also sometimes to add arbitrary
+ points to a score. Take care, `yes(0)` could be named 'no'...
+
+
+Rset selectors
+~~~~~~~~~~~~~~
+:none_rset():
+ Return 1 if the result set is None.
+
+:any_rset():
+ Return 1 for any result set, whatever the number of rows in it.
+
+:nonempty_rset():
+ Return 1 for non empty result set.
+
+:empty_rset():
+ Return 1 for empty result set.
+
+:one_line_rset():
+ Return 1 if the result set is of size 1 or if a row is specified.
+
+:two_lines_rset():
+ Return 1 if the result set has *at least* two rows.
+
+:two_cols_rset():
+ Return 1 if the result set is not empty and has *at least* two columns per
+ row.
+
+:paginated_rset():
+ Return 1 if the result set has more rows the specified by the
+ `navigation.page-size` property.
+
+:sorted_rset():
+ Return 1 if the result set has an ORDERBY clause.
+
+:one_etype_rset():
+ Return 1 if the result set has entities which are all of the same type in a
+ given column (default to column 0).
+
+:non_final_entity():
+ Return 1 if the result set contains entities in a given column (the first one
+ by default), and no "final" values such as string of int.
+
+:implements(<iface or etype>, ...):
+ Return positive score if entities in the result set are of the given entity
+ type or implements given interface. If multiple arguments are given, matching
+ one of them is enough. Returned score reflects the "distance" between expected
+ type or interface and matched entities. Entity types are usually given as
+ string, the corresponding class will be fetched from the vregistry.
+
+:two_etypes_rset(): XXX
+:entity_implements(): XXX
+:relation_possible(): XXX
+:partial_relation_possible(): XXX
+:may_add_relation(): XXX
+:partial_may_add_relation(): XXX
+:has_related_entities(): XXX
+:partial_has_related_entities(): XXX
+:has_permission(): XXX
+:has_add_permission(): XXX
+:rql_condition(): XXX
+:but_etype(): XXX
+:score_entity(): XXX
+
+Request selectors
+~~~~~~~~~~~~~~~~~~
+:anonymous_user():
+ Return 1 if user isn't authenticated (eg is the anonymous user).
+
+:authenticated_user():
+ Return 1 if user is authenticated.
+
+:match_user_groups(): XXX
+:match_search_state(): XXX
+:match_form_params(): XXX
+
+Other selectors
+~~~~~~~~~~~~~~~
+:match_kwargs(): XXX
+:match_context_prop(): XXX
+:appobject_selectable(): XXX
+:specified_etype_implements(): XXX
+:primary_view(): XXX
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/devcore/vreg.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,151 @@
+The VRegistry
+--------------
+
+The recording process on startup
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Details of the recording process
+````````````````````````````````
+
+* par défaut on enregistre automatiquement tout les objets
+
+* si certains objets doivent remplacer d'autres objets ou être inclus
+ conditionnellement,
+ - enregistrement explicite en définissant la fonction `registration_callback(vreg)`
+ - appel des méthodes d'enregistrement des objets sur le vreg
+
+* suppression de l'ancien système quand il ne restera plus de réference au
+ module registerers dans le code des cubes existants.
+
+
+Examples
+
+.. code-block:: python
+
+ # web/views/basecomponents.py
+ def registration_callback(vreg):
+ vreg.register_all(globals().values(), __name__, (SeeAlsoVComponent,))
+ if 'see_also' in vreg.schema:
+ vreg.register(SeeAlsoVComponent)
+
+ # goa/appobjects/sessions.py
+ def registration_callback(vreg):
+ vreg.register(SessionsCleaner)
+ vreg.register(GAEAuthenticationManager, clear=True)
+ vreg.register(GAEPersistentSessionManager, clear=True)
+
+
+API d'enregistrement des objets
+```````````````````````````````
+.. code-block:: python
+
+ register(obj, registryname=None, oid=None, clear=False)
+
+ register_all(objects, modname, butclasses=())
+
+ unregister(obj, registryname=None)
+
+ register_and_replace(obj, replaced, registryname=None)
+
+ register_if_interface_found(obj, ifaces, **kwargs)
+
+
+Runtime objects selection
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Defining selectors
+``````````````````
+The object's selector is defined by itsd `__select__` class attribute.
+
+When two selectors are combined using the `&` operator (former `chainall`), it
+means that both should return a positive score. On success, the sum of scores is returned.
+
+When two selectors are combined using the `|` operator (former `chainfirst`), it
+means that one of them should return a positive score. On success, the first
+positive score is returned.
+
+Of course you can use paren to balance expressions.
+
+
+For instance, if you're selecting the primary (eg `id = 'primary'`) view (eg
+`__registry__ = 'view'`) for a result set containing a `Card` entity, 2 objects
+will probably be selectable:
+
+* the default primary view (`__select__ = implements('Any')`), meaning that the object is selectable for any kind of entity type
+
+* the specific `Card` primary view (`__select__ = implements('Card')`, meaning that the object is selectable for Card entities
+
+Other primary views specific to other entity types won't be selectable in this
+case. Among selectable objects, the implements selector will return a higher score
+to the second view since it's more specific, so it will be selected as expected.
+
+
+Example
+````````
+
+Le but final : quand on est sur un Blog, on veut que le lien rss de celui-ci pointe
+vers les entrées de ce blog, non vers l'entité blog elle-même.
+
+L'idée générale pour résoudre ça : on définit une méthode sur les classes d'entité
+qui renvoie l'url du flux rss pour l'entité en question. Avec une implémentation
+par défaut sur AnyEntity et une implémentation particulière sur Blog qui fera ce
+qu'on veut.
+
+La limitation : on est embêté dans le cas ou par ex. on a un result set qui contient
+plusieurs entités Blog (ou autre chose), car on ne sait pas sur quelle entité appeler
+la méthode sus-citée. Dans ce cas, on va conserver le comportement actuel (eg appel
+Ã limited_rql)
+
+Donc : on veut deux cas ici, l'un pour un rset qui contient une et une seule entité,
+l'autre pour un rset qui contient plusieurs entité.
+
+Donc... On a déja dans web/views/boxes.py la classe RSSIconBox qui fonctionne. Son
+sélecteur ::
+
+ class RSSIconBox(ExtResourcesBoxTemplate):
+ """just display the RSS icon on uniform result set"""
+ __select__ = ExtResourcesBoxTemplate.__select__ & non_final_entity()
+
+
+indique qu'il prend en compte :
+
+* les conditions d'apparition de la boite (faut remonter dans les classes parentes
+ pour voir le détail)
+* non_final_entity, qui filtre sur des rset contenant une liste d'entité non finale
+
+ça correspond donc à notre 2eme cas. Reste à fournir un composant plus spécifique
+pour le 1er cas ::
+
+ class EntityRSSIconBox(RSSIconBox):
+ """just display the RSS icon on uniform result set for a single entity"""
+ __select__ = RSSIconBox.__select__ & one_line_rset()
+
+
+Ici, on ajoute le selector one_line_rset, qui filtre sur des result set de taille 1. Il faut
+savoir que quand on chaine des selecteurs, le score final est la somme des scores
+renvoyés par chaque sélecteur (sauf si l'un renvoie zéro, auquel cas l'objet est
+non sélectionnable). Donc ici, sur un rset avec plusieurs entités, onelinerset_selector
+rendra la classe EntityRSSIconBox non sélectionnable, et on obtiendra bien la
+classe RSSIconBox. Pour un rset avec une entité, la classe EntityRSSIconBox aura un
+score supérieur à RSSIconBox et c'est donc bien elle qui sera sélectionnée.
+
+Voili voilou, il reste donc pour finir tout ça :
+
+* à définir le contenu de la méthode call de EntityRSSIconBox
+* fournir l'implémentation par défaut de la méthode renvoyant l'url du flux rss sur
+ AnyEntity
+* surcharger cette methode dans blog.Blog
+
+
+When to use selectors?
+```````````````````````
+
+Il faut utiliser les sélecteurs pour faire des choses différentes en
+fonction de ce qu'on a en entrée. Dès qu'on a un "if" qui teste la
+nature de `self.rset` dans un objet, il faut très sérieusement se
+poser la question s'il ne vaut pas mieux avoir deux objets différent
+avec des sélecteurs approprié.
+
+Debugging
+`````````
+XXX explain traced_selection context manager
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/devrepo/hooks.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,32 @@
+.. -*- coding: utf-8 -*-
+
+.. _hooks:
+
+Hooks
+=====
+
+XXX FILLME
+
+*Hooks* are executed before or after updating an entity or a relation in the
+repository.
+
+Their prototypes are as follows:
+
+ * after_add_entity (session, entity)
+ * after_update_entity (session, entity)
+ * after_delete_entity (session, eid)
+ * before_add_entity (session, entity)
+ * before_update_entity (session, entity)
+ * before_delete_entity (session, eid)
+
+ * after_add_relation (session, fromeid, rtype, toeid)
+ * after_delete_relation (session, fromeid, rtype, toeid)
+ * before_add_relation (session, fromeid, rtype, toeid)
+ * before_delete_relation (session, fromeid, rtype, toeid)
+
+ * server_startup
+ * server_shutdown
+
+ * session_open
+ * session_close
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/devrepo/index.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,14 @@
+.. -*- coding: utf-8 -*-
+
+Repository customization
+++++++++++++++++++++++++
+.. toctree::
+ :maxdepth: 1
+
+ sessions
+ hooks
+ notifications
+ operations
+ tasks
+
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/devrepo/notifications.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,6 @@
+.. -*- coding: utf-8 -*-
+
+Notifications management
+========================
+
+XXX FILLME
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/devrepo/operations.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,9 @@
+.. -*- coding: utf-8 -*-
+
+Repository operations
+======================
+
+[WRITE ME]
+
+* repository operations
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/devrepo/sessions.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,9 @@
+.. -*- coding: utf-8 -*-
+
+Sessions
+========
+
+[WRITE ME]
+
+* authentication and management of sessions
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/devrepo/tasks.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,9 @@
+.. -*- coding: utf-8 -*-
+
+Tasks
+=========
+
+[WRITE ME]
+
+* repository tasks
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/devweb/controllers.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,4 @@
+Controllers
+-----------
+
+XXX the view controller, other controllers
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/devweb/css.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,29 @@
+.. -*- coding: utf-8 -*-
+
+CSS Stylesheet
+---------------
+Conventions
+~~~~~~~~~~~
+
+XXX external_resources variable
+ naming convention
+ request.add_css
+
+
+Extending / overriding existing styles
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We cannot modify the order in which the application is reading the CSS. In
+the case we want to create new CSS style, the best is to define it a in a new
+CSS located under ``myapp/data/`` and use those new styles while writing
+customized views and templates.
+
+If you want to modify an existing CSS styling property, you will have to use
+``!important`` declaration to override the existing property. The application
+apply a higher priority on the default CSS and you can not change that.
+Customized CSS will not be read first.
+
+
+CubicWeb stylesheets
+~~~~~~~~~~~~~~~~~~~~
+XXX explain diffenrent files and main classes
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/devweb/facets.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,3 @@
+The facets system
+-----------------
+XXX feed me
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/devweb/form.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,29 @@
+Form construction
+------------------
+
+Forms
+~~~~~
+XXX feed me
+:Vocabulary control on relations:
+
+ * `vocabulary(rtype, x='subject', limit=None)`, called by the
+ editing views, it returns a list of couples (label, eid) of entities
+ that could be related to the entity by the relation `rtype`
+ * `subject_relation_vocabulary(rtype, limit=None)`, called internally
+ by `vocabulary` in the case of a subject relation
+ * `object_relation_vocabulary(rtype, limit=None)`, called internally
+ by `vocabulary` in the case of an object relation
+ * `relation_vocabulary(rtype, targettype, x, limit=None)`, called
+ internally by `subject_relation_vocabulary` and `object_relation_vocabulary`
+
+Fields
+~~~~~~
+XXX feed me
+
+Widgets
+~~~~~~~
+XXX feed me
+
+Renderers
+~~~~~~~~~
+XXX feed me
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/devweb/httpcaching.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,3 @@
+HTTP cache management
+---------------------
+XXX feedme
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/devweb/index.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,20 @@
+Web development
+===============
+
+In this chapter, we will core api for web development in the CubicWeb framework.
+
+.. toctree::
+ :maxdepth: 1
+
+ request
+ publisher
+ controllers
+ property
+ rtags
+ views
+ form
+ facets
+ httpcaching
+ js
+ css
+ internationalization
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/devweb/internationalization.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,110 @@
+.. -*- coding: utf-8 -*-
+
+.. _internationalisation:
+
+
+Internationalisation
+---------------------
+
+Cubicweb fully supports the internalization of it's content and interface.
+
+Cubicweb's interface internationalization is based on the translation project `GNU gettext`_.
+
+.. _`GNU gettext`: http://www.gnu.org/software/gettext/
+
+Cubicweb' internalization involves two steps:
+
+* in your Python code and cubicweb-tal templates : mark translatable strings
+
+* in your application : handle the translation catalog
+
+String internationalization
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In the Python code and cubicweb-tal templates translatable strings can be
+marked in one of the following ways :
+
+ * by using the *built-in* function `_` ::
+
+ class PrimaryView(EntityView):
+ """the full view of an non final entity"""
+ id = 'primary'
+ title = _('primary')
+
+ OR
+
+ * by using the equivalent request's method ::
+
+ class NoResultView(EmptyRsetView):
+ """default view when no result has been found"""
+ id = 'noresult'
+
+ def call(self, **kwargs):
+ self.w(u'<div class="searchMessage"><strong>%s</strong></div>\n'
+ % self.req._('No result matching query'))
+
+The goal of the *built-in* function `_` is only **to mark the
+translatable strings**, it will only return the string to translate
+it-self, but not its translation (it's actually refering to the `unicode` builtin).
+
+In the other hand the request's method `self.req._` is meant to retrieve the
+proper translation of translation strings in the requested language.
+
+Finally you can also use the `__` attribute of request object to get a
+translation for a string *which should not itself added to the catalog*,
+usually in case where the actual msgid is created by string interpolation ::
+
+ self.req.__('This %s' % etype)
+
+In this example `req.__` is used instead of `req._` so we don't have 'This %s' in
+messages catalogs.
+
+
+Translations in cubicweb-tal template can also be done with TAL tags
+`i18n:content` and `i18n:replace`.
+
+.. note::
+
+ We dont need to mark the translation strings of entities/relations
+ used by a particular application's schema as they are generated
+ automatically.
+
+
+Handle the translation catalog
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Once the internationalization is done in your application's code, you need
+to populate and update the translation catalog. Cubicweb provides the
+following commands for this purpose:
+
+
+* `i18nlibupdate` updates Cubicweb framework's translation
+ catalogs. Unless you work on the framework development, you don't
+ need to use this command.
+
+* `i18nupdate` updates the translation catalogs of *one particular
+ component* (or of all components). After this command is
+ executed you must update the translation files *.po* in the "i18n"
+ directory of your template. This command will of course not remove
+ existing translations still in use.
+
+* `i18ncompile` recompile the translation catalogs of *one particular
+ instance* (or of all instances) after the translation catalogs of
+ its components have been updated. This command is automatically
+ called every time you create or update your instance. The compiled
+ catalogs (*.mo*) are stored in the i18n/<lang>/LC_MESSAGES of
+ application where `lang` is the language identifier ('en' or 'fr'
+ for exemple).
+
+
+Example
+```````
+You have added and/or modified some translation strings in your application
+(after creating a new view or modifying the application's schema for exemple).
+To update the translation catalogs you need to do:
+
+1. `cubicweb-ctl i18nupdate <component>`
+2. Edit the <component>/xxx.po files and add missing translations (empty `msgstr`)
+3. `hg ci -m "updated i18n catalogs"`
+4. `cubicweb-ctl i18ncompile <myapplication>`
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/devweb/js.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,18 @@
+.. -*- coding: utf-8 -*-
+
+Javascript
+----------
+
+XXX jquery...
+
+Conventions
+~~~~~~~~~~~
+
+XXX external_resources variable
+ naming convention
+ request.add_js
+
+
+CubicWeb javascrip api
+~~~~~~~~~~~~~~~~~~~~~~
+XXX explain diffenrent files and main functions
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/devweb/property.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,12 @@
+The property mecanims
+---------------------
+XXX CWProperty and co
+
+
+Property API
+~~~~~~~~~~~~
+XXX feed me
+
+Registering and using your own property
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+XXX feed me
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/devweb/publisher.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,4 @@
+Publisher
+---------
+
+XXX cubicweb.web.application; coop diagram for execution of a http query
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/devweb/request.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,59 @@
+
+
+The `Request` class (`cubicweb.web`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A request instance is created when an HTTP request is sent to the web server.
+It contains informations such as form parameters, user authenticated, etc.
+
+**Globally, a request represents a user query, either through HTTP or not
+(we also talk about RQL queries on the server side for example).**
+
+An instance of `Request` has the following attributes:
+
+* `user`, instance of `cubicweb.common.utils.User` corresponding to the authenticated
+ user
+* `form`, dictionary containing the values of a web form
+* `encoding`, character encoding to use in the response
+
+But also:
+
+:Session data handling:
+ * `session_data()`, returns a dictionary containing all the session data
+ * `get_session_data(key, default=None)`, returns a value associated to the given
+ key or the value `default` if the key is not defined
+ * `set_session_data(key, value)`, assign a value to a key
+ * `del_session_data(key)`, suppress the value associated to a key
+
+
+:Cookies handling:
+ * `get_cookie()`, returns a dictionary containing the value of the header
+ HTTP 'Cookie'
+ * `set_cookie(cookie, key, maxage=300)`, adds a header HTTP `Set-Cookie`,
+ with a minimal 5 minutes length of duration by default (`maxage` = None
+ returns a *session* cookie which will expire when the user closes the browser
+ window)
+ * `remove_cookie(cookie, key)`, forces a value to expire
+
+:URL handling:
+ * `url()`, returns the full URL of the HTTP request
+ * `base_url()`, returns the root URL of the web application
+ * `relative_path()`, returns the relative path of the request
+
+:And more...:
+ * `set_content_type(content_type, filename=None)`, adds the header HTTP
+ 'Content-Type'
+ * `get_header(header)`, returns the value associated to an arbitrary header
+ of the HTTP request
+ * `set_header(header, value)`, adds an arbitrary header in the response
+ * `cursor()` returns a RQL cursor on the session
+ * `execute(*args, **kwargs)`, shortcut to ``.cursor().execute()``
+ * `property_value(key)`, properties management (`CWProperty`)
+ * dictionary `data` to store data to share informations between components
+ *while a request is executed*
+
+Please note that this class is abstract and that a concrete implementation
+will be provided by the *frontend* web used (in particular *twisted* as of
+today). For the views or others that are executed on the server side,
+most of the interface of `Request` is defined in the session associated
+to the client.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/devweb/rtags.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,24 @@
+
+Relation tags
+--------------
+XXX cubicweb.rtags
+ ref to action box and auto edit form
+
+
+*rtags* allow to specify certain behaviors of relations relative to a given
+entity type (see later). They are defined for ::
+
+ <relation type>, <context position ("subject" ou "object")>, <subject entity type or *>, <object entity type or *>
+
+and as values may be a `set` or single value, depending on what the relation tags is used for.
+
+It is possible to simplify this dictionary:
+
+* if we want a marker to apply independently from a subject or object entity type,
+ we have to use the string `*` as entity type
+
+
+Please note that this dictionary is *treated at the time the class is created*.
+It is automatically merged with the parent class(es) (no need to copy the
+dictionary from the parent class to modify it). Also, modifying it after the
+class is created will not have any effect...
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/devweb/views.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,232 @@
+Views
+-----
+
+This chapter aims to describe the concept of a `view` used all along
+the development of a web application and how it has been implemented
+in `CubicWeb`.
+
+We'll start with a description of the interface providing you with a basic
+understanding of the classes and methods available, then detail the view
+selection principle which makes `CubicWeb` web interface very flexible.
+
+A `View` is an object applied to another object such as an entity.
+
+Basic class for views
+---------------------
+
+Class `View` (`cubicweb.view`)
+`````````````````````````````````````
+
+This class is an abstraction of a view class, used as a base class for every
+renderable object such as views, templates, graphic components, etc.
+
+A `View` is instantiated to render a result set or part of a result set. `View`
+subclasses may be parametrized using the following class attributes:
+
+ * `templatable` indicates if the view may be embeded in a main
+ template or if it has to be rendered standalone (i.e. XML views
+ must not be embeded in the main template for HTML pages)
+ * if the view is not templatable, it should set the `content_type` class
+ attribute to the correct MIME type (text/xhtml by default)
+ * the `category` attribute may be used in the interface to regroup related
+ objects together
+
+At instantiation time, the standard `req`, `rset`, and `cursor`
+attributes are added and the `w` attribute will be set at rendering
+time.
+
+A view writes to its output stream thanks to its attribute `w` (`UStreamIO`).
+
+The basic interface for views is as follows (remember that the result set has a
+tabular structure with rows and columns, hence cells):
+
+* `dispatch(**context)`, render the view by calling `call` or
+ `cell_call` depending on the given parameters
+* `call(**kwargs)`, call the view for a complete result set or null (default
+ implementation calls `cell_call()` on each cell of the result set)
+* `cell_call(row, col, **kwargs)`, call the view for a given cell of a result set
+* `url()`, returns the URL enabling us to get the view with the current
+ result set
+* `view(__vid, rset, __fallback_vid=None, **kwargs)`, call the view of identifier
+ `__vid` on the given result set. It is possible to give a view identifier
+ of fallback that will be used if the view requested is not applicable to the
+ result set
+
+* `wview(__vid, rset, __fallback_vid=None, **kwargs)`, similar to `view` except
+ the flow is automatically passed in the parameters
+
+* `html_headers()`, returns a list of HTML headers to set by the main template
+
+* `page_title()`, returns the title to use in the HTML header `title`
+
+
+Other basic view classes
+````````````````````````
+Here are some of the subclasses of `View` defined in `cubicweb.common.view`
+that are more concrete as they relate to data rendering within the application:
+
+* `EntityView`, view applying to lines or cell containing an entity (e.g. an eid)
+* `StartupView`, start view that does not require a result set to apply to
+* `AnyRsetView`, view applied to any result set
+* `EmptyRsetView`, view applied to an empty result set
+
+
+Examples of views class
+-----------------------
+
+- Using `templatable`, `content_type` and HTTP cache configuration
+
+.. code-block:: python
+
+
+ class RSSView(XMLView):
+ id = 'rss'
+ title = _('rss')
+ templatable = False
+ content_type = 'text/xml'
+ http_cache_manager = MaxAgeHTTPCacheManager
+ cache_max_age = 60*60*2 # stay in http cache for 2 hours by default
+
+
+
+- Using custom selector
+
+.. code-block:: python
+
+
+ class SearchForAssociationView(EntityView):
+ """view called by the edition view when the user asks
+ to search for something to link to the edited eid
+ """
+ id = 'search-associate'
+ title = _('search for association')
+ __select__ = one_line_rset() & match_search_state('linksearch') & implements('Any')
+
+
+Example of a view customization
+-------------------------------
+
+[FIXME] XXX Example needs to be rewritten as it shows how to modify cell_call which
+contredicts our advise of not modifying it.
+
+We'll show you now an example of a ``primary`` view and how to customize it.
+
+If you want to change the way a ``BlogEntry`` is displayed, just override
+the method ``cell_call()`` of the view ``primary`` in ``BlogDemo/views.py`` ::
+
+.. code-block:: python
+
+ from cubicweb.view import EntityView
+ from cubicweb.selectors import implements
+
+ class BlogEntryPrimaryView(EntityView):
+ id = 'primary'
+ __select__ =implements('Blog')
+
+ def cell_call(self, row, col):
+ entity = self.entity(row, col)
+ self.w(u'<h1>%s</h1>' % entity.title)
+ self.w(u'<p>published on %s in category %s</p>' % \
+ (entity.publish_date.strftime('%Y-%m-%d'), entity.category))
+ self.w(u'<p>%s</p>' % entity.text)
+
+The above source code defines a new primary view (`line 03`) for
+``BlogEntry`` (`line 05`).
+
+Since views are applied to result sets which can be tables of
+data, we have to recover the entity from its (row,col)-coordinates (`line 08`).
+We will get to this in more detail later.
+
+The view method ``self.w()`` is used to output data. Here `lines
+09-12` output HTML tags and values of the entity's attributes.
+
+When displaying the same blog entry as before, you will notice that the
+page is now looking much nicer. [FIXME: it is not clear to what this refers.]
+
+.. image:: ../../images/lax-book.09-new-view-blogentry.en.png
+ :alt: blog entries now look much nicer
+
+Let us now improve the primary view of a blog
+
+.. code-block:: python
+
+ class BlogPrimaryView(EntityView):
+ id = 'primary'
+ __select__ =implements('Blog')
+
+ def cell_call(self, row, col):
+ entity = self.entity(row, col)
+ self.w(u'<h1>%s</h1>' % entity.title)
+ self.w(u'<p>%s</p>' % entity.description)
+ rset = self.req.execute('Any E WHERE E entry_of B, B eid "%s"' % entity.eid)
+ self.wview('primary', rset)
+
+In the above source code, `lines 01-08` are similar to the previous
+view we defined. [FIXME: defined where ?]
+
+At `line 09`, a simple request is made to build a result set with all
+the entities linked to the current ``Blog`` entity by the relationship
+``entry_of``. The part of the framework handling the request knows
+about the schema and infer that such entities have to be of the
+``BlogEntry`` kind and retrieves them.
+
+The request returns a selection of data called a result set. At
+`line 10` the view 'primary' is applied to this result set to output
+HTML.
+
+**This is to be compared to interfaces and protocols in object-oriented
+languages. Applying a given view called 'a_view' to all the entities
+of a result set only requires to have for each entity of this result set,
+an available view called 'a_view' which accepts the entity.**
+
+Assuming we added entries to the blog titled `MyLife`, displaying it
+now allows to read its description and all its entries.
+
+.. image:: ../../images/lax-book.10-blog-with-two-entries.en.png
+ :alt: a blog and all its entries
+
+**Before we move forward, remember that the selection/view principle is
+at the core of `CubicWeb`. Everywhere in the engine, data is requested
+using the RQL language, then HTML/XML/text/PNG is output by applying a
+view to the result set returned by the query. That is where most of the
+flexibility comes from.**
+
+[WRITE ME]
+
+* implementing interfaces, calendar for blog entries
+* show that a calendar view can export data to ical
+
+We will implement the `cubicweb.interfaces.ICalendarable` interfaces on
+entities.BlogEntry and apply the OneMonthCalendar and iCalendar views
+to result sets like "Any E WHERE E is BlogEntry"
+
+* create view "blogentry table" with title, publish_date, category
+
+We will show that by default the view that displays
+"Any E,D,C WHERE E publish_date D, E category C" is the table view.
+Of course, the same can be obtained by calling
+self.wview('table',rset)
+
+* in view blog, select blogentries and apply view "blogentry table"
+* demo ajax by filtering blogentry table on category
+
+we did the same with 'primary', but with tables we can turn on filters
+and show that ajax comes for free.
+[FILLME]
+
+
+
+XML views, binaries...
+----------------------
+For views generating other formats than HTML (an image generated dynamically
+for example), and which can not simply be included in the HTML page generated
+by the main template (see above), you have to:
+
+* set the attribute `templatable` of the class to `False`
+* set, through the attribute `content_type` of the class, the MIME type generated
+ by the view to `application/octet-stream`
+
+For views dedicated to binary content creation (like dynamically generated
+images), we have to set the attribute `binary` of the class to `True` (which
+implies that `templatable == False`, so that the attribute `w` of the view could be
+replaced by a binary flow instead of unicode).
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/entityclasses/data-as-objects.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,95 @@
+Access to persistent data
+--------------------------
+
+XXX is provided by the :class:`Entity <cubicweb.entity.entity>` class
+
+An entity class is bound to a schema entity type. Descriptors are added when
+classes are registered in order to initialize the class according to its schema:
+
+* we can access the defined attributes in the schema thanks to the attributes of
+ the same name on instances (typed value)
+
+* we can access the defined relations in the schema thanks to the relations of
+ the same name on instances (entities instances list)
+
+
+:Formatting and output generation:
+
+ * `view(vid, **kwargs)`, applies the given view to the entity
+
+ * `absolute_url(**kwargs)`, returns an absolute URL to access the primary view
+ of an entity
+
+ * `rest_path()`, returns a relative REST URL to get the entity
+
+ * `format(attr)`, returns the format (MIME type) of the field given un parameter
+
+ * `printable_value(attr, value=_marker, attrtype=None, format='text/html')`,
+ returns a string enabling the display of an attribute value in a given format
+ (the value is automatically recovered if necessary)
+
+:Data handling:
+
+ * `as_rset()`, converts the entity into an equivalent result set simulating the
+ request `Any X WHERE X eid _eid_`
+
+ * `complete(skip_bytes=True)`, executes a request that recovers in one time
+ all the missing attributes of an entity
+
+ * `get_value(name)`, returns the value associated to the attribute name given
+ in parameter
+
+ * `related(rtype, x='subject', limit=None, entities=False)`, returns a list
+ of entities related to the current entity by the relation given in parameter
+
+ * `unrelated(rtype, targettype, x='subject', limit=None)`, returns a result set
+ corresponding to the entities not related to the current entity by the
+ relation given in parameter and satisfying its constraints
+
+ * `set_attributes(**kwargs)`, updates the attributes list with the corresponding
+ values given named parameters
+
+ * `copy_relations(ceid)`, copies the relations of the entities having the eid
+ given in the parameters on the current entity
+
+ * `last_modified(view)`, returns the date the object has been modified
+ (used by HTTP cache handling)
+
+ * `delete()` allows to delete the entity
+
+
+Tne :class:`AnyEntity` class
+----------------------------
+
+To provide a specific behavior for each entity, we have to define
+a class inheriting from `cubicweb.entities.AnyEntity`. In general, we
+define this class in a module of `mycube.entities` package of an application
+so that it will be available on both server and client side.
+
+The class `AnyEntity` is loaded dynamically from the class `Entity`
+(`cubciweb.entity`). We define a sub-class to add methods or to
+specialize the handling of a given entity type
+
+The methods defined for `AnyEntity` or `Entity` are the following ones:
+
+:Standard meta-data (Dublin Core):
+
+ * `dc_title()`, returns a unicode string corresponding to the meta-data
+ `Title` (used by default the first attribute non-meta of the entity
+ schema)
+
+ * `dc_long_title()`, same as dc_title but can return a more
+ detailled title
+
+ * `dc_description(format='text/plain')`, returns a unicode string
+ corresponding to the meta-data `Description` (look for a description
+ attribute by default)
+
+ * `dc_authors()`, returns a unicode string corresponding to the meta-data
+ `Authors` (owners by default)
+
+ * `dc_date(date_format=None)`, returns a unicode string corresponding to
+ the meta-data `Date` (update date by default)
+
+ * `dc_type(form='')`, returns a string to display the entity type by
+ specifying the preferred form (`plural` for a plural form)
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/entityclasses/index.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,13 @@
+Data as objects
+===============
+
+In this chapter, we will introduce the objects that are used to handle
+the data stored in the database.
+
+.. toctree::
+ :maxdepth: 1
+
+ data-as-objects
+ load-sort
+ interfaces
+ more
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/entityclasses/interfaces.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,16 @@
+Interfaces
+----------
+
+XXX how to define a cw interface
+
+Declaration of interfaces implemented by a class
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+XXX __implements__
+
+
+Interfaces defined in the library
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: cubicweb.interface
+ :members:
+`````````````
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/entityclasses/load-sort.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,38 @@
+
+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.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/entityclasses/more.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,12 @@
+Navigation on deletion
+----------------------
+XXX after_deletion_path, pre_web_edit
+
+Controlling output url
+---------------------
+XXX
+
+Controling notification references
+----------------------------------
+XXX
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/index.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,20 @@
+.. _Part2:
+
+---------------------
+Part II - Development
+---------------------
+
+This part is about developing web applications with the `CubicWeb` framework.
+
+.. toctree::
+ :maxdepth: 2
+
+ cubes/index
+ datamodel/index
+ entityclasses/index
+ devcore/index
+ devweb/index
+ devrepo/index
+ testing/index
+ migration/index
+ webstdlib/index
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/migration/index.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,213 @@
+.. -*- coding: utf-8 -*-
+
+.. _migration:
+
+Migration
+=========
+
+One of the main concept in `CubicWeb` is to create incremental applications.
+For this purpose, multiple actions are provided to facilitate the improvement
+of an application, and in particular to handle the changes to be applied
+to the data model, without loosing existing data.
+
+The current version of an application model is provided in the file
+`__pkginfo__.py` as a tuple of 3 integers.
+
+Migration scripts management
+----------------------------
+
+Migration scripts has to be located in the directory `migration` of your
+application and named accordingly:
+
+::
+
+ <version n° X.Y.Z>[_<description>]_<mode>.py
+
+in which :
+
+* X.Y.Z is the model version number to which the script enables to migrate.
+
+* *mode* (between the last "_" and the extension ".py") is used for
+ distributed installation. It indicates to which part
+ of the application (RQL server, web server) the script applies.
+ Its value could be :
+
+ * `common`, applies to the RQL server as well as the web server and updates
+ files on the hard drive (configuration files migration for example).
+
+ * `web`, applies only to the web server and updates files on the hard drive.
+
+ * `repository`, applies only to the RQL server and updates files on the
+ hard drive.
+
+ * `Any`, applies only to the RQL server and updates data in the database
+ (schema and data migration for example).
+
+Again in the directory `migration`, the file `depends.map` allows to indicate
+that for the migration to a particular model version, you always have to first
+migrate to a particular `CubicWeb` version. This file can contain comments (lines
+starting by `#`) and a dependancy is listed as follows: ::
+
+ <model version n° X.Y.Z> : <cubicweb version n° X.Y.Z>
+
+For example: ::
+
+ 0.12.0: 2.26.0
+ 0.13.0: 2.27.0
+ # 0.14 works with 2.27 <= cubicweb <= 2.28 at least
+ 0.15.0: 2.28.0
+
+Base context
+------------
+
+The following identifiers are pre-defined in migration scripts:
+
+* `config`, instance configuration
+
+* `interactive_mode`, boolean indicating that the script is executed in
+ an interactive mode or not
+
+* `appltemplversion`, application model version of the instance
+
+* `templversion`, installed application model version
+
+* `cubicwebversion`, installed cubicweb version
+
+* `confirm(question)`, function asking the user and returning true
+ if the user answers yes, false otherwise (always returns true in
+ non-interactive mode)
+
+* the function `_`, it is equivalent to `unicode` allowing to flag the strings
+ to internationalize in the migration scripts.
+
+In the `repository` scripts, the following identifiers are also defined:
+
+* `checkpoint`, request confirming and executing a "commit" at checking point
+
+* `repo_schema`, instance persisting schema (e.g. instance schema of the
+ current migration)
+
+* `newschema`, installed schema on the file system (e.g. schema of
+ the updated model and cubicweb)
+
+* `sqlcursor`, SQL cursor for very rare cases where it is really
+ necessary or beneficial to go through the sql
+
+* `repo`, repository object
+
+
+Schema migration
+----------------
+The following functions for schema migration are available in `repository`
+scripts:
+
+* `add_attribute(etype, attrname, attrtype=None, commit=True)`, adds a new
+ attribute to an existing entity type. If the attribute type is not specified,
+ then it is extracted from the updated schema.
+
+* `drop_attribute(etype, attrname, commit=True)`, removes an attribute from an
+ existing entity type.
+
+* `rename_attribute(etype, oldname, newname, commit=True)`, renames an attribute
+
+* `add_entity_type(etype, auto=True, commit=True)`, adds a new entity type.
+ If `auto` is True, all the relations using this entity type and having a known
+ entity type on the other hand will automatically be added.
+
+* `drop_entity_type(etype, commit=True)`, removes an entity type and all the
+ relations using it.
+
+* `rename_entity_type(oldname, newname, commit=True)`, renames an entity type
+
+* `add_relation_type(rtype, addrdef=True, commit=True)`, adds a new relation
+ type. If `addrdef` is True, all the relations definitions of this type will
+ be added.
+
+* `drop_relation_type(rtype, commit=True)`, removes a relation type and all the
+ definitions of this type.
+
+* `rename_relation(oldname, newname, commit=True)`, renames a relation.
+
+* `add_relation_definition(subjtype, rtype, objtype, commit=True)`, adds a new
+ relation definition.
+
+* `drop_relation_definition(subjtype, rtype, objtype, commit=True)`, removes
+ a relation definition.
+
+* `synchronize_permissions(ertype, commit=True)`, synchronizes permissions on
+ an entity type or relation type.
+
+* `synchronize_rschema(rtype, commit=True)`, synchronizes properties and permissions
+ on a relation type.
+
+* `synchronize_eschema(etype, commit=True)`, synchronizes properties and persmissions
+ on an entity type.
+
+* `synchronize_schema(commit=True)`, synchronizes the persisting schema with the
+ updated schema (but without adding or removing new entity types, relations types
+ or even relations definitions).
+
+* `change_relation_props(subjtype, rtype, objtype, commit=True, **kwargs)`, changes
+ properties of a relation definition by using the named parameters of the properties
+ to change.
+
+* `set_widget(etype, rtype, widget, commit=True)`, changes the widget used for the
+ relation <rtype> of entity type <etype>.
+
+* `set_size_constraint(etype, rtype, size, commit=True)`, changes the size constraints
+ for the relation <rtype> of entity type <etype>.
+
+Data migration
+--------------
+The following functions for data migration are available in `repository` scripts:
+
+* `rql(rql, kwargs=None, cachekey=None, ask_confirm=True)`, executes an arbitrary RQL
+ query, either to interrogate or update. A result set object is returned.
+
+* `add_entity(etype, *args, **kwargs)`, adds a nes entity type of the given
+ type. The attribute and relation values are specified using the named and
+ positionned parameters.
+
+Workflow creation
+-----------------
+
+The following functions for workflow creation are available in `repository`
+scripts:
+
+* `add_state(name, stateof, initial=False, commit=False, **kwargs)`, adds a new state
+ in the workflow.
+
+* `add_transition(name, transitionof, fromstates, tostate, requiredgroups=(), commit=False, **kwargs)`,
+ adds a new transition in the workflow.
+
+You can find more details about workflows in the chapter :ref:`Workflow` .
+
+Configuration migration
+-----------------------
+
+The following functions for configuration migration are available in all
+scripts:
+
+* `option_renamed(oldname, newname)`, indicates that an option has been renamed
+
+* `option_group_change(option, oldgroup, newgroup)`, indicates that an option does not
+ belong anymore to the same group.
+
+* `option_added(oldname, newname)`, indicates that an option has been added.
+
+* `option_removed(oldname, newname)`, indicates that an option has been deleted.
+
+
+Others migration functions
+--------------------------
+Those functions are only used for low level operations that could not be
+accomplished otherwise or to repair damaged databases during interactive
+session. They are available in `repository` scripts:
+
+* `sqlexec(sql, args=None, ask_confirm=True)`, executes an arbitrary SQL query
+* `add_entity_type_table(etype, commit=True)`
+* `add_relation_type_table(rtype, commit=True)`
+* `uninline_relation(rtype, commit=True)`
+
+
+[FIXME] Add explanation on how to use cubicweb-ctl shell
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/testing/index.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,44 @@
+.. -*- coding: utf-8 -*-
+
+Tests
+=====
+
+.. toctree::
+ :maxdepth: 1
+
+
+Unit tests
+----------
+
+`CubicWeb` framework provides essentially two Python test classes in the
+module `cubicweb.devtools.apptest`:
+
+* `EnvBasedTC`, to simulate a complete environment (web + repository)
+* `RepositoryBasedTC`, to simulate a repository environment only
+
+Thos two classes almost have the same interface and offers numerous methods to
+write tests rapidely and efficiently.
+
+XXX FILLME describe API
+
+In most of the cases, you will inherit `EnvBasedTC` to write Unittest or
+functional tests for your entities, views, hooks, etc...
+
+
+Email notifications tests
+-------------------------
+When running tests potentially generated e-mails are not really
+sent but is found in the list `MAILBOX` of module `cubicweb.devtools.apptest`.
+This list is reset at each test *setUp* (by the setUp of classes `EnvBasedTC`
+and `RepositoryBasedTC`).
+
+
+You can test your notifications by analyzing the contents of this list, which
+contains objects with two attributes:
+* `recipients`, the list of recipients
+* `msg`, object email.Message
+
+
+Automatic testing
+-----------------
+XXXFILLME
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/webstdlib/autoform.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,31 @@
+The automatic entity form (:mod:`cubicweb.web.views.autoform`)
+---------------------------------------------------------------
+
+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 and represented as a combobox. Each item of the
+ combobox is a link to an existing entity.
+
+* `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 will be included in the
+ editing form and represented as a combobox. Each item of the combobox
+ is a link to an existing entity.
+
+* `inlineview`, includes the target entity's form in the editing form
+ of the current entity. It allows to create the target entity in the
+ same time as the current entity.
+
+* `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 necessary, it is possible to overwrite the method
+`relation_category(rtype, x='subject')` to dynamically compute
+a relation editing category.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/webstdlib/basetemplates.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,189 @@
+.. -*- coding: utf-8 -*-
+
+.. _templates:
+
+Templates
+=========
+
+[WRITE ME]
+
+* talk about main templates, etc.
+
+
+
+Look at ``cubicweb/web/views/basetemplates.py`` and you will
+find the base templates used to generate HTML for your application.
+
+A page is composed as indicated on the schema below :
+
+.. image:: ../../images/lax-book.06-main-template-layout.en.png
+
+In this section we will go through a couple of the primary templates
+you must be interested in, that is to say, the HTMLPageHeader,
+the HTMLPageFooter and the TheMainTemplate.
+
+
+HTMLPageHeader
+--------------
+
+Customize header
+~~~~~~~~~~~~~~~~
+
+Let's now move the search box in the header and remove the login form
+from the header. We'll show how to move it to the left column of the application.
+
+Let's say we do not want anymore the login menu to be in the header, but we
+prefer it to be in the left column just below the logo. As the left column is
+rendered by ``TheMainTemplate``, we will show how to do it in TheMainTemplate_.
+
+First, to remove the login menu, we just need to comment out the display of the
+login component such as follows : ::
+
+ class MyHTMLPageHeader(HTMLPageHeader):
+
+ def main_header(self, view):
+ """build the top menu with authentification info and the rql box"""
+ self.w(u'<table id="header"><tr>\n')
+ self.w(u'<td id="firstcolumn">')
+ self.vreg.select_component('logo', self.req, self.rset).dispatch(w=self.w)
+ self.w(u'</td>\n')
+ # appliname and breadcrumbs
+ self.w(u'<td id="headtext">')
+ comp = self.vreg.select_component('appliname', self.req, self.rset)
+ if comp and comp.propval('visible'):
+ comp.dispatch(w=self.w)
+ comp = self.vreg.select_component('breadcrumbs', self.req, self.rset, view=view)
+ if comp and comp.propval('visible'):
+ comp.dispatch(w=self.w, view=view)
+ self.w(u'</td>')
+ # logged user and help
+ #self.w(u'<td>\n')
+ #comp = self.vreg.select_component('loggeduserlink', self.req, self.rset)
+ #comp.dispatch(w=self.w)
+ #self.w(u'</td><td>')
+
+ self.w(u'<td>')
+ helpcomp = self.vreg.select_component('help', self.req, self.rset)
+ if helpcomp: # may not be available if Card is not defined in the schema
+ helpcomp.dispatch(w=self.w)
+ self.w(u'</td>')
+ # lastcolumn
+ self.w(u'<td id="lastcolumn">')
+ self.w(u'</td>\n')
+ self.w(u'</tr></table>\n')
+ self.template('logform', rset=self.rset, id='popupLoginBox', klass='hidden',
+ title=False, message=False)
+
+
+
+.. image:: ../../images/lax-book.06-header-no-login.en.png
+
+Let's now move the search box in the top-right header area. To do so, we will
+first create a method to get the search box display and insert it in the header
+table.
+
+::
+
+ from cubicweb.web.views.basetemplates import HTMLPageHeader
+ class MyHTMLPageHeader(HTMLPageHeader):
+ def main_header(self, view):
+ """build the top menu with authentification info and the rql box"""
+ self.w(u'<table id="header"><tr>\n')
+ self.w(u'<td id="firstcolumn">')
+ self.vreg.select_component('logo', self.req, self.rset).dispatch(w=self.w)
+ self.w(u'</td>\n')
+ # appliname and breadcrumbs
+ self.w(u'<td id="headtext">')
+ comp = self.vreg.select_component('appliname', self.req, self.rset)
+ if comp and comp.propval('visible'):
+ comp.dispatch(w=self.w)
+ comp = self.vreg.select_component('breadcrumbs', self.req, self.rset, view=view)
+ if comp and comp.propval('visible'):
+ comp.dispatch(w=self.w, view=view)
+ self.w(u'</td>')
+
+ # logged user and help
+ #self.w(u'<td>\n')
+ #comp = self.vreg.select_component('loggeduserlink', self.req, self.rset)
+ #comp.dispatch(w=self.w)
+ #self.w(u'</td><td>')
+
+ # search box
+ self.w(u'<td>')
+ self.get_searchbox(view, 'left')
+ self.w(u'</td>')
+
+ self.w(u'<td>')
+ helpcomp = self.vreg.select_component('help', self.req, self.rset)
+ if helpcomp: # may not be available if Card is not defined in the schema
+ helpcomp.dispatch(w=self.w)
+ self.w(u'</td>')
+ # lastcolumn
+ self.w(u'<td id="lastcolumn">')
+ self.w(u'</td>\n')
+ self.w(u'</tr></table>\n')
+ self.template('logform', rset=self.rset, id='popupLoginBox', klass='hidden',
+ title=False, message=False)
+
+ def get_searchbox(self, view, context):
+ boxes = list(self.vreg.possible_vobjects('boxes', self.req, self.rset,
+ view=view, context=context))
+ if boxes:
+ for box in boxes:
+ if box.id == 'search_box':
+ box.dispatch(w=self.w, view=view)
+
+
+
+
+HTMLPageFooter
+--------------
+
+If you want to change the footer for example, look
+for HTMLPageFooter and override it in your views file as in :
+::
+
+ form cubicweb.web.views.basetemplates import HTMLPageFooter
+ class MyHTMLPageFooter(HTMLPageFooter):
+ def call(self, **kwargs):
+ self.w(u'<div class="footer">')
+ self.w(u'This website has been created with <a href="http://cubicweb.org">CubicWeb</a>.')
+ self.w(u'</div>')
+
+Updating a view does not require any restart of the server. By reloading
+the page you can see your new page footer.
+
+
+TheMainTemplate
+---------------
+.. _TheMainTemplate:
+
+TheMainTemplate is responsible for the general layout of the entire application.
+It defines the template of ``id = main`` that is used by the application.
+
+The default main template (`cubicweb.web.views.basetemplates.TheMainTemplate`)
+builds the page based on the following pattern:
+
+.. image:: ../../images/main_template_layout.png
+
+The rectangle containing `view.dispatch()` represents the area where the content
+view has to be displayed. The others represents sub-templates called to complete
+the page. A default implementation of those is provided in
+`cubicweb.views.basetemplates`. You can, of course, overload those sub-templates
+to implement your own customization of the HTML page.
+
+We can also control certain aspects of the main template thanks to the following
+forms parameters:
+
+* `__notemplate`, if present (whatever the value assigned), only the content view
+ is returned
+* `__force_display`, if present and its value is not null, no navigation
+ whatever the number of entities to display
+* `__method`, if the result set to render contains only one entity and this
+ parameter is set, it refers to a method to call on the entity by passing it
+ the dictionary of the forms parameters, before going the classic way (through
+ step 1 and 2 described juste above)
+
+The MainTemplate is a bit complex as it tries to accomodate many
+different cases. We are now about to go through it and cutomize entirely
+our application.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/webstdlib/baseviews.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,66 @@
+.. -*- coding: utf-8 -*-
+
+Base views (:mod:`cubicweb.web.views.baseviews`)
+------------------------------------------------
+
+`CubicWeb` provides a lot of standard views. You can find them in
+``cubicweb/web/views/``.
+
+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:
+
+HTML views
+~~~~~~~~~~
+*oneline*
+ This is a hyper linked *text* view. 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.
+
+*secondary*
+ This is a combinaison of an icon and a *oneline* view.
+ By default it renders the two first attributes of the entity as a
+ clickable link redirecting to the primary view.
+
+*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.
+
+List
+`````
+*list*
+ This view displays a list of entities by creating a HTML list (`<ul>`)
+ and call the view `listitem` for each entity of the result set.
+
+*listitem*
+ This view redirects by default to the `outofcontext` view.
+
+
+Special views
+`````````````
+
+*noresult*
+ This view is the default view used when no result has been found
+ (e.g. empty result set).
+
+*final*
+ Display the value of a cell without trasnformation (in case of a non final
+ entity, we see the eid). Applicable on any result set.
+
+*null*
+ This view is the default view used when nothing needs to be rendered.
+ It is always applicable and it does not return anything
+
+Text views
+~~~~~~~~~~
+*text*
+ This is the simplest text view for an entity. It displays the
+ title of an entity. It should not contain HTML.
+
+*textincontext, textoutofcontext*
+ Similar to the `text` view, but called when 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.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/webstdlib/boxes.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,34 @@
+Boxes (:mod:`cubicweb.web.views.boxes`)
+---------------------------------------------------------------
+
+*sidebox*
+ This view displays usually a side box of some related entities
+ in a primary view.
+
+The action box
+~~~~~~~~~~~~~~~
+
+The ``add_related`` is an automatic menu in the action 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
+`cubicweb.web.uicfg.rmode` *relation tag*:
+
+* `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 necessary, 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).
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/webstdlib/breadcrumbs.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,3 @@
+Breadcrumbs (:mod:`cubicweb.web.views.ibreadcrumbs`)
+----------------------------------------------------
+XXX feedme
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/webstdlib/editcontroller.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,118 @@
+.. -*- coding: utf-8 -*-
+The 'edit' controller (:mod:`cubicweb.web.views.editcontroller`)
+----------------------------------------------------------------
+
+Editing control
+~~~~~~~~~~~~~~~~
+
+Re-requisites: the parameters related to entities to edit are
+specified as follows ::
+
+ <field name>:<entity eid>
+
+where entity eid could be a letter in case of an entity to create. We
+name those parameters as *qualified*.
+
+1. Retrieval of entities to edit by looking for the forms parameters
+ starting by `eid:` and also having a parameter `__type` associated
+ (also *qualified* by eid)
+
+2. For all the attributes and the relations of an entity to edit:
+
+ 1. search for a parameter `edits-<relation name>` or `edito-<relation name>`
+ qualified in the case of a relation where the entity is object
+ 2. if found, the value returned is considered as the initial value
+ for this relaiton and we then look for the new value(s) in the parameter
+ <relation name> (qualified)
+ 3. if the value returned is different from the initial value, an database update
+ request is done
+
+3. For each entity to edit:
+
+ 1. if a qualified parameter `__linkto` is specified, its value has to be
+ a string (or a list of string) such as: ::
+
+ <relation type>:<eids>:<target>
+
+ where <target> is either `subject` or `object` and each eid could be
+ separated from the others by a `_`. Target specifies if the *edited entity*
+ is subject or object of the relation and each relation specified will
+ be inserted.
+
+ 2. if a qualified parameter `__clone_eid` is specified for an entity, the
+ relations of the specified entity passed as value of this parameter are
+ copied on the edited entity.
+
+ 3. if a qualified parameter `__delete` is specified, its value must be
+ a string or a list of string such as follows: ::
+
+ <ssubjects eids>:<relation type>:<objects eids>
+
+ where each eid subject or object can be seperated from the other
+ by `_`. Each relation specified will be deleted.
+
+ 4. if a qualified parameter `__insert` is specified, its value should
+ follow the same pattern as `__delete`, but each relation specified is
+ inserted.
+
+4. If the parameters `__insert` and/or `__delete` are found not qualified,
+ they are interpreted as explained above (independantly from the number
+ of entities edited).
+
+5. If no entity is edited but the form contains the parameters `__linkto`
+ and `eid`, this one is interpreted by using the value specified for `eid`
+ to designate the entity on which to add the relations.
+
+
+.. note::
+
+ * If the parameter `__action_delete` is found, all the entities specified
+ as to be edited will be deleted.
+
+ * If the parameter`__action_cancel` is found, no action is completed.
+
+ * If the parameter `__action_apply` is found, the editing is applied
+ normally but the redirection is done on the form
+ (see :ref:`RedirectionControl`).
+
+ * The parameter `__method` is also supported as for the main template
+ (XXX not very consistent, maybe __method should be dealed in the view
+ controller).
+
+ * If no entity is found to be edited and if there is no parameter
+ `__action_delete`, `__action_cancel`, `__linkto`, `__delete` or
+ `__insert`, an error is raised.
+
+ * Using the parameter `__message` in the form will allow to use its value
+ as a message to provide the user once the editing is completed.
+
+
+.. _RedirectionControl:
+
+Redirection control
+~~~~~~~~~~~~~~~~~~~
+Once editing is completed, there is still an issue left: where should we go
+now? If nothing is specified, the controller will do his job but it does not
+mean we will be happy with the result. We can control that by using the
+following parameters:
+
+* `__redirectpath`: path of the URL (relative to the root URL of the site,
+ no form parameters
+
+* `__redirectparams`: forms parameters to add to the path
+
+* `__redirectrql`: redirection RQL request
+
+* `__redirectvid`: redirection view identifier
+
+* `__errorurl`: initial form URL, used for redirecting in case a validation
+ error is raised during editing. If this one is not specified, an error page
+ is displayed instead of going back to the form (which is, if necessary,
+ responsible for displaying the errors)
+
+* `__form_id`: initial view form identifier, used if `__action_apply` is
+ found
+
+In general we use either `__redirectpath` and `__redirectparams` or
+`__redirectrql` and `__redirectvid`.
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/webstdlib/editforms.py Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,3 @@
+Standard forms (:mod:`cubicweb.web.views.editforms`)
+-----------------------------------------------------
+XXX feed me
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/webstdlib/embedding.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,9 @@
+.. -*- coding: utf-8 -*-
+
+Embedding external pages (:mod:`cubicweb.web.views.embedding`)
+---------------------------------------------------------------
+
+including external content
+
+XXX feeed me
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/webstdlib/facets.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,3 @@
+Facets (:mod:`cubicweb.web.views.facets`)
+-----------------------------------------
+XXX feed me
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/webstdlib/idownloadable.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,3 @@
+The 'download' view (:mod:`cubicweb.web.views.idownloadable`)
+---------------------------------------------------------------
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/webstdlib/index.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,27 @@
+Standard features for web interface development
+===============================================
+
+This chapter describes generic web features built as CubicWeb application objects.
+
+They are used for CubicWeb default automatic interface, but you're free to use
+them or not for you're own application.
+
+.. toctree::
+ :maxdepth: 1
+
+ basetemplates
+ primary
+ baseviews
+ startup
+ boxes
+ table
+ xmlrss
+ autoform
+ editforms
+ editcontroller
+ urlpublish
+ breadcrumbs
+ facets
+ wdoc
+ embedding
+ idownloadable
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/webstdlib/primary.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,117 @@
+The default 'primary' view (:mod:`cubicweb.web.views.primary`)
+---------------------------------------------------------------
+
+The primary view of an entity 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.
+
+
+
+Rendering methods and attributes for ``PrimaryView``
+----------------------------------------------------
+
+By default, `CubicWeb` provides a primary view for each new entity type
+you create. The first view you might be interested in modifying.
+
+Let's have a quick look at the EntityView ``PrimaryView`` as well as
+its rendering method
+
+.. code-block:: python
+
+ class PrimaryView(EntityView):
+ """the full view of an non final entity"""
+ id = 'primary'
+ title = _('primary')
+ show_attr_label = True
+ show_rel_label = True
+ skip_none = True
+ skip_attrs = ('eid', 'creation_date', 'modification_date')
+ skip_rels = ()
+ main_related_section = True
+
+ ...
+
+ def cell_call(self, row, col):
+ self.row = row
+ self.render_entity(self.complete_entity(row, col))
+
+ def render_entity(self, entity):
+ """return html to display the given entity"""
+ siderelations = []
+ self.render_entity_title(entity)
+ self.render_entity_metadata(entity)
+ # entity's attributes and relations, excluding meta data
+ # if the entity isn't meta itself
+ self.w(u'<div>')
+ self.w(u'<div class="mainInfo">')
+ self.render_entity_attributes(entity, siderelations)
+ self.w(u'</div>')
+ self.content_navigation_components('navcontenttop')
+ if self.main_related_section:
+ self.render_entity_relations(entity, siderelations)
+ self.w(u'</div>')
+ # side boxes
+ self.w(u'<div class="primaryRight">')
+ self.render_side_related(entity, siderelations)
+ self.w(u'</div>')
+ self.w(u'<div class="clear"></div>')
+ self.content_navigation_components('navcontentbottom')
+
+ ...
+
+``cell_call`` is executed for each entity of a result set and apply ``render_entity``.
+
+The methods you want to modify while customizing a ``PrimaryView`` are:
+
+*render_entity_title(self, entity)*
+ Renders the entity title based on the assumption that the method
+ ``def content_title(self)`` is implemented for the given entity type.
+
+*render_entity_metadata(self, entity)*
+ Renders the entity metadata based on the assumption that the method
+ ``def summary(self)`` is implemented for the given entity type.
+
+*render_entity_attributes(self, entity, siderelations)*
+ Renders all the attribute of an entity with the exception of attribute
+ of type `Password` and `Bytes`.
+
+*content_navigation_components(self, context)*
+ This method is applicable only for entity type implementing the interface
+ `IPrevNext`. This interface is for entities which can be linked to a previous
+ and/or next entity. This methods will render the navigation links between
+ entities of this type, either at the top or at the bottom of the page
+ given the context (navcontent{top|bottom}).
+
+*render_entity_relations(self, entity, siderelations)*
+ Renders all the relations of the entity in the main section of the page.
+
+*render_side_related(self, entity, siderelations)*
+ Renders all the relations of the entity in a side box. This is equivalent
+ to *render_entity_relations* in addition to render the relations
+ in a box.
+
+Also, please note that by setting the following attributes in you class,
+you can already customize some of the rendering:
+
+*show_attr_label*
+ Renders the attribute label next to the attribute value if set to True.
+ Otherwise, does only display the attribute value.
+
+*show_rel_label*
+ Renders the relation label next to the relation value if set to True.
+ Otherwise, does only display the relation value.
+
+*skip_none*
+ Does not render an attribute value that is None if set to True.
+
+*main_related_section*
+ Renders the relations of the entity if set to True.
+
+A good practice is for you to identify the content of your entity type for which
+the default rendering does not answer your need so that you can focus on the specific
+method (from the list above) that needs to be modified. We do not recommand you to
+overwrite ``render_entity`` as you might potentially loose the benefits of the side
+boxes handling.
+
+.. XXX talk about uicfg.rdisplay
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/webstdlib/startup.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,13 @@
+Startup views (:mod:`cubicweb.web.views.startup`)
+-------------------------------------------------
+Usual selector: no_rset or yes.
+
+Views that don't apply to a result set
+
+*index*
+ This view defines the home page of your application. It does not require
+ a result set to apply to.
+
+*schema*
+ A view dedicated to the display of the schema of the application
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/webstdlib/table.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,10 @@
+Table views (:mod:`cubicweb.web.views.table`)
+----------------------------------------------
+
+*table*
+ Creates a HTML table (`<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
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/webstdlib/urlpublish.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,6 @@
+.. -*- coding: utf-8 -*-
+URL Rewriting (:mod:`cubicweb.web.views.urlpublish`) and (:mod:`cubicweb.web.views.urlrewrite`)
+------------------------------------------------------------------------------------------------
+
+XXX feed me
+show how urls are mapped to selections and views and explain URLRewriting
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/webstdlib/wdoc.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,7 @@
+.. -*- coding: utf-8 -*-
+
+Online documentation system (:mod:`cubicweb.web.views.wdoc`)
+-------------------------------------------------------------
+
+XXX describe the on-line documentation system
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/webstdlib/xmlrss.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,10 @@
+XML and RSS views (:mod:`cubicweb.web.views.xmlrss`)
+----------------------------------------------------
+
+*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 dublin core
+ methods of the entity (`dc_*`)
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/index.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,64 @@
+.. -*- coding: utf-8 -*-
+
+.. _contents:
+
+=====================================================
+`CubicWeb` - The Semantic Web is a construction game!
+=====================================================
+
+`CubicWeb` is a semantic web application framework, licensed under the LGPL,
+that empowers developers to efficiently build web applications by reusing
+components (called `cubes`) and following the well known object-oriented design
+principles.
+
+Its main features are:
+
+* an engine driven by the explicit :ref:`data model <DefineDataModel>` of the application,
+* a query language name :ref:`RQL <RQL>` similar to W3C's SPARQL,
+* a :ref:`selection+view <DefineViews>` mechanism for semi-automatic XHTML/XML/JSON/text generation,
+* a library of reusable :ref:`components <cubes>` (data model and views) that fulfill common needs,
+* the power and flexibility of the Python_ programming language,
+* the reliability of SQL databases, LDAP directories, Subversion and Mercurial for storage backends.
+
+Built since 2000 from an R&D effort still continued, supporting 100,000s of
+daily visits at some production sites, `CubicWeb` is a proven end to end solution
+for semantic web application development that promotes quality, reusability and
+efficiency.
+
+The unbeliever will read the :ref:`Tutorial`.
+
+The hacker will join development at the forge_.
+
+The impatient will go strait away to :ref:`QuickInstall`.
+
+The impatient developper will move right away to :ref:`SetUpEnv`.
+
+.. _Logilab: http://www.logilab.fr/
+.. _forge: http://www.cubicweb.org/project/
+.. _Python: http://www.python.org/
+
+The book
+========
+
+.. toctree::
+ :maxdepth: 2
+
+ intro/index
+ development/index
+ admin/index
+ annexes/index
+
+
+
+Table of Contents
+-----------------
+
+Complete :ref:`TOC`.
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
--- a/doc/book/en/index.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,63 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-.. _contents:
-
-=====================================================
-`CubicWeb` - The Semantic Web is a construction game!
-=====================================================
-
-`CubicWeb` is a semantic web application framework, licensed under the LGPL,
-that empowers developers to efficiently build web applications by reusing
-components (called `cubes`) and following the well known object-oriented design
-principles.
-
-Its main features are:
-
-* an engine driven by the explicit :ref:`data model <DefineDataModel>` of the application,
-* a query language name :ref:`RQL <RQL>` similar to W3C's SPARQL,
-* a :ref:`selection+view <DefineViews>` mechanism for semi-automatic XHTML/XML/JSON/text generation,
-* a library of reusable :ref:`components <cubes>` (data model and views) that fulfill common needs,
-* the power and flexibility of the Python_ programming language,
-* the reliability of SQL databases, LDAP directories, Subversion and Mercurial for storage backends.
-
-Built since 2000 from an R&D effort still continued, supporting 100,000s of
-daily visits at some production sites, `CubicWeb` is a proven end to end solution
-for semantic web application development that promotes quality, reusability and
-efficiency.
-
-The unbeliever will read the :ref:`Tutorial`.
-
-The hacker will join development at the forge_.
-
-The impatient will go strait away to :ref:`QuickInstall`.
-
-The impatient developper will move right away to :ref:`SetUpEnv`.
-
-.. _Logilab: http://www.logilab.fr/
-.. _forge: http://www.cubicweb.org/project/
-.. _Python: http://www.python.org/
-
-The book
-========
-
-.. toctree::
- :maxdepth: 2
-
- A000-introduction.en.txt
- B000-development.en.txt
- C000-administration.en.txt
- D000-annex.en.txt
-
-
-Table of Contents
------------------
-
-Complete :ref:`TOC`.
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/intro/book-map.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,10 @@
+.. -*- coding: utf-8 -*-
+
+Book map
+========
+
+[XXX WRITE ME]
+
+* explain how to use this book and what chapters to read in what order depending on the
+ objectives of the reader
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/intro/concepts/index.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,265 @@
+.. -*- coding: utf-8 -*-
+
+The Core Concepts of CubicWeb
+=============================
+
+.. toctree::
+ :maxdepth: 1
+
+------------------------------
+
+This section aims to provide you the keys of success with *CubicWeb*
+by clarifying the terms specific to our framework. If you want to do anything
+serious with CubicWeb, you should understand concepts in those lines.
+
+*CubicWeb* defines its own terminology. To make sure there is no confusion
+while reading this book, we strongly recommand you take time to go through
+the following definitions that are the basics to understand while
+developing with *CubicWeb*.
+
+
+.. _Cube:
+
+Cubes
+-----
+** Construct your application by assembling cubes **
+
+A cube provides a specific functionality, or a complete *CubicWeb*
+application usually by assembling other cubes.
+
+It's usually composed of a data model, some logic to manipulate it and some parts
+of web interface.
+
+You can decide to write your own set of cubes if you wish to re-use the
+entity types you develop or/and if you have specific needs not covered by
+cubes are available from the `CubicWeb Forge`_ under a free software license.
+
+Available cubes on your system are defined in the directory
+:file:`/usr/share/cubicweb/cubes` when using a system wide installation. For people
+using the mercurial repository of cubicweb, the :file:`/path/to/forest/cubicweb/cubes`
+directory is used. You can specify additional location using the :envvar:`CW_CUBES_PATH`
+environment variable, using ':' as separator.
+
+.. _`CubicWeb Forge`: http://www.cubicweb.org/project/
+
+
+
+Instances
+----------
+** *CubicWeb* framework is a server/client application framework**
+
+An instance is a specific installation of one or multiple cubes. All the required
+configuration files necessary for the well being of your web application are
+grouped in an instance. This will refer to the cube(s) your application is based
+on. For example logilab.org and our intranet are two instances of a single cube
+`jpl`
+
+We recommand not to define schema, entities or views in the instance
+file system itself but in the cube, in order to maintain re-usability of
+entities and their views. We strongly recommand to develop cubes which
+could be used in other instances (modular approach).
+
+An instance usually usually consists into a web interface which is talking to a
+rql repository, itself connected to a SQL database, all into a single
+process. You can have some more complicated configurations using several web
+front-ends talking to a rql repository using `Pyro`_, databases replication...
+
+.. image:: ../../images/archi_globale.en.png
+
+The term application is sometimes used to talk about an instance and sometimes to
+talk of a cube depending on the context. So we would like to avoid using this
+term and try to use *cube* and *instance* instead.
+
+Data Repository
+~~~~~~~~~~~~~~~
+The repository (Be carefull not to get confused with a Mercurial repository or a
+debian repository!) manages all interactions with various data sources by
+providing access to them using uniformly using the Relation Query Language (RQL). The
+web interface and the repository communicate using this language.
+
+Usually, the web server and repository sides are integrated in the same process and
+interact directly, without the need for distant calls using Pyro. But, it is
+important to note that those two sides, client/server, are disjointed and it is
+possible to execute a couple of calls in distinct processes to balance the load
+of your web site on one or more machines.
+
+
+A data source is a container of data integrated in the *CubicWeb* repository. A
+repository has at least one source, named `system`, which contains the schema of
+the application, plain-text index and other vital informations for the
+system. You'll find source for SQL databases, LDAP servers, other RQL
+repositories and even mercurial /svn repositories or `Google App Engine`'s
+datastore.
+
+Web interface
+~~~~~~~~~~~~~
+By default the web server provides a generated interface based on its schema.
+Entities can be created, displayed, updated and deleted. As display views are not
+very fancy, it is usually necessary to develop your own.
+
+Instances are defined on your system in the directory :file:`/etc/cubicweb.d` when
+using a system wide installation. For people using the mercurial repository of
+cubicweb, the :file:`etc` directory is searched in the user home directory. You can
+also specify an alternative directory using the :envvar:`CW_REGISTRY` environment
+variable.
+
+
+
+Schema
+------
+** *CubicWeb* is schema driven **
+
+The schema describes the persistent data model using entities and
+relations. It is modeled with a comprehensive language made of Python classes based on
+the `yams`_ library.
+
+When you create a new cubicweb instance, the schema is stored in the database,
+and it will usually evolves as you upgrade cubicweb and used cubes.
+
+*CubicWeb* provides a certain number of system entities included
+sytematically (necessary for the core of *CubicWeb*, notably the schema itself).
+You will also find a library of cubes which defines more piece of schema for standard needs.
+necessary.
+
+*CubicWeb* add some metadata to every entity type, such as the eid (a global
+ identifier, unique into an instance), entity's creation date...
+
+
+Attributes may be of the following types:
+ `String`, `Int`, `Float`, `Boolean`, `Date`, `Time`, `Datetime`,
+ `Interval`, `Password`, `Bytes`.
+
+New in 3.2: RichString
+
+see :ref:`yams.BASE_TYPES`
+
+Data level security is defined by setting permissions on entity and relation types.
+
+A schema consist of parts detailed below.
+
+
+Entity type
+~~~~~~~~~~~
+An *entity type* defines set of attributes and is used in some relations. It may
+have some permissions telling who can read/add/update/delete entities of this type.
+
+Relation type
+~~~~~~~~~~~~~
+A *relation type* is used to define a semantic relation between two entity types.
+It may have some permissions telling who can read/add/delete relation of this type.
+
+In *CubicWeb* relations are ordered and binary: by convention we name the first
+item of a relation the `subject` and the second the `object`.
+
+Relation definition
+~~~~~~~~~~~~~~~~~~~
+A *relation definition* is a 3-uple (*subject entity type*, *relation type*, *object
+entity type*), with an associated set of property such as cardinality, constraints...
+
+
+
+Dynamic objects for reusable components
+---------------------------------------
+** Dynamic objects management or how CubicWeb provides really reusable components **
+
+Application objects
+~~~~~~~~~~~~~~~~~~~
+Beside a few core functionalities, almost every feature of the framework is
+acheived by dynamic objects (`application objects` or `appobjects`) stored in a
+two-levels registry (the `vregistry`). Each object is affected to a registry with
+an identifier in this registry. You may have more than one object sharing an
+identifier in the same registry, At runtime, appobjects are selected in the
+vregistry according to the context.
+
+Application objects are stored in the registry using a two level hierarchy :
+
+ object's `__registry__` : object's `id` : [list of app objects]
+
+The base class of appobjects is `AppRsetObject` (module `cubicweb.appobject`).
+
+The `vregistry`
+~~~~~~~~~~~~~~~
+At startup, the `registry` or registers base, inspects a number of directories
+looking for compatible classes definition. After a recording process, the objects
+are assigned to registers so that they can be selected dynamically while the
+application is running.
+
+Selectors
+~~~~~~~~~
+Each appobject has a selector, which is used to score how well it suits to a
+given context by returning a score. A score of 0 means the object doesn't apply
+to the context. The score is used to choose the most pertinent object: the "more"
+the appobject suits the context the higher the score.
+
+CubicWeb provides a set of basic selectors which may be parametrized and combined
+using binary `&` and `|` operators to provide a custom selector (which can be
+itself reused...).
+
+There is 3 current ways to retreive some appobject from the repository:
+
+* get the most appropriate objects by specifying a registry and an identifier. In
+ that case, the object with the greatest score is selected. There should always
+ be a single appobject with a greater score than others.
+
+* get all appobjects applying to a context by specifying a registry.In
+ that case, every objects with the a postive score are selected.
+
+* get the object within a particular registry/identifier. In that case no
+ selection process is involved, the vregistry will expect to find a single
+ object in that cell.
+
+Selector sets are the glue that tie views to the data model. Using them
+appropriately is an essential part of the construction of well behaved cubes.
+
+
+When no score is higher than the others, an exception is raised in development
+mode to let you know that the engine was not able to identify the view to
+apply. This error is silented in production mode and one of the objects with the
+higher score is picked.
+
+If no object has a positive score, ``NoSelectableObject`` exception is raised.
+
+If no object is found for a particular registry and identifier,
+``ObjectNotFound`` exception is raised.
+
+In such cases you would need to review your design and make sure your views are
+properly defined.
+
+
+
+The RQL query language
+----------------------
+**No needs for a complicated ORM when you've a powerful query language**
+
+All the persistant data in a CubicWeb application is retreived and modified by using the
+Relation Query Language.
+
+This query language is inspired by SQL but is on a higher level in order to
+emphasize browsing relations.
+
+db-api
+~~~~~~
+The repository exposes a `db-api`_ like api but using the RQL instead of SQL.
+XXX feed me
+
+Result set
+~~~~~~~~~~
+XXX feed me
+
+
+Views
+-----
+** *CubicWeb* is data driven **
+
+XXX feed me.
+
+
+Hooks
+-----
+** *CubicWeb* provides an extensible data repository **
+
+XXX feed me.
+
+
+.. _`Python Remote Object`: http://pyro.sourceforge.net/
+.. _`yams`: http://www.logilab.org/project/yams/
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/intro/foundations/index.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,33 @@
+.. -*- coding: utf-8 -*-
+
+`CubicWeb` Foundations
+======================
+
+A little history...
+-------------------
+
+`CubicWeb` is a web application framework developped by Logilab_ since 2001.
+
+Entirely written in Python, `CubicWeb` publishes data from all sorts
+of sources such as SQL database, LDAP directory and versioning system such
+as subversion.
+
+`CubicWeb` user interface was designed to let the final user a huge flexibility
+on how to select and how to display content. It allows to browse the knowledge
+database and to display the results with the best rendering according to
+the context.
+This interface flexibility gives back the user the control of the
+rendering parameters that are usually reserved for developpers.
+
+
+We can list a couple of web applications developped with `CubicWeb`, an online
+public phone directory (see http://www.118000.fr/), a system for managing
+digital studies and simulations for a research lab, a tool for shared children
+babysitting (see http://garde-partagee.atoukontact.fr/), a tool to manage
+software developpment (see http://www.logilab.org), an application for
+managing museums collections (see
+http://collections.musees-haute-normandie.fr/collections/), etc.
+
+In 2008, `CubicWeb` was ported for a new type of source : the datastore
+from `GoogleAppEngine`_.
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/intro/index.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,20 @@
+.. -*- coding: utf-8 -*-
+
+.. _Part1:
+
+-----------------------------------
+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
+overview of its features and list its key concepts.
+
+
+.. toctree::
+ :maxdepth: 2
+
+ book-map
+ foundations/index
+ concepts/index
+ tutorial/index
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/intro/tutorial/blog-less-ten-minutes.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,26 @@
+.. -*- coding: utf-8 -*-
+
+.. _BlogTenMinutes:
+
+Get a Blog running in less than ten minutes!
+--------------------------------------------
+
+You need to install the following packages (:ref:`DebianInstallation`)::
+
+ cubicweb, cubicweb-dev, cubicweb-blog
+
+Creation and initialization of your application by running::
+
+ cubicweb-ctl create blog myblog
+
+Your application is now ready to go::
+
+ cubicweb-ctl start -D myblog
+
+This is it. Your blog is ready to you. Go to http://localhost:8080 and enjoy!!
+
+As a developper, you'll want to know more about how to develop new
+cubes and cutomize the look of your application and this is what we
+talk about now.
+
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/intro/tutorial/components.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,81 @@
+.. -*- coding: utf-8 -*-
+
+.. _cubes:
+
+Cubes
+-----
+
+Standard library
+~~~~~~~~~~~~~~~~
+
+A library of standard cubes are available from `CubicWeb Forge`_
+Cubes provide entities and views.
+
+The available application entities are:
+
+* addressbook: PhoneNumber and PostalAddress
+
+* basket: Basket (like a shopping cart)
+
+* blog: Blog (a *very* basic blog)
+
+* classfolder: Folder (to organize things but grouping them in folders)
+
+* classtags: Tag (to tag anything)
+
+* file: File (to allow users to upload and store binary or text files)
+
+* link: Link (to collect links to web resources)
+
+* mailinglist: MailingList (to reference a mailing-list and the URLs
+ for its archives and its admin interface)
+
+* person: Person (easily mixed with addressbook)
+
+* task: Task (something to be done between start and stop date)
+
+* zone: Zone (to define places within larger places, for example a
+ city in a state in a country)
+
+The available system entities are:
+
+* comment: Comment (to attach comment threads to entities)
+
+
+Adding comments to BlogDemo
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To import a cube in your application just change the line in the
+``__pkginfo__.py`` file and verify that the cube you are planning
+to use is listed by the command ``cubicweb-ctl list``.
+For example::
+
+ __use__ = ('comment',)
+
+will make the ``Comment`` entity available in your ``BlogDemo``
+application.
+
+Change the schema to add a relationship between ``BlogEntry`` and
+``Comment`` and you are done. Since the comment cube defines the
+``comments`` relationship, adding the line::
+
+ comments = ObjectRelation('Comment', cardinality='1*', composite='object')
+
+to the definition of a ``BlogEntry`` will be enough.
+
+Synchronize the data model
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Once you modified your data model, you need to synchronize the
+database with your model. For this purpose, `CubicWeb` provides
+a very useful command ``cubicweb-ctl shell blogdemo`` which
+launches an interactive migration Python shell. (see
+:ref:`cubicweb-ctl-shell` for more details))
+As you modified a relation from the `BlogEntry` schema,
+run the following command:
+::
+
+ synchronize_rschema('BlogEntry')
+
+You can now start your application and add comments to each
+`BlogEntry`.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/intro/tutorial/conclusion.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,17 @@
+.. -*- coding: utf-8 -*-
+
+What's next?
+------------
+
+We demonstrated how from a straight out of the box `CubicWeb`
+installation, you can build your web-application based on a
+schema. It's all already there: views, templates, permissions,
+etc. The step forward is now for you to customize according
+to your needs.
+
+More than a web application, many features are available to
+extend your application, for example: RSS channel integration
+(:ref:`rss`), hooks (:ref:`hooks`), support of sources such as
+Google App Engine (:ref:`gaecontents`) and lots of others to
+discover through our book.
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/intro/tutorial/create-cube.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,269 @@
+.. -*- coding: utf-8 -*-
+
+Create your cube
+----------------
+
+Once your `CubicWeb` development environment is set up, you can create a new
+cube::
+
+ cubicweb-ctl newcube blog
+
+This will create in the cubes directory (``/path/to/forest/cubes`` for Mercurial
+installation, ``/usr/share/cubicweb/cubes`` for debian packages installation)
+a directory named ``blog`` reflecting the structure described in :ref:`cubesConcepts`.
+
+.. _DefineDataModel:
+
+Define your data model
+----------------------
+
+The data model or schema is the core of your `CubicWeb` application.
+It defines the type of content your application will handle.
+
+The data model of your cube ``blog`` is defined in the file ``schema.py``:
+
+::
+
+ class Blog(EntityType):
+ title = String(maxsize=50, required=True)
+ description = String()
+
+ class BlogEntry(EntityType):
+ title = String(required=True, fulltextindexed=True, maxsize=256)
+ publish_date = Date(default='TODAY')
+ content = String(required=True, fulltextindexed=True)
+ entry_of = SubjectRelation('Blog', cardinality='?*')
+
+
+A Blog has a title and a description. The title is a string that is
+required by the class EntityType and must be less than 50 characters.
+The description is a string that is not constrained.
+
+A BlogEntry has a title, a publish_date and a content. The title is a
+string that is required and must be less than 100 characters. The
+publish_date is a Date with a default value of TODAY, meaning that
+when a BlogEntry is created, its publish_date will be the current day
+unless it is modified. The content is a string that will be indexed in
+the full-text index and has no constraint.
+
+A BlogEntry also has a relationship ``entry_of`` that links it to a
+Blog. The cardinality ``?*`` means that a BlogEntry can be part of
+zero or one Blog (``?`` means `zero or one`) and that a Blog can
+have any number of BlogEntry (``*`` means `any number including
+zero`). For completeness, remember that ``+`` means `one or more`.
+
+
+Create your instance
+--------------------
+
+To use this cube as an application and create a new instance named ``blogdemo``, do::
+
+ cubicweb-ctl create blog blogdemo
+
+
+This command will create the corresponding database and initialize it.
+
+Welcome to your web application
+-------------------------------
+
+Start your application in debug mode with the following command: ::
+
+ cubicweb-ctl start -D blogdemo
+
+
+You can now access your web application to create blogs and post messages
+by visiting the URL http://localhost:8080/.
+
+A login form will appear. By default, the application will not allow anonymous
+users to enter the application. To login, you need then use the admin account
+you created at the time you initialized the database with ``cubicweb-ctl
+create``.
+
+.. image:: ../../images/login-form.png
+
+
+Once authenticated, you can start playing with your application
+and create entities.
+
+.. image:: ../../images/blog-demo-first-page.png
+
+Please notice that so far, the `CubicWeb` franework managed all aspects of
+the web application based on the schema provided at first.
+
+
+Add entities
+------------
+
+We will now add entities in our web application.
+
+Add a Blog
+~~~~~~~~~~
+
+Let us create a few of these entities. Click on the `[+]` at the left of the
+link Blog on the home page. Call this new Blog ``Tech-blog`` and type in
+``everything about technology`` as the description, then validate the form by
+clicking on ``Validate``.
+
+.. image:: ../../images/cbw-create-blog.en.png
+ :alt: from to create blog
+
+Click on the logo at top left to get back to the home page, then
+follow the Blog link that will list for you all the existing Blog.
+You should be seeing a list with a single item ``Tech-blog`` you
+just created.
+
+.. image:: ../../images/cbw-list-one-blog.en.png
+ :alt: displaying a list of a single blog
+
+Clicking on this item will get you to its detailed description except
+that in this case, there is not much to display besides the name and
+the phrase ``everything about technology``.
+
+Now get back to the home page by clicking on the top-left logo, then
+create a new Blog called ``MyLife`` and get back to the home page
+again to follow the Blog link for the second time. The list now
+has two items.
+
+.. image:: ../../images/cbw-list-two-blog.en.png
+ :alt: displaying a list of two blogs
+
+Add a BlogEntry
+~~~~~~~~~~~~~~~
+
+Get back to the home page and click on [+] at the left of the link
+BlogEntry. Call this new entry ``Hello World`` and type in some text
+before clicking on ``Validate``. You added a new blog entry without
+saying to what blog it belongs. There is a box on the left entitled
+``actions``, click on the menu item ``modify``. You are back to the form
+to edit the blog entry you just created, except that the form now has
+another section with a combobox titled ``add relation``. Chose
+``entry_of`` in this menu and a second combobox appears where you pick
+``MyLife``.
+
+You could also have, at the time you started to fill the form for a
+new entity BlogEntry, hit ``Apply`` instead of ``Validate`` and the
+combobox titled ``add relation`` would have showed up.
+
+
+.. image:: ../../images/cbw-add-relation-entryof.en.png
+ :alt: editing a blog entry to add a relation to a blog
+
+Validate the changes by clicking ``Validate``. The entity BlogEntry
+that is displayed now includes a link to the entity Blog named
+``MyLife``.
+
+.. image:: ../../images/cbw-detail-one-blogentry.en.png
+ :alt: displaying the detailed view of a blogentry
+
+Note that all of this was handled by the framework and that the only input
+that was provided so far is the schema. To get a graphical view of the schema,
+point your browser to the URL http://localhost:8080/schema
+
+.. image:: ../../images/cbw-schema.en.png
+ :alt: graphical view of the schema (aka data-model)
+
+
+.. _DefineViews:
+
+Define your entity views
+------------------------
+
+Each entity defined in a model inherits default views allowing
+different rendering of the data. You can redefine each of them
+according to your needs and preferences. So let's see how the
+views are defined.
+
+
+The view selection principle
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A view is defined by a Python class which includes:
+
+ - an identifier (all objects in `CubicWeb` are entered in a registry
+ and this identifier will be used as a key)
+
+ - a filter to select the result sets it can be applied to
+
+A view has a set of methods complying
+with the `View` class interface (`cubicweb.common.view`).
+
+`CubicWeb` provides a lot of standard views for the type `EntityView`;
+for a complete list, read the code in directory ``cubicweb/web/views/``.
+
+A view is applied on a `result set` which contains a set of
+entities we are trying to display. `CubicWeb` uses a selector
+mechanism which computes for each available view a score:
+the view with the highest score is then used to display the given `result set`.
+The standard library of selectors is in
+``cubicweb.common.selector`` and a library of methods used to
+compute scores is available in ``cubicweb.vregistry.vreq``.
+
+It is possible to define multiple views for the same identifier
+and to associate selectors and filters to allow the application
+to find the best way to render the data.
+
+For example, the view named ``primary`` is the one used to display
+a single entity. We will now show you how to customize this view.
+
+
+View customization
+~~~~~~~~~~~~~~~~~~
+
+If you wish to modify the way a `BlogEntry` is rendered, you will have to
+overwrite the `primary` view defined in the module ``views`` of the cube
+``cubes/blog/views.py``.
+
+We can for example add in front of the publication date a prefix specifying
+that the date we see is the publication date.
+
+To do so, please apply the following changes:
+
+.. code-block:: python
+
+ from cubicweb.web.views import baseviews
+
+
+ class BlogEntryPrimaryView(baseviews.PrimaryView):
+
+ accepts = ('BlogEntry',)
+
+ def render_entity_title(self, entity):
+ self.w(u'<h1>%s</h1>' % html_escape(entity.dc_title()))
+
+ def content_format(self, entity):
+ return entity.view('reledit', rtype='content_format')
+
+ def cell_call(self, row, col):
+ entity = self.entity(row, col)
+
+ # display entity attributes with prefixes
+ self.w(u'<h1>%s</h1>' % entity.title)
+ self.w(u'<p>published on %s</p>' % entity.publish_date.strftime('%Y-%m-%d'))
+ self.w(u'<p>%s</p>' % entity.content)
+
+ # display relations
+ siderelations = []
+ if self.main_related_section:
+ self.render_entity_relations(entity, siderelations)
+
+.. note::
+ When a view is modified, it is not required to restart the application
+ server. Save the Python file and reload the page in your web browser
+ to view the changes.
+
+You can now see that the publication date has a prefix.
+
+.. image:: ../../images/cbw-update-primary-view.en.png
+ :alt: modified primary view
+
+
+The above source code defines a new primary view for ``BlogEntry``.
+
+Since views are applied to result sets and result sets can be tables of
+data, we have to recover the entity from its (row,col)-coordinates.
+The view has a ``self.w()`` method that is used to output data, in our
+example HTML output.
+
+You can find more details about views and selectors in :ref:`ViewDefinition`.
+
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/intro/tutorial/index.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,31 @@
+.. -*- coding: utf-8 -*-
+
+.. _Tutorial:
+
+Tutorial
+========
+
+`CubicWeb` is a semantic web application framework that favors reuse and
+object-oriented design.
+
+A `cube` is a component that includes a model defining the data types and a set of
+views to display the data.
+
+An application is a `cube`, but usually an application is built by assembling
+a few smaller cubes.
+
+An `instance` is a specific installation of an application and includes
+configuration files.
+
+
+This tutorial will show how to create a `cube` and how to use it as an
+application to run an `instance`.
+
+.. toctree::
+ :maxdepth: 2
+
+ blog-less-ten-minutes
+ create-cube
+ components
+ maintemplate
+ conclusion
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/intro/tutorial/maintemplate.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,131 @@
+.. -*- coding: utf-8 -*-
+
+Templates
+---------
+
+Look at ``cubicweb/web/views/basetemplates.py`` and you will
+find the base templates used to generate HTML for your application.
+
+A page is composed as indicated on the schema below:
+
+.. image:: ../../images/lax-book.06-main-template-layout.en.png
+
+In this section we will demonstrate a change in one of the main
+interesting template from the three you will look for,
+that is to say, the HTMLPageHeader, the HTMLPageFooter
+and the TheMainTemplate.
+
+
+Customize a template
+~~~~~~~~~~~~~~~~~~~~
+
+Based on the diagram below, each template can be overriden
+by your customized template. To do so, we recommand you create
+a Python module ``blog.views.templates`` to keep it organized.
+In this module you will have to import the parent class you are
+interested as follows: ::
+
+ from cubicweb.web.views.basetemplates import HTMLPageHeader, \
+ HTMLPageFooter, TheMainTemplate
+
+and then create your sub-class::
+
+ class MyBlogHTMLPageHeader(HTMLPageHeader):
+ ...
+
+Customize header
+`````````````````
+
+Let's now move the search box in the header and remove the login form
+from the header. We'll show how to move it to the left column of the application.
+
+Let's say we do not want anymore the login menu to be in the header
+
+First, to remove the login menu, we just need to comment out the display of the
+login graphic component such as follows:
+
+.. code-block :: python
+
+ class MyBlogHTMLPageHeader(HTMLPageHeader):
+
+ def main_header(self, view):
+ """build the top menu with authentification info and the rql box"""
+ self.w(u'<table id="header"><tr>\n')
+ self.w(u'<td id="firstcolumn">')
+ self.vreg.select_component('logo', self.req, self.rset).dispatch(w=self.w)
+ self.w(u'</td>\n')
+ # appliname and breadcrumbs
+ self.w(u'<td id="headtext">')
+ comp = self.vreg.select_component('appliname', self.req, self.rset)
+ if comp and comp.propval('visible'):
+ comp.dispatch(w=self.w)
+ comp = self.vreg.select_component('breadcrumbs', self.req, self.rset, view=view)
+ if comp and comp.propval('visible'):
+ comp.dispatch(w=self.w, view=view)
+ self.w(u'</td>')
+ # logged user and help
+ #self.w(u'<td>\n')
+ #comp = self.vreg.select_component('loggeduserlink', self.req, self.rset)
+ #comp.dispatch(w=self.w)
+ #self.w(u'</td><td>')
+
+ self.w(u'<td>')
+ helpcomp = self.vreg.select_component('help', self.req, self.rset)
+ if helpcomp: # may not be available if Card is not defined in the schema
+ helpcomp.dispatch(w=self.w)
+ self.w(u'</td>')
+ # lastcolumn
+ self.w(u'<td id="lastcolumn">')
+ self.w(u'</td>\n')
+ self.w(u'</tr></table>\n')
+ self.template('logform', rset=self.rset, id='popupLoginBox', klass='hidden',
+ title=False, message=False)
+
+
+
+.. image:: ../../images/lax-book.06-header-no-login.en.png
+
+Customize footer
+````````````````
+
+If you want to change the footer for example, look
+for HTMLPageFooter and override it in your views file as in: ::
+
+..code-block :: python
+
+ from cubicweb.web.views.basetemplates import HTMLPageFooter
+
+ class MyHTMLPageFooter(HTMLPageFooter):
+
+ def call(self, **kwargs):
+ self.w(u'<div class="footer">')
+ self.w(u'This website has been created with <a href="http://cubicweb.org">CubicWeb</a>.')
+ self.w(u'</div>')
+
+Updating a view does not require any restart of the server. By reloading
+the page you can see your new page footer.
+
+
+TheMainTemplate
+```````````````
+
+.. _TheMainTemplate:
+
+The MainTemplate is a bit complex as it tries to accomodate many
+different cases. We are now about to go through it and cutomize entirely
+our application.
+
+TheMainTemplate is responsible for the general layout of the entire application.
+It defines the template of ``id = main`` that is used by the application. Is
+also defined in ``cubicweb/web/views/basetemplates.py`` another template that can
+be used based on TheMainTemplate called SimpleMainTemplate which does not have
+a top section.
+
+.. image:: ../../images/lax-book.06-simple-main-template.en.png
+
+XXX
+[WRITE ME]
+
+* customize MainTemplate and show that everything in the user
+ interface can be changed
+
--- a/doc/book/en/toc.en.txt Tue Apr 28 11:22:43 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,15 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-.. _TOC:
-
-Table of contents
-=================
-
-
-.. toctree::
-
- A000-introduction.en.txt
- B000-development.en.txt
- C000-administration.en.txt
- D000-annex.en.txt
-
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/toc.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,25 @@
+.. -*- coding: utf-8 -*-
+
+.. _TOC:
+
+Table of contents
+=================
+
+
+.. toctree::
+ :numbered:
+
+ concepts/index
+ cubes/index
+ datamodel/index
+ entityclasses/index
+ devcore/index
+ devweb/index
+ devrepo/index
+ testing/index
+ migration/index
+ webstdlib/index
+ admin/index
+ rql/index
+ annexes/index
+