doc/book/fr/01-introduction.fr.txt
changeset 93 9c919a47e140
parent 90 7fd4ffeb082b
child 2789 39712da6f397
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/fr/01-introduction.fr.txt	Tue Nov 18 01:16:30 2008 +0100
@@ -0,0 +1,343 @@
+.. -*- coding: utf-8 -*-
+
+.. _Overview:
+
+Aperçu rapide de `CubicWeb`
+===========================
+
+`CubicWeb` nous permet de développer des instances d'applications web
+basées sur un ou plusieurs `cube`. 
+
+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.
+
+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.
+
+Dans ce document, nous allons vous montrer comment créer un cube et l'utiliser
+dans une instance pour votre application web.
+
+Créez votre cube
+----------------
+
+Après avoir installé votre environement de développement `CubicWeb`, vous pouvez
+commencer à construire votre premier cube: ::
+
+  cubicweb-ctl newcube blog
+
+Cela va créer dans ``/path/to/forest/cubes`` une répertoire contenant ::
+
+  blog/
+  |
+  |-- data/
+  |   |-- cubes.blog.css
+  |   |-- cubes.blog.js  
+  |   |-- external_resources
+  |
+  |-- debian/
+  |   |-- changelog
+  |   |-- compat
+  |   |-- control
+  |   |-- copyright
+  |   |-- cubicweb-blog.prerm
+  |   |-- rules
+  |
+  |-- entities.py
+  |
+  |-- i18n/
+  |   |-- en.po
+  |   |-- fr.po
+  |
+  |-- __init__.py
+  |
+  |-- MANIFEST.in
+  |
+  |-- migration/
+  |   |-- postcreate.py
+  |   |-- precreate.py
+  |
+  |-- __pkginfo__.py
+  |
+  |-- schema.py
+  |
+  |-- setup.py
+  |
+  |-- site_cubicweb.py
+  |
+  |-- sobjects.py
+  |
+  |-- test/
+  |   |-- data/
+  |       |-- bootstrap_cubes
+  |   |-- pytestconf.py
+  |   |-- realdb_test_blog.py
+  |   |-- test_blog.py
+  |
+  |-- views.py
+
+Toute modification apportée à votre modele de données devra
+etre effectué dans ce répertoire. 
+
+
+
+Définissez votre schéma de données
+----------------------------------
+
+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.
+
+Votre modele de données est défini dans le fichier ``schema.py`` de votre cube
+``blog`` comme suit.
+
+::
+
+  from cubicweb.schema import format_constraint
+  class Blog(EntityType):
+    title = String(maxsize=50, required=True)
+    description = String()
+
+  class BlogEntry(EntityType):
+    title = String(required=True, fulltextindexed=True, maxsize=256)
+    publish_date = Date(default='TODAY')
+    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.
+
+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.
+
+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`.
+
+
+Créez votre 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.
+
+L'instance ``blogdemo`` est construite sur le cube ``blog``.
+
+Bienvenue dans votre application web
+------------------------------------
+
+Lancez votre application en exécutant : ::
+
+  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
+``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 !
+
+.. image:: images/blog-demo-first-page.png
+
+
+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
+------------------
+
+Nous allons maintenant créer quelques entités dans notre application.
+
+Créez un 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``.
+
+.. image:: images/cbw-create-blog.fr.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``.
+
+.. image:: images/cbw-list-one-blog.fr.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``
+
+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.
+
+.. image:: images/cbw-list-two-blog.fr.png
+   :alt: displaying a list of two blogs
+
+Créons un article
+~~~~~~~~~~~~~~~~~
+
+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``.
+
+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.
+
+.. image:: images/cbw-add-relation-entryof.fr.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``.
+
+.. image:: images/cbw-detail-one-blogentry.fr.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 :
+http://localhost:8080/view?vid=schema
+
+.. image:: images/cbw-schema.fr.png
+   :alt: graphical view of the schema (aka data-model)
+
+
+Définissez les vues de vos données
+----------------------------------
+
+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é)
+
+  - 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``.
+
+
+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`.
+
+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.
+
+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``.
+
+Nous pourrions par exemple ajouter devant la date de publication un préfixe
+indiquant que la date visualisée est la date de publication.
+
+Pour cela appliquez les modifications suivantes: 
+
+:: 
+
+  from cubicweb.web.views import baseviews
+
+
+  class BlogEntryPrimaryView(baseviews.PrimaryView):
+
+    accepts = ('BlogEntry',)
+
+    def render_entity_title(self, entity):
+        self.w(u'<h1>%s</h1>' % html_escape(entity.dc_title()))
+
+    def content_format(self, entity):
+        return entity.view('reledit', rtype='content_format')
+
+    def cell_call(self, row, col):
+        entity = self.entity(row, col)
+
+        # display entity attributes with prefixes
+        self.w(u'<h1>%s</h1>' % entity.title)
+        self.w(u'<p>published on %s</p>' % entity.publish_date.strftime('%Y-%m-%d'))
+        self.w(u'<p>%s</p>' % entity.content)
+        
+        # display relations
+        siderelations = []
+        if self.main_related_section:
+            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.
+
+
+Nous pouvons voir que la date de publication est préfixée comme souhaitée.
+
+
+.. image:: images/cbw-update-primary-view.fr.png
+   :alt: modified primary view
+
+
+
+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).
+
+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é.
+
+