# HG changeset patch # User Nicolas Chauvat # Date 1241087252 -7200 # Node ID 8f400d5f6742eac48ab6611d00d186e5bf28a4c7 # Parent 8602116daef304b45087c565ee4c0e33cb4b2dbf# Parent 3960f764bbf6a006a6727c0c34a0b7420aca402f merge diff -r 8602116daef3 -r 8f400d5f6742 doc/book/en/A020-tutorial.en.txt --- a/doc/book/en/A020-tutorial.en.txt Wed Apr 22 09:46:13 2009 -0500 +++ b/doc/book/en/A020-tutorial.en.txt Thu Apr 30 12:27:32 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 8602116daef3 -r 8f400d5f6742 doc/book/en/A02a-create-cube.en.txt --- a/doc/book/en/A02a-create-cube.en.txt Wed Apr 22 09:46:13 2009 -0500 +++ b/doc/book/en/A02a-create-cube.en.txt Thu Apr 30 12:27:32 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 8602116daef3 -r 8f400d5f6742 doc/book/en/A02b-components.en.txt --- a/doc/book/en/A02b-components.en.txt Wed Apr 22 09:46:13 2009 -0500 +++ b/doc/book/en/A02b-components.en.txt Thu Apr 30 12:27:32 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 8602116daef3 -r 8f400d5f6742 doc/book/en/B0012-schema-definition.en.txt --- a/doc/book/en/B0012-schema-definition.en.txt Wed Apr 22 09:46:13 2009 -0500 +++ b/doc/book/en/B0012-schema-definition.en.txt Thu Apr 30 12:27:32 2009 +0200 @@ -23,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`) @@ -43,7 +65,7 @@ - `owned_by` (`EUser`) (to whom the entity belongs; by default the creator but not necessary, and it could have multiple owners) - - `is` (`EEType`) + - `is` (`EEType`) (of which type the entity is) * relations can be defined by using `ObjectRelation` or `SubjectRelation`. @@ -64,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 @@ -97,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 8602116daef3 -r 8f400d5f6742 doc/book/en/B0040-migration.en.txt --- a/doc/book/en/B0040-migration.en.txt Wed Apr 22 09:46:13 2009 -0500 +++ b/doc/book/en/B0040-migration.en.txt Thu Apr 30 12:27:32 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 8602116daef3 -r 8f400d5f6742 doc/book/en/B1020-define-views.en.txt --- a/doc/book/en/B1020-define-views.en.txt Wed Apr 22 09:46:13 2009 -0500 +++ b/doc/book/en/B1020-define-views.en.txt Thu Apr 30 12:27:32 2009 +0200 @@ -220,12 +220,19 @@ 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. + Renders all the relations of the entity in the main section of the page. *render_side_related(self, entity, siderelations)* - Renders side related relations. + 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: diff -r 8602116daef3 -r 8f400d5f6742 doc/book/en/B1090-internationalization.en.txt --- a/doc/book/en/B1090-internationalization.en.txt Wed Apr 22 09:46:13 2009 -0500 +++ b/doc/book/en/B1090-internationalization.en.txt Thu Apr 30 12:27:32 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 8602116daef3 -r 8f400d5f6742 doc/book/en/C000-administration.en.txt --- a/doc/book/en/C000-administration.en.txt Wed Apr 22 09:46:13 2009 -0500 +++ b/doc/book/en/C000-administration.en.txt Thu Apr 30 12:27:32 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 8602116daef3 -r 8f400d5f6742 doc/book/en/C010-setup.en.txt --- a/doc/book/en/C010-setup.en.txt Wed Apr 22 09:46:13 2009 -0500 +++ b/doc/book/en/C010-setup.en.txt Thu Apr 30 12:27:32 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 8602116daef3 -r 8f400d5f6742 doc/book/en/C011-installation.en.txt --- a/doc/book/en/C011-installation.en.txt Wed Apr 22 09:46:13 2009 -0500 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,209 +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 - -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 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 8602116daef3 -r 8f400d5f6742 doc/book/en/C012-create-instance.en.txt --- a/doc/book/en/C012-create-instance.en.txt Wed Apr 22 09:46:13 2009 -0500 +++ /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 8602116daef3 -r 8f400d5f6742 doc/book/en/C013-cubicweb-ctl.en.txt --- a/doc/book/en/C013-cubicweb-ctl.en.txt Wed Apr 22 09:46:13 2009 -0500 +++ /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 8602116daef3 -r 8f400d5f6742 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 Thu Apr 30 12:27:32 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 8602116daef3 -r 8f400d5f6742 doc/book/en/C020-site-config.en.txt --- a/doc/book/en/C020-site-config.en.txt Wed Apr 22 09:46:13 2009 -0500 +++ /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 8602116daef3 -r 8f400d5f6742 doc/book/en/C030-instance-config.en.txt --- a/doc/book/en/C030-instance-config.en.txt Wed Apr 22 09:46:13 2009 -0500 +++ /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. "`
.