# HG changeset patch # User sylvain.thenault@logilab.fr # Date 1240585454 -7200 # Node ID b056a49c16dca56fe397b931f680cdd0605fb228 # Parent f94b41709ce6896ba65e61bb85a0a2b00282e492# Parent 09afa1f808c4b50dc9076fee7dbdf22d27b4c1e1 backport default branch diff -r f94b41709ce6 -r b056a49c16dc __pkginfo__.py diff -r f94b41709ce6 -r b056a49c16dc cwctl.py --- a/cwctl.py Fri Apr 24 16:48:38 2009 +0200 +++ b/cwctl.py Fri Apr 24 17:04:14 2009 +0200 @@ -616,8 +616,6 @@ def upgrade_application(self, appid): from logilab.common.changelog import Version - if not (cwcfg.mode == 'dev' or self.config.nostartstop): - self.stop_application(appid) config = cwcfg.config_for(appid) config.creating = True # notice we're not starting the server config.verbosity = self.config.verbosity @@ -661,6 +659,9 @@ return for cube, fromversion, toversion in toupgrade: print '**** %s migration %s -> %s' % (cube, fromversion, toversion) + # only stop once we're sure we have something to do + if not (cwcfg.mode == 'dev' or self.config.nostartstop): + self.stop_application(appid) # run cubicweb/componants migration scripts mih.migrate(vcconf, reversed(toupgrade), self.config) # rewrite main configuration file diff -r f94b41709ce6 -r b056a49c16dc cwvreg.py --- a/cwvreg.py Fri Apr 24 16:48:38 2009 +0200 +++ b/cwvreg.py Fri Apr 24 17:04:14 2009 +0200 @@ -210,9 +210,9 @@ def possible_actions(self, req, rset, **kwargs): if rset is None: - actions = self.possible_vobjects('actions', req, rset) + actions = self.possible_vobjects('actions', req, rset, **kwargs) else: - actions = rset.possible_actions() # cached implementation + actions = rset.possible_actions(**kwargs) # cached implementation result = {} for action in actions: result.setdefault(action.category, []).append(action) diff -r f94b41709ce6 -r b056a49c16dc debian.hardy/compat --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/debian.hardy/compat Fri Apr 24 17:04:14 2009 +0200 @@ -0,0 +1,1 @@ +5 diff -r f94b41709ce6 -r b056a49c16dc debian.hardy/control --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/debian.hardy/control Fri Apr 24 17:04:14 2009 +0200 @@ -0,0 +1,131 @@ +Source: cubicweb +Section: web +Priority: optional +Maintainer: Logilab S.A. +Uploaders: Sylvain Thenault , + Julien Jehannet , + Aurélien Campéas +Build-Depends: debhelper (>= 5), python-dev (>=2.4), python-central (>= 0.5) +Standards-Version: 3.8.0 +Homepage: http://www.cubicweb.org +XS-Python-Version: >= 2.4, << 2.6 + + +Package: cubicweb +Architecture: all +XB-Python-Version: ${python:Versions} +Depends: ${python:Depends}, cubicweb-server (= ${source:Version}), cubicweb-twisted (= ${source:Version}), cubicweb-client (= ${source:Version}) +XB-Recommends: (postgresql, postgresql-plpython, postgresql-contrib) | mysql | sqlite3 +Recommends: postgresql | mysql | sqlite3 +Description: the complete CubicWeb framework + CubicWeb is a semantic web application framework. + . + This package will install all the components you need to run cubicweb on + a single machine. You can also deploy cubicweb by running the different + process on different computers, in which case you need to install the + corresponding packages on the different hosts. + + +Package: cubicweb-server +Architecture: all +XB-Python-Version: ${python:Versions} +Conflicts: cubicweb-multisources +Replaces: cubicweb-multisources +Provides: cubicweb-multisources +Depends: ${python:Depends}, cubicweb-common (= ${source:Version}), cubicweb-ctl (= ${source:Version}), python-indexer (>= 0.6.1), python-psycopg2 | python-mysqldb | python-pysqlite2 +Recommends: pyro, cubicweb-documentation (= ${source:Version}) +Description: server part of the CubicWeb framework + CubicWeb is a semantic web application framework. + . + This package provides the repository server part of the system. + . + This package provides the repository server part of the library and + necessary shared data files such as the schema library. + + +Package: cubicweb-twisted +Architecture: all +XB-Python-Version: ${python:Versions} +Provides: cubicweb-web-frontend +Depends: ${python:Depends}, cubicweb-web (= ${source:Version}), cubicweb-ctl (= ${source:Version}), python-twisted-web2 +Recommends: pyro, cubicweb-documentation (= ${source:Version}) +Description: twisted-based web interface for the CubicWeb framework + CubicWeb is a semantic web application framework. + . + This package provides a twisted based HTTP server to serve + the adaptative web interface (see cubicweb-web package). + . + This package provides only the twisted server part of the library. + + +Package: cubicweb-web +Architecture: all +XB-Python-Version: ${python:Versions} +Depends: ${python:Depends}, cubicweb-common (= ${source:Version}), python-docutils, python-vobject, python-elementtree +Recommends: fckeditor +Description: web interface library for the CubicWeb framework + CubicWeb is a semantic web application framework. + . + This package provides an adaptative web interface to the CubicWeb server. + Install the cubicweb-twisted package to serve this interface via HTTP. + . + This package provides the web interface part of the library and + necessary shared data files such as defaut views, images... + + +Package: cubicweb-common +Architecture: all +XB-Python-Version: ${python:Versions} +Depends: ${python:Depends}, python-logilab-mtconverter (>= 0.6.0), python-simpletal (>= 4.0), graphviz, gettext, python-lxml, python-logilab-common (>= 0.38.1), python-yams (>= 0.20.2), python-rql (>= 0.20.2), python-simplejson (>= 1.3) +Recommends: python-psyco +Conflicts: cubicweb-core +Replaces: cubicweb-core +Description: common library for the CubicWeb framework + CubicWeb is a semantic web application framework. + . + This package provides the common parts of the library used by both server + code and web application code. + + +Package: cubicweb-ctl +Architecture: all +XB-Python-Version: ${python:Versions} +Depends: ${python:Depends}, cubicweb-common (= ${source:Version}) +Description: tool to manage the CubicWeb framework + CubicWeb is a semantic web application framework. + . + This package provides a control script to manage (create, upgrade, start, + stop, etc) CubicWeb applications. It also include the init.d script + to automatically start and stop CubicWeb applications on boot or shutdown. + + +Package: cubicweb-client +Architecture: all +XB-Python-Version: ${python:Versions} +Depends: ${python:Depends}, cubicweb-ctl (= ${source:Version}), pyro +Description: RQL command line client for the CubicWeb framework + CubicWeb is a semantic web application framework. + . + This package provides a RQL (Relation Query Language) command line client using + pyro to connect to a repository server. + + +Package: cubicweb-dev +Architecture: all +XB-Python-Version: ${python:Versions} +Depends: ${python:Depends}, cubicweb-server (= ${source:Version}), cubicweb-web (= ${source:Version}), python-pysqlite2 +Suggests: w3c-dtd-xhtml +Description: tests suite and development tools for the CubicWeb framework + CubicWeb is a semantic web application framework. + . + This package provides the CubicWeb tests suite and some development tools + helping in the creation of application. + + +Package: cubicweb-documentation +Architecture: all +Recommends: doc-base +Description: documentation for the CubicWeb framework + CubicWeb is a semantic web application framework. + . + This package provides the system's documentation. diff -r f94b41709ce6 -r b056a49c16dc debian.hardy/rules --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/debian.hardy/rules Fri Apr 24 17:04:14 2009 +0200 @@ -0,0 +1,78 @@ +#!/usr/bin/make -f +# Sample debian/rules that uses debhelper. +# GNU copyright 1997 to 1999 by Joey Hess. + +# Uncomment this to turn on verbose mode. +#export DH_VERBOSE=1 + +PY_VERSION:=$(shell pyversions -d) + +build: build-stamp +build-stamp: + dh_testdir + # XXX doesn't work if logilab-doctools, logilab-xml are not in build depends + # and I can't get pbuilder find them in its chroot :( + # cd doc && make + # FIXME cleanup and use sphinx-build as build-depends ? + python setup.py build + touch build-stamp + +clean: + dh_testdir + dh_testroot + rm -f build-stamp configure-stamp + rm -rf build + #rm -rf debian/cubicweb-*/ + find . -name "*.pyc" -delete + rm -f $(basename $(wildcard debian/*.in)) + dh_clean + +install: build $(basename $(wildcard debian/*.in)) + dh_testdir + dh_testroot + dh_clean + dh_installdirs + + #python setup.py install_lib --no-compile --install-dir=debian/cubicweb-common/usr/lib/python2.4/site-packages/ + python setup.py -q install --no-compile --prefix=debian/tmp/usr + + # Put all the python library and data in cubicweb-common + # and scripts in cubicweb-server + dh_install -vi + #dh_lintian XXX not before debhelper 7 + + # Remove unittests directory (should be available in cubicweb-dev only) + rm -rf debian/cubicweb-server/usr/lib/${PY_VERSION}/site-packages/cubicweb/server/test + rm -rf debian/cubicweb-server/usr/lib/${PY_VERSION}/site-packages/cubicweb/sobjects/test + rm -rf debian/cubicweb-web/usr/lib/${PY_VERSION}/site-packages/cubicweb/web/test + rm -rf debian/cubicweb-common/usr/lib/${PY_VERSION}/site-packages/cubicweb/common/test + + # cubes directory must be managed as a valid python module + touch debian/cubicweb-common/usr/share/cubicweb/cubes/__init__.py + +%: %.in + sed "s/PY_VERSION/${PY_VERSION}/g" < $< > $@ + +# Build architecture-independent files here. +binary-indep: build install + dh_testdir + dh_testroot -i + dh_pycentral -i + dh_installinit -i -n --name cubicweb -u"defaults 99" + dh_installlogrotate -i + dh_installdocs -i -A README + dh_installman -i + dh_installchangelogs -i + dh_link -i + dh_compress -i -X.py -X.ini -X.xml + dh_fixperms -i + dh_installdeb -i + dh_gencontrol -i + dh_md5sums -i + dh_builddeb -i + +binary-arch: + +binary: binary-indep +.PHONY: build clean binary binary-indep binary-arch + diff -r f94b41709ce6 -r b056a49c16dc devtools/apptest.py --- a/devtools/apptest.py Fri Apr 24 16:48:38 2009 +0200 +++ b/devtools/apptest.py Fri Apr 24 17:04:14 2009 +0200 @@ -14,6 +14,8 @@ from logilab.common.pytest import nocoverage from logilab.common.umessage import message_from_string +from logilab.common.deprecation import deprecated_function + from cubicweb.devtools import init_test_database, TestServerConfiguration, ApptestConfiguration from cubicweb.devtools._apptest import TestEnvironment from cubicweb.devtools.fake import FakeRequest @@ -218,6 +220,13 @@ def pactions(self, req, rset, skipcategories=('addrelated', 'siteactions', 'useractions')): return [(a.id, a.__class__) for a in self.vreg.possible_vobjects('actions', req, rset) if a.category not in skipcategories] + + def pactions_by_cats(self, req, rset, categories=('addrelated',)): + return [(a.id, a.__class__) for a in self.vreg.possible_vobjects('actions', req, rset) + if a.category in categories] + + paddrelactions = deprecated_function(pactions_by_cats) + def pactionsdict(self, req, rset, skipcategories=('addrelated', 'siteactions', 'useractions')): res = {} for a in self.vreg.possible_vobjects('actions', req, rset): @@ -225,10 +234,7 @@ res.setdefault(a.category, []).append(a.__class__) return res - def paddrelactions(self, req, rset): - return [(a.id, a.__class__) for a in self.vreg.possible_vobjects('actions', req, rset) - if a.category == 'addrelated'] - + def remote_call(self, fname, *args): """remote call simulation""" dump = simplejson.dumps diff -r f94b41709ce6 -r b056a49c16dc doc/book/en/A020-tutorial.en.txt --- a/doc/book/en/A020-tutorial.en.txt Fri Apr 24 16:48:38 2009 +0200 +++ b/doc/book/en/A020-tutorial.en.txt Fri Apr 24 17:04:14 2009 +0200 @@ -1,9 +1,9 @@ .. -*- coding: utf-8 -*- -.. _Overview: +.. _Tutorial: -Quick overview of `CubicWeb` -============================ +Tutorial +======== `CubicWeb` is a semantic web application framework that favors reuse and object-oriented design. @@ -17,6 +17,7 @@ An `instance` is a specific installation of an application and includes configuration files. + This tutorial will show how to create a `cube` and how to use it as an application to run an `instance`. diff -r f94b41709ce6 -r b056a49c16dc doc/book/en/A02a-create-cube.en.txt --- a/doc/book/en/A02a-create-cube.en.txt Fri Apr 24 16:48:38 2009 +0200 +++ b/doc/book/en/A02a-create-cube.en.txt Fri Apr 24 17:04:14 2009 +0200 @@ -24,8 +24,6 @@ :: - from cubicweb.schema import format_constraint - class Blog(EntityType): title = String(maxsize=50, required=True) description = String() @@ -63,9 +61,7 @@ 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. +This command will create the corresponding database and initialize it. Welcome to your web application ------------------------------- diff -r f94b41709ce6 -r b056a49c16dc doc/book/en/A02b-components.en.txt --- a/doc/book/en/A02b-components.en.txt Fri Apr 24 16:48:38 2009 +0200 +++ b/doc/book/en/A02b-components.en.txt Fri Apr 24 17:04:14 2009 +0200 @@ -68,7 +68,7 @@ Once you modified your data model, you need to synchronize the database with your model. For this purpose, `CubicWeb` provides -a very usefull command ``cubicweb-ctl shell blogdemo`` which +a very useful command ``cubicweb-ctl shell blogdemo`` which launches an interactive migration Python shell. (see :ref:`cubicweb-ctl-shell` for more details)) As you modified a relation from the `BlogEntry` schema, diff -r f94b41709ce6 -r b056a49c16dc doc/book/en/B0012-schema-definition.en.txt --- a/doc/book/en/B0012-schema-definition.en.txt Fri Apr 24 16:48:38 2009 +0200 +++ b/doc/book/en/B0012-schema-definition.en.txt Fri Apr 24 17:04:14 2009 +0200 @@ -6,7 +6,9 @@ An entity type is defined by a Python class which inherits from `EntityType`. The class definition contains the description of attributes and relations for the defined entity type. -The class name corresponds to the entity type name. +The class name corresponds to the entity type name. It is exepected to be +defined in the module ``mycube.schema``. + For example :: @@ -21,14 +23,36 @@ works_for = SubjectRelation('Company', cardinality='?*') -* the name of the Python attribute corresponds to the name of the attribute - or the relation in `CubicWeb` application. +The entity described above defines three attributes of type String, +last_name, first_name and title, an attribute of type Date for the date of +birth and a relation that connects a `Person` to another entity of type +`Company` through the semantic `works_for`. + +The name of the Python attribute corresponds to the name of the attribute +or the relation in `CubicWeb` application. + +Built-in types for attributes +````````````````````````````` -* all `CubicWeb` built-in types are available : `String`, `Int`, `Float`, - `Boolean`, `Date`, `Datetime`, `Time`, `Byte`; they are and implicitely - imported (as well as the special the function "_"). +All `CubicWeb` built-in types are available : `String`, `Int`, `Float`, +`Decimal`, `Boolean`, `Date`, `Datetime`, `Time`, `Interval`, `Byte` +and `Password`. +They are implicitely imported (as well as the special the function "_" +for translation :ref:`internationalization`). + +An attribute is defined in the schema as follows:: + + attr_name = attr_type(properties*) -* each entity type has at least the following meta-relations : +where `attr_type` is one of the type listed above and `properties` is +a list of the attribute needs to statisfy (see :ref:`properties` +for more details). + + +Meta-data +````````` + +Each entity type has at least the following meta-relations : - `eid` (`Int`) @@ -41,7 +65,7 @@ - `owned_by` (`CWUser`) (to whom the entity belongs; by default the creator but not necessary, and it could have multiple owners) - - `is` (`CWEType`) + - `is` (`CWEType`) (of which type the entity is) * relations can be defined by using `ObjectRelation` or `SubjectRelation`. @@ -62,6 +86,11 @@ * it is possible to use the attribute `meta` to flag an entity type as a `meta` (e.g. used to describe/categorize other entities) +Optionnal properties +```````````````````` +.. _properties: + + * optional properties for attributes and relations : - `description` : a string describing an attribute or a relation. By default @@ -95,7 +124,7 @@ or not within all entities of the same type (false by default) - `indexed` : boolean indicating if an index needs to be created for this - attribute in the database (false by default). This is usefull only if + attribute in the database (false by default). This is useful only if you know that you will have to run numerous searches on the value of this attribute. diff -r f94b41709ce6 -r b056a49c16dc doc/book/en/B0030-data-as-objects.en.txt --- a/doc/book/en/B0030-data-as-objects.en.txt Fri Apr 24 16:48:38 2009 +0200 +++ b/doc/book/en/B0030-data-as-objects.en.txt Fri Apr 24 17:04:14 2009 +0200 @@ -7,12 +7,12 @@ In this chapter, we will introduce the objects that are used to handle the data stored in the database. -Classes `Entity` and `AnyEntity` --------------------------------- +Class `Entity` and `AnyEntity` +------------------------------ To provide a specific behavior for each entity, we have to define a class inheriting from `cubicweb.entities.AnyEntity`. In general, we -define this class in a module of `entities` package of an application +define this class in a module of `mycube.entities` package of an application so that it will be available on both server and client side. The class `AnyEntity` is loaded dynamically from the class `Entity` @@ -114,6 +114,105 @@ * `relation_vocabulary(rtype, targettype, x, limit=None)`, called internally by `subject_relation_vocabulary` and `object_relation_vocabulary` +Class `TreeMixIn` +----------------- + +This class provides a tree interface. This mixin has to be inherited +explicitly and configured using the tree_attribute, parent_target and +children_target class attribute to benefit from this default implementation. + +This class provides the following methods: + + * `different_type_children(entities=True)`, returns children entities + of different type as this entity. According to the `entities` parameter, + returns entity objects (if entity=True) or the equivalent result set. + + * `same_type_children(entities=True)`, returns children entities of + the same type as this entity. According to the `entities` parameter, + return entity objects (if entity=True) or the equivalent result set. + + * `iterchildren( _done=None)`, iters on the children of the entity. + + * `prefixiter( _done=None)` + + * `path()`, returns the list of eids from the root object to this object. + + * `iterparents()`, iters on the parents of the entity. + + * `notification_references(view)`, used to control References field + of email send on notification for this entity. `view` is the notification view. + Should return a list of eids which can be used to generate message ids + of previously sent email. + +`TreeMixIn` implements also the ITree interface (``cubicweb.interfaces``): + + * `parent()`, returns the parent entity if any, else None (e.g. if we are on the + root) + + * `children(entities=True, sametype=False)`, returns children entities + according to the `entities` parameter, return entity objects or the + equivalent result set. + + * `children_rql()`, returns the RQL query corresponding to the children + of the entity. + + * `is_leaf()`, returns True if the entity does not have any children. + + * `is_root()`, returns True if the entity does not have any parent. + + * `root()`, returns the root object of the tree representation of + the entity and its related entities. + +Example of use +`````````````` + +Imagine you defined three types of entities in your schema, and they +relates to each others as follows in ``schema.py``:: + + class Entity1(EntityType): + title = String() + is_related_to = SubjectRelation('Entity2', 'subject') + + class Entity2(EntityType): + title = String() + belongs_to = SubjectRelation('Entity3', 'subject') + + class Entity3(EntityType): + name = String() + +You would like to create a view that applies to both entity types +`Entity1` and `Entity2` and which lists the entities they are related to. +That means when you view `Entity1` you want to list all `Entity2`, and +when you view `Entity2` you want to list all `Entity3`. + +In ``entities.py``:: + + class Entity1(TreeMixIn, AnyEntity): + id = 'Entity1' + __implements__ = AnyEntity.__implements__ + (ITree,) + __rtags__ = {('is_related_to', 'Entity2', 'object'): 'link'} + tree_attribute = 'is_related_to' + + def children(self, entities=True): + return self.different_type_children(entities) + + class Entity2(TreeMixIn, AnyEntity): + id = 'Entity2' + __implements__ = AnyEntity.__implements__ + (ITree,) + __rtags__ = {('belongs_to', 'Entity3', 'object'): 'link'} + tree_attribute = 'belongs_to' + + def children(self, entities=True): + return self.different_type_children(entities) + +Once this is done, you can define your common view as follows:: + + class E1E2CommonView(baseviews.PrimaryView): + accepts = ('Entity11, 'Entity2') + + def render_entity_relations(self, entity, siderelations): + self.wview('list', entity.children(entities=False)) + *rtags* ------- diff -r f94b41709ce6 -r b056a49c16dc doc/book/en/B0031-define-entities.en.txt --- a/doc/book/en/B0031-define-entities.en.txt Fri Apr 24 16:48:38 2009 +0200 +++ b/doc/book/en/B0031-define-entities.en.txt Fri Apr 24 17:04:14 2009 +0200 @@ -133,7 +133,7 @@ The method ``filterform_vocabulary(rtype, x, var, rqlst, args, cachekey)`` takes the name of a relation and the target as parameters, [XXX what does it mean ?] - which indicates of the +which indicates of the entity on which we apply the method is subject or object of the relation. It has to return: diff -r f94b41709ce6 -r b056a49c16dc doc/book/en/B0040-migration.en.txt --- a/doc/book/en/B0040-migration.en.txt Fri Apr 24 16:48:38 2009 +0200 +++ b/doc/book/en/B0040-migration.en.txt Fri Apr 24 17:04:14 2009 +0200 @@ -208,3 +208,6 @@ * `add_entity_type_table(etype, commit=True)` * `add_relation_type_table(rtype, commit=True)` * `uninline_relation(rtype, commit=True)` + + +[FIXME] Add explanation on how to use cubicweb-ctl shell diff -r f94b41709ce6 -r b056a49c16dc doc/book/en/B1020-define-views.en.txt --- a/doc/book/en/B1020-define-views.en.txt Fri Apr 24 16:48:38 2009 +0200 +++ b/doc/book/en/B1020-define-views.en.txt Fri Apr 24 17:04:14 2009 +0200 @@ -13,6 +13,8 @@ understanding of the classes and methods available, then detail the view selection principle which makes `CubicWeb` web interface very flexible. +A `View` is an object applied to another object such as an entity. + Basic class for views --------------------- @@ -72,6 +74,7 @@ * `AnyRsetView`, view applied to any result set * `EmptyRsetView`, view applied to an empty result set + The selection view principle ---------------------------- @@ -96,6 +99,9 @@ Registerer `````````` +[Registerers are deprecated: they will soon disappear for explicite +registration...] + A view is also customizable through its attribute ``__registerer__``. This is used at the time the application is launched to manage how objects (views, graphic components, actions, etc.) @@ -110,9 +116,6 @@ when they are selected for display. -`CubicWeb` provides a lot of standard views for the default class -`EntityType`. You can find them in ``cubicweb/web/views/``. - .. include:: B1022-views-stdlib.en.txt @@ -150,12 +153,122 @@ search_states = ('linksearch',) +Rendering methods and attributes for ``PrimaryView`` +---------------------------------------------------- +By default, `CubicWeb` provides a primary view for each new entity type +you create. The first view you might be interested in modifying. +Let's have a quick look at the EntityView ``PrimaryView`` as well as +its rendering method:: + + class PrimaryView(EntityView): + """the full view of an non final entity""" + id = 'primary' + title = _('primary') + show_attr_label = True + show_rel_label = True + skip_none = True + skip_attrs = ('eid', 'creation_date', 'modification_date') + skip_rels = () + main_related_section = True + + ... + + def cell_call(self, row, col): + self.row = row + self.render_entity(self.complete_entity(row, col)) + + def render_entity(self, entity): + """return html to display the given entity""" + siderelations = [] + self.render_entity_title(entity) + self.render_entity_metadata(entity) + # entity's attributes and relations, excluding meta data + # if the entity isn't meta itself + self.w(u'
') + self.w(u'
') + self.render_entity_attributes(entity, siderelations) + self.w(u'
') + self.content_navigation_components('navcontenttop') + if self.main_related_section: + self.render_entity_relations(entity, siderelations) + self.w(u'
') + # side boxes + self.w(u'
') + self.render_side_related(entity, siderelations) + self.w(u'
') + self.w(u'
') + self.content_navigation_components('navcontentbottom') + + ... + +``cell_call`` is executed for each entity of a result set and apply ``render_entity``. + +The methods you want to modify while customizing a ``PrimaryView`` are: + +*render_entity_title(self, entity)* + Renders the entity title based on the assumption that the method + ``def content_title(self)`` is implemented for the given entity type. + +*render_entity_metadata(self, entity)* + Renders the entity metadata based on the assumption that the method + ``def summary(self)`` is implemented for the given entity type. + +*render_entity_attributes(self, entity, siderelations)* + Renders all the attribute of an entity with the exception of attribute + of type `Password` and `Bytes`. + +*content_navigation_components(self, context)* + This method is applicable only for entity type implementing the interface + `IPrevNext`. This interface is for entities which can be linked to a previous + and/or next entity. This methods will render the navigation links between + entities of this type, either at the top or at the bottom of the page + given the context (navcontent{top|bottom}). + +*render_entity_relations(self, entity, siderelations)* + Renders all the relations of the entity in the main section of the page. + +*render_side_related(self, entity, siderelations)* + Renders all the relations of the entity in a side box. This is equivalent + to *render_entity_relations* in addition to render the relations + in a box. + +Also, please note that by setting the following attributes in you class, +you can already customize some of the rendering: + +*show_attr_label* + Renders the attribute label next to the attribute value if set to True. + Otherwise, does only display the attribute value. + +*show_rel_label* + Renders the relation label next to the relation value if set to True. + Otherwise, does only display the relation value. + +*skip_none* + Does not render an attribute value that is None if set to True. + +*skip_attrs* + Given a list of attributes name, does not render the value of the attributes listed. + +*skip_rels* + Given a list of relations name, does not render the relations listed. + +*main_related_section* + Renders the relations of the entity if set to True. + +A good practice is for you to identify the content of your entity type for which +the default rendering does not answer your need so that you can focus on the specific +method (from the list above) that needs to be modified. We do not recommand you to +overwrite ``render_entity`` as you might potentially loose the benefits of the side +boxes handling. Example of a view customization ------------------------------- +[FIXME] XXX Example needs to be rewritten as it shows how to modify cell_call which +contredicts our advise of not modifying it. + We'll show you now an example of a ``primary`` view and how to customize it. If you want to change the way a ``BlogEntry`` is displayed, just override diff -r f94b41709ce6 -r b056a49c16dc doc/book/en/B1022-views-stdlib.en.txt --- a/doc/book/en/B1022-views-stdlib.en.txt Fri Apr 24 16:48:38 2009 +0200 +++ b/doc/book/en/B1022-views-stdlib.en.txt Fri Apr 24 17:04:14 2009 +0200 @@ -2,6 +2,10 @@ Predefined views in the library ``````````````````````````````` + +`CubicWeb` provides a lot of standard views. You can find them in +``cubicweb/web/views/``. + A certain number of views are used to build the web interface, which apply to one or more entities. Their identifier is what distinguish them from each others and the main ones are: @@ -56,7 +60,8 @@ This view displays usually a side box of some related entities in a primary view. -Start view: + +Start view (e.g. views that don't apply to a result set): *index* This view defines the home page of your application. It does not require diff -r f94b41709ce6 -r b056a49c16dc doc/book/en/B1090-internationalization.en.txt --- a/doc/book/en/B1090-internationalization.en.txt Fri Apr 24 16:48:38 2009 +0200 +++ b/doc/book/en/B1090-internationalization.en.txt Fri Apr 24 17:04:14 2009 +0200 @@ -1,9 +1,9 @@ .. -*- coding: utf-8 -*- -.. _internationalization: +.. _internationalisation: -Internationalization +Internationalisation ==================== Cubicweb fully supports the internalization of it's content and interface. diff -r f94b41709ce6 -r b056a49c16dc doc/book/en/C000-administration.en.txt --- a/doc/book/en/C000-administration.en.txt Fri Apr 24 16:48:38 2009 +0200 +++ b/doc/book/en/C000-administration.en.txt Fri Apr 24 17:04:14 2009 +0200 @@ -13,7 +13,8 @@ :maxdepth: 1 C010-setup.en.txt - C020-site-config.en.txt - C030-instance-config.en.txt - C040-rql.en.txt + C020-create-instance.en.txt + C030-site-config.en.txt + C040-instance-config.en.txt + C050-rql.en.txt diff -r f94b41709ce6 -r b056a49c16dc doc/book/en/C010-setup.en.txt --- a/doc/book/en/C010-setup.en.txt Fri Apr 24 16:48:38 2009 +0200 +++ b/doc/book/en/C010-setup.en.txt Fri Apr 24 17:04:14 2009 +0200 @@ -6,7 +6,202 @@ Installation and set-up of a `CubicWeb` environment =================================================== -.. include:: C011-installation.en.txt -.. include:: C012-create-instance.en.txt -.. include:: C013-cubicweb-ctl.en.txt +Installation of `Cubicweb` and its dependencies +----------------------------------------------- + +`CubicWeb` is packaged for Debian and Ubuntu, but can be installed from source +using a tarball or the Mercurial version control system. + +.. _DebianInstallation: + +Debian and Ubuntu packages +``````````````````````````` + +Depending on the distribution you are using, add the appropriate line to your list +of sources (for example by editing ``/etc/apt/sources.list``). + +For Debian Lenny:: + + deb http://ftp.logilab.org/dists/ lenny/ + +For Debian Sid:: + + deb http://ftp.logilab.org/dists/ sid/ + +For Ubuntu Hardy:: + + deb http://ftp.logilab.org/dists/ hardy/ + + +You can now install the required packages with the following command:: + + apt-get update + apt-get install cubicweb cubicweb-dev + +`cubicweb` installs the framework itself, allowing you to create +new applications. + +`cubicweb-dev` installs the development environment allowing you to +develop new cubes. + +There is also a wide variety of cubes listed on http://www.cubicweb.org/Project available as debian packages and tarball. + + +Install from source +``````````````````` + +You can download the archive containing the sources from our `ftp site`_ at:: + + http://ftp.logilab.org/pub/cubicweb/ + +.. _`ftp site`: http://ftp.logilab.org/pub/cubicweb/ + +or keep up to date with on-going development by using Mercurial and its forest +extension:: + + hg fclone http://www.logilab.org/hg/forests/cubicweb + +See :ref:`MercurialPresentation` for more details about Mercurial. + +Postgres installation +````````````````````` + +Please refer to the `Postgresql project online documentation`_. + +.. _`Postgresql project online documentation`: http://www.postgresql.org/ + +You need to install the three following packages: `postgres-8.3`, +`postgres-contrib-8.3` and `postgresql-plpython-8.3`. + + +Then you can install: + +* `pyro` if you wish the repository to be accessible through Pyro + or if the client and the server are not running on the same machine + (in which case the packages will have to be installed on both + machines) + +* `python-ldap` if you plan to use a LDAP source on the server + +.. _ConfigurationEnv: + +Environment configuration +------------------------- + +If you installed `CubicWeb` by cloning the Mercurial forest, then you +will need to update the environment variable PYTHONPATH by adding +the path to the forest ``cubicweb``: + +Add the following lines to either `.bashrc` or `.bash_profile` to configure +your development environment :: + + export PYTHONPATH=/full/path/to/cubicweb-forest + +If you installed the debian packages, no configuration is required. +Your new cubes will be placed in `/usr/share/cubicweb/cubes` and +your applications will be placed in `/etc/cubicweb.d`. + +To use others directories then you will have to configure the +following environment variables as follows:: + export CW_CUBES_PATH=~/lib/cubes + export CW_REGISTRY=~/etc/cubicweb.d/ + export CW_INSTANCE_DATA=$CW_REGISTRY + export CW_RUNTIME=/tmp + +.. note:: + The values given above are our suggestions but of course + can be different. + + +Databases configuration +----------------------- + + + +.. _ConfigurationPostgres: + +Postgres configuration +`````````````````````` + +.. note:: + If you already have an existing cluster and postgres server + running, you do not need to execute the initilization step + of your Postgres database. + +* First, initialize the database Postgres with the command ``initdb``. + :: + + $ initdb -D /path/to/pgsql + + Once initialized, start the database server Postgres + with the command:: + + $ postgres -D /path/to/psql + + If you cannot execute this command due to permission issues, please + make sure that your username has write access on the database. + :: + + $ chown username /path/to/pgsql + +* The database authentication can be either set to `ident sameuser` + or `md5`. + If set to `md5`, make sure to use an existing user + of your database. + If set to `ident sameuser`, make sure that your + client's operating system user name has a matching user in + the database. If not, please do as follow to create a user:: + + $ su + $ su - postgres + $ createuser -s -P username + + The option `-P` (for password prompt), will encrypt the password with + the method set in the configuration file ``pg_hba.conf``. + If you do not use this option `-P`, then the default value will be null + and you will need to set it with:: + + $ su postgres -c "echo ALTER USER username WITH PASSWORD 'userpasswd' | psql" + + This login/password will be requested when you will create an + instance with `cubicweb-ctl create` to initialize the database of + your application. + +.. note:: + The authentication method can be configured in ``pg_hba.conf``. + + +.. FIXME Are these steps really necessary? It seemed to work without. + +* Installation of plain-text index extension :: + + cat /usr/share/postgresql/8.3/contrib/tsearch2.sql | psql -U username template1 + +* Installation of plpythonu language by default :: + + createlang -U pgadmin plpythonu template1 + +MySql configuration +``````````````````` +Yout must add the following lines in /etc/mysql/my.cnf file:: + + transaction-isolation = READ-COMMITTED + default-storage-engine=INNODB + default-character-set=utf8 + max_allowed_packet = 128M + +Pyro configuration +------------------ + +If you use Pyro, it is required to have a name server Pyro running on your +network (by default it is detected by a broadcast request). + +To do so, you need to : + +* launch the server manually before starting cubicweb as a server with + `pyro-nsd start` + +* edit the file ``/etc/default/pyro-nsd`` so that the name server pyro + will be launched automatically when the machine fire up + diff -r f94b41709ce6 -r b056a49c16dc doc/book/en/C011-installation.en.txt --- a/doc/book/en/C011-installation.en.txt Fri Apr 24 16:48:38 2009 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,201 +0,0 @@ -.. -*- coding: utf-8 -*- - -.. _CubicWebInstallation: - -Installation -============ - -Installation of `Cubicweb` and its dependencies ------------------------------------------------ - -`CubicWeb` is packaged for Debian and Ubuntu, but can be installed from source -using a tarball or the Mercurial version control system. - -Debian and Ubuntu packages -``````````````````````````` -Depending on the distribution you are using, add the appropriate line to your list -of sources (for example by editing ``/etc/apt/sources.list``). - -For Debian Lenny:: - - deb http://ftp.logilab.org/dists/ lenny/ - -For Debian Sid:: - - deb http://ftp.logilab.org/dists/ sid/ - -For Ubuntu Hardy:: - - deb http://ftp.logilab.org/dists/ hardy/ - - -You can now install the required packages with the following command:: - - apt-get update - apt-get install cubicweb - apt-get install cubicweb-dev - -`cubicweb` installs the framework itself, allowing you to create -new applications. - -`cubicweb-dev` installs the development environment allowing you to -develop new cubes. - -There is also a wide variety of cubes listed on http://www.cubicweb.org/Project available as debian packages and tarball. - - -Install from source -``````````````````` - -You can download the archive containing the sources from our `ftp site`_ at:: - - http://ftp.logilab.org/pub/cubicweb/ - -.. _`ftp site`: http://ftp.logilab.org/pub/cubicweb/ - -or keep up to date with on-going development by using Mercurial and its forest -extension:: - - hg fclone http://www.logilab.org/hg/forests/cubicweb - -See :ref:`MercurialPresentation` for more details about Mercurial. - -Postgres installation -````````````````````` - -Please refer to the `Postgresql project online documentation`_. - -.. _`Postgresql project online documentation`: http://www.postgresql.org/ - -You need to install the three following packages: `postgres-8.3`, -`postgres-contrib-8.3` and `postgresql-plpython-8.3`. - - -Then you can install: - -* `pyro` if you wish the repository to be accessible through Pyro - or if the client and the server are not running on the same machine - (in which case the packages will have to be installed on both - machines) - -* `python-ldap` if you plan to use a LDAP source on the server - -.. _ConfigurationEnv: - -Environment configuration -------------------------- - -If you installed `CubicWeb` by cloning the Mercurial forest, then you -will need to update the environment variable PYTHONPATH by adding -the path to the forest ``cubicweb``: - -Add the following lines to either `.bashrc` or `.bash_profile` to configure -your development environment :: - - export PYTHONPATH=/full/path/to/cubicweb-forest - -If you installed the debian packages, no configuration is required. -Your new cubes will be placed in `/usr/share/cubicweb/cubes` and -your applications will be placed in `/etc/cubicweb.d`. - -To use others directories then you will have to configure the -following environment variables as follows:: - - export CW_CUBES_PATH=~/lib/cubes - export CW_REGISTRY=~/etc/cubicweb.d/ - export CW_INSTANCE_DATA=$CW_REGISTRY - export CW_RUNTIME=/tmp - -.. note:: - The values given above are our suggestions but of course - can be different. - -.. _ConfigurationPostgres: - -Postgres configuration ----------------------- - -.. note:: - If you already have an existing cluster and postgres server - running, you do not require to execute the initilization step - of your Postgres database. - -* First you have to initialize the database Postgres with the command ``initdb``. - :: - - $ initdb -D /path/to/pgsql - - Once initialized, you can launch the database server Postgres - with the command:: - - $ postgres -D /path/to/psql - - If you cannot execute this command due to permission issues, please - make sure that your username has write access on the database. - :: - - $ chown username /path/to/pgsql - -* The database authentication can be either set to `ident sameuser` - or `md5`. - If set to `md5`, make sure to use an existing user - of your database. - If set to `ident sameuser`, make sure that your - client's operating system user name has a matching user in - the database. If not, please do as follow to create a user:: - - $ su - $ su - postgres - $ createuser -s username - - If created with the options -P (for password prompt, - ``createuser -s -P username``), the password will be encrypted with - the method set in the configuration file ``pg_hba.conf``. - If you do not use this option, then the default value will be null - and this require to set the password in the database itself. - To do so: :: - - $ su - $ su - postgres - $ psql - - And then execute de following query:: - - ALTER USER username WITH PASSWORD `password` - - This login/password will be requested when you will create an - instance with `cubicweb-ctl create` to initialize the database of - your application. - -.. note:: - The authentication method can be configured in ``pg_hba.conf``. - - -.. FIXME Are these steps really necessary? It seemed to work without. - -* Installation of plain-text index extension :: - - cat /usr/share/postgresql/8.3/contrib/tsearch2.sql | psql -U username template1 - -* Installation of plpythonu language by default :: - - createlang -U pgadmin plpythonu template1 - - -Pyro configuration ------------------- - -If you use Pyro, it is required to have a name server Pyro running on your -network (by default it is identified by a broadcast request). - -To do so, you need to : - -* launch the server manually before starting cubicweb with `pyro-ns` - -* launch the server manually before starting cubicweb as a server with - `pyro-nsd start` - -* edit the file ``/etc/default/pyro-nsd`` so that the name server pyro - will be launched automatically when the machine fire up - - diff -r f94b41709ce6 -r b056a49c16dc doc/book/en/C012-create-instance.en.txt --- a/doc/book/en/C012-create-instance.en.txt Fri Apr 24 16:48:38 2009 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,132 +0,0 @@ -.. -*- coding: utf-8 -*- - -Creation of your first instance -=============================== - -What is an instance? --------------------- - -A `CubicWeb` instance is a directory in ``~/etc/cubicweb.d`` -which enables us to run a web application. An instance is based on -one or more cubes. - -An instance is a container that refers to cubes and configuration -parameters for your web application. - -We recommand not to define schema, entities or views in the instance -file system itself but in the cube, in order to maintain re-usability of -entities and their views. We strongly recommand to develop cubes which -could be used in other instances (modular approach). - - -What is a cube? ---------------- - -A cube defines entities, their views, their schemas and workflows -in an independant directory located in ``/path/to/forest/cubicweb/cubes/`` -for a Mercurial installation or in ``/usr/share/cubicweb/cubes`` for -a debian package installation. - -When an instance is created, you list one or more cubes that your instance -will use. Using a cube means having the entities defined in your cube's schema -available in your instance as well as their views and workflows. - -.. note:: - The commands used below are more detailled in the section dedicated to - :ref:`cubicweb-ctl`. - - -Create a cube -------------- - -Let's start by creating the cube environment in which we will develop :: - - cd ~/hg - - cubicweb-ctl newcube mycube - - # answer questions - hg init moncube - cd mycube - hg add . - hg ci - -If all went well, you should see the cube you just create in the list -returned by `cubicweb-ctl list` in the section *Available components*, -and if it is not the case please refer to :ref:`ConfigurationEnv`. - -To use a cube, you have to list it in the variable ``__use__`` -of the file ``__pkginfo__.py`` of the instance. -This variable is used for the instance packaging (dependencies -handled by system utility tools such as APT) and the usable cubes -at the time the base is created (import_erschema('MyCube') will -not properly work otherwise). - -.. note:: - Please note that if you do not wish to use default directory - for your cubes library, then you want 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 cube_name`` - -Instance creation ------------------ - -Now that we created our cube, we can create an instance to view our -application in a web browser. To do so we will use a `all-in-on` -configuration to simplify things :: - - cubicweb-ctl create -c all-in-one mycube myinstance - -.. note:: - Please note that we created a new cube for a demo purpose but - you could have use an existing cube available in our standard library - such as blog or person for example. - -A serie of questions will be prompted to you, the default answer is usually -sufficient. You can anyway modify the configuration later on by editing -configuration files. When a user/psswd is requested to access the database -please use the login you create at the time you configured the database -(:ref:`ConfigurationPostgres`). - -It is important to distinguish here the user used to access the database and -the user used to login to the cubicweb application. When a `CubicWeb` application -starts, it uses the login/psswd for the database to get the schema and handle -low level transaction. But, when ``cubicweb-ctl create`` asks for -a manager login/psswd of `CubicWeb`, it refers to an application user you will -use during the development to administrate your web application. It will be -possible, later on, to create others users for your final web application. - -When this command is completed, the definition of your instance is -located in *~/etc/cubicweb.d/myinstance/*. To launch it, you just type :: - - cubicweb-ctl start -D myinstance - -The option `-D` specify the *debug mode* : the instance is not running in -server mode and does not disconnect from the termnial, which simplifies debugging -in case the instance is not properly launched. You can see how it looks by -visiting the URL `http://localhost:8080` (the port number depends of your -configuration). To login, please use the cubicweb administrator login/psswd you -defined when you created the instance. - -To shutdown the instance, Crtl-C in the terminal window is enough. -If you did not use the option `-D`, then type :: - - cubicweb-ctl stop myinstance - -This is it! All is settled down to start developping your data model... - - -Usage of `cubicweb-liveserver` -`````````````````````````````` - -To quickly test a new cube, you can also use the script `cubicweb-liveserver` -which allows to create an application in memory (use of SQLite database by -default) and make it accessible through a web server :: - - cubicweb-ctl live-server mycube - -or by using an existing database (SQLite or Postgres):: - - cubicweb-ctl live-server -s myfile_sources mycube - diff -r f94b41709ce6 -r b056a49c16dc doc/book/en/C013-cubicweb-ctl.en.txt --- a/doc/book/en/C013-cubicweb-ctl.en.txt Fri Apr 24 16:48:38 2009 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,140 +0,0 @@ -.. -*- coding: utf-8 -*- - -.. _cubicweb-ctl: - -``cubicweb-ctl`` tool -===================== - -`cubicweb-ctl` is the swiss knife to manage `CubicWeb` instances. -The general syntax is :: - - cubicweb-ctl [options command] - -To view available commands :: - - cubicweb-ctl - cubicweb-ctl --help - -Please note that the commands available depends on the `CubicWeb` packages -and cubes that have been installed. - -To view the help menu on specific command :: - - cubicweb-ctl --help - -Command to create a cube ------------------------- - -* ``newcube``, create a new cube on the file system based on the name - given in the parameters. This command create a cube from an application - skeleton that includes default files required for debian packaging. - - -Command to create an instance ------------------------------ -* ``create``, creates the files for the instance configuration -* ``db-create``, creates the system database of an instance (tables and - extensions only) -* ``db-init``, initializes the system database of an instance - (schema, groups, users, workflows...) - -By default, those three commandes are encapsulated in ``create`` so -that they can be executed consecutively. - -Command to create an instance for Google AppEngine datastore source -------------------------------------------------------------------- -* ``newgapp``, creates the configuration files for an instance - -This command needs to be followed by the commands responsible for -the database initialization. As those are specific to the `datastore`, -specific Google AppEgine database, they are not available for now -in cubicweb-ctl, but they are available in the instance created. - -For more details, please see :ref:`gaecontents` . - -Commands to launch instance ---------------------------- -* ``start``, starts one or more or all instances -* ``stop``, stops one or more or all instances -* ``restart``, restarts one or more or all instances -* ``status``, returns the status of the instance - -Commands to maintain instances ------------------------------- -* ``upgrade``, launches the existing instances migration when a new version - of `CubicWeb` or the cubes installed is available -* ``shell``, opens a migration shell for manual maintenance of the instance - (see :ref:`cubicweb-ctl-shell` for more details) -* ``db-dump``, creates a dump of the system database -* ``db-restore``, restores a dump of the system database -* ``db-check``, checks data integrity of an instance. If the automatic correction - is activated, it is recommanded to create a dump before this operation. -* ``schema-sync``, synchronizes the persistent schema of an instance with - the application schema. It is recommanded to create a dump before this operation. - -Commands to maintain i18n catalogs ----------------------------------- -* ``i18nlibupdate``, regenerates messages catalogs of the `CubicWeb` library -* ``i18nupdate``, regenerates the messages catalogs of a cube -* ``i18ncompile``, recompiles the messages catalogs of an instance. - This is automatically done while upgrading. - -Cf :ref:`Internationalisation`. - -Other commands --------------- -* ``list``, provides a list of the available configuration, cubes - and instances. -* ``delete``, deletes an instance (configuration files and database) - - -.. _cubicweb-ctl-shell: - -``cubicweb-ctl shell`` addon ----------------------------- - -This migration shell provides an interactive interface to all -the migrations functions described in the chapter :ref:`migration`. - -Usage -````` -:: - - ``cubicweb-ctl shell myapp`` - -Examples --------- - -Create an instance from an existing cube -```````````````````````````````````````` - -To create an instance from an existing cube, execute the following -command :: - - cubicweb-ctl create - -This command will create the configuration files of an instance in -``~/etc/cubicweb.d/``. -The tool ``cubicweb-ctl`` allows you to execute the command ``db-create`` -and ``db-init`` when you run ``create`` so that you can complete an -instance creation in a single command. - -If you decide not to execut those commands while ``cubicweb-ctl create``, -then you will have to execute them seperately(``cubicweb-ctl db-create``, -``cubicweb-ctl db-init`` ) otherwise your installation will not be complete -and you will not be able to launch your instance. - - -Creation of an instance from a new cube -``````````````````````````````````````` - -Create first your new cube cube :: - - cubicweb-ctl newcube - -This will create a new cube in ``/path/to/forest/cubicweb/cubes/`` -for a Mercurial forest installation, or in ``/usr/share/cubicweb/cubes`` -for a debian packages installation, and then create an instance as -explained just above. - - diff -r f94b41709ce6 -r b056a49c16dc doc/book/en/C020-create-instance.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/C020-create-instance.en.txt Fri Apr 24 17:04:14 2009 +0200 @@ -0,0 +1,132 @@ +.. -*- coding: utf-8 -*- + +Creation of your first instance +=============================== + +What is an instance? +-------------------- + +A `CubicWeb` instance is a directory in ``~/etc/cubicweb.d`` +which enables us to run a web application. An instance is based on +a cube. + +An instance is a container that refers to cubes and configuration +parameters for your web application. + +We recommand not to define schema, entities or views in the instance +file system itself but in the cube, in order to maintain re-usability of +entities and their views. We strongly recommand to develop cubes which +could be used in other instances (modular approach). + + +What is a cube? +--------------- + +A cube defines entities, their views, their schemas and workflows +in an independant directory located in ``/path/to/forest/cubicweb/cubes/`` +for a Mercurial installation or in ``/usr/share/cubicweb/cubes`` for +a debian package installation. + +When an instance is created, you list one or more cubes that your instance +will use. Using a cube means having the entities defined in your cube's schema +available in your instance as well as their views and workflows. + +.. note:: + The commands used below are more detailled in the section dedicated to + :ref:`cubicweb-ctl`. + + +Create a cube +------------- + +Let's start by creating the cube environment in which we will develop :: + + cd ~/hg + + cubicweb-ctl newcube mycube + + # answer questions + hg init moncube + cd mycube + hg add . + hg ci + +If all went well, you should see the cube you just create in the list +returned by `cubicweb-ctl list` in the section *Available components*, +and if it is not the case please refer to :ref:`ConfigurationEnv`. + +To use a cube, you have to list it in the variable ``__use__`` +of the file ``__pkginfo__.py`` of the instance. +This variable is used for the instance packaging (dependencies +handled by system utility tools such as APT) and the usable cubes +at the time the base is created (import_erschema('MyCube') will +not properly work otherwise). + +.. note:: + Please note that if you do not wish to use default directory + for your cubes library, then you want 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 cube_name`` + +Instance creation +----------------- + +Now that we created our cube, we can create an instance to view our +application in a web browser. To do so we will use a `all-in-on` +configuration to simplify things :: + + cubicweb-ctl create -c all-in-one mycube myinstance + +.. note:: + Please note that we created a new cube for a demo purpose but + you could have use an existing cube available in our standard library + such as blog or person for example. + +A serie of questions will be prompted to you, the default answer is usually +sufficient. You can anyway modify the configuration later on by editing +configuration files. When a user/psswd is requested to access the database +please use the login you create at the time you configured the database +(:ref:`ConfigurationPostgres`). + +It is important to distinguish here the user used to access the database and +the user used to login to the cubicweb application. When a `CubicWeb` application +starts, it uses the login/psswd for the database to get the schema and handle +low level transaction. But, when ``cubicweb-ctl create`` asks for +a manager login/psswd of `CubicWeb`, it refers to an application user you will +use during the development to administrate your web application. It will be +possible, later on, to create others users for your final web application. + +When this command is completed, the definition of your instance is +located in *~/etc/cubicweb.d/myinstance/*. To launch it, you just type :: + + cubicweb-ctl start -D myinstance + +The option `-D` specify the *debug mode* : the instance is not running in +server mode and does not disconnect from the termnial, which simplifies debugging +in case the instance is not properly launched. You can see how it looks by +visiting the URL `http://localhost:8080` (the port number depends of your +configuration). To login, please use the cubicweb administrator login/psswd you +defined when you created the instance. + +To shutdown the instance, Crtl-C in the terminal window is enough. +If you did not use the option `-D`, then type :: + + cubicweb-ctl stop myinstance + +This is it! All is settled down to start developping your data model... + + +Usage of `cubicweb-liveserver` +`````````````````````````````` + +To quickly test a new cube, you can also use the script `cubicweb-liveserver` +which allows to create an application in memory (use of SQLite database by +default) and make it accessible through a web server :: + + cubicweb-ctl live-server mycube + +or by using an existing database (SQLite or Postgres):: + + cubicweb-ctl live-server -s myfile_sources mycube + diff -r f94b41709ce6 -r b056a49c16dc doc/book/en/C020-site-config.en.txt --- a/doc/book/en/C020-site-config.en.txt Fri Apr 24 16:48:38 2009 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,94 +0,0 @@ -.. -*- coding: utf-8 -*- - -User interface for web site configuration -========================================= - -.. image:: images/lax-book.03-site-config-panel.en.png - -This panel allows you to configure the appearance of your application site. -Six menus are available and we will go through each of them to explain how -to use them. - -Navigation -~~~~~~~~~~ -This menu provides you a way to adjust some navigation options depending on -your needs, such as the number of entities to display by page of results. -Follows the detailled list of available options : - -* navigation.combobox-limit : maximum number of entities to display in related - combo box (sample format: 23) -* navigation.page-size : maximum number of objects displayed by page of results - (sample format: 23) -* navigation.related-limit : maximum number of related entities to display in - the primary view (sample format: 23) -* navigation.short-line-size : maximum number of characters in short description - (sample format: 23) - -UI -~~ -This menu provides you a way to customize the user interface settings such as -date format or encoding in the produced html. -Follows the detailled list of available options : - -* ui.date-format : how to format date in the ui ("man strftime" for format description) -* ui.datetime-format : how to format date and time in the ui ("man strftime" for format - description) -* ui.default-text-format : default text format for rich text fields. -* ui.encoding : user interface encoding -* ui.fckeditor :should html fields being edited using fckeditor (a HTML WYSIWYG editor). - You should also select text/html as default text format to actually get fckeditor. -* ui.float-format : how to format float numbers in the ui -* ui.language : language of the user interface -* ui.main-template : id of main template used to render pages -* ui.site-title : site title, which is displayed right next to the logo in the header -* ui.time-format : how to format time in the ui ("man strftime" for format description) - - -Actions -~~~~~~~ -This menu provides a way to configure the context in which you expect the actions -to be displayed to the user and if you want the action to be visible or not. -You must have notice that when you view a list of entities, an action box is -available on the left column which display some actions as well as a drop-down -menu for more actions. - -The context available are : - -* mainactions : actions listed in the left box -* moreactions : actions listed in the `more` menu of the left box -* addrelated : add actions listed in the left box -* useractions : actions listed in the first section of drop-down menu - accessible from the right corner user login link -* siteactions : actions listed in the second section of drop-down menu - accessible from the right corner user login link -* hidden : select this to hide the specific action - -Boxes -~~~~~ -The application has already a pre-defined set of boxes you can use right away. -This configuration section allows you to place those boxes where you want in the -application interface to customize it. - -The available boxes are : - -* actions box : box listing the applicable actions on the displayed data - -* boxes_blog_archives_box : box listing the blog archives - -* possible views box : box listing the possible views for the displayed data - -* rss box : RSS icon to get displayed data as a RSS thread - -* search box : search box - -* startup views box : box listing the configuration options available for - the application site, such as `Preferences` and `Site Configuration` - -Components -~~~~~~~~~~ -[WRITE ME] - -Contextual components -~~~~~~~~~~~~~~~~~~~~~ -[WRITE ME] - diff -r f94b41709ce6 -r b056a49c16dc doc/book/en/C030-instance-config.en.txt --- a/doc/book/en/C030-instance-config.en.txt Fri Apr 24 16:48:38 2009 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,163 +0,0 @@ -.. -*- coding: utf-8 -*- - - -Configure an instance -===================== - -While creating an instance, a configuration file is generated in:: - - $ (CW_REGISTRY) / / .conf - -For example:: - - /etc/cubicweb.d/JPL/all-in-one.conf - -It is a simple text file format INI. In the following description, -each option name is prefixed with its own section and followed by its -default value if necessary, e.g. "`
.