diff -r 7c59d513883e -r 54944faf9b61 doc/book/en/tutorials/advanced/part05_ui-advanced.rst --- a/doc/book/en/tutorials/advanced/part05_ui-advanced.rst Mon Jan 24 09:40:54 2011 +0100 +++ b/doc/book/en/tutorials/advanced/part05_ui-advanced.rst Mon Jan 24 09:42:09 2011 +0100 @@ -1,4 +1,4 @@ -Building my photos web site with |CubiWeb| part V: let's make it even more user friendly +Building my photos web site with |cubiweb| part V: let's make it even more user friendly ========================================================================================= We'll now see how to benefit from features introduced in 3.9 and 3.10 releases of CubiWeb @@ -11,7 +11,7 @@ first! The first thing we can to is to change the logo. There are various way to achieve -this. The easiest way is to put a `logo.png` file into the cube's `data` +this. The easiest way is to put a :file:`logo.png` file into the cube's :file:`data` directory. As data files are looked at according to cubes order (CubiWeb resources coming last), that file will be selected instead of CubiWeb's one. @@ -19,9 +19,9 @@ As the location for static resources are cached, you'll have to restart your instance for this to be taken into account. -Though there are some cases where you don't want to use a `logo.png` file. For -instance if it's a JPEG file. You can still change the logo by defining in the -cube's `:file:`uiprops.py`` file: +Though there are some cases where you don't want to use a :file:`logo.png` file. +For instance if it's a JPEG file. You can still change the logo by defining in +the cube's :file:`uiprops.py` file: .. sourcecode:: python @@ -47,14 +47,15 @@ All I've to do is to override some stuff of the default CubiWeb user interface to apply it as explained. -The first thing to to get the ```` tag as first element after the ```` -tag. If you know a way to avoid this by simply specifying the image in the CSS, -tell me! The easiest way to do so is to override the `HTMLPageHeader` view, -since that's the one that is directly called once the ```` has -been written. How did I find this? By looking in the `cubiweb.web.views.basetemplates` -module, since I know that global page layouts sits there. I could also have -grep the "body" tag in `cubicweb.web.views`... Finding this was the hardest -part. Now all I need is to customize it to write that ``img`` tag, as below: +The first thing to to get the ```` tag as first element after the +```` tag. If you know a way to avoid this by simply specifying the image +in the CSS, tell me! The easiest way to do so is to override the +:class:`HTMLPageHeader` view, since that's the one that is directly called once +the ```` has been written. How did I find this? By looking in the +:mod:`cubiweb.web.views.basetemplates` module, since I know that global page +layouts sits there. I could also have grep the "body" tag in +:mod:`cubicweb.web.views`... Finding this was the hardest part. Now all I need is +to customize it to write that ``img`` tag, as below: .. sourcecode:: python @@ -72,26 +73,26 @@ vreg.register_and_replace(HTMLPageHeader, basetemplates.HTMLPageHeader) -As you may have guessed, my background image is in a `backgroundjpg` -file in the cube's `data` directory, but there are still some things to explain to -newcomers here: +As you may have guessed, my background image is in a :file:`background.jpg` file +in the cube's :file:`data` directory, but there are still some things to explain +to newcomers here: -* The `call` method is there the main access point of the view. It's called by - the view's `render` method. It is not the only access point for a view, but +* The :meth:`call` method is there the main access point of the view. It's called by + the view's :meth:`render` method. It is not the only access point for a view, but this will be detailed later. * Calling `self.w` writes something to the output stream. Except for binary views (which do not generate text), it *must* be passed an Unicode string. -* The proper way to get a file in `data` directory is to use the `datadir_url` +* The proper way to get a file in :file:`data` directory is to use the `datadir_url` attribute of the incoming request (e.g. `self._cw`). -I won't explain again the `registration_callback` stuff, you should understand it +I won't explain again the :func:`registration_callback` stuff, you should understand it now! If not, go back to previous posts in the series :) -Fine. Now all I've to do is to add a bit of CSS to get it to behave -nicely (which is not the case at all for now). I'll put all this in a -`cubes.sytweb.css` file, stored as usual in our `data` directory: +Fine. Now all I've to do is to add a bit of CSS to get it to behave nicely (which +is not the case at all for now). I'll put all this in a :file:`cubes.sytweb.css` +file, stored as usual in our :file:`data` directory: .. sourcecode:: css @@ -181,7 +182,9 @@ Step 2: configuring boxes ~~~~~~~~~~~~~~~~~~~~~~~~~ -Boxes present to the user some ways to use the application. Let's first do a few tweaks: + +Boxes present to the user some ways to use the application. Let's first do a few +user interface tweaks in our :file:`views.py` file: .. sourcecode:: python @@ -203,8 +206,8 @@ The idea is to move all boxes in the left column, so we get more space for the photos. Now, serious things: I want a box similar to the tags box but to handle -the `Person displayed_on File` relation. We can do this simply by configuring a -:class:`AjaxEditRelationCtxComponent` subclass as below: +the `Person displayed_on File` relation. We can do this simply by adding a +:class:`AjaxEditRelationCtxComponent` subclass to our views, as below: .. sourcecode:: python @@ -275,10 +278,10 @@ attributes give the name of methods that should be defined on the json control to make the AJAX part of the widget work: one to get the vocabulary, one to add a relation and another to delete a relation. These methods must start by a `js_` -prefix and are added to the controller using the `@monkeypatch` -decorator. In my case, the most complicated method is the one which adds a relation, since it tries to see if the -person already exists, and else automatically create it, assuming the user -entered "firstname surname". +prefix and are added to the controller using the `@monkeypatch` decorator. In my +case, the most complicated method is the one which adds a relation, since it +tries to see if the person already exists, and else automatically create it, +assuming the user entered "firstname surname". Let's see how it looks like on a file primary view: @@ -299,12 +302,26 @@ '/file' url, you'll see a set of 'facets' appearing in the left column. Facets provide an intuitive way to build a query incrementally, by proposing to the user various way to restrict the result set. For instance CubiWeb proposes a facet to -restrict based on who created an entity; the tag cube proposes a facet to restrict -based on tags. In that gist, I want to propose a facet to restrict based -on the people displayed on the picture. To do so, there are various classes in the +restrict based on who created an entity; the tag cube proposes a facet to +restrict based on tags; the zoe cube a facet to restrict based on geographical +location, and so on. In that gist, I want to propose a facet to restrict based on +the people displayed on the picture. To do so, there are various classes in the :mod:`cubicweb.web.facet` module which simply have to be configured using class attributes as we've done for the box. In our case, we'll define a subclass of -:class:`RelationFacet`: +:class:`RelationFacet`. + +.. Note: + + Since that's ui stuff, we'll continue to add code below to our + :file:`views.py` file. Though we begin to have a lot of various code their, so + it's may be a good time to split our views module into submodules of a `view` + package. In our case of a simple application (glue) cube, we could start using + for instance the layout below: :: + + views/__init__.py # uicfg configuration, facets + views/layout.py # header/footer/background stuff + views/components.py # boxes, adapters + views/pages.py # index view, 404 view .. sourcecode:: python @@ -333,8 +350,10 @@ .. Note: - Facets which have no choice to propose (i.e. one or less elements of - vocabulary) are not displayed. This may be why you don't see yours. + By default a facet must be applyable to every entity in the result set and + provide at leat two elements of vocabulary to be displayed (for instance you + won't see the `created_by` facet if the same user has created all + entities). This may explain why you don't see yours... Conclusion