doc/book/en/A02a-create-cube.en.txt
author Sandrine Ribeau <sandrine.ribeau@logilab.fr>
Fri, 26 Dec 2008 11:37:56 -0800
changeset 296 65564e83853e
parent 280 ce829abf7c29
child 1249 905d76e38433
permissions -rw-r--r--
[doc] Moves cube description from tutoriel to foundations.
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
268
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
     6
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
     7
cube::
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     8
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     9
  cubicweb-ctl newcube blog
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    10
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
    11
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
    12
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
    13
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
    14
255
5d2804b9a28c [doc] add internal links from book abstract
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 229
diff changeset
    15
.. _DefineDataModel:
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    16
268
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
    17
Define your data model
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
    18
----------------------
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    19
268
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
    20
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
    21
It defines the type of content your application will handle.
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    22
268
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
    23
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
    24
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    25
::
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    26
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    27
  from cubicweb.schema import format_constraint
268
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
    28
  
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    29
  class Blog(EntityType):
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    30
    title = String(maxsize=50, required=True)
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    31
    description = String()
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    32
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    33
  class BlogEntry(EntityType):
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    34
    title = String(required=True, fulltextindexed=True, maxsize=256)
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    35
    publish_date = Date(default='TODAY')
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    36
    content = String(required=True, fulltextindexed=True)
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    37
    entry_of = SubjectRelation('Blog', cardinality='?*') 
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    38
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    39
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    40
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
    41
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
    42
The description is a string that is not constrained.
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    43
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    44
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
    45
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
    46
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
    47
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
    48
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
    49
the full-text index and has no constraint.
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    50
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    51
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
    52
Blog. The cardinality ``?*`` means that a BlogEntry can be part of
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    53
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
    54
have any number of BlogEntry (``*`` means `any number including
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    55
zero`). For completeness, remember that ``+`` means `one or more`.
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    56
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    57
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    58
Create your instance
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
268
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
    61
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
    62
  
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    63
  cubicweb-ctl create blog blogdemo
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
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    66
This command will create a directory ``~/etc/cubicweb.d/blogdemo``
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    67
which will contain all the configuration files required to start
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    68
you web application.
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
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   172
Define your entities views
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   173
--------------------------
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   174
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
   175
Each entity defined in a model inherits defaults views allowing
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
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
   177
according to your needs and preferences. If you feel like it then
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
   178
you have to know how a view is defined.
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
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   181
The views selection principle
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   182
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
  
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   189
  - a filter to select the resulsets it can be applied to
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
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   194
`CubicWeb` provides a lot of standard views for the type
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   195
`EntityView`, for a complete list, you
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   196
will have to read the code in directory ``cubicweb/web/views/``
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   197
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   198
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
   199
entities we are trying to display. `CubicWeb` uses a selector
268
0575e7973c5e [doc] trying to improve the tutorial
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 255
diff changeset
   200
mechanism which computes a score used to identify which view
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   201
is the best to apply for the `result set` we are trying to 
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   202
display. The standard library of selectors is in 
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   203
``cubicweb.common.selector`` and a library of methods used to
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   204
compute scores is available in ``cubicweb.vregistry.vreq``.
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   205
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   206
It is possible to define multiple views for the same identifier
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   207
and to associate selectors and filters to allow the application
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   208
to find the best way to render the data. We will see more details
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   209
on this in :ref:`DefinitionVues`.
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   210
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   211
For example, the view named ``primary`` is the one used to display
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   212
a single entity. We will now show you hos to customize this view.
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   213
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
View customization
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   216
~~~~~~~~~~~~~~~~~~
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   217
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   218
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
   219
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
   220
``cubes/blog/views.py``.
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   221
229
767ff7f5d5a7 [doc] Replace all : s/by example/for example/
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
   222
We can for example add in front of the pulication date a prefix specifying
117
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   223
the date we see is the publication date.
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
To do so, please apply the following changes:
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
:: 
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
  from cubicweb.web.views import baseviews
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   230
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
  class BlogEntryPrimaryView(baseviews.PrimaryView):
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
    accepts = ('BlogEntry',)
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   235
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   236
    def render_entity_title(self, entity):
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   237
        self.w(u'<h1>%s</h1>' % html_escape(entity.dc_title()))
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   238
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   239
    def content_format(self, entity):
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   240
        return entity.view('reledit', rtype='content_format')
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   241
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   242
    def cell_call(self, row, col):
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   243
        entity = self.entity(row, col)
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   244
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   245
        # display entity attributes with prefixes
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   246
        self.w(u'<h1>%s</h1>' % entity.title)
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   247
        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
   248
        self.w(u'<p>%s</p>' % entity.content)
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   249
        
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   250
        # display relations
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   251
        siderelations = []
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   252
        if self.main_related_section:
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   253
            self.render_entity_relations(entity, siderelations)
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   254
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   255
.. note::
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   256
  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
   257
  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
   258
  to view the changes.
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
You can now see that the publication date has a prefix.
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   261
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   262
.. image:: images/cbw-update-primary-view.en.png
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   263
   :alt: modified primary view
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   264
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   265
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   266
The above source code defines a new primary view for
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   267
``BlogEntry``. 
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   268
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   269
Since views are applied to resultsets and resulsets can be tables of
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   270
data, it is needed to recover the entity from its (row,col)
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   271
coordinates. We will get to this in more detail later.
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   272
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   273
The view has a ``self.w()`` method that is used to output data. In our
22c0fad39c13 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   274
example we use it to output HTML tags and values of the entity's attributes.