# HG changeset patch # User Sandrine Ribeau # Date 1230067728 28800 # Node ID 487bcc269d507ff854c960137b908ae76f33a1e6 # Parent adbf9a24c41ea4afdb5ec1dc761704559efb6d27 [doc] Renaming for web interface thematic. diff -r adbf9a24c41e -r 487bcc269d50 doc/book/en/B030-define-views.en.txt --- a/doc/book/en/B030-define-views.en.txt Tue Dec 23 13:20:14 2008 -0800 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,238 +0,0 @@ -.. -*- coding: utf-8 -*- - -.. _DefinitionVues: - -Views definition -================ - -Basic class for views ---------------------- - -Class `View` (`cubicweb.common.view`) -````````````````````````````````````` - -A view writes in its output exit thanks to its attribute `w` (`UStreamIO`). - -The basic interface for views is as follows: - -* `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 -* `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` - -* `creator(eid)`, returns the eid and the login of the entity creator of the entity - having the eid given in the parameter - -Other basic classes: - -* `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 - - -The selection view principle ----------------------------- - -A view includes : - -- an identifier (all objects in `LAX` 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 - - -For a given identifier, multiple views can be defined. `CubicWeb` uses -a selector which computes scores so that it can identify and select the -best view to apply in context. The selector library is in -``cubicweb.common.selector`` and a library of the methods used to -compute scores is in ``cubicweb.vregistry.vreq``. - - -`CubicWeb` provides a lot of standard views, for a complete list, you -will have to read the code in directory ``cubicweb/web/views/`` (XXX -improve doc). - -For example, the view named ``primary`` is the one used to display -a single entity. - -If you want to change the way a ``BlogEntry`` is displayed, just -override the view ``primary`` in ``BlogDemo/views.py`` :: - - 01. from ginco.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'

%s

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

published on %s in category %s

' % \ - 11. (entity.publish_date.strftime('%Y-%m-%d'), entity.category)) - 12. self.w(u'

%s

' % entity.text) - -The above source code defines a new primary view (`line 03`) for -``BlogEntry`` (`line 05`). - -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 (`line 08`). We will get to this in more detail later. - -The view has a ``self.w()`` method that is used to output data. Here `lines -09-12` output HTML tags and values of the entity's attributes. - -When displaying same blog entry as before, you will notice that the -page is now looking much nicer. - -.. 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'

%s

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

%s

' % 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. - -At `line 09`, a simple request in made to build a resultset 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 resultset. At -`line 10` the view 'primary' is applied to this resultset to output -HTML. - -**This is to be compared to interfaces and protocols in object-oriented -languages. Applying a given view to all the entities of a resultset only -requires the availability, for each entity of this resultset, of a -view with that name that can 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 resultset 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 cubicwweb.interfaces.ICalendarable interfaces on -entities.BloEntry and apply the OneMonthCalendar and iCalendar views -to resultsets 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 view that does 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 (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 necessarry -2. identifying the view to use to render data if it is not specified -3. composing the HTML page to return - - -The default main template (`cubicweb.web.views.basetemplates.TheMainTemplate`) ------------------------------------------------------------------------------- - -The default main template build the page based on the following pattern: - -.. image:: images/main_template_layout.png - -The rectangle containing `view.dispathc()` 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 dictionnary of the forms parameters, before going the classic way (through - step 1 and 2 described juste above) - -.. include:: B031-views-stdlib.en.txt - - -XML views, binaries... ----------------------- -For the views generating other formats that HTML (an image generated dynamically -for example), and which can not usually be included in the HTML page generated -by the main template (see above), you have to: - -* set the atribute `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 the views dedicated to binary content creation (an image dynamically generated -for example), we have to set the attribute `binary` of the class to `True` (which -implies that `templateable == 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 `
` -(by empty we mean that there is no content in the tag, but there -could be attributes), so we should always use `
` even if -it is empty and not use `
`. - diff -r adbf9a24c41e -r 487bcc269d50 doc/book/en/B060-form-management.en.txt --- a/doc/book/en/B060-form-management.en.txt Tue Dec 23 13:20:14 2008 -0800 +++ /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 :: - - : - -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-` or `edito-` - 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 - (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: :: - - :: - - where 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: :: - - :: - - 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 necessarry, - 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`. - diff -r adbf9a24c41e -r 487bcc269d50 doc/book/en/B070-ajax-json.en.txt --- a/doc/book/en/B070-ajax-json.en.txt Tue Dec 23 13:20:14 2008 -0800 +++ /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 diff -r adbf9a24c41e -r 487bcc269d50 doc/book/en/B080-internationalization.en.txt --- a/doc/book/en/B080-internationalization.en.txt Tue Dec 23 13:20:14 2008 -0800 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,100 +0,0 @@ -.. -*- coding: utf-8 -*- - -.. _internationalization: - - -Internationalization -==================== - -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'
%s
\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//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 ` -2. Edit the /xxx.po files and add missing translations (empty `msgstr`) -3. `hg ci -m "updated i18n catalogs"` -4. `cubicweb-ctl i18n compile ` - diff -r adbf9a24c41e -r 487bcc269d50 doc/book/en/B090-ui-components.en.txt --- a/doc/book/en/B090-ui-components.en.txt Tue Dec 23 13:20:14 2008 -0800 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,14 +0,0 @@ -Others web interface components -=============================== - -Actions -------- -XXXFILLME - -Component, VComponent ---------------------- -XXXFILLME - -EProperty ---------- -XXXFILLME diff -r adbf9a24c41e -r 487bcc269d50 doc/book/en/B1-web-interface.en.txt --- a/doc/book/en/B1-web-interface.en.txt Tue Dec 23 13:20:14 2008 -0800 +++ b/doc/book/en/B1-web-interface.en.txt Tue Dec 23 13:28:48 2008 -0800 @@ -5,15 +5,15 @@ .. toctree:: :maxdepth: 1 - BXXX-request.en.txt - B030-define-views.en.txt - B060-form-management.en.txt - BXXX-actions.en.txt - BXXX-boxes.en.txt - BXXX-templates.en.txt - B090-ui-components.en.txt - B070-ajax-json.en.txt - B080-internationalization.en.txt - BXXX-online-doc.en.txt - BXXX-embedding-external-page.en.txt - BXXX-urlrewrite.en.txt + 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 diff -r adbf9a24c41e -r 487bcc269d50 doc/book/en/B1010-request.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/B1010-request.en.txt Tue Dec 23 13:28:48 2008 -0800 @@ -0,0 +1,9 @@ +.. -*- coding: utf-8 -*- + +request +======= + +[WRITE ME] + +* the request object + diff -r adbf9a24c41e -r 487bcc269d50 doc/book/en/B1020-define-views.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/B1020-define-views.en.txt Tue Dec 23 13:28:48 2008 -0800 @@ -0,0 +1,238 @@ +.. -*- coding: utf-8 -*- + +.. _DefinitionVues: + +Views definition +================ + +Basic class for views +--------------------- + +Class `View` (`cubicweb.common.view`) +````````````````````````````````````` + +A view writes in its output exit thanks to its attribute `w` (`UStreamIO`). + +The basic interface for views is as follows: + +* `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 +* `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` + +* `creator(eid)`, returns the eid and the login of the entity creator of the entity + having the eid given in the parameter + +Other basic classes: + +* `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 + + +The selection view principle +---------------------------- + +A view includes : + +- an identifier (all objects in `LAX` 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 + + +For a given identifier, multiple views can be defined. `CubicWeb` uses +a selector which computes scores so that it can identify and select the +best view to apply in context. The selector library is in +``cubicweb.common.selector`` and a library of the methods used to +compute scores is in ``cubicweb.vregistry.vreq``. + + +`CubicWeb` provides a lot of standard views, for a complete list, you +will have to read the code in directory ``cubicweb/web/views/`` (XXX +improve doc). + +For example, the view named ``primary`` is the one used to display +a single entity. + +If you want to change the way a ``BlogEntry`` is displayed, just +override the view ``primary`` in ``BlogDemo/views.py`` :: + + 01. from ginco.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'

%s

' % entity.title) + 10. self.w(u'

published on %s in category %s

' % \ + 11. (entity.publish_date.strftime('%Y-%m-%d'), entity.category)) + 12. self.w(u'

%s

' % entity.text) + +The above source code defines a new primary view (`line 03`) for +``BlogEntry`` (`line 05`). + +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 (`line 08`). We will get to this in more detail later. + +The view has a ``self.w()`` method that is used to output data. Here `lines +09-12` output HTML tags and values of the entity's attributes. + +When displaying same blog entry as before, you will notice that the +page is now looking much nicer. + +.. 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'

%s

' % entity.title) + 08. self.w(u'

%s

' % 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. + +At `line 09`, a simple request in made to build a resultset 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 resultset. At +`line 10` the view 'primary' is applied to this resultset to output +HTML. + +**This is to be compared to interfaces and protocols in object-oriented +languages. Applying a given view to all the entities of a resultset only +requires the availability, for each entity of this resultset, of a +view with that name that can 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 resultset 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 cubicwweb.interfaces.ICalendarable interfaces on +entities.BloEntry and apply the OneMonthCalendar and iCalendar views +to resultsets 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 view that does 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 (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 necessarry +2. identifying the view to use to render data if it is not specified +3. composing the HTML page to return + + +The default main template (`cubicweb.web.views.basetemplates.TheMainTemplate`) +------------------------------------------------------------------------------ + +The default main template build the page based on the following pattern: + +.. image:: images/main_template_layout.png + +The rectangle containing `view.dispathc()` 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 dictionnary of the forms parameters, before going the classic way (through + step 1 and 2 described juste above) + +.. include:: B031-views-stdlib.en.txt + + +XML views, binaries... +---------------------- +For the views generating other formats that HTML (an image generated dynamically +for example), and which can not usually be included in the HTML page generated +by the main template (see above), you have to: + +* set the atribute `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 the views dedicated to binary content creation (an image dynamically generated +for example), we have to set the attribute `binary` of the class to `True` (which +implies that `templateable == 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 `
` +(by empty we mean that there is no content in the tag, but there +could be attributes), so we should always use `
` even if +it is empty and not use `
`. + diff -r adbf9a24c41e -r 487bcc269d50 doc/book/en/B1030-form-management.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/B1030-form-management.en.txt Tue Dec 23 13:28:48 2008 -0800 @@ -0,0 +1,137 @@ +.. -*- 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 :: + + : + +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-` or `edito-` + 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 + (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: :: + + :: + + where 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: :: + + :: + + 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 necessarry, + 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`. + diff -r adbf9a24c41e -r 487bcc269d50 doc/book/en/B1040-actions.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/B1040-actions.en.txt Tue Dec 23 13:28:48 2008 -0800 @@ -0,0 +1,9 @@ +.. -*- coding: utf-8 -*- + +Actions +========= + +[WRITE ME] + +* talk about actions that appear in the action box + diff -r adbf9a24c41e -r 487bcc269d50 doc/book/en/B1050-boxes.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/B1050-boxes.en.txt Tue Dec 23 13:28:48 2008 -0800 @@ -0,0 +1,9 @@ +.. -*- coding: utf-8 -*- + +Boxes +========= + +[WRITE ME] + +* boxes in the web interface + diff -r adbf9a24c41e -r 487bcc269d50 doc/book/en/B1060-templates.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/B1060-templates.en.txt Tue Dec 23 13:28:48 2008 -0800 @@ -0,0 +1,196 @@ +.. -*- coding: utf-8 -*- + +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'\n') + self.w(u'\n') + # appliname and breadcrumbs + self.w(u'') + # logged user and help + #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) + + + +.. 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 +-------------- + +If you want to change the footer for example, look +for HTMLPageFooter and override it in your views file as in : +:: + + form ginco.web.views.basetemplates import HTMLPageFooter + class MyHTMLPageFooter(HTMLPageFooter): + def call(self, **kwargs): + self.w(u'
') + self.w(u'This website has been created with LAX.') + self.w(u'
') + +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 + +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/``. + +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. + +1 +[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 cubciweb-ctl shell ou +on liste les commandes dispos. diff -r adbf9a24c41e -r 487bcc269d50 doc/book/en/B1070-ui-components.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/B1070-ui-components.en.txt Tue Dec 23 13:28:48 2008 -0800 @@ -0,0 +1,14 @@ +Others web interface components +=============================== + +Actions +------- +XXXFILLME + +Component, VComponent +--------------------- +XXXFILLME + +EProperty +--------- +XXXFILLME diff -r adbf9a24c41e -r 487bcc269d50 doc/book/en/B1080-ajax-json.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/B1080-ajax-json.en.txt Tue Dec 23 13:28:48 2008 -0800 @@ -0,0 +1,16 @@ +.. -*- coding: utf-8 -*- + +AJAX +==== +JSON bla bla +XXX FILLME + + +Le contrôleur 'json' +-------------------- +XXX FILLME + + +API Javascript +-------------- +XXX FILLME diff -r adbf9a24c41e -r 487bcc269d50 doc/book/en/B1090-internationalization.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/B1090-internationalization.en.txt Tue Dec 23 13:28:48 2008 -0800 @@ -0,0 +1,100 @@ +.. -*- coding: utf-8 -*- + +.. _internationalization: + + +Internationalization +==================== + +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'
%s
\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//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 ` +2. Edit the /xxx.po files and add missing translations (empty `msgstr`) +3. `hg ci -m "updated i18n catalogs"` +4. `cubicweb-ctl i18n compile ` + diff -r adbf9a24c41e -r 487bcc269d50 doc/book/en/B1100-online-doc.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/B1100-online-doc.en.txt Tue Dec 23 13:28:48 2008 -0800 @@ -0,0 +1,9 @@ +.. -*- coding: utf-8 -*- + +Online documentation system +=========================== + +[WRITE ME] + +* describe the on-line documentation system + diff -r adbf9a24c41e -r 487bcc269d50 doc/book/en/B1110-embedding-external-page.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/B1110-embedding-external-page.en.txt Tue Dec 23 13:28:48 2008 -0800 @@ -0,0 +1,9 @@ +.. -*- coding: utf-8 -*- + +Embedding external pages +======================== + +[WRITE ME] + +* including external content + diff -r adbf9a24c41e -r 487bcc269d50 doc/book/en/B1120-urlrewrite.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/B1120-urlrewrite.en.txt Tue Dec 23 13:28:48 2008 -0800 @@ -0,0 +1,11 @@ +.. -*- coding: utf-8 -*- + +URL Rewriting +============= + +XXX FIXME this should be a chapter + +[WRITE ME] + +* show how urls are mapped to selections and views and explain URLRewriting + diff -r adbf9a24c41e -r 487bcc269d50 doc/book/en/BXXX-actions.en.txt --- a/doc/book/en/BXXX-actions.en.txt Tue Dec 23 13:20:14 2008 -0800 +++ /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 - diff -r adbf9a24c41e -r 487bcc269d50 doc/book/en/BXXX-boxes.en.txt --- a/doc/book/en/BXXX-boxes.en.txt Tue Dec 23 13:20:14 2008 -0800 +++ /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 - diff -r adbf9a24c41e -r 487bcc269d50 doc/book/en/BXXX-embedding-external-page.en.txt --- a/doc/book/en/BXXX-embedding-external-page.en.txt Tue Dec 23 13:20:14 2008 -0800 +++ /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 - diff -r adbf9a24c41e -r 487bcc269d50 doc/book/en/BXXX-online-doc.en.txt --- a/doc/book/en/BXXX-online-doc.en.txt Tue Dec 23 13:20:14 2008 -0800 +++ /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 - diff -r adbf9a24c41e -r 487bcc269d50 doc/book/en/BXXX-request.en.txt --- a/doc/book/en/BXXX-request.en.txt Tue Dec 23 13:20:14 2008 -0800 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,9 +0,0 @@ -.. -*- coding: utf-8 -*- - -request -======= - -[WRITE ME] - -* the request object - diff -r adbf9a24c41e -r 487bcc269d50 doc/book/en/BXXX-templates.en.txt --- a/doc/book/en/BXXX-templates.en.txt Tue Dec 23 13:20:14 2008 -0800 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,196 +0,0 @@ -.. -*- coding: utf-8 -*- - -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'\n') - self.w(u'\n') - # appliname and breadcrumbs - self.w(u'') - # logged user and help - #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) - - - -.. 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 --------------- - -If you want to change the footer for example, look -for HTMLPageFooter and override it in your views file as in : -:: - - form ginco.web.views.basetemplates import HTMLPageFooter - class MyHTMLPageFooter(HTMLPageFooter): - def call(self, **kwargs): - self.w(u'
') - self.w(u'This website has been created with LAX.') - self.w(u'
') - -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 - -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/``. - -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. - -1 -[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 cubciweb-ctl shell ou -on liste les commandes dispos. diff -r adbf9a24c41e -r 487bcc269d50 doc/book/en/BXXX-urlrewrite.en.txt --- a/doc/book/en/BXXX-urlrewrite.en.txt Tue Dec 23 13:20:14 2008 -0800 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,11 +0,0 @@ -.. -*- coding: utf-8 -*- - -URL Rewriting -============= - -XXX FIXME this should be a chapter - -[WRITE ME] - -* show how urls are mapped to selections and views and explain URLRewriting -