doc/book/en/A02a-create-cube.en.txt
author Sandrine Ribeau <sandrine.ribeau@logilab.fr>
Thu, 23 Apr 2009 13:46:57 -0700
changeset 1674 e4383a510089
parent 1440 4fc48f2a1748
permissions -rw-r--r--
[doc] Add brief reference to the chapter cubicweb-ctl tool.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     1
.. -*- coding: utf-8 -*-
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     2
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     3
Create your cube
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     4
----------------
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     5
1674
e4383a510089 [doc] Add brief reference to the chapter cubicweb-ctl tool.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 1440
diff changeset
     6
The packages ``cubicweb`` and ``cubicweb-dev`` installs a command line tool
e4383a510089 [doc] Add brief reference to the chapter cubicweb-ctl tool.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 1440
diff changeset
     7
for `CubicWeb` called ``cubicweb-ctl``. This tool provides a wide range of
e4383a510089 [doc] Add brief reference to the chapter cubicweb-ctl tool.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 1440
diff changeset
     8
commands described in details in :ref:`cubicweb-ctl`. 
e4383a510089 [doc] Add brief reference to the chapter cubicweb-ctl tool.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 1440
diff changeset
     9
268
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
    10
Once your `CubicWeb` development environment is set up, you can create a new
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
    11
cube::
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    12
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    13
  cubicweb-ctl newcube blog
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    14
272
06077d56f2c4 [doc] Does not keep mercurial forest as the only reference for path description.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 268
diff changeset
    15
This will create in the cubes directory (``/path/to/forest/cubes`` for Mercurial
06077d56f2c4 [doc] Does not keep mercurial forest as the only reference for path description.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 268
diff changeset
    16
installation, ``/usr/share/cubicweb/cubes`` for debian packages installation) 
296
65564e83853e [doc] Moves cube description from tutoriel to foundations.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 280
diff changeset
    17
a directory named ``blog`` reflecting the structure described in :ref:`cubesConcepts`.
280
ce829abf7c29 [doc] Improved tutoriel. Moved appropriate content to cubicweb foundations chapter. Adds section to fill about cubicweb-ctl shell.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 272
diff changeset
    18
255
5d2804b9a28c [doc] add internal links from book abstract
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 229
diff changeset
    19
.. _DefineDataModel:
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    20
268
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
    21
Define your data model
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
    22
----------------------
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    23
268
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
    24
The data model or schema is the core of your `CubicWeb` application.
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
    25
It defines the type of content your application will handle.
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    26
268
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
    27
The data model of your cube ``blog`` is defined in the file ``schema.py``:
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    28
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    29
::
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    30
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    31
  class Blog(EntityType):
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    32
    title = String(maxsize=50, required=True)
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    33
    description = String()
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    34
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    35
  class BlogEntry(EntityType):
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    36
    title = String(required=True, fulltextindexed=True, maxsize=256)
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    37
    publish_date = Date(default='TODAY')
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    38
    content = String(required=True, fulltextindexed=True)
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    39
    entry_of = SubjectRelation('Blog', cardinality='?*') 
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    40
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    41
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    42
A Blog has a title and a description. The title is a string that is
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    43
required by the class EntityType and must be less than 50 characters. 
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    44
The description is a string that is not constrained.
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    45
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    46
A BlogEntry has a title, a publish_date and a content. The title is a
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    47
string that is required and must be less than 100 characters. The
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    48
publish_date is a Date with a default value of TODAY, meaning that
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    49
when a BlogEntry is created, its publish_date will be the current day
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    50
unless it is modified. The content is a string that will be indexed in
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    51
the full-text index and has no constraint.
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    52
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    53
A BlogEntry also has a relationship ``entry_of`` that links it to a
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    54
Blog. The cardinality ``?*`` means that a BlogEntry can be part of
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    55
zero or one Blog (``?`` means `zero or one`) and that a Blog can
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    56
have any number of BlogEntry (``*`` means `any number including
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    57
zero`). For completeness, remember that ``+`` means `one or more`.
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    58
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    59
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    60
Create your instance
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    61
--------------------
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    62
268
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
    63
To use this cube as an application and create a new instance named ``blogdemo``, do::
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    64
  
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    65
  cubicweb-ctl create blog blogdemo
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    66
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    67
1440
4fc48f2a1748 [doc] Typos and minor changes.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 1253
diff changeset
    68
This command will create the corresponding database and initialize it.
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    69
268
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
    70
Welcome to your web application
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    71
-------------------------------
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    72
268
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
    73
Start your application in debug mode with the following command: ::
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    74
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    75
  cubicweb-ctl start -D blogdemo
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    76
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    77
268
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
    78
You can now access your web application to create blogs and post messages
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
    79
by visiting the URL http://localhost:8080/.
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
    80
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
    81
A login form will appear. By default, the application will not allow anonymous
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
    82
users to enter the application. To login, you need then use the admin account
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
    83
you created at the time you initialized the database with ``cubicweb-ctl
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
    84
create``.
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    85
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    86
.. image:: images/login-form.png
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    87
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    88
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    89
Once authenticated, you can start playing with your application 
268
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
    90
and create entities.
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    91
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    92
.. image:: images/blog-demo-first-page.png
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    93
268
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
    94
Please notice that so far, the `CubicWeb` franework managed all aspects of 
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
    95
the web application based on the schema provided at first.
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    96
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    97
268
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
    98
Add entities
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
    99
------------
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   100
268
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
   101
We will now add entities in our web application.
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   102
268
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
   103
Add a Blog
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
   104
~~~~~~~~~~
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   105
268
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
   106
Let us create a few of these entities. Click on the `[+]` at the left of the
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
   107
link Blog on the home page. Call this new Blog ``Tech-blog`` and type in
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
   108
``everything about technology`` as the description, then validate the form by
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
   109
clicking on ``Validate``.
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   110
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   111
.. image:: images/cbw-create-blog.en.png
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   112
   :alt: from to create blog
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   113
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   114
Click on the logo at top left to get back to the home page, then
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   115
follow the Blog link that will list for you all the existing Blog.
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   116
You should be seeing a list with a single item ``Tech-blog`` you
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   117
just created.
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   118
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   119
.. image:: images/cbw-list-one-blog.en.png
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   120
   :alt: displaying a list of a single blog
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   121
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   122
Clicking on this item will get you to its detailed description except
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   123
that in this case, there is not much to display besides the name and
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   124
the phrase ``everything about technology``.
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   125
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   126
Now get back to the home page by clicking on the top-left logo, then
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   127
create a new Blog called ``MyLife`` and get back to the home page
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   128
again to follow the Blog link for the second time. The list now
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   129
has two items.
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   130
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   131
.. image:: images/cbw-list-two-blog.en.png
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   132
   :alt: displaying a list of two blogs
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   133
268
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
   134
Add a BlogEntry
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
   135
~~~~~~~~~~~~~~~
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   136
268
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
   137
Get back to the home page and click on [+] at the left of the link
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   138
BlogEntry. Call this new entry ``Hello World`` and type in some text
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   139
before clicking on ``Validate``. You added a new blog entry without
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   140
saying to what blog it belongs. There is a box on the left entitled
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   141
``actions``, click on the menu item ``modify``. You are back to the form
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   142
to edit the blog entry you just created, except that the form now has
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   143
another section with a combobox titled ``add relation``. Chose
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   144
``entry_of`` in this menu and a second combobox appears where you pick
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   145
``MyLife``. 
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   146
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   147
You could also have, at the time you started to fill the form for a
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   148
new entity BlogEntry, hit ``Apply`` instead of ``Validate`` and the 
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   149
combobox titled ``add relation`` would have showed up.
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   150
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   151
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   152
.. image:: images/cbw-add-relation-entryof.en.png
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   153
   :alt: editing a blog entry to add a relation to a blog
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   154
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   155
Validate the changes by clicking ``Validate``. The entity BlogEntry
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   156
that is displayed now includes a link to the entity Blog named
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   157
``MyLife``.
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   158
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   159
.. image:: images/cbw-detail-one-blogentry.en.png
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   160
   :alt: displaying the detailed view of a blogentry
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   161
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   162
Note that all of this was handled by the framework and that the only input
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   163
that was provided so far is the schema. To get a graphical view of the schema,
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   164
point your browser to the URL http://localhost:8080/schema
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   165
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   166
.. image:: images/cbw-schema.en.png
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   167
   :alt: graphical view of the schema (aka data-model)
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   168
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   169
255
5d2804b9a28c [doc] add internal links from book abstract
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 229
diff changeset
   170
.. _DefineViews:
5d2804b9a28c [doc] add internal links from book abstract
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 229
diff changeset
   171
1249
905d76e38433 [doc] improve view explanation
Emile Anclin <emile.anclin@logilab.fr>
parents: 296
diff changeset
   172
Define your entity views
905d76e38433 [doc] improve view explanation
Emile Anclin <emile.anclin@logilab.fr>
parents: 296
diff changeset
   173
------------------------
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   174
1249
905d76e38433 [doc] improve view explanation
Emile Anclin <emile.anclin@logilab.fr>
parents: 296
diff changeset
   175
Each entity defined in a model inherits default views allowing
280
ce829abf7c29 [doc] Improved tutoriel. Moved appropriate content to cubicweb foundations chapter. Adds section to fill about cubicweb-ctl shell.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 272
diff changeset
   176
different rendering of the data. You can redefine each of them
1249
905d76e38433 [doc] improve view explanation
Emile Anclin <emile.anclin@logilab.fr>
parents: 296
diff changeset
   177
according to your needs and preferences. So let's see how the
905d76e38433 [doc] improve view explanation
Emile Anclin <emile.anclin@logilab.fr>
parents: 296
diff changeset
   178
views are defined.
280
ce829abf7c29 [doc] Improved tutoriel. Moved appropriate content to cubicweb foundations chapter. Adds section to fill about cubicweb-ctl shell.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 272
diff changeset
   179
ce829abf7c29 [doc] Improved tutoriel. Moved appropriate content to cubicweb foundations chapter. Adds section to fill about cubicweb-ctl shell.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 272
diff changeset
   180
1249
905d76e38433 [doc] improve view explanation
Emile Anclin <emile.anclin@logilab.fr>
parents: 296
diff changeset
   181
The view selection principle
905d76e38433 [doc] improve view explanation
Emile Anclin <emile.anclin@logilab.fr>
parents: 296
diff changeset
   182
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   183
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   184
A view is defined by a Python class which includes: 
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   185
  
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   186
  - an identifier (all objects in `CubicWeb` are entered in a registry
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   187
    and this identifier will be used as a key)
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   188
  
1249
905d76e38433 [doc] improve view explanation
Emile Anclin <emile.anclin@logilab.fr>
parents: 296
diff changeset
   189
  - a filter to select the result sets it can be applied to
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   190
280
ce829abf7c29 [doc] Improved tutoriel. Moved appropriate content to cubicweb foundations chapter. Adds section to fill about cubicweb-ctl shell.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 272
diff changeset
   191
A view has a set of methods complying
ce829abf7c29 [doc] Improved tutoriel. Moved appropriate content to cubicweb foundations chapter. Adds section to fill about cubicweb-ctl shell.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 272
diff changeset
   192
with the `View` class interface (`cubicweb.common.view`).
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   193
1249
905d76e38433 [doc] improve view explanation
Emile Anclin <emile.anclin@logilab.fr>
parents: 296
diff changeset
   194
`CubicWeb` provides a lot of standard views for the type `EntityView`;
905d76e38433 [doc] improve view explanation
Emile Anclin <emile.anclin@logilab.fr>
parents: 296
diff changeset
   195
for a complete list, read the code in directory ``cubicweb/web/views/``.
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   196
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   197
A view is applied on a `result set` which contains a set of
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   198
entities we are trying to display. `CubicWeb` uses a selector
1249
905d76e38433 [doc] improve view explanation
Emile Anclin <emile.anclin@logilab.fr>
parents: 296
diff changeset
   199
mechanism which computes for each available view a score: 
905d76e38433 [doc] improve view explanation
Emile Anclin <emile.anclin@logilab.fr>
parents: 296
diff changeset
   200
the view with the highest score is then used to display the given `result set`.
905d76e38433 [doc] improve view explanation
Emile Anclin <emile.anclin@logilab.fr>
parents: 296
diff changeset
   201
The standard library of selectors is in 
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   202
``cubicweb.common.selector`` and a library of methods used to
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   203
compute scores is available in ``cubicweb.vregistry.vreq``.
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   204
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   205
It is possible to define multiple views for the same identifier
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   206
and to associate selectors and filters to allow the application
1253
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
   207
to find the best way to render the data. 
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   208
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   209
For example, the view named ``primary`` is the one used to display
1249
905d76e38433 [doc] improve view explanation
Emile Anclin <emile.anclin@logilab.fr>
parents: 296
diff changeset
   210
a single entity. We will now show you how to customize this view.
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   211
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   212
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   213
View customization
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   214
~~~~~~~~~~~~~~~~~~
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   215
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   216
If you wish to modify the way a `BlogEntry` is rendered, you will have to 
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   217
overwrite the `primary` view defined in the module ``views`` of the cube
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   218
``cubes/blog/views.py``.
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   219
1249
905d76e38433 [doc] improve view explanation
Emile Anclin <emile.anclin@logilab.fr>
parents: 296
diff changeset
   220
We can for example add in front of the publication date a prefix specifying
905d76e38433 [doc] improve view explanation
Emile Anclin <emile.anclin@logilab.fr>
parents: 296
diff changeset
   221
that the date we see is the publication date.
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   222
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   223
To do so, please apply the following changes:
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   224
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   225
:: 
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   226
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   227
  from cubicweb.web.views import baseviews
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   228
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   229
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   230
  class BlogEntryPrimaryView(baseviews.PrimaryView):
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   231
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   232
    accepts = ('BlogEntry',)
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   233
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   234
    def render_entity_title(self, entity):
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   235
        self.w(u'<h1>%s</h1>' % html_escape(entity.dc_title()))
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   236
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   237
    def content_format(self, entity):
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   238
        return entity.view('reledit', rtype='content_format')
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   239
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   240
    def cell_call(self, row, col):
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   241
        entity = self.entity(row, col)
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   242
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   243
        # display entity attributes with prefixes
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   244
        self.w(u'<h1>%s</h1>' % entity.title)
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   245
        self.w(u'<p>published on %s</p>' % entity.publish_date.strftime('%Y-%m-%d'))
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   246
        self.w(u'<p>%s</p>' % entity.content)
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   247
        
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   248
        # display relations
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   249
        siderelations = []
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   250
        if self.main_related_section:
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   251
            self.render_entity_relations(entity, siderelations)
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   252
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   253
.. note::
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   254
  When a view is modified, it is not required to restart the application
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   255
  server. Save the Python file and reload the page in your web browser
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   256
  to view the changes.
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   257
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   258
You can now see that the publication date has a prefix.
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   259
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   260
.. image:: images/cbw-update-primary-view.en.png
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   261
   :alt: modified primary view
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   262
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   263
1249
905d76e38433 [doc] improve view explanation
Emile Anclin <emile.anclin@logilab.fr>
parents: 296
diff changeset
   264
The above source code defines a new primary view for ``BlogEntry``. 
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   265
1249
905d76e38433 [doc] improve view explanation
Emile Anclin <emile.anclin@logilab.fr>
parents: 296
diff changeset
   266
Since views are applied to result sets and result sets can be tables of
905d76e38433 [doc] improve view explanation
Emile Anclin <emile.anclin@logilab.fr>
parents: 296
diff changeset
   267
data, we have to recover the entity from its (row,col)-coordinates.
1253
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
   268
The view has a ``self.w()`` method that is used to output data, in our
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
   269
example HTML output.
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   270
1253
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
   271
You can find more details about views and selectors in :ref:`ViewDefinition`.
1249
905d76e38433 [doc] improve view explanation
Emile Anclin <emile.anclin@logilab.fr>
parents: 296
diff changeset
   272
1253
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
   273