diff -r 7044297a70ab -r a5c7609de579 doc/book/en/01-introduction.en.txt --- a/doc/book/en/01-introduction.en.txt Tue Nov 18 01:19:13 2008 +0100 +++ b/doc/book/en/01-introduction.en.txt Mon Nov 17 23:54:24 2008 -0800 @@ -2,31 +2,31 @@ .. _Overview: -Aperçu rapide de `CubicWeb` -=========================== +Quick overview of `CubicWeb` +============================ -`CubicWeb` nous permet de développer des instances d'applications web -basées sur un ou plusieurs `cube`. +`CubicWeb` allows us to develop web applications instances based on +one or more `cubes`. -Ce à quoi nous réferrons en parlant de `cube` est un modèle définissant -des types de données et des vues. Un `cube` est un composant re-utilisable -regroupé avec d'autres cubes sur le système de fichiers. +What we call a `cube` is a model defining the data types and views. +A `cube` is a reusable component grouped with others cubes in the file +system. -Un `instance` réferre à une installation spécifique d'un ou plusieurs cubes -où sont regroupés tous les fichiers de configuration de l'application web finale. +An `instance` refers to a specific installation of one or more `cubes` + where are grouped configuration files of the final web application. -Dans ce document, nous allons vous montrer comment créer un cube et l'utiliser -dans une instance pour votre application web. +In this document, we will show you how to create a `cube` and how to use it +in an `instance` for your web application. -Créez votre cube +Create your cube ---------------- -Après avoir installé votre environement de développement `CubicWeb`, vous pouvez -commencer à construire votre premier cube: :: +After you installed your `CubicWeb` development environment, you can start +to build your first cube: :: cubicweb-ctl newcube blog -Cela va créer dans ``/path/to/forest/cubes`` une répertoire contenant :: +This will create in ``/path/to/forest/cubes`` a directory containing: :: blog/ | @@ -76,20 +76,18 @@ | |-- views.py -Toute modification apportée à votre modele de données devra -etre effectué dans ce répertoire. - +Any changes applied to your data model should be done in this +directory. -Définissez votre schéma de données ----------------------------------- +Define your data schema +----------------------- -Le modèle de données ou schéma est au coeur d'une application `CubicWeb`. -C'est là où vous allez devoir définir le type de contenu que votre application -devra gérer. +The data model or schema is hte core of your `CubicWeb` application. +This is where is defined the type of content you application will handle. -Votre modele de données est défini dans le fichier ``schema.py`` de votre cube -``blog`` comme suit. +The data model is defined in the file ``schema.py`` of your cube +``blog`` such as follows. :: @@ -104,188 +102,187 @@ content = String(required=True, fulltextindexed=True) entry_of = SubjectRelation('Blog', cardinality='?*') -Un ``Blog`` a un titre et une description. Le titre est une chaîne -de caractères requise par la classe parente EntityType et ne doit -pas excéder 50 caractères. La description est une chaîne de -caractères sans contraintes. + +A Blog has a title and a description. The title is a string that is +required by the class EntityType and must be less than 50 characters. +The description is a string that is not constrained. -Une ``BlogEntry`` a un titre, une date de publication et du texte -étant son contenu. Le titre est une chaîne de caractères qui ne -doit pas excéder 100 caractères. La date de publication est de type Date et a -pour valeur par défaut TODAY, ce qui signifie que lorsqu'une -``BlogEntry`` sera créée, sa date de publication sera la date -courante a moins de modifier ce champ. Le texte est une chaîne de -caractères qui sera indexée en plein texte et sans contraintes. +A BlogEntry has a title, a publish_date and a content. The title is a +string that is required and must be less than 100 characters. The +publish_date is a Date with a default value of TODAY, meaning that +when a BlogEntry is created, its publish_date will be the current day +unless it is modified. The content is a string that will be indexed in +the full-text index and has no constraint. -Une ``BlogEntry`` a aussi une relation nommée ``entry_of`` qui la -relie à un ``Blog``. La cardinalité ``?*`` signifie que BlogEntry -peut faire partie de zero a un Blog (``?`` signifie `zero ou un`) et -qu'un Blog peut avoir une infinité de BlogEntry (``*`` signifie -`n'importe quel nombre incluant zero`). -Par soucis de complétude, nous rappellerons que ``+`` signifie -`un ou plus`. +A BlogEntry also has a relationship ``entry_of`` that links it to a +Blog. The cardinality ``?*`` means that a BlogEntry can be part of +zero or one Blog (``?`` means `zero or one`) and that a Blog can +have any number of BlogEntry (``*`` means `any number including +zero`). For completeness, remember that ``+`` means `one or more`. -Créez votre instance +Create your instance -------------------- :: cubicweb-ctl create blog blogdemo -Cette commande va créer un répertoire ``~/etc/cubicweb.d/blogdemo`` -contenant tous les fichiers de configuration nécessaire au lancement -de votre application web. + +This command will create a directory ``~/etc/cubicweb.d/blogdemo`` +which will contain all the configuration files required to start +you web application. -L'instance ``blogdemo`` est construite sur le cube ``blog``. +The instance ``blogdemo`` is based on the cube ``blog``. + -Bienvenue dans votre application web ------------------------------------- +Welcome in your web application +------------------------------- -Lancez votre application en exécutant : :: +Run your application with the following command: :: cubicweb-ctl start -D blogdemo -Vous pouvez à présent accéder à votre application web vous permettant de -créer des blogs et d'y poster des messages en visitant l'URL http://localhost:8080/. -Un premier formulaire d'authentification va vous être proposé. Par défaut, -l'application n'autorisera pas d'utilisateur anonyme à accéder a votre -application. Vous devrez donc utiliser l'utilisateur administrateur que -vous aurez crée lors de l'initialisation de votre base de données via +You can now access to your web application to create blogs and post messages +by visitin the URL http://localhost:8080/. +A login form will first be prompted. By default, the application will not allow +anonymous user to get in the application. You should then use the admin +account you created at the time you initialized the database with ``cubicweb-ctl create``. .. image:: images/login-form.png -Une fois authentifié, vous pouvez commencer à jouer avec votre -application et créer des entités. Bravo ! +Once authenticated, you can start playing with your application +and create entities. Bravo! .. image:: images/blog-demo-first-page.png +Please notice that so far, `CubicWeb` franework managed all aspects of +the web application based in the schema provided at first. -Rappelez-vous que pour le moment, tout a été géré par la plate-forme -`CubicWeb` et que la seule chose qui a été fournie est le schéma de -données. -Créons des entités ------------------- +Create entities +--------------- -Nous allons maintenant créer quelques entités dans notre application. +We will now create a couple of entities in our web application. -Créez un Blog +Create a Blog ~~~~~~~~~~~~~ -Créons à présent quelques entités. Cliquez sur `[+]` sur la -droite du lien Blog. Appelez cette nouvelle entité Blog ``Tech-Blog`` -et tapez pour la description ``everything about technology``, -puis validez le formulaire d'édition en cliquant sur le bouton -``Validate``. +Let us create a few of these entities. Click on the `[+]` at the right +of the link Blog. Call this new Blog ``Tech-blog`` and type in +``everything about technology`` as the description, then validate the +form by clicking on ``Validate``. .. image:: images/cbw-create-blog.en.png :alt: from to create blog -En cliquant sur le logo situé dans le coin gauche de la fenêtre, -vous allez être redirigé vers la page d'accueil. Ensuite, si vous allez -sur le lien Blog, vous devriez voir la liste des entités Blog, en particulier -celui que vous venez juste de créer ``Tech-Blog``. +Click on the logo at top left to get back to the home page, then +follow the Blog link that will list for you all the existing Blog. +You should be seeing a list with a single item ``Tech-blog`` you +just created. .. image:: images/cbw-list-one-blog.en.png :alt: displaying a list of a single blog -Si vous cliquez sur ``Tech-Blog`` vous devriez obtenir une description -détaillée, ce qui dans notre cas, n'est rien de plus que le titre -et la phrase ``everything about technology`` +Clicking on this item will get you to its detailed description except +that in this case, there is not much to display besides the name and +the phrase ``everything about technology``. -Maintenant retournons sur la page d'accueil et créons un nouveau -Blog ``MyLife`` et retournons sur la page d'accueil, puis suivons -le lien Blog et nous constatons qu'à présent deux blogs sont listés. +Now get back to the home page by clicking on the top-left logo, then +create a new Blog called ``MyLife`` and get back to the home page +again to follow the Blog link for the second time. The list now +has two items. .. image:: images/cbw-list-two-blog.en.png :alt: displaying a list of two blogs -Créons un article -~~~~~~~~~~~~~~~~~ +Create a BlogEntry +~~~~~~~~~~~~~~~~~~ -Revenons sur la page d'accueil et cliquons sur `[+]` à droite du lien -`articles`. Appellons cette nouvelle entité ``Hello World`` et introduisons -un peut de texte avant de ``Valider``. Vous venez d'ajouter un article -sans avoir précisé à quel Blog il appartenait. Dans la colonne de gauche -se trouve une boite intitulé ``actions``, cliquez sur le menu ``modifier``. -Vous êtes de retour sur le formulaire d'édition de l'article que vous -venez de créer, à ceci près que ce formulaire a maintenant une nouvelle -section intitulée ``ajouter relation``. Choisissez ``entry_of`` dans ce menu, -cela va faire apparaitre une deuxième menu déroulant dans lequel vous -allez pouvoir séléctionner le Blog ``MyLife``. +Get back to the home page and click on [+] at the right of the link +BlogEntry. Call this new entry ``Hello World`` and type in some text +before clicking on ``Validate``. You added a new blog entry without +saying to what blog it belongs. There is a box on the left entitled +``actions``, click on the menu item ``modify``. You are back to the form +to edit the blog entry you just created, except that the form now has +another section with a combobox titled ``add relation``. Chose +``entry_of`` in this menu and a second combobox appears where you pick +``MyLife``. -Vous auriez pu aussi, au moment où vous avez crée votre article, sélectionner -``appliquer`` au lieu de ``valider`` et le menu ``ajouter relation`` serait apparu. +You could also have, at the time you started to fill the form for a +new entity BlogEntry, hit ``Apply`` instead of ``Validate`` and the +combobox titled ``add relation`` would have showed up. + .. image:: images/cbw-add-relation-entryof.en.png :alt: editing a blog entry to add a relation to a blog -Validez vos modifications en cliquant sur ``Valider``. L'entité article -qui est listée contient maintenant un lien vers le Blog auquel il -appartient, ``MyLife``. +Validate the changes by clicking ``Validate``. The entity BlogEntry +that is displayed now includes a link to the entity Blog named +``MyLife``. .. image:: images/cbw-detail-one-blogentry.en.png :alt: displaying the detailed view of a blogentry -Rappelez-vous que pour le moment, tout a été géré par la plate-forme -`CubicWeb` et que la seule chose qui a été fournie est le schéma de -données. D'ailleurs pour obtenir une vue graphique du schéma, visitez -le lien `Application schema`` a l'URL suivante : +Please notice that so far, `CubicWeb` franework managed all aspects of +the web application based in the schema provided at first. +Also if you wish to get a graphical view of the schema, visit +the link `Application schema`` which will direct you to : http://localhost:8080/view?vid=schema .. image:: images/cbw-schema.en.png :alt: graphical view of the schema (aka data-model) -Définissez les vues de vos données ----------------------------------- +Define your entities views +-------------------------- -Le principe de sélection des vues -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Une vue est une classe Python qui inclut: - - - un identifiant (tous les objets dans `CubicWeb` sont listés - dans un registre et cet identifiant est utilisé comme la clé) +The views selection principle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - un filtre de sélection de `result sets` auxquels il - peut s'appliquer - -`CubicWeb` fournit un ensemble de vues standard pour le type d'objet -`EntityView`. vous poubez les trouver listées dans ``cubicweb/web/views``. - -Une vue est appliquée sur un `result set` qui représente l'ensemble -des entités que nous cherchons à appliquer. `CubicWeb` utilise un -sélecteur qui permet de calculer un score et d'identifier la vue -la plus adaptée au `result set` que nous voulons afficher. La librarie -standard des sélecteurs se trouve dans ``cubicweb.common.selector`` -et une librairie des méthodes utilisées pour calculer les scores -est dans ``cubicweb.vregistry.vreq``. +A view is defined by a Python class which includes: + + - an identifier (all objects in `CubicWeb` are entered in a registry + and this identifier will be used as a key) + + - a filter to select the resulsets it can be applied to -Il est possible de définir plusieurs vues ayant le meme identifiant -et d'y associer des sélecteurs et des filtres afin de permettre à -l'application de s'adapter au mieux aux données que nous avons -besoin d'afficher. Nous verrons cela plus en détails dans :ref:`DefinitionVues`. +`CubicWeb` provides a lot of standard views for the type +`EntityView`, for a complete list, you +will have to read the code in directory ``cubicweb/web/views/`` -On peut citer l'exemple de la vue nommée ``primary`` qui est celle utilisée -pour visualiser une entité seule. Nous allons vous montrer comment modifier -cette vue. +A view is applied on a `result set` which contains a set of +entities we are trying to display. `CubicWeb` uses a selector +mecanism which computes a score used to identify which view +is the best to apply for the `result set` we are trying to +display. The standard library of selectors is in +``cubicweb.common.selector`` and a library of methods used to +compute scores is available in ``cubicweb.vregistry.vreq``. -Modification des vues -~~~~~~~~~~~~~~~~~~~~~ -Si vous souhaitez modifier la manière dont est rendue un article (`Blogentry`), -vous devez surcharger la vue ``primary`` définie dans le module ``views`` de -votre cube, ``cubes/blog/views.py``. +It is possible to define multiple views for the same identifier +and to associate selectors and filters to allow the application +to find the best way to render the data. We will see more details +on this in :ref:`DefinitionVues`. + +For example, the view named ``primary`` is the one used to display +a single entity. We will now show you hos to customize this view. + -Nous pourrions par exemple ajouter devant la date de publication un préfixe -indiquant que la date visualisée est la date de publication. +View customization +~~~~~~~~~~~~~~~~~~ -Pour cela appliquez les modifications suivantes: +If you wish to modify the way a `BlogEntry` is rendered, you will have to +overwrite the `primary` view defined in the module ``views`` of the cube +``cubes/blog/views.py``. + +We can by example add in front of the pulication date a prefix specifying +the date we see is the publication date. + +To do so, please apply the following changes: :: @@ -316,28 +313,26 @@ self.render_entity_relations(entity, siderelations) .. note:: - Lors qu'une vue est modifiée il n'est pas nécessaire de relancer - l'application. Sauvez juste le fichier Python et rechargez la page - dans votre navigateur afin de visualiser les modifications. + When a view is modified, it is not required to restart the application + server. Save the Python file and reload the page in your web browser + to view the changes. - -Nous pouvons voir que la date de publication est préfixée comme souhaitée. - +You can now see that the publication date has a prefix. .. image:: images/cbw-update-primary-view.en.png :alt: modified primary view +The above source code defines a new primary view for +``BlogEntry``. Le code que nous avons modifié définit une vue primaire pour une entité de type `BlogEntry`. -Etant donné que les vues sont appliquées sur des `result sets` et que -les `result sets` peuvent être des tableaux de données, il est indispensable -de récupérer l'entité selon ses coordonnées (row,col). +Since views are applied to resultsets and resulsets can be tables of +data, it is needed to recover the entity from its (row,col) +coordinates. We will get to this in more detail later. -La méthode ``self.w()`` est utilisée pour afficher des données. En particulier -dans notre exemple, nous l'utilisons pour afficher des tags HTML et des valeurs -des attributs de notre entité. +The view has a ``self.w()`` method that is used to output data. In our +example we use it to output HTML tags and values of the entity's attributes. -