# HG changeset patch # User Sandrine Ribeau # Date 1230057831 28800 # Node ID ce829abf7c294b244aa1e76666faa394358cc557 # Parent a11a3c231050a3879b0034aaa0824fa87a473ae0 [doc] Improved tutoriel. Moved appropriate content to cubicweb foundations chapter. Adds section to fill about cubicweb-ctl shell. diff -r a11a3c231050 -r ce829abf7c29 doc/book/en/A02a-create-cube.en.txt --- a/doc/book/en/A02a-create-cube.en.txt Tue Dec 23 15:42:01 2008 +0100 +++ b/doc/book/en/A02a-create-cube.en.txt Tue Dec 23 10:43:51 2008 -0800 @@ -60,6 +60,10 @@ | `-- views.py +.. note:: + You will find a more detailled description of the `cube` concept in + :ref:`cubesConcepts`. + .. _DefineDataModel: Define your data model @@ -220,6 +224,12 @@ Define your entities views -------------------------- +Each entity defined in a model inherits defaults views allowing +different rendering of the data. You can redefine each of them +according to your needs and preferences. If you feel like it then +you have to know how a view is defined. + + The views selection principle ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -230,6 +240,8 @@ - a filter to select the resulsets 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, you diff -r a11a3c231050 -r ce829abf7c29 doc/book/en/A02b-components.en.txt --- a/doc/book/en/A02b-components.en.txt Tue Dec 23 15:42:01 2008 +0100 +++ b/doc/book/en/A02b-components.en.txt Tue Dec 23 10:43:51 2008 -0800 @@ -5,24 +5,11 @@ 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 -others 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/ - Standard library ~~~~~~~~~~~~~~~~ -A library of standard cubes is part of the `CubicWeb` release (look at the -output of ``cubicweb-ctl list``). Cubes provide entities and views. +A library of standard cubes are available from `CubicWeb Forge`_ +Cubes provide entities and views. The available application entities are: @@ -59,9 +46,11 @@ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To import a cube in your application just change the line in the -``app.conf`` file. For example:: +``__pkginfo__.py`` file and verify that the cube you are planning +to use is listed by the command ``cubicweb-ctl list``. +For example:: - included-yams-cubes=comment + __use__ = ('comment',) will make the ``Comment`` entity available in your ``BlogDemo`` application. @@ -74,75 +63,19 @@ to the definition of a ``BlogEntry`` will be enough. -Clear the datastore and restart. - -Cube structure -~~~~~~~~~~~~~~ - -A complex cube is structured as follows: -:: +Synchronize the data model +~~~~~~~~~~~~~~~~~~~~~~~~~~ - mycube/ - | - |-- schema.py - | - |-- entities/ - | - |-- sobjects/ - | - |-- views/ - | - |-- test/ - | - |-- i18n/ - | - |-- data/ - | - |-- migration/ - | |- postcreate.py - | \- depends.map - | - |-- debian/ - | - \-- __pkginfo__.py - -We can also define simple Python module instead of directories (packages), for example: +Once you modified your data model, you need to synchronize the +database with your model. For this purpose, `CubicWeb` provides +a very usefull 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: :: - mycube/ - | - |-- entities.py - |-- hooks.py - \-- views.py - - -where: - -* ``schema`` contains the definition of the schema (server side only) -* ``entities`` contains entities definition (server side and web interface) -* ``sobjects`` contains hooks and/or notification views (server side only) -* ``views`` contains the web interface components (web interface only) -* ``test`` contains tests related to the application (not installed) -* ``i18n`` contains messages 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-components used by - the component. - -At least you should have: - -* the file ``__pkginfo__.py`` -* schema definition - -[WRITE ME] - -* explain the cube architecture - -* add comments to the blog by importing the comments cube + synchronize_rschema('BlogEntry') + +You can now start your application and add comments to each +`BlogEntry`. diff -r a11a3c231050 -r ce829abf7c29 doc/book/en/A02c-maintemplate.en.txt --- a/doc/book/en/A02c-maintemplate.en.txt Tue Dec 23 15:42:01 2008 +0100 +++ b/doc/book/en/A02c-maintemplate.en.txt Tue Dec 23 10:43:51 2008 -0800 @@ -1,22 +1,37 @@ .. -*- coding: utf-8 -*- -Views & Templates ------------------ +Templates +--------- -Look at ``lax/skel/ginco/web/views/basetemplates.py`` and you will +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. +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. -HTMLPageHeader -~~~~~~~~~~~~~~~ +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 ````````````````` @@ -24,14 +39,12 @@ 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_. +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 component such as follows: :: +login graphic component such as follows: :: - class MyHTMLPageHeader(HTMLPageHeader): + class MyBlogHTMLPageHeader(HTMLPageHeader): def main_header(self, view): """build the top menu with authentification info and the rql box""" @@ -70,66 +83,8 @@ .. 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 ginco.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'\n') - self.w(u'\n') - # appliname and breadcrumbs - self.w(u'') - - # logged user and help - #self.w(u'') - - self.w(u'') - # lastcolumn - self.w(u'\n') - self.w(u'\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 -~~~~~~~~~~~~~~ +Customize footer +```````````````` If you want to change the footer for example, look for HTMLPageFooter and override it in your views file as in: @@ -147,7 +102,7 @@ TheMainTemplate -~~~~~~~~~~~~~~~ +``````````````` .. _TheMainTemplate: @@ -157,34 +112,32 @@ 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 ``ginco/web/views/basetemplates.py`` another template that can +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 +* Add login menu in left column ? + 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/``. +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. -[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 ginco-doc rajouter une section pour cubicweb-ctl shell ou -on liste les commandes dispos. diff -r a11a3c231050 -r ce829abf7c29 doc/book/en/A03a-concepts.en.txt --- a/doc/book/en/A03a-concepts.en.txt Tue Dec 23 15:42:01 2008 +0100 +++ b/doc/book/en/A03a-concepts.en.txt Tue Dec 23 10:43:51 2008 -0800 @@ -341,9 +341,28 @@ 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 +others 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/ + + Standard structure for a cube -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +````````````````````````````` A complex cube is structured as follows: @@ -389,25 +408,63 @@ * ``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 different components of the web interface (web interface only) -* ``test`` contains tests specifics to the application (not installed) -* ``i18n`` contains the messages catalog for supported languages (server side and - web interface) -* ``data`` contains arbitrary data files served statically - (images, css, javascripts files)... (web interface only) -* ``migration`` contains the initialization file for new instances - (``postcreate.py``) and in general a file containing the `CubicWeb` dependancies - of the cube depending on its version (``depends.map``) -* ``debian`` contains all the files that manages the debian packaging - (you would find there the classical structure with ``control``, ``rules``, - ``changelog``... (not installed) -* the file ``__pkginfo__.py`` provides meta-data on the cube, especially the - distribution name and the current version (server side and web interface) or - also the sub-cubes used by this cube - -The only required files are: +* ``views`` contains the web interface components (web interface only) +* ``test`` contains tests related to the application (not installed) +* ``i18n`` contains messages 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 embeding 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) + +* 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) + + diff -r a11a3c231050 -r ce829abf7c29 doc/book/en/C013-cubicweb-ctl.en.txt --- a/doc/book/en/C013-cubicweb-ctl.en.txt Tue Dec 23 15:42:01 2008 +0100 +++ b/doc/book/en/C013-cubicweb-ctl.en.txt Tue Dec 23 10:43:51 2008 -0800 @@ -65,6 +65,7 @@ * ``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 + (see :ref:`cubicweb-ctl-shell` for more details) * ``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 @@ -87,6 +88,16 @@ and instances. * ``delete``, deletes an instance (configuration files and database) + +.. _cubicweb-ctl-shell: + +``cubicweb-ctl shell`` addon +---------------------------- + +XXX +[FIXME] +Add list of commands available in cubicweb-ctl shell. + Examples --------