.. -*- coding: utf-8 -*-

.. _Steps:

Steps for creating your cube

----------------------------

The following steps will help you to create and customize a new cube.

1. :ref:`CreateYourCube`

Create the directory to hold the code of your cube. The most important

files that will be useful to customize your newly created cube are:

  * schema.py: contains the data model

  * views.py: contains your custom views

  * entities.py: contains XXX

The detailed structure of the code directory is described in :ref:`cubelayout`.

2. :ref:`DefineDataModel`

Define the data model of your application.

3. :ref:`ExploreYourInstance`

Create, run, and explore an instance of your cube.

4. :ref:`DefineViews`

Customize the views of your data: how and which part of your data are showed.

.. note:: views do not define the look'n'feel and the design of your application. For that, you will use CSS and the files located 'blog/data/'.

5. :ref:`DefineEntities`

Define your own entities to add useful functions when you manipulate your data, especially when you write view.

.. _CreateYourCube:

Create your cube

----------------

The packages ``cubicweb`` and ``cubicweb-dev`` install a command line

tool for *CubicWeb* called ``cubicweb-ctl``. This tool provides a wide

range of commands described in details in :ref:`cubicweb-ctl`.

Once your *CubicWeb* development environment is set up, you can create

a new cube::

  cubicweb-ctl newcube blog

This will create in the cubes directory (``/path/to/forest/cubes`` for Mercurial

installation, ``/usr/share/cubicweb/cubes`` for debian packages installation)

a directory named ``blog`` reflecting the structure described in :ref:`Concepts`.

For packages installation, you can still create new cubes in your home directory using the following configuration. Let's say you want to develop your new cubes in `~src/cubes`, then set the following environment variables:

::

  CW_CUBES_PATH=~/src/cubes

  CW_MODE=user

and then create your new cube using:

::

  cubicweb-ctl newcube --directory=~/src/cubes blog

.. _DefineDataModel:

Define your data model

----------------------

The data model or schema is the core of your *CubicWeb* application.

It defines the type of content your application will handle.

The data model of your cube ``blog`` is defined in the file ``schema.py``:

.. sourcecode:: python

  from yams.buildobjs import EntityType, String, SubjectRelation, Date

  class Blog(EntityType):

    title = String(maxsize=50, required=True)

    description = String()

  class BlogEntry(EntityType):

    title = String(required=True, fulltextindexed=True, maxsize=256)

    publish_date = Date(default='TODAY')

    content = String(required=True, fulltextindexed=True)

    entry_of = SubjectRelation('Blog', cardinality='?*')

The first step is the import of the EntityType (generic class for entity and

attributes that will be used in both Blog and BlogEntry entities.

A Blog has a title and a description. The title is a string that is

required and must be less than 50 characters.  The

description is a string that is not constrained.

A BlogEntry has a title, a publish_date and a content. The title is a

string that is required and must be less than 100 characters. The

publish_date is a Date with a default value of TODAY, meaning that

when a BlogEntry is created, its publish_date will be the current day

unless it is modified. The content is a string that will be indexed in

the database full-text index and has no constraint.

A BlogEntry also has a relationship ``entry_of`` that links it to a

Blog. The cardinality ``?*`` means that a BlogEntry can be part of

zero or one Blog (``?`` means `zero or one`) and that a Blog can

have any number of BlogEntry (``*`` means `any number including

zero`). For completeness, remember that ``+`` means `one or more`.

.. _ExploreYourInstance:

Create and explore your instance

--------------------------------

.. _CreateYourInstance:

Create your instance

~~~~~~~~~~~~~~~~~~~~

To use this cube as an instance and create a new instance named ``blogdemo``, do::

  cubicweb-ctl create blog blogdemo

This command will create the corresponding database and initialize it.

.. _WelcomeToYourWebInstance:

Welcome to your web instance

~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Start your instance in debug mode with the following command: ::

  cubicweb-ctl start -D blogdemo

You can now access your web instance to create blogs and post messages

by visiting the URL http://localhost:8080/.

A login form will appear. By default, the instance will not allow anonymous

users to enter the instance. To login, you need then use the admin account

you created at the time you initialized the database with ``cubicweb-ctl

create``.

.. image:: ../../images/login-form.png

Once authenticated, you can start playing with your instance

and create entities.

.. image:: ../../images/blog-demo-first-page.png

Please notice that so far, the *CubicWeb* framework managed all aspects of

the web application based on the schema provided at the beginning.

.. _AddEntities:

Add entities

~~~~~~~~~~~~

We will now add entities in our web application.

Add a Blog

**********

Let us create a few of these entities. Click on the `[+]` at the left of the

link Blog on the home page. Call this new Blog ``Tech-blog`` and type in

``everything about technology`` as the description, then validate the form by

clicking on ``Validate``.

.. image:: ../../images/cbw-create-blog_en.png

   :alt: from to create blog

Click on the logo at top left to get back to the home page, then

follow the Blog link that will list for you all the existing Blog.

You should be seeing a list with a single item ``Tech-blog`` you

just created.

.. image:: ../../images/cbw-list-one-blog_en.png

   :alt: displaying a list of a single blog

Clicking on this item will get you to its detailed description except

that in this case, there is not much to display besides the name and

the phrase ``everything about technology``.

Now get back to the home page by clicking on the top-left logo, then

create a new Blog called ``MyLife`` and get back to the home page

again to follow the Blog link for the second time. The list now

has two items.

.. image:: ../../images/cbw-list-two-blog_en.png

   :alt: displaying a list of two blogs

Add a BlogEntry

***************

Get back to the home page and click on [+] at the left of the link

BlogEntry. Call this new entry ``Hello World`` and type in some text

before clicking on ``Validate``. You added a new blog entry without

saying to what blog it belongs. There is a box on the left entitled

``actions``, click on the menu item ``modify``. You are back to the form

to edit the blog entry you just created, except that the form now has

another section with a combobox titled ``add relation``. Chose

``entry_of`` in this menu and a second combobox appears where you pick

``MyLife``.

You could also have, at the time you started to fill the form for a

new entity BlogEntry, hit ``Apply`` instead of ``Validate`` and the

combobox titled ``add relation`` would have showed up.

.. image:: ../../images/cbw-add-relation-entryof_en.png

   :alt: editing a blog entry to add a relation to a blog

Validate the changes by clicking ``Validate``. The entity BlogEntry

that is displayed now includes a link to the entity Blog named

``MyLife``.

.. image:: ../../images/cbw-detail-one-blogentry_en.png

   :alt: displaying the detailed view of a blogentry

Note that all of this was handled by the framework and that the only input

that was provided so far is the schema. To get a graphical view of the schema,

point your browser to the URL http://localhost:8080/schema

.. image:: ../../images/cbw-schema_en.png

   :alt: graphical view of the schema (aka data-model)

.. _DefineViews:

Define your entity views

------------------------

Each entity defined in a model is associated with default views

allowing different renderings of the data. You can redefine each of

them according to your needs and preferences. So let's see how the

views are defined.

The view selection principle

~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A view is defined by a Python class which includes:

  - an identifier (all objects in *CubicWeb* are recorded in a

    registry and this identifier will be used as a key)

  - a filter to select the result sets it can be applied to

A view has a set of methods complying with the `View` class interface

(`cubicweb.common.view`).

*CubicWeb* provides a lot of standard views for the type `EntityView`;

for a complete list, read the code in directory ``cubicweb/web/views/``.

A view is applied on a `result set` which contains a set of entities

we are trying to display. *CubicWeb* uses a selector mechanism which

computes for each available view a score: the view with the highest

score is then used to display the given `result set`.  The standard

library of selectors is in ``cubicweb.selector``.

It is possible to define multiple views for the same identifier

and to associate selectors and filters to allow the application

to find the most appropriate way to render the data.

For example, the view named ``primary`` is the one used to display a

single entity. We will now show you how to create a primary view for

BlogEntry.

Primary view customization

~~~~~~~~~~~~~~~~~~~~~~~~~~

If you wish to modify the way a `BlogEntry` is rendered, you will have

to subclass the `primary` view, for instance in the module ``views``

of the cube ``cubes/blog/views.py``.

The standard primary view is the most sophisticated view of all. It

has more than a call() method. It is a template. Actually the entry

point calls the following sequence of (redefinable) methods:

 * render_entity_title

 * render_entity_metadata

 * render_entity_attributes

 * render_entity_relations

 * render_side_boxes

Excepted side boxes, we can see all of them already in action in the

blog entry view. This is all described in more details in

:ref:`primary_view`.

We can for example add in front of the publication date a prefix

specifying that the date we see is the publication date.

To do so, please apply the following changes:

.. sourcecode:: python

  from cubicweb.selectors import implements

  from cubicweb.web.views import primary

  class BlogEntryPrimaryView(primary.PrimaryView):

      __select__ = implements('BlogEntry')

      def render_entity_attributes(self, entity):

          self.w(u'<p>published on %s</p>' %

                 entity.publish_date.strftime('%Y-%m-%d'))

          super(BlogEntryPrimaryView, self).render_entity_attributes(entity)

.. note::

  When a view is modified, it is not required to restart the instance

  server. Save the Python file and reload the page in your web browser

  to view the changes.

You can now see that the publication date has a prefix.

.. image:: ../../images/cbw-update-primary-view_en.png

   :alt: modified primary view

The above source code defines a new primary view for ``BlogEntry``.

Since views are applied to result sets and result sets can be tables of

data, we have to recover the entity from its (row,col)-coordinates.

The view has a ``self.w()`` method that is used to output data, in our

example HTML output.

.. note::

   You can find more details about views and selectors in :ref:`Views`.

.. _DefineEntities:

Write entities to add logic in your data

----------------------------------------

By default, CubicWeb provides a default entity for each data type defined in the schema.

A default entity mainly contains the attributes defined in the data model.

You can redefine each entity to provide additional functions to help you write your views.

.. sourcecode:: python

    from cubicweb.entities import AnyEntity

    class BlogEntry(AnyEntity):

        """customized class for BlogEntry entities"""

    	__regid__ = 'BlogEntry'

    	__implements__ = AnyEntity.__implements__

        def display_cw_logo(self):

            if 'CW' in self.title:

                return True

            else:

                return False

Customizing an entity requires that your entity:

 - inherits from ``cubicweb.entities`` or any subclass

 - defines a ``__regid__`` linked to the corresponding data type of your schema

 - implements the base class by explicitly using ``__implements__``.

We implemented here a function ``display_cw_logo`` which tests if the blog entry title contains 'CW'.

This function can then be used when you customize your views. For instance, you can modify your previous ``views.py`` as follows:

.. sourcecode:: python

 class BlogEntryPrimaryView(primary.PrimaryView):

     __select__ = implements('BlogEntry')

     ...

     def render_entity_title(self, entity):

	 if entity.display_cw_logo():

	     self.w(u'<image src="http://www.cubicweb.org/doc/en/_static/cubicweb.png"/>')

	 super(BlogEntryPrimaryView, self).render_entity_title(entity)

Then each blog entry whose title contains 'CW' is shown with the CubicWeb logo in front of it.

.. _UpdatingSchemaAndSynchronisingInstance:

Updating the schema and synchronising the instance

--------------------------------------------------

While developping your cube, you may want to update your data model. Let's say you

want to add a ``category`` attribute in the ``Blog`` data type. This is called a migration.

The required steps are:

1. modify the file ``schema.py``. The ``Blog`` class looks now like this:

.. sourcecode:: python

 class Blog(EntityType):

   title = String(maxsize=50, required=True)

   description = String()

   category = String(required=True, vocabulary=(_('Professional'), _('Personal')), default='Personal')

2. stop your ``blogdemo`` instance:

.. sourcecode:: bash

  cubicweb-ctl stop blogdemo

3. start the cubicweb shell for your instance by running the following command:

.. sourcecode:: bash

  cubicweb-ctl shell blogdemo

4. at the cubicweb shell prompt, execute:

.. sourcecode:: python

 add_attribute('Blog', 'category')

5. restart your instance:

.. sourcecode:: bash

  cubicweb-ctl start blogdemo

6. modify a blog entity and check that the new attribute

``category`` has been added.

Of course, you may also want to add relations, entity types, etc. See :ref:`migration`

for a list of all available migration commands.