# HG changeset patch # User Sandrine Ribeau # Date 1240513091 25200 # Node ID 023b123ab76b8854528798adc0f53fd18bdb8d3d # Parent 6520efef1824338abc59d1ec75cde344d64b2b5b [doc] Splits initial set-up section in two sections => re-order part III. diff -r 6520efef1824 -r 023b123ab76b doc/book/en/C000-administration.en.txt --- a/doc/book/en/C000-administration.en.txt Thu Apr 23 11:55:29 2009 -0700 +++ b/doc/book/en/C000-administration.en.txt Thu Apr 23 11:58:11 2009 -0700 @@ -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 6520efef1824 -r 023b123ab76b doc/book/en/C012-create-instance.en.txt --- a/doc/book/en/C012-create-instance.en.txt Thu Apr 23 11:55:29 2009 -0700 +++ /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 -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 6520efef1824 -r 023b123ab76b 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 23 11:58:11 2009 -0700 @@ -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 6520efef1824 -r 023b123ab76b doc/book/en/C020-site-config.en.txt --- a/doc/book/en/C020-site-config.en.txt Thu Apr 23 11:55:29 2009 -0700 +++ /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 6520efef1824 -r 023b123ab76b doc/book/en/C030-instance-config.en.txt --- a/doc/book/en/C030-instance-config.en.txt Thu Apr 23 11:55:29 2009 -0700 +++ /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. "`
.