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

.. _TutosBaseCustomizingTheApplication:

Customizing your application

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

So far so good. The point is that usually, you won't get enough by assembling

cubes out-of-the-box. You will want to customize them, have a personal look and

feel, add your own data model and so on. Or maybe start from scratch?

So let's get a bit deeper and start coding our own cube. In our case, we want

to customize the blog we created to add more features to it.

Create your own cube

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

First, notice that if you've installed |cubicweb| using Debian packages, you will

need the additional ``cubicweb-dev`` package to get the commands necessary to

|cubicweb| development. All `cubicweb-ctl` commands are described in details in

:ref:`cubicweb-ctl`.

Once your |cubicweb| development environment is set up, you can create a new

cube::

  cubicweb-ctl newcube myblog

This will create in the cubes directory (:file:`/path/to/grshell/cubes` for source

installation, :file:`/usr/share/cubicweb/cubes` for Debian packages installation)

a directory named :file:`blog` reflecting the structure described in

:ref:`cubelayout`.

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

and then create your new cube using: ::

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

.. Note::

   We previously used `myblog` as the name of our *instance*. We're now creating

   a *cube* with the same name. Both are different things. We'll now try to

   specify when we talk about one or another, but keep in mind this difference.

Cube metadata

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

A simple set of metadata about your cube are stored in the :file:`__pkginfo__.py`

file. In our case, we want to extend the blog cube, so we have to tell that our

cube depends on this cube, by modifying the ``__depends__`` dictionary in that

file:

.. sourcecode:: python

   __depends__ =  {'cubicweb': '>= 3.10.7',

                   'cubicweb-blog': None}

where the ``None`` means we do not depends on a particular version of the cube.

.. _TutosBaseCustomizingTheApplicationDataModel:

Extending the data model

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

The data model or schema is the core of your |cubicweb| application.  It defines

the type of content your application will handle. It is defined in the file

:file:`schema.py` of the cube.

Defining our model

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

For the sake of example, let's say we want a new entity type named `Community`

with a name, a description. A `Community` will hold several blogs.

.. sourcecode:: python

  from yams.buildobjs import EntityType, RelationDefinition, String, RichString

  class Community(EntityType):

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

      description = RichString()

  class community_blog(RelationDefinition):

      subject = 'Community'

      object = 'Blog'

      cardinality = '*?'

      composite = 'subject'

The first step is the import from the :mod:`yams` package necessary classes to build

the schema.

This file defines the following:

* a `Community` has a name and a description as attributes

  - the name is a string that is required and can't be longer than 50 characters

  - the description is a string that is not constrained and may contains rich

    content such as HTML or Restructured text.

* a `Community` may be linked to a `Blog` using the `community_blog` relation

  - ``*`` means a community may be linked to 0 to N blog, ``?`` means a blog may

    be linked to 0 to 1 community. For completeness, you can also use ``+`` for

    1 to N, and ``1`` for single, mandatory relation (e.g. one to one);

  - this is a composite relation where `Community` (e.g. the subject of the

    relation) is the composite. That means that if you delete a community, its

    blog will be deleted as well.

Of course, there are a lot of other data types and things such as constraints,

permissions, etc, that may be defined in the schema, but those won't be covered

in this tutorial.

Notice that our schema refers to the `Blog` entity type which is not defined

here.  But we know this type is available since we depend on the `blog` cube

which is defining it.

Applying changes to the model into our instance

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

Now the problem is that we created an instance using the `blog` cube, not our

`myblog` cube, so if we don't do anything there is no way that we'll see anything

changing in the instance.

One easy way, as we've no really valuable data in the instance would be to trash and recreated it::

  cubicweb-ctl stop myblog # or Ctrl-C in the terminal running the server in debug mode

  cubicweb-ctl delete myblog

  cubicweb-ctl create myblog myblog

  cubicweb-ctl start -D myblog

Another way is to add our cube to the instance using the cubicweb-ctl shell

facility. It's a python shell connected to the instance with some special

commands available to manipulate it (the same as you'll have in migration

scripts, which are not covered in this tutorial). In that case, we're interested

in the `add_cube` command: ::

  $ cubicweb-ctl stop myblog # or Ctrl-C in the terminal running the server in debug mode

  $ cubicweb-ctl shell myblog

  entering the migration python shell

  just type migration commands or arbitrary python code and type ENTER to execute it

  type "exit" or Ctrl-D to quit the shell and resume operation

  >>> add_cube('myblog')

  >>>

  $ cubicweb-ctl start -D myblog

The `add_cube` command is enough since it automatically updates our

application to the cube's schema. There are plenty of other migration

commands of a more finer grain. They are described in :ref:`migration`

As explained, leave the shell by typing Ctrl-D. If you restart the instance and

take another look at the schema, you'll see that changes to the data model have

actually been applied (meaning database schema updates and all necessary stuff

has been done).

.. image:: ../../images/tutos-base_myblog-schema_en.png

   :alt: the instance schema after adding our cube

If you follow the 'info' link in the user pop-up menu, you'll also see that the

instance is using blog and myblog cubes.

.. image:: ../../images/tutos-base_myblog-siteinfo_en.png

   :alt: the instance schema after adding our cube

You can now add some communities, link them to blog, etc... You'll see that the

framework provides default views for this entity type (we have not yet defined any

view for it!), and also that the blog primary view will show the community it's

linked to if any. All this thanks to the model driven interface provided by the

framework.

You'll then be able to redefine each of them according to your needs

and preferences. We'll now see how to do such thing.

.. _TutosBaseCustomizingTheApplicationCustomViews:

Defining your views

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

|cubicweb| provides a lot of standard views in the directory

:file:`cubicweb/web/views/`. We already talked about 'primary' and 'list' views,

which are views which apply to one ore more entities.

A view is defined by a python class which includes:

  - an identifier: all objects used to build the user interface in |cubicweb| are

    recorded in a registry and this identifier will be used as a key in that

    registry to store the view. There may be multiple views for the same identifier.

  - a *selector*, which is a kind of filter telling how well a view suit to a

    particular context. When looking for a particular view (e.g. given an

    identifier), |cubicweb| computes for each available view with that identifier

    a score which is returned by the selector. Then the view with the highest

    score is used. The standard library of predicates is in

    :mod:`cubicweb.predicates`.

A view has a set of methods inherited from the :class:`cubicweb.view.View` class,

though you usually don't derive directly from this class but from one of its more

specific child class.

Last but not least, |cubicweb| provides a set of default views accepting any kind

of entities.

Want a proof? Create a community as you've already done for other entity types

through the index page, you'll then see something like that:

.. image:: ../../images/tutos-base_myblog-community-default-primary_en.png

   :alt: the default primary view for our community entity type

If you notice the weird messages that appear in the page: those are messages

generated for the new data model, which have no translation yet. To fix that,

we'll have to use dedicated `cubicweb-ctl` commands:

.. sourcecode: bash

  cubicweb-ctl i18ncube myblog # build/update cube's message catalogs

  # then add translation into .po file into the cube's i18n directory

  cubicweb-ctl i18ninstance myblog # recompile instance's message catalogs

  cubicweb-ctl restart -D myblog # instance has to be restarted to consider new catalogs

You'll then be able to redefine each of them according to your needs and

preferences. So let's see how to do such thing.

Changing the layout of the application

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

The layout is the general organization of the pages in the site. Views that generate

the layout are sometimes referred to as 'templates'. They are implemented in the

framework in the module :mod:`cubicweb.web.views.basetemplates`. By overriding

classes in this module, you can customize whatever part you wish of the default

layout.

But notice that |cubicweb| provides many other ways to customize the

interface, thanks to actions and components (which you can individually

(de)activate, control their location, customize their look...) as well as

"simple" CSS customization. You should first try to achieve your goal using such

fine grained parametrization rather then overriding a whole template, which usually

embeds customisation access points that you may loose in the process.

But for the sake of example, let's say we want to change the generic page

footer...  We can simply add to the module ``views`` of our cube,

e.g. :file:`cubes/myblog/views.py`, the code below:

.. sourcecode:: python

  from cubicweb.web.views import basetemplates

  class MyHTMLPageFooter(basetemplates.HTMLPageFooter):

      def footer_content(self):

          self.w(u'This website has been created with <a href="http://cubicweb.org">CubicWeb</a>.')

  def registration_callback(vreg):

      vreg.register_all(globals().values(), __name__, (MyHTMLPageFooter,))

      vreg.register_and_replace(MyHTMLPageFooter, basetemplates.HTMLPageFooter)

* Our class inherits from the default page footer to ease getting things right,

  but this is not mandatory.

* When we want to write something to the output stream, we simply call `self.w`,

  which *must be passed a unicode string*.

* The latest function is the most exotic stuff. The point is that without it, you

  would get an error at display time because the framework wouldn't be able to

  choose which footer to use between :class:`HTMLPageFooter` and

  :class:`MyHTMLPageFooter`, since both have the same selector, hence the same

  score...  In this case, we want our footer to replace the default one, so we have

  to define a :func:`registration_callback` function to control object

  registration: the first instruction tells to register everything in the module

  but the :class:`MyHTMLPageFooter` class, then the second to register it instead

  of :class:`HTMLPageFooter`. Without this function, everything in the module is

  registered blindly.

.. Note::

  When a view is modified while running in debug mode, 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.

We will now have this simple footer on every page of the site.

Primary view customization

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

The 'primary' view (i.e. any view with the identifier set to 'primary') is the one used to

display all the information about a single entity. The standard primary view is one

of the most sophisticated views of all. It has several customisation points, but

its power comes with `uicfg`, allowing you to control it without having to

subclass it.

However this is a bit off-topic for this first tutorial. Let's say we simply want a

custom primary view for my `Community` entity type, using directly the view

interface without trying to benefit from the default implementation (you should

do that though if you're rewriting reusable cubes; everything is described in more

details in :ref:`primary_view`).

So... Some code! That we'll put again in the module ``views`` (:file:`myblog/views.py`) of our cube.

.. sourcecode:: python

  from cubicweb.predicates import is_instance

  from cubicweb.web.views import primary

  class CommunityPrimaryView(primary.PrimaryView):

      __select__ = is_instance('Community')

      def cell_call(self, row, col):

          entity = self.cw_rset.get_entity(row, col)

          self.w(u'<h1>Welcome to the "%s" community</h1>' % entity.printable_value('name'))

          if entity.description:

              self.w(u'<p>%s</p>' % entity.printable_value('description'))

What's going on here?

* Our class inherits from the default primary view, here mainly to get the correct

  view identifier, since we don't use any of its features.

* We set on it a selector telling that it only applies when trying to display

  some entity of the `Community` type. This is enough to get an higher score than

  the default view for entities of this type.

* A view that applies to an entity usually have to define the method

  `cell_call` as an entry point. This method will received the arguments

  `row` and `col` that tell to which entity in the result set the view is

  applied. We can then get this entity from the result set (`self.cw_rset`) by

  using the `get_entity` method.

* To ease thing, we access our entity's attribute for display using its

  printable_value method, which will handle formatting and escaping when

  necessary. As you can see, you can also access attributes by their name on the

  entity to get the raw value.

You can now reload the page of the community we just created and see the changes.

.. image:: ../../images/tutos-base_myblog-community-custom-primary_en.png

   :alt: the custom primary view for our community entity type

We've seen here a lot of thing you'll have to deal with to write views in

|cubicweb|. The good news is that this is almost everything that is used to

build higher level layers.

.. Note::

  As things get complicated and the volume of code in your cube increases, you can

  of course still split your views module into a python package with subpackages.

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

Write entities to add logic in your data

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

|cubicweb| provides an ORM to easily programmaticaly manipulate

entities (just like the one we have fetched earlier by calling

`get_entity` on a result set). By default, entity

types are instances of the :class:`AnyEntity` class, which holds a set of

predefined methods as well as property automatically generated for

attributes/relations of the type it represents.

You can redefine each entity to provide additional methods or whatever you want

to help you write your application. Customizing an entity requires that your

entity:

- inherits from :class:`cubicweb.entities.AnyEntity` or any subclass

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

You may then want to add your own methods, override default implementation of some

method, etc... To do so, write this code in :file:`myblog/entities.py`:

.. sourcecode:: python