diff -r e2303f9b5bfa -r 22c0fad39c13 doc/book/en/01-01-create-cube.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/01-01-create-cube.en.txt Thu Nov 20 21:56:45 2008 +0100 @@ -0,0 +1,314 @@ +.. -*- coding: utf-8 -*- + +Create your cube +---------------- + +After you installed your `CubicWeb` development environment, you can start +to build your first cube: :: + + cubicweb-ctl newcube blog + +This will create in ``/path/to/forest/cubes`` a directory containing: :: + + blog/ + | + |-- data/ + | |-- cubes.blog.css + | |-- cubes.blog.js + | |-- external_resources + | + |-- debian/ + | |-- changelog + | |-- compat + | |-- control + | |-- copyright + | |-- cubicweb-blog.prerm + | |-- rules + | + |-- entities.py + | + |-- i18n/ + | |-- en.po + | |-- fr.po + | + |-- __init__.py + | + |-- MANIFEST.in + | + |-- migration/ + | |-- postcreate.py + | |-- precreate.py + | + |-- __pkginfo__.py + | + |-- schema.py + | + |-- setup.py + | + |-- site_cubicweb.py + | + |-- sobjects.py + | + |-- test/ + | |-- data/ + | |-- bootstrap_cubes + | |-- pytestconf.py + | |-- realdb_test_blog.py + | |-- test_blog.py + | + |-- views.py + +Any changes applied to your data model should be done in this +directory. + + +Define your data schema +----------------------- + +The data model or schema is hte core of your `CubicWeb` application. +This is where is defined the type of content you application will handle. + +The data model is defined in the file ``schema.py`` of your cube +``blog`` such as follows. + +:: + + from cubicweb.schema import format_constraint + 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='?*') + + +A Blog has a title and a description. The title is a string that is +required by the class EntityType 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 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`. + + +Create your instance +-------------------- + +:: + + cubicweb-ctl create blog blogdemo + + +This command will create a directory ``~/etc/cubicweb.d/blogdemo`` +which will contain all the configuration files required to start +you web application. + +The instance ``blogdemo`` is based on the cube ``blog``. + + +Welcome in your web application +------------------------------- + +Run your application with the following command: :: + + cubicweb-ctl start -D blogdemo + + +You can now access to your web application to create blogs and post messages +by visitin the URL http://localhost:8080/. +A login form will first be prompted. By default, the application will not allow +anonymous user to get in the application. You should 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 application +and create entities. Bravo! + +.. image:: images/blog-demo-first-page.png + +Please notice that so far, `CubicWeb` franework managed all aspects of +the web application based in the schema provided at first. + + +Create entities +--------------- + +We will now create a couple of entities in our web application. + +Create a Blog +~~~~~~~~~~~~~ + +Let us create a few of these entities. Click on the `[+]` at the right +of the link Blog. 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 + +Create a BlogEntry +~~~~~~~~~~~~~~~~~~ + +Get back to the home page and click on [+] at the right 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) + + +Define your entities views +-------------------------- + +The views selection principle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A view is defined by a Python class which includes: + + - an identifier (all objects in `CubicWeb` are entered in a registry + and this identifier will be used as a key) + + - a filter to select the resulsets it can be applied to + + +`CubicWeb` provides a lot of standard views for the type +`EntityView`, for a complete list, you +will have to 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 +mecanism which computes a score used to identify which view +is the best to apply for the `result set` we are trying to +display. The standard library of selectors is in +``cubicweb.common.selector`` and a library of methods used to +compute scores is available in ``cubicweb.vregistry.vreq``. + +It is possible to define multiple views for the same identifier +and to associate selectors and filters to allow the application +to find the best way to render the data. We will see more details +on this in :ref:`DefinitionVues`. + +For example, the view named ``primary`` is the one used to display +a single entity. We will now show you hos to customize this view. + + +View customization +~~~~~~~~~~~~~~~~~~ + +If you wish to modify the way a `BlogEntry` is rendered, you will have to +overwrite the `primary` view defined in the module ``views`` of the cube +``cubes/blog/views.py``. + +We can by example add in front of the pulication date a prefix specifying +the date we see is the publication date. + +To do so, please apply the following changes: + +:: + + from cubicweb.web.views import baseviews + + + class BlogEntryPrimaryView(baseviews.PrimaryView): + + accepts = ('BlogEntry',) + + def render_entity_title(self, entity): + self.w(u'

%s

' % html_escape(entity.dc_title())) + + def content_format(self, entity): + return entity.view('reledit', rtype='content_format') + + def cell_call(self, row, col): + entity = self.entity(row, col) + + # display entity attributes with prefixes + self.w(u'

%s

' % entity.title) + self.w(u'

published on %s

' % entity.publish_date.strftime('%Y-%m-%d')) + self.w(u'

%s

' % entity.content) + + # display relations + siderelations = [] + if self.main_related_section: + self.render_entity_relations(entity, siderelations) + +.. note:: + When a view is modified, it is not required to restart the application + 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 resultsets and resulsets can be tables of +data, it is needed to recover the entity from its (row,col) +coordinates. We will get to this in more detail later. + +The view has a ``self.w()`` method that is used to output data. In our +example we use it to output HTML tags and values of the entity's attributes.