--- a/doc/book/en/01-00-introduction.en.txt Thu Nov 20 21:30:55 2008 +0100
+++ b/doc/book/en/01-00-introduction.en.txt Thu Nov 20 21:55:16 2008 +0100
@@ -18,316 +18,7 @@
In this document, we will show you how to create a `cube` and how to use it
in an `instance` for your web application.
-Create your cube
-----------------
-
-After you installed your `CubicWeb` development environment, you can start
-to build your first cube: ::
-
- cubicweb-ctl newcube blog
-
-This will create in ``/path/to/forest/cubes`` a directory containing: ::
-
- blog/
- |
- |-- data/
- | |-- cubes.blog.css
- | |-- cubes.blog.js
- | |-- external_resources
- |
- |-- debian/
- | |-- changelog
- | |-- compat
- | |-- control
- | |-- copyright
- | |-- cubicweb-blog.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
- |
- |-- sobjects.py
- |
- |-- test/
- | |-- data/
- | |-- bootstrap_cubes
- | |-- pytestconf.py
- | |-- realdb_test_blog.py
- | |-- test_blog.py
- |
- |-- views.py
-
-Any changes applied to your data model should be done in this
-directory.
-
-
-Define your data schema
------------------------
-
-The data model or schema is hte core of your `CubicWeb` application.
-This is where is defined the type of content you application will handle.
-
-The data model is defined in the file ``schema.py`` of your cube
-``blog`` such as follows.
-
-::
-
- from cubicweb.schema import format_constraint
- 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
---------------------
-
-::
-
- cubicweb-ctl create blog blogdemo
-
-
-This command will create a directory ``~/etc/cubicweb.d/blogdemo``
-which will contain all the configuration files required to start
-you web application.
-
-The instance ``blogdemo`` is based on the cube ``blog``.
-
-
-Welcome in your web application
--------------------------------
-
-Run your application with the following command: ::
-
- cubicweb-ctl start -D blogdemo
-
-
-You can now access to your web application to create blogs and post messages
-by visitin the URL http://localhost:8080/.
-A login form will first be prompted. By default, the application will not allow
-anonymous user to get in the application. You should 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. Bravo!
-
-.. image:: images/blog-demo-first-page.png
-
-Please notice that so far, `CubicWeb` franework managed all aspects of
-the web application based in the schema provided at first.
-
-
-Create entities
----------------
-
-We will now create a couple of entities in our web application.
-
-Create a Blog
-~~~~~~~~~~~~~
-
-Let us create a few of these entities. Click on the `[+]` at the right
-of the link Blog. 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
-
-Create a BlogEntry
-~~~~~~~~~~~~~~~~~~
-
-Get back to the home page and click on [+] at the right 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)
-
-
-Define your entities views
---------------------------
-
-The views 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 resulsets it can be applied to
-
-
-`CubicWeb` provides a lot of standard views for the type
-`EntityView`, for a complete list, you
-will have to 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
-mecanism which computes a score used to identify which view
-is the best to apply for the `result set` we are trying to
-display. 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. We will see more details
-on this in :ref:`DefinitionVues`.
-
-For example, the view named ``primary`` is the one used to display
-a single entity. We will now show you hos 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 by example add in front of the pulication date a prefix specifying
-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 resultsets and resulsets can be tables of
-data, it is needed to recover the entity from its (row,col)
-coordinates. We will get to this in more detail later.
-
-The view has a ``self.w()`` method that is used to output data. In our
-example we use it to output HTML tags and values of the entity's attributes.
-
+.. include:: 01-01-create-cube.en.txt
+.. include:: 01-05-components.en.txt
+.. include:: 01-06-maintemplate.en.txt
+.. include:: 01-07-rss-xml.en.txt
--- a/doc/book/en/01-05-components.en.txt Thu Nov 20 21:30:55 2008 +0100
+++ b/doc/book/en/01-05-components.en.txt Thu Nov 20 21:55:16 2008 +0100
@@ -3,12 +3,10 @@
.. _components:
Components
-===========
-
-XXXFIXME TURN THIS INTO A CHAPTER
+----------
What is a component
--------------------
+~~~~~~~~~~~~~~~~~~~
A component 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
@@ -19,7 +17,7 @@
Standard library
-----------------
+~~~~~~~~~~~~~~~~
A library of standard components is part of the `LAX` release (look at
``lax/skel/ginco-apps``). Components provide entities and views. With
@@ -60,7 +58,7 @@
Adding comments to BlogDemo
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To import a component in your application just change the line in the
``app.conf`` file. For example::
@@ -81,7 +79,7 @@
Clear the datastore and restart.
Component structure
--------------------
+~~~~~~~~~~~~~~~~~~~
A complex component is structured as follows:
::
--- a/doc/book/en/01-06-maintemplate.en.txt Thu Nov 20 21:30:55 2008 +0100
+++ b/doc/book/en/01-06-maintemplate.en.txt Thu Nov 20 21:55:16 2008 +0100
@@ -1,7 +1,7 @@
.. -*- coding: utf-8 -*-
Views & Templates
-=================
+-----------------
Look at ``lax/skel/ginco/web/views/basetemplates.py`` and you will
find the base templates used to generate HTML for your application.
@@ -16,13 +16,13 @@
HTMLPageHeader
---------------
+~~~~~~~~~~~~~~~
Let's use a different logo than the default one provided with LAX
and customize our header.
Change logo
-~~~~~~~~~~~
+```````````
The easiest way to use a different logo is to replace the existing
``logo.png`` in ``myapp/data`` by your prefered icon and refresh.
@@ -38,7 +38,7 @@
ADD how to use external_resources variables used in ginco/web/webconfig.py
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.
@@ -148,7 +148,7 @@
HTMLPageFooter
---------------
+~~~~~~~~~~~~~~
If you want to change the footer for example, look
for HTMLPageFooter and override it in your views file as in:
@@ -166,7 +166,8 @@
TheMainTemplate
----------------
+~~~~~~~~~~~~~~~
+
.. _TheMainTemplate:
The MainTemplate is a bit complex as it tries to accomodate many
@@ -182,7 +183,7 @@
.. image:: images/lax-book.06-simple-main-template.en.png
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
@@ -193,7 +194,6 @@
apply a higher priority on the default CSS and you can not change that.
Customized CSS will not be read first.
-1
[TODO]
Add login menu in left column
--- a/doc/book/en/01-07-rss-xml.en.txt Thu Nov 20 21:30:55 2008 +0100
+++ b/doc/book/en/01-07-rss-xml.en.txt Thu Nov 20 21:55:16 2008 +0100
@@ -1,7 +1,7 @@
.. -*- 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::
--- a/doc/book/en/02-00-foundation.en.txt Thu Nov 20 21:30:55 2008 +0100
+++ b/doc/book/en/02-00-foundation.en.txt Thu Nov 20 21:55:16 2008 +0100
@@ -565,3 +565,6 @@
* 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 embeding for instance)
+
+.. include:: 02-01-registry.en.txt
+.. include:: 02-02-configuration.en.txt
--- a/doc/book/en/06-00-define-workflows.en.txt Thu Nov 20 21:30:55 2008 +0100
+++ b/doc/book/en/06-00-define-workflows.en.txt Thu Nov 20 21:55:16 2008 +0100
@@ -1,7 +1,8 @@
.. -*- coding: utf-8 -*-
-Définition de workflow
+Workflow definition
======================
+
On peut mettre une condition rql ou/et un groupe auquel doit appartenir l'utilisateur.
Si on met à la fois un(ou plusieurs) groupe et une condition RQL, il faut que les deux soient respectés.
--- a/doc/book/en/11-00-definition-workflow.en.txt Thu Nov 20 21:30:55 2008 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,43 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Defining a Workflow
-===================
-
-General
--------
-
-A workflow can be defined in a `LAX` application thanks to the system
-entities ``State`` and ``Transition``. Those are defined within all
-LAX application and can be set-up through the main administrator interface.
-
-Once your schema is defined, you can start creating the set of states and
-the required transitions for your applications entities.
-
-You first need to define the states and then the transitions between those
-to complete your workflow.
-
-A ``State`` defines the status of an entity. While creating a new state,
-you will be first given the option to select the entity type the state
-can be applied to. By choosing ``Apply``, a new section will be displayed
-in the editing screen to enable you to add relation to the state you are
-creating.
-
-A ``Transition`` is also based on an entity type it can be applied to.
-By choosing ``Apply``, a new section will be displayed in the editing
-screen to enable you to add relation to the transition you are
-creating.
-
-At the transition level you will also define the group of user which can
-aplly this transition to an object.
-
-
-Example of a simple workflow
-----------------------------
-
-Please see the tutorial to view and example of a simple workflow.
-
-
-[Create a simple workflow for BlogDemo, to have a moderator approve new blog
-entry to be published. This implies, specify a dedicated group of blog
-moderator as well as hide the view of a blog entry to the user until
-it reaches the published state.]
--- a/doc/book/en/11-00-faq.en.txt Thu Nov 20 21:30:55 2008 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,110 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Frequently Asked Questions
-==========================
-
-* Why does not LAX have a template language ?
-
- It does. Actually, you can use your preferred template language if you
- want. [explain how to use a template language]
-
- The reason template languages are not used in this book is that
- experience has proved us that using pure python was more efficient.
-
-* Why do you think using pure python is better than using a template language ?
-
- [copy answer from forum]
-
- code is easier to maintain, does not have to learn a new dialect
- each time, real function/classes etc -> real development
-
-* Why do you use the GPL license to prevent me from doing X ?
-
- [copy answer from forum]
-
-* LAX looks pretty recent. Is it stable ?
-
- [answer that framework has evolved over the past seven years and that
- data migrated from one schema to the other ever since]
-
-* Why is the RQL query language looking similar to X ?
-
- [copy answer from forum, explain why similar to sparql and why better
- than django and SQL]
-
-* which ajax library
-
- [we use mochikit 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 - (erudi.rest) ERROR: error while publishing ReST text
- Traceback (most recent call last):
- File "/home/sandrine/src/blogdemo/ginco/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
-[ADD MORE FAQ]
-.. -*- coding: utf-8 -*-
-
-Frequently Asked Questions
-==========================
-
-* Why does not LAX have a template language ?
-
- It does. Actually, you can use your preferred template language if you
- want. [explain how to use a template language]
-
- The reason template languages are not used in this book is that
- experience has proved us that using pure python was more efficient.
-
-* Why do you think using pure python is better than using a template language ?
-
- [copy answer from forum]
-
- code is easier to maintain, does not have to learn a new dialect
- each time, real function/classes etc -> real development
-
-* Why do you use the GPL license to prevent me from doing X ?
-
- [copy answer from forum]
-
-* LAX looks pretty recent. Is it stable ?
-
- [answer that framework has evolved over the past seven years and that
- data migrated from one schema to the other ever since]
-
-* Why is the RQL query language looking similar to X ?
-
- [copy answer from forum, explain why similar to sparql and why better
- than django and SQL]
-
-* which ajax library
-
- [we use mochikit 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 - (erudi.rest) ERROR: error while publishing ReST text
- Traceback (most recent call last):
- File "/home/sandrine/src/blogdemo/ginco/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 :
- `Google group appengine <http://code.google.com/p/googleappengine/issues/detail?id=48>`_
-
-[ADD MORE FAQ]
--- a/doc/book/en/22-00-faq.en.txt Thu Nov 20 21:30:55 2008 +0100
+++ b/doc/book/en/22-00-faq.en.txt Thu Nov 20 21:55:16 2008 +0100
@@ -1,18 +1,66 @@
.. -*- coding: utf-8 -*-
-Foire Aux Questions
-===================
+Frequently Asked Questions
+==========================
+
+* Why does not LAX have a template language ?
+
+ It does. Actually, you can use your preferred template language if you
+ want. [explain how to use a template language]
+
+ The reason template languages are not used in this book is that
+ experience has proved us that using pure python was more efficient.
+
+* Why do you think using pure python is better than using a template language ?
+
+ [copy answer from forum]
+
+ code is easier to maintain, does not have to learn a new dialect
+ each time, real function/classes etc -> real development
+
+* Why do you use the GPL license to prevent me from doing X ?
+
+ [copy answer from forum]
+
+* LAX looks pretty recent. Is it stable ?
+
+ [answer that framework has evolved over the past seven years and that
+ data migrated from one schema to the other ever since]
-[FILL ME]
+* Why is the RQL query language looking similar to X ?
+
+ [copy answer from forum, explain why similar to sparql and why better
+ than django and SQL]
+
+* which ajax library
+
+ [we use mochikit and things on top of that]
-* A quoi servent les crochets?
+* `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 - (erudi.rest) ERROR: error while publishing ReST text
+ Traceback (most recent call last):
+ File "/home/sandrine/src/blogdemo/ginco/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?
Les crochets sont appeles lorsqu'une requete RQL est executee. Cela
permet d'executer des actions specifiques lors d'un acces a la base
de donnees, ce qui donne un controle de la base de donnees afin de
prevenir l'insertion de `mauvaises` entites dans la base.
-* Quand utiliser un template HTML plutot qu'un composant graphique?
+* When should you define an HTML template rather than define a graphical component?
Un template HTML ne peut contenir de logique, il ne permettra donc
que de definir une vue statique. Un composant permet lui de gerer
@@ -20,7 +68,7 @@
s'applique. Il faut donc bien reflechir avant de decider de l'un ou
de l'autre, mais vous avez la possibilite de choisir.
-* Comment mettre à jour une base de données après avoir modifié le schéma?
+* How to update a database after a schema modification?
Cela dépend de ce qui a été modifié dans le schéma.
@@ -30,7 +78,7 @@
[TO COMPLETE]
-* Comment créer un utilisateur anonyme?
+* How to create an anonymous user?
Cela vous permet d'acceder a votre site sans avoir besoin de vous authentifier.
Dans le fichier ``all-in-one.conf`` de votre instance, définir l'utilisateur
@@ -47,9 +95,10 @@
de données, le plus simple étant de s'identifier sur votre application en
administrateur et de rajouter l'utilisateur `anon` via l'interface d'administration.
-* Quelle est la différence entre `AppRsetObject` et `AppObject` ?
+* What is the difference between `AppRsetObject` and `AppObject` ?
La différence entre la classe `AppRsetObject` et la classe `AppObject` est que
les instances de la premières sont séléctionnées pour une requête et un "result
set" et alors que les secondes ne sont séléctionnées qu'en fonction de leur
identifiant.
+
--- a/doc/book/en/index.txt Thu Nov 20 21:30:55 2008 +0100
+++ b/doc/book/en/index.txt Thu Nov 20 21:55:16 2008 +0100
@@ -36,7 +36,7 @@
.. toctree::
- :maxdepth: 1
+ :maxdepth: 2
01-00-introduction.en.txt
02-00-foundation.en.txt
@@ -60,6 +60,17 @@
20-00-google-appengine.en.txt
21-00-appendix.en.txt
22-00-faq.en.txt
+ XX-XX-actions.en.txt
+ XX-XX-repository-operations.en.txt
+ XX-XX-sessions.en.txt
+ XX-XX-boxes.en.txt
+ XX-XX-repository-session.en.txt
+ XX-XX-templates.en.txt
+ XX-XX-dbapi.en.txt
+ XX-XX-repository-tasks.en.txt
+ XX-XX-urlrewrite.en.txt
+ XX-XX-embedding-external-page.en.txt
+ XX-XX-request.en.txt
Indices and tables