CubicWeboffers several text formats for the RichString type used in schemas, including restructuredtext.
Three additional restructuredtext roles are defined by CubicWeb:
cubicweb.ext.rest.eid_reference_role(role, rawtext, text, lineno, inliner, options={}, con-tent=
[ ]
)cubicweb.ext.rest.rql_role(role, rawtext, text, lineno, inliner, options={}, content=
[ ]
) :rql:‘<rql-expr>‘or :rql:‘<rql-expr>:<vid>‘Example: :rql:‘Any X,Y WHERE X is CWUser, X login Y:table‘
Replace the directive with the output of applying the view to the resultset returned by the query.
“X eid %(userid)s” can be used in the RQL query for this query will be executed with the argument {‘userid’:
_cw.user.eid}.
cubicweb.ext.rest.bookmark_role(role, rawtext, text, lineno, inliner, options={}, content=
[ ]
):bookmark:‘<bookmark-eid>‘or :bookmark:‘<eid>:<vid>‘
Example: :bookmark:‘1234:table‘
Replace the directive with the output of applying the view to the resultset returned by the query stored in the bookmark. By default, the view is the one stored in the bookmark, but it can be overridden by the directive as in the example above.
“X eid %(userid)s” can be used in the RQL query stored in the Bookmark, for this query will be executed with the argument {‘userid’: _cw.user.eid}.
Repository development
This part is about developing applications with the CubicWeb framework. It is not concerned with the web system, which is a separate layer and has its own whole chapter.
3.1 Cubes
This chapter describes how to define your own cubes and reuse already available cubes.
3.1.1 Standard structure for a cube
A cube is structured as follows:
mycube/
|
|-- data/
| |-- cubes.mycube.css
| |-- cubes.mycube.js
| ‘-- external_resources
|
|-- debian/
| |-- changelog
| |-- compat
| |-- control
| |-- copyright
| |-- cubicweb-mycube.prerm
| ‘-- rules
|
|-- entities.py
|
|-- i18n/
| |-- en.po
| |-- es.po
| ‘-- fr.po
|
|-- __init__.py
|
|-- MANIFEST.in
|
|-- migration/
| |-- postcreate.py
| ‘-- precreate.py
We can use subpackages instead of python modules for views.py, entities.py, schema.py or hooks.py.
For example, we could have:
mycube/
• schema contains the schema definition (server side only)
• entities contains the entity definitions (server side and web interface)
• hooks contains hooks and/or views notifications (server side only)
• views contains the web interface components (web interface only)
• test contains tests related to the cube (not installed)
• i18n contains message catalogs for supported languages (server side and web interface)
• data contains data files for static content (images, css, javascript code)...(web interface only)
• migration contains initialization files for new instances (postcreate.py) and a file containing depen-dencies of the component depending on the version (depends.map)
• debian contains all the files managing debian packaging (you will find the usual files control, rules, changelog... not installed)
• file __pkginfo__.py provides component meta-data, especially the distribution and the current version (server side and web interface) or sub-cubes used by the cube.
At least you should have the file __pkginfo__.py.
The __init__.py and site_cubicweb.py files The __pkginfo__.py file
It contains metadata describing your cube, mostly useful for packaging.
Two important attributes of this module are __depends__ and __recommends__ dictionaries that indicates what should be installed (and each version if necessary) for the cube to work.
Dependency on other cubes are expected to be of the form ‘cubicweb-<cubename>’.
When an instance is created, dependencies are automatically installed, while recommends are not.
Recommends may be seen as a kind of ‘weak dependency’. Eg, the most important effect of recommending a cube is that, if cube A recommends cube B, the cube B will be loaded before the cube A (same thing happend when A depends on B).
Having this behaviour is sometime desired: on schema creation, you may rely on something defined in the other’s schema; on database creation, on something created by the other’s postcreate, and so on.
migration/precreate.pyand migration/postcreate.py
External resources such as image, javascript and css files Out-of the box testing
Packaging and distribution
3.1.2 Creating a new cube from scratch
Let’s start by creating the cube environment in which we will develop cd ~/cubes
# use cubicweb-ctl to generate a template for the cube
# will ask some questions, most with nice default cubicweb-ctl newcube mycube
# makes the cube source code managed by mercurial cd mycube
hg init hg add . hg ci
If all went well, you should see the cube you just created in the list returned by cubicweb-ctl list in the Available cubessection. If not, please refer toEnvironment configuration.
To reuse an existing cube, add it to the list named __depends_cubes__ which is defined in __pkginfo__.py.
This variable is used for the instance packaging (dependencies handled by system utility tools such as APT) and to find used cubes when the database for the instance is created (import_erschema(‘MyCube’) will not properly work otherwise).
On a Unix system, the available cubes are usually stored in the directory /usr/share/cubicweb/cubes.
If you are using the cubicweb mercurial repository (Install from source), the cubes are searched in the direc-tory /path/to/cubicweb_toplevel/cubes. In this configuration cubicweb itself ought to be located at /path/to/cubicweb_toplevel/cubicweb.
Note: Please note that if you do not wish to use default directory for your cubes library, you should set the CW_CUBES_PATHenvironment variable to add extra directories where cubes will be search, and you’ll then have to use the option –directory to specify where you would like to place the source code of your cube:
cubicweb-ctl newcube --directory=/path/to/cubes/library mycube
3.1.3 Available cubes
An instance is made of several basic cubes. In the set of available basic cubes we can find for example:
Base entity types
• addressbook: PhoneNumber and PostalAddress
• card: Card, generic documenting card
• event: Event (define events, display them in calendars)
• file: File (to allow users to upload and store binary or text files)
• link: Link (to collect links to web resources)
• mailinglist: MailingList (to reference a mailing-list and the URLs for its archives and its admin interface)
• person: Person (easily mixed with addressbook)
• task: Task (something to be done between start and stop date)
• zone: Zone (to define places within larger places, for example a city in a state in a country)
Classification
• folder: Folder (to organize things by grouping them in folders)
• keyword: Keyword (to define classification schemes)
• tag: Tag (to tag anything)
Other features
• basket: Basket (like a shopping cart)
• blog: a blogging system using Blog and BlogEntry entity types
• comment: system to attach comment threads to entities)
• email: archiving management for emails (Email, Emailpart, Emailthread), trigger action in cubicweb through email
To declare the use of a cube, once installed, add the name of the cube and its dependency relation in the __de-pends_cubes__dictionary defined in the file __pkginfo__.py of your own component.
Note: The listed cubes above are available as debian-packages onCubicWeb’s forge.