Commit 3e4113a8 authored by Adrien Chauve's avatar Adrien Chauve
Browse files

Updated CW tutorial.

* Summarized the list of steps to create a new cube.
* Added a subsection on writing entities.
* Added a subsection on modifying the schema and updating the corresponding instance.
parent 0b6a069eb29e
......@@ -53,6 +53,8 @@ The repositories are signed with `Logilab's gnupg key`_. To avoid warning on "ap
.. _`Logilab's gnupg key`: http://ftp.logilab.org/dists/logilab-dists-key.asc
.. _SourceInstallation:
Install from source
```````````````````
......@@ -83,6 +85,8 @@ Do not forget to update the forest itself (using `cd path/to/forest ; hg up`).
Make sure you have installed the dependencies (see appendixes for the list).
.. _WindowsInstallation:
Windows installation
````````````````````
......
......@@ -29,6 +29,7 @@ A cube is structured as follows:
|
|-- i18n/
| |-- en.po
| |-- es.po
| `-- fr.po
|
|-- __init__.py
......
......@@ -5,10 +5,12 @@
Get a blog running in five minutes!
-----------------------------------
First install the following packages (:ref:`DebianInstallation`)::
For Debian or Ubuntu users, first install the following packages (:ref:`DebianInstallation`)::
cubicweb, cubicweb-dev, cubicweb-blog
For Windows or Mac OS X users, you must install cubicweb from source (see :ref:`SourceInstallation` and :ref:`WindowsInstallation`).
Then create and initialize your instance::
cubicweb-ctl create blog myblog
......
......@@ -69,7 +69,7 @@ Once you modified your data model, you need to synchronize the
database with your model. For this purpose, *CubicWeb* provides
a very useful command ``cubicweb-ctl shell blogdemo`` which
launches an interactive shell where you can enter migration
commands. (see :ref:`cubicweb-ctl` for more details))
commands (see :ref:`cubicweb-ctl` for more details)).
As you added the cube named `comment`, you need to run:
::
......
.. -*- 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 don't concern the look'n'feel or design of the site. For that, you should use CSS instead, and default CSS or your new cube are located in '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
----------------
......@@ -16,6 +54,23 @@ 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
......@@ -26,7 +81,7 @@ 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
......@@ -40,7 +95,7 @@ The data model of your cube ``blog`` is defined in the file ``schema.py``:
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
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
......@@ -61,8 +116,14 @@ 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::
......@@ -71,8 +132,10 @@ To use this cube as an instance and create a new instance named ``blogdemo``, do
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: ::
......@@ -98,14 +161,15 @@ and create entities.
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
......@@ -136,7 +200,7 @@ has two items.
: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
......@@ -249,7 +313,7 @@ To do so, please apply the following changes:
from cubicweb.web.views import primary
class BlogEntryPrimaryView(primary.PrimaryView):
__select__ = implements('BlogEntry')
__select__ = implements('BlogEntry')
def render_entity_attributes(self, entity):
self.w(u'<p>published on %s</p>' %
......@@ -278,3 +342,88 @@ example HTML output.
You can find more details about views and selectors in :ref:`ViewDefinition`.
.. _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
3. start the cubicweb shell for your instance by running the following command:
.. sourcecode:: bash
cubicweb-ctl shell blogdemo
4. in the shell, execute:
.. sourcecode:: python
add_attribute('Blog', 'category')
5. you can restart your instance, 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, ... See :ref:`migration`
for a list of all available migration commands.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment