# HG changeset patch # User Alexandre Fayolle # Date 1295275526 -3600 # Node ID 7562418985efbf10c3f2abdbf145bf6ec8676f41 # Parent fb3633142d8fd340efe524803cc350f79257c886 tutorial proof reading diff -r fb3633142d8f -r 7562418985ef doc/book/en/tutorials/base/blog-in-five-minutes.rst --- a/doc/book/en/tutorials/base/blog-in-five-minutes.rst Mon Jan 17 13:36:18 2011 +0100 +++ b/doc/book/en/tutorials/base/blog-in-five-minutes.rst Mon Jan 17 15:45:26 2011 +0100 @@ -10,7 +10,7 @@ cubicweb, cubicweb-dev, cubicweb-blog -For Windows or Mac OS X users, you must install |cubicweb| from source (see +Windows or Mac OS X users must install |cubicweb| from source (see :ref:`SourceInstallation` and :ref:`WindowsInstallation`). Then create and initialize your instance:: @@ -20,8 +20,8 @@ You'll be asked a few questions, and you can keep the default answer for most of them. The one question you'll have to think about is the database you'll want to use for that instance. For a quick test, if you don't have `postgresql` installed -and configured (see :ref:`PostgresqlConfiguration`), it's higly recommended to -choose `sqlite` when asked for which database driber to use, since it has a much +and configured (see :ref:`PostgresqlConfiguration`), it's highly recommended to +choose `sqlite` when asked for which database driver to use, since it has a much simple setup (no database server needed). One the process is completed (including database initialisation), you can start @@ -29,23 +29,25 @@ cubicweb-ctl start -D myblog -The `-D` option activate the debugging mode, removing it will launch the instance -as a daemon in the background. +The `-D` option activates the debugging mode. Removing it will launch the instance +as a daemon in the background, and ``cubicweb-ctl stop myblog`` will stop +it in that case. -About file-system permissions +About file system permissions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Unless you installed from sources, above commands assumes that you have root -access to the :file:`/etc/` path. In order to initialize your instance as a -regulary user, within your home directory, you can use the :envvar:`CW_MODE` +Unless you installed from sources, the above commands assume that you have root +access to the :file:`/etc/` directory. In order to initialize your instance as a +regular user, within your home directory, you can use the :envvar:`CW_MODE` environment variable: :: export CW_MODE=user then create a :file:`~/etc/cubicweb.d` directory that will hold your instances. -More information about how to configure your own environment in :ref:`ResourceMode`. +More information about how to configure your own environment is +available in :ref:`ResourceMode`. Instance parameters @@ -59,10 +61,10 @@ cubicweb-ctl db-create myblog -Other paramaters, like web server or emails parameters, can be modified in the +Other parameters, like web server or emails parameters, can be modified in the :file:`/etc/cubicweb.d/myblog/all-in-one.conf` file. You'll have to restart the instance after modification in one of those files. -This is it. Your blog is functionnal and running. Visit http://localhost:8080 and enjoy it! +This is it. Your blog is functional and running. Visit http://localhost:8080 and enjoy it! diff -r fb3633142d8f -r 7562418985ef doc/book/en/tutorials/base/customizing-the-application.rst --- a/doc/book/en/tutorials/base/customizing-the-application.rst Mon Jan 17 13:36:18 2011 +0100 +++ b/doc/book/en/tutorials/base/customizing-the-application.rst Mon Jan 17 15:45:26 2011 +0100 @@ -6,7 +6,7 @@ ---------------------------- So far so good. The point is that usually, you won't get enough by assembling -cubes out-of-the-box. You'll want to customize them, have a personal look and +cubes out-of-the-box. You will want to customize them, have a personal look and feel, add your own data model and so on. Or maybe start from scratch? So let's get a bit deeper and start coding our own cube. In our case, we want @@ -16,7 +16,7 @@ Create your own cube ~~~~~~~~~~~~~~~~~~~~ -First, notice that if you've installed |cubicweb| using debian packages, you'll +First, notice that if you've installed |cubicweb| using Debian packages, you will need the additional ``cubicweb-dev`` package to get the commands necessary to |cubicweb| development. All `cubicweb-ctl` commands are described in details in :ref:`cubicweb-ctl`. @@ -27,7 +27,7 @@ cubicweb-ctl newcube myblog This will create in the cubes directory (:file:`/path/to/forest/cubes` for source -installation, :file:`/usr/share/cubicweb/cubes` for debian packages installation) +installation, :file:`/usr/share/cubicweb/cubes` for Debian packages installation) a directory named :file:`blog` reflecting the structure described in :ref:`cubelayout`. @@ -48,8 +48,8 @@ specify when we talk about one or another, but keep in mind this difference. -Cube's metadata -~~~~~~~~~~~~~~~ +Cube metadata +~~~~~~~~~~~~~ A simple set of metadata about your cube are stored in the :file:`__pkginfo__.py` file. In our case, we want to extend the blog cube, so we have to tell that our @@ -69,7 +69,7 @@ The data model or schema is the core of your |cubicweb| application. It defines the type of content your application will handle. It is defined in the file -:file:`schema.py` of cubes. +:file:`schema.py` of the cube. Defining our model @@ -102,9 +102,9 @@ - the name is a string that is required and can't be longer than 50 characters - the description is a string that is not constrained and may contains rich - content such as html or Restructured text. + content such as HTML or Restructured text. -* a `Commnunity` may be linked to a `Blog` using the `community_blog` relation +* a `Community` may be linked to a `Blog` using the `community_blog` relation - ``*`` means a community may be linked to 0 to N blog, ``?`` means a blog may be linked to 0 to 1 community. For completeness, remember that you can also @@ -118,8 +118,8 @@ permissions, etc, that may be defined in the schema, but those won't be covered in this tutorial. -Notice that our schema refers to the `Blog` entity types which is not defined -here. But we know this type is available since we depends on the `blog` cube +Notice that our schema refers to the `Blog` entity type which is not defined +here. But we know this type is available since we depend on the `blog` cube which is defining it. @@ -150,8 +150,9 @@ >>> add_cube('myblog') >>> -The `add_cube` command is enough since it automatically updates our application -to the cube'schema. There are plenty of other migration commands of a more finer grain. They are described in :ref:`migration` +The `add_cube` command is enough since it automatically updates our +application to the cube's schema. There are plenty of other migration +commands of a more finer grain. They are described in :ref:`migration` As explained, leave the shell by typing Ctrl-D. If you restart the instance and take another look at the schema, you'll see that changes to the data model have @@ -159,17 +160,17 @@ has been done). .. image:: ../../images/tutos-base_myblog-schema_en.png - :alt: the instance'schema after adding our cube + :alt: the instance schema after adding our cube If you follow the 'info' link in the user pop-up menu, you'll also see that the instance is using blog and myblog cubes. .. image:: ../../images/tutos-base_myblog-siteinfo_en.png - :alt: the instance'schema after adding our cube + :alt: the instance schema after adding our cube -You can now add some community, link them to blog, etc... You'll see that the -framework provides default views for this entity type (we've not yet defined any -view for it!), and also that the blog primary view'll show the community it's +You can now add some communities, link them to blog, etc... You'll see that the +framework provides default views for this entity type (we have not yet defined any +view for it!), and also that the blog primary view will show the community it's linked to if any. All this thanks to the model driven interface provided by the framework. @@ -227,16 +228,16 @@ Changing the layout of the application ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The layout is the general organization of pages of the site. Views that generates -the layout ore sometimes refered as 'templates'. They are implemented in the +The layout is the general organization of the pages in the site. Views that generate +the layout are sometimes referred to as 'templates'. They are implemented in the framework in the module :mod:`cubicweb.web.views.basetemplates`. By overriding classes in this module, you can customize whatever part you wish of the default layout. -But notice that |cubicweb| provides a lot of other ways to customize the +But notice that |cubicweb| provides many other ways to customize the interface, thanks to actions and components (which you can individually (de)activate, control their location, customize their look...) as well as -"simple" CSS customization. You should first try to acheive your goal using such +"simple" CSS customization. You should first try to achieve your goal using such fine grained parametrization rather then overriding a whole template, which usually embeds customisation access points that you may loose in the process. @@ -258,17 +259,17 @@ vreg.register_and_replace(MyHTMLPageFooter, basetemplates.HTMLPageFooter) -* Our class inherit from the default page footer to ease getting things right, +* Our class inherits from the default page footer to ease getting things right, but this is not mandatory. * When we want to write something to the output stream, we simply call `self.w`, - that *must be given an unicode string*. + with *must be passed an unicode string*. -* The latest function is the more exotic stuff. The point is that without it, you - would get an error at display time because the framework woulnd't be able to +* The latest function is the most exotic stuff. The point is that without it, you + would get an error at display time because the framework wouldn't be able to choose which footer to use between :class:`HTMLPageFooter` and :class:`MyHTMLPageFooter`, since both have the same selector, hence the same - score... In this case, we want our footer to replace the default one, so we've + score... In this case, we want our footer to replace the default one, so we have to define a :func:`registration_callback` function to control object registration: the first instruction tells to register everything in the module but the :class:`MyHTMLPageFooter` class, then the second to register it instead @@ -281,22 +282,22 @@ restart the instance server. Save the Python file and reload the page in your web browser to view the changes. -We'll now have on every page of the site this simple footer. +We will now have this simple footer on every page of the site. Primary view customization ~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'primary' view (e.g. whose identifier is 'primary') is the one used to -display all information about a single entity. The standard primary view is one -of the most sophisticated view of all. It has several customisation points, but +The 'primary' view (i.e. any view with the identifier set to 'primary') is the one used to +display all the information about a single entity. The standard primary view is one +of the most sophisticated views of all. It has several customisation points, but its power comes with `uicfg`, allowing you to control it without having to subclass it. -But, this is a bit off-topic for this first tutorial. Let say we simply want a +However this is a bit off-topic for this first tutorial. Let's say we simply want a custom primary view for my `Community` entity type, using directly the view interface without trying to benefit from the default implementation (you should -do that though if you're rewriting reusable cubes; this is all described in more +do that though if you're rewriting reusable cubes; everything is described in more details in :ref:`primary_view`). @@ -318,7 +319,7 @@ What's going on here? -* Our class inherit from the default primary view, here mainly to get the correct +* Our class inherits from the default primary view, here mainly to get the correct view identifier, since we don't use any of its features. * We set on it a selector telling that it only applies when trying to display @@ -326,12 +327,12 @@ the default view for entities of this type. * View applying to entities usually have to define `cell_call` as entry point, - where given `row` and `col` arguments tell to which entity in the result set - the view is applied. We can then get this entity on the result set + and are given `row` and `col` arguments tell to which entity in the result set + the view is applied. We can then get this entity from the result set (`self.cw_rset`) by using the `get_entity` method. * To ease thing, we access our entity's attribute for display using its - printable_value method, which will handle formating and escaping when + printable_value method, which will handle formatting and escaping when necessary. As you can see, you can also access attributes by their name on the entity to get the raw value. @@ -342,7 +343,7 @@ :alt: the custom primary view for our community entity type We've seen here a lot of thing you'll have to deal with to write views in -|cubicweb|. The good news is that here is almost everything that is then used to +|cubicweb|. The good news is that this is almost everything that is used to build higher level layers. .. Note:: @@ -356,9 +357,10 @@ Write entities to add logic in your data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -|cubicweb| provides an ORM to easily programitically manipulate entities (as -we've fetched ealier by calling `get_entity` on a reslut set). By default, entity -types are instances of the :class:`AnyEntity` class, which hold a set of +|cubicweb| provides an ORM to easily programmaticaly manipulate +entities (just like the one we have fetched earlier by calling +`get_entity` on a result set). By default, entity +types are instances of the :class:`AnyEntity` class, which holds a set of predefined methods as well as property automatically generated for attributes/relations of the type it represents. @@ -366,7 +368,7 @@ to help you write your application. Customizing an entity requires that your entity: -- inherits from :class:`cubicweb.entities.AnyEntyt` or any subclass +- inherits from :class:`cubicweb.entities.AnyEntity` or any subclass - defines a :attr:`__regid__` linked to the corresponding data type of your schema @@ -390,13 +392,13 @@ def display_cw_logo(self): return 'CubicWeb' in self.description -Here : +In this example: * we used convenience :func:`fetch_config` function to tell which attributes should be prefetched by the ORM when looking for some related entities of this type, and how they should be ordered -* we overrided standard `dc_title` method, used in various place in the interface +* we overrode the standard `dc_title` method, used in various place in the interface to display the entity (though in this case the default implementation would have had the same result) @@ -436,17 +438,17 @@ components. To do so, they must both behave nicely when plugged into the application and be easily customisable, from the data model to the user interface. And I think the result is pretty successful, thanks to system such as -the selection mecanism and the choice to write views as python code which allow -use to build our page using true object oriented programming technics, that no -template langage provides. +the selection mechanism and the choice to write views as python code which allows +to build our page using true object oriented programming techniques, that no +template language provides. -A library of standard cubes are available from `CubicWeb Forge`_, to address a +A library of standard cubes is available from `CubicWeb Forge`_, to address a lot of common concerns such has manipulating people, files, things to do, etc. In -our community blog case, we could be interested for instance in functionnalities +our community blog case, we could be interested for instance in functionalities provided by the `comment` and `tag` cubes. The former provides threaded -discussion functionalities, the later a simple tag mecanism to classify content. -Let's say we want to try those. We'll first modify our cube's :file:`__pkginfo__.py` +discussion functionalities, the latter a simple tag mechanism to classify content. +Let's say we want to try those. We will first modify our cube's :file:`__pkginfo__.py` file: .. sourcecode:: python @@ -457,7 +459,7 @@ 'cubicweb-tag': None} Now, we'll simply tell on which entity types we want to activate the 'comment' -and 'tag' facilities by adding respectivly the 'comments' and 'tags' relations on +and 'tag' facilities by adding respectively the 'comments' and 'tags' relations on them in our schema (:file:`schema.py`). .. sourcecode:: python @@ -500,7 +502,7 @@ framework. Though if we take a look at a community, we won't see the tags box! That's because by default this box try to locate itself in the left column within the white frame, and this column is handled by the primary view we -hi-jacked. Let's change our view to make it more extensible, by keeping both our +hijacked. Let's change our view to make it more extensible, by keeping both our custom rendering but also extension points provided by the default implementation. @@ -524,9 +526,9 @@ .. image:: ../../images/tutos-base_myblog-community-taggable-primary_en.png :alt: the custom primary view for a community entry with tags activated -You can control part of the interface independantly from each others, piece by +You can control part of the interface independently from each others, piece by piece. Really. -.. _`CubicWeb Forge`: http://www.cubicweb.org/project \ No newline at end of file +.. _`CubicWeb Forge`: http://www.cubicweb.org/project diff -r fb3633142d8f -r 7562418985ef doc/book/en/tutorials/base/discovering-the-ui.rst --- a/doc/book/en/tutorials/base/discovering-the-ui.rst Mon Jan 17 13:36:18 2011 +0100 +++ b/doc/book/en/tutorials/base/discovering-the-ui.rst Mon Jan 17 15:45:26 2011 +0100 @@ -8,7 +8,7 @@ by visiting the URL http://localhost:8080/. By default, anonymous access is disabled, so a login form will appear. If you -asked to allow anonymous access when initailizing the instance, click on the +asked to allow anonymous access when initializing the instance, click on the 'login' link in the top right hand corner. To login, you need then use the admin account you specified at the time you initialized the database with ``cubicweb-ctl create``. @@ -27,8 +27,8 @@ Minimal configuration ~~~~~~~~~~~~~~~~~~~~~ -Before creating entities, let's change that 'unset title' thing that appeared -there and there. This is handled using |cubicweb| properties system. To set it, +Before creating entities, let's change that 'unset title' thing that appears +here and there. This comes from a |cubicweb| system properties. To set it, click on the 'site configuration link' in the pop-up menu behind your login name in the upper left-hand corner @@ -41,19 +41,19 @@ .. image:: ../../images/tutos-base_siteconfig_en.png :alt: the site configuration form -You should see a 'changes applied' message appear. You can now go back to the +You should see a 'changes applied' message. You can now go back to the index page by clicking on the |cubicweb| logo in the upper left-hand corner. You will much likely still see 'unset title' at this point. This is because by default the index page is cached. Force a refresh of the page (by typing Ctrl-R -in firefox for instance) and you should now see the title you entered. +in Firefox for instance) and you should now see the title you entered. Adding entities ~~~~~~~~~~~~~~~ The ``blog`` cube defines several entity types, among them ``Blog`` which is a -container for ``BlogEntry`` (e.g. post) on a particular topic. We can get a +container for ``BlogEntry`` (i.e. posts) on a particular topic. We can get a graphical view of the schema by clicking on the 'site schema' link in the user pop-up menu we've already seen: @@ -78,7 +78,7 @@ For instance, call this new blog 'Tech-blog' and type in 'everything about technology' as the description , then validate the form by clicking on -'Validate'. You'll be redirected to the `primary` view of the newly created blog. +'Validate'. You will be redirected to the `primary` view of the newly created blog. .. image:: ../../images/tutos-base_blog-primary_en.png :alt: the blog primary view @@ -87,11 +87,11 @@ Add a blog post *************** -There are several way to add a blog entry. The simplest is to click on the 'add -blog entry' link in the actions box on viewing the blog we've juste created. -You'll then see a form to create a post, with a 'blog entry of' selector preset +There are several ways to add a blog entry. The simplest is to click on the 'add +blog entry' link in the actions box on viewing the blog you have just created. +You will then see a form to create a post, with a 'blog entry of' field preset to the blog we're coming from. Enter a title, some content, click the 'validate' -button and you're done. You'll be redirected to the blog primary view, though you +button and you're done. You will be redirected to the blog primary view, though you now see that it contains the blog post you've just created. .. image:: ../../images/tutos-base_blog-primary-after-post-creation_en.png @@ -101,22 +101,24 @@ You can achieve the same thing by following the same path as we did for the blog creation, e.g. by clicking on the `[+]` at the left of the 'Blog entry' link on -the index page. The diffence being that since there is now context information, +the index page. The diffidence being that since there is no context information, the 'blog entry of' selector won't be preset to the blog. -If you click on the 'modify' link of the action box, you are back to the form to -edit the entity you just created, except that the form now has another section -with a combo-box entitled 'add relation'. It provices a generic way to edit -relations which don't appears in the above form. Choose the relation you want to -add and a second combobox appears where you can pick existing entities. If there -are too much of them, you'll be proposed to navigate (so go away from the form to -go back to it later, once you've selected the entity you want to link with). +If you click on the 'modify' link of the action box, you are back to +the form to edit the entity you just created, except that the form now +has another section with a combo-box entitled 'add relation'. It +provisos a generic way to edit relations which don't appears in the +above form. Choose the relation you want to add and a second combo box +appears where you can pick existing entities. If there are too many +of them, you will be offered to navigate to the target entity, that is +go away from the form and go back to it later, once you've selected +the entity you want to link with. .. image:: ../../images/tutos-base_form-generic-relations_en.png - :alt: the generic relations combobox + :alt: the generic relations combo box -This combobox can't appear until the entity is actually created. That's why you +This combo box can't appear until the entity is actually created. That's why you haven't seen it at creation time. You could also have hit 'Apply' instead of 'validate' and it would have showed up. @@ -124,35 +126,36 @@ About ui auto-adaptation ~~~~~~~~~~~~~~~~~~~~~~~~ -One thing among other that makes |cubicweb| different than other framework is +One of the things that make |cubicweb| different of other frameworks is its automatic user interface that adapts itself according to the data being displayed. Let's see an example. -If you go back to the home page an click on the 'Blog' link, you'll be redirected +If you go back to the home page an click on the 'Blog' link, you will be redirected to the primary view of the blog, the same we've seen earlier. Now, add another -blog, go back to the index page, and click again on this link. You'll see +blog, go back to the index page, and click again on this link. You will see a very different view (namely the 'list' view). .. image:: ../../images/tutos-base_blogs-list_en.png :alt: the list view when there are more than one blog to display -This is because in the first case, the framework choosed to use the 'primary' -view since there were only one entity in the data to be displayed. Now that there -are two entities, the 'list' view is more appropriate and hence has been used. +This is because in the first case, the framework chose to use the 'primary' +view since there was only one entity in the data to be displayed. Now that there +are two entities, the 'list' view is more appropriate and hence is being used. -There are various other places where it's able to adapt to display data in the best -way, the main being provided by views *selection* mecanism that will be detailled +There are various other places where |cubicweb| adapts to display data in the best +way, the main being provided by the view *selection* mechanism that will be detailed later. Digging deeper ~~~~~~~~~~~~~~ -By following principles explained below, you should now be able to create new -user to your application, to configure with a finer grain, etc... You'll notice -that the index page list a lot of types you don't know about. Most are built-in -type provided by the framework to make work the whole system. You may ignore them -in a first time and discover them as time goes. +By following principles explained below, you should now be able to +create new users for your application, to configure with a finer +grain, etc... You will notice that the index page lists a lot of types +you don't know about. Most are built-in types provided by the framework +to make the whole system work. You may ignore them in a first time and +discover them as time goes. One thing that is worth playing with is the search box. It may be used in various -way, from simple full text search to advanced queries using the :ref:`RQL` . \ No newline at end of file +way, from simple full text search to advanced queries using the :ref:`RQL` . diff -r fb3633142d8f -r 7562418985ef doc/book/en/tutorials/base/index.rst --- a/doc/book/en/tutorials/base/index.rst Mon Jan 17 13:36:18 2011 +0100 +++ b/doc/book/en/tutorials/base/index.rst Mon Jan 17 15:45:26 2011 +0100 @@ -10,13 +10,13 @@ This tutorial is designed to help in your very first steps to start with -|cubicweb|. We will glance through basic concepts such as: +|cubicweb|. We will tour through basic concepts such as: -* having an application running by using existing components +* getting an application running by using existing components * discovering the default user interface -* basically extending and customizing the look and feel of that application +* basic extending and customizing the look and feel of that application -More advanced concepts will covered in :ref:`advanced_tutorial`. +More advanced concepts are covered in :ref:`advanced_tutorial`. .. _TutosBaseVocab: @@ -32,10 +32,10 @@ and a set of views to display them. A cube can be built by assembling other cubes; -* an `instance` is a specific installation of one more more cubes and includes +* an `instance` is a specific installation of one or more cubes and includes configuration files, a web server and a database. -Reading :ref:`Concepts` for more vocabulary will be a must do at some point. +Reading :ref:`Concepts` for more vocabulary will be required at some point. Now, let's start the hot stuff!