# HG changeset patch # User Nicolas Chauvat # Date 1227214516 -3600 # Node ID e2303f9b5bfad0388046ddd158f10d79edba724b # Parent 4b66ad23fbd183b2c1ee5ac7d4d138244891cad3 [doc] more merging and reorg diff -r 4b66ad23fbd1 -r e2303f9b5bfa doc/book/en/01-00-introduction.en.txt --- 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'

%s

' % 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'

%s

' % entity.title) - self.w(u'

published on %s

' % entity.publish_date.strftime('%Y-%m-%d')) - self.w(u'

%s

' % 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 diff -r 4b66ad23fbd1 -r e2303f9b5bfa doc/book/en/01-05-components.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: :: diff -r 4b66ad23fbd1 -r e2303f9b5bfa doc/book/en/01-06-maintemplate.en.txt --- 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 diff -r 4b66ad23fbd1 -r e2303f9b5bfa doc/book/en/01-07-rss-xml.en.txt --- 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:: diff -r 4b66ad23fbd1 -r e2303f9b5bfa doc/book/en/02-00-foundation.en.txt --- 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 diff -r 4b66ad23fbd1 -r e2303f9b5bfa doc/book/en/06-00-define-workflows.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. diff -r 4b66ad23fbd1 -r e2303f9b5bfa doc/book/en/11-00-definition-workflow.en.txt --- 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.] diff -r 4b66ad23fbd1 -r e2303f9b5bfa doc/book/en/11-00-faq.en.txt --- 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 `_ - -[ADD MORE FAQ] diff -r 4b66ad23fbd1 -r e2303f9b5bfa doc/book/en/22-00-faq.en.txt --- 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. + diff -r 4b66ad23fbd1 -r e2303f9b5bfa doc/book/en/index.txt --- 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