goa/doc/quickstart.txt
author Stephanie Marcu <stephanie.marcu@logilab.fr>
Thu, 15 Apr 2010 16:20:20 +0200
branchstable
changeset 5285 7be5878bc86c
parent 2789 39712da6f397
permissions -rw-r--r--
[doc/book] change font to improve lisibility (in particular cl -> d)
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
2789
39712da6f397 R propagate deprecation of AppObject.entity()
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
     1
.. -*- coding: utf-8 -*-
39712da6f397 R propagate deprecation of AppObject.entity()
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
     2
0
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
     3
Introduction
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
     4
=============
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
     5
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
     6
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
     7
Concepts et vocabulaire
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
     8
-----------------------
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
     9
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    10
*schéma*
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    11
  le schéma définit le modèle de données d'une application sous forme
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    12
  d'entités et de relations. C'est l'élément central d'une
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    13
  application.
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    14
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    15
*result set*
2789
39712da6f397 R propagate deprecation of AppObject.entity()
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
    16
  objet qui encaspule les résultats d'une requête adressée à l'entrepôt
0
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    17
  de données et des informations sur cette requête.
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    18
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    19
*vue*
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    20
  une vue est une manière de représenter les données d'un `result set`
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    21
  sous forme HTML, CSV, JSON, etc.
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    22
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    23
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    24
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    25
Définition d'une application de Blog
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    26
====================================
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    27
2789
39712da6f397 R propagate deprecation of AppObject.entity()
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
    28
La première chose à faire est de copier le squelette depuis le répertoire
39712da6f397 R propagate deprecation of AppObject.entity()
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
    29
``lax/skel`` vers un nouveau répertoire qui sera votre application
0
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    30
``Google AppEngine``::
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    31
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    32
  $ cp -r lax/skel myapp
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    33
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    34
Définition du schéma
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    35
--------------------
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    36
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    37
Ouvrir le fichier ``myapp/schema.py`` afin de définir le schéma des
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    38
données manipulées. La syntaxe de la définition est la même que celle
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    39
proposée par `Google AppEngine`_ mais il faut remplacer la ligne
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    40
d'import::
2789
39712da6f397 R propagate deprecation of AppObject.entity()
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
    41
0
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    42
  from google.appengine.ext import db
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    43
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    44
par celle-ci::
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    45
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    46
  from cubicweb.goa import db
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    47
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    48
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    49
Un exemple de schéma de données pour un ``Blog`` pourrait être::
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    50
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    51
  from cubicweb.goa import db
2789
39712da6f397 R propagate deprecation of AppObject.entity()
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
    52
0
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    53
  class Blog(db.Model):
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    54
      # un titre à donner à l'entrée
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    55
      title = db.StringProperty(required=True)
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    56
      # la date à laquelle le blog est créé
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    57
      diem = db.DateProperty(required=True, auto_now_add=True)
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    58
      # le contenu de l'entrée
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    59
      content = db.TextProperty()
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    60
      # une entrée peut en citer une autre
2789
39712da6f397 R propagate deprecation of AppObject.entity()
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
    61
      cites = db.SelfReferenceProperty()
39712da6f397 R propagate deprecation of AppObject.entity()
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
    62
0
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    63
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    64
Personnalisation des vues
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    65
-------------------------
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    66
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    67
``LAX`` permet de générer directement, à partir de la définition
2789
39712da6f397 R propagate deprecation of AppObject.entity()
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
    68
du schéma, des vues de consultation, d'ajout et de modification
39712da6f397 R propagate deprecation of AppObject.entity()
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
    69
pour tous les types de donées manipulés. Il est toutefois
0
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    70
généralement souhaitable de personnaliser les vues de consultations.
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    71
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    72
Dans ``LAX``, les vues sont représentées par des classes Python.
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    73
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    74
Une vue se caractérise par :
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    75
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    76
- un identifiant (tous les objets dans ``LAX`` sont enregistrés
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    77
  dans un registre et cet identifiant sert de clé pour y retrouver
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    78
  la vue)
2789
39712da6f397 R propagate deprecation of AppObject.entity()
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
    79
0
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    80
- une description des types de données auxquels elle s'applique
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    81
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    82
Il existe dans ``LAX`` des vues prédéfinies et utilisées par le moteur
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    83
d'affichage. Pour avoir une liste exhaustive de ces vues prédéfinies,
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    84
vous pouvez consulter cette page. (XXX mettre le lien vers la liste).
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    85
Par exemple, la vue ``primary`` est la vue utilisée pour générer la
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    86
page principale de consultation d'un objet.
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    87
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    88
Par exemple, si on souhaite modifier la page principale d'une entrée de
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    89
blog, il faut surcharger la vue ``primary`` des objets ``Blog`` dans
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    90
le fichier ``myapp/views.py``::
2789
39712da6f397 R propagate deprecation of AppObject.entity()
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
    91
0
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    92
  from cubicweb.web.views import baseviews
2789
39712da6f397 R propagate deprecation of AppObject.entity()
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
    93
0
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    94
  class BlogPrimaryView(baseviews.PrimaryView):
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    95
      accepts = ('Blog',)
2789
39712da6f397 R propagate deprecation of AppObject.entity()
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
    96
0
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    97
      def cell_call(self, row, col):
2789
39712da6f397 R propagate deprecation of AppObject.entity()
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
    98
          entity = self.rset.get_entity(row, col)
0
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
    99
          self.w(u'<h1>%s</h1>' % entity.title)
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
   100
          self.w(u'<div>%s</div>' entity.content)
2789
39712da6f397 R propagate deprecation of AppObject.entity()
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
   101
0
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
   102
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
   103
Génération du graphique de schéma
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
   104
---------------------------------
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
   105
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
   106
Il existe une vue ``schema`` qui permet d'afficher un graphique
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
   107
représantant les différents types d'entités définis dans le schéma
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
   108
ainsi que les relations entre ces types. Ce graphique doit être généré
2789
39712da6f397 R propagate deprecation of AppObject.entity()
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
   109
statiquement. Le script à utiliser pour générer ce schéma est
0
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
   110
dans ``myapp/tools``. Ce script nécessite d'avoir accès aux
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
   111
bibliothèques fournies par le SDK de ``Google AppEngine``. Il faut
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
   112
donc modifier son PYTHONPATH::
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
   113
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
   114
  $ export PYTHONPATH=GAE_ROOT/google:GAE_ROOT/lib/yaml
2789
39712da6f397 R propagate deprecation of AppObject.entity()
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 0
diff changeset
   115
  $ python tools/generate_schema_img.py
0
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
   116
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
   117
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
   118
Génération des fichiers de traduction
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
   119
-------------------------------------
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
   120
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
   121
Des catalogues de traduction se trouvent dans `myapp/i18n`. Il faut
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
   122
pour l'instant les mettre à jour à la main (et/ou avec les outils
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
   123
``GNU`` comme ``xgettext``) et ensuite les compiler grâce au script
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
   124
``myapp/tools/i18ncompile.py``::
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
   125
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
   126
  $ python tools/i18ncompile.py
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
   127
b97547f5f1fa Showtime !
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents:
diff changeset
   128
.. _`Google AppEngine` :: http://code.google.com/appengine/docs/datastore/overview.html