Fondements du framework CubicWeb

=============================

Le moteur web d'cubicweb consiste en quelques classes g�rant un ensemble d'objets

charg�s dynamiquement au lancement d'cubicweb. Ce sont ces objets dynamiques, issus

du mod�le ou de la librairie, qui construisent le site web final. Les diff�rents

composants dynamiques sont par exemple : 

* cot� client et serveur

 - les d�finitions d'entit�s, contenant la logique permettant la manipulation des

   donn�es de l'application

* cot� client

  - les *vues* , ou encore plus sp�cifiquement 

    - les boites

    - l'en-t�te et le pied de page

    - les formulaires

    - les gabarits de pages

  - les *actions*

  - les *controleurs*

* cot� serveur

  - les crochets de notification

  - les vues de notification

Les diff�rents composants du moteur sont :

* un frontal web (seul twisted disponible pour le moment), transparent du point

  de vue des objets dynamiques

* un objet encapsulant la configuration

* un `vregistry` (`cubicweb.cwvreg`) contenant les objets charg�s dynamiquements

D�tail de la proc�dure d'enregistrement

---------------------------------------

Au d�marage le `vregistry` ou base de registres inspecte un certain nombre de

r�pertoires � la recherche de d�finition de classes "compatible". Apr�s une

proc�dure d'enregistrement les objets sont affect�s dans diff�rents registres

afin d'�tre ensuite s�l�ctionn� dynamiquement pendant le fonctionnement de

l'application.

La classe de base de tout ces objets est la classe `AppRsetObject` (module

`cubicweb.common.appobject`). 

API Python/RQL

--------------

Inspir� de la db-api standard, avec un object Connection poss�dant les m�thodes

cursor, rollback et commit principalement. La m�thode importante est la m�thode

`execute` du curseur :

`execute(rqlstring, args=None, eid_key=None, build_descr=True)`

:rqlstring: la requ�te rql � �x�cuter (unicode)

:args: si la requ�te contient des substitutions, un dictionnaire contenant les

       valeurs � utiliser

:eid_key: 

   un d�tail d'impl�mentation du cache de requ�tes RQL fait que si une substitution est

   utilis�e pour introduire un eid *levant des ambiguit�s dans la r�solution de

   type de la requ�te*, il faut sp�cifier par cet argument la cl� correspondante

   dans le dictionnaire

C'est l'objet Connection qui poss�de les m�thodes classiques `commit` et

`rollback`. Vous ne *devriez jamais avoir � les utiliser* lors du d�veloppement

d'interface web sur la base du framework CubicWeb �tant donn� que la fin de la

transaction est d�termin�e par celui-ci en fonction du succ�s d'�x�cution de la

requ�te. 

NOTE : lors de l'�x�cution de requ�tes de modification (SET,INSERT,DELETE), si une

requ�te g�n�re une erreur li�e � la s�curit�, un rollback est syst�matiquement

effectu�e sur la transaction courante.

La classe `Request` (`cubicweb.web`)

---------------------------------

Une instance de requ�te est cr��e lorsque une requ�te HTTP est transmise au

serveur web. Elle contient des informations telles que les param�tres de

formulaires, l'utilisateur connect�, etc. 

**De mani�re plus g�n�rale une requ�te repr�sente une demande d'un utilisateur,

que se soit par HTTP ou non (on parle �galement de requ�te rql cot� serveur par

exemple)**

Une instance de la classe `Request` poss�de les attributs :

* `user`, instance de`cubicweb.common.utils.User` correspondant � l'utilisateur

  connect� 

* `form`, dictionaire contenant les valeurs de formulaire web

* `encoding`, l'encodage de caract�re � utiliser dans la r�ponse

Mais encore :

:Gestion des donn�es de session:        

  * `session_data()`, retourne un dictionaire contenant l'int�gralit� des

    donn�es de la session

  * `get_session_data(key, default=None)`, retourne la valeur associ�e �

    la cl� ou la valeur `default` si la cl� n'est pas d�finie

  * `set_session_data(key, value)`, associe une valeur � une cl�

  * `del_session_data(key)`,  supprime la valeur associ� � une cl�

:Gestion de cookie:

  * `get_cookie()`, retourne un dictionnaire contenant la valeur de l'ent�te

    HTTP 'Cookie'

  * `set_cookie(cookie, key, maxage=300)`, ajoute un en-t�te HTTP `Set-Cookie`,

    avec une dur�e de vie 5 minutes par d�fault (`maxage` = None donne un cooke

    *de session"* expirant quand l'utilisateur ferme son navigateur

  * `remove_cookie(cookie, key)`, fait expirer une valeur

:Gestion d'URL:

  * `url()`, retourne l'url compl�te de la requ�te HTTP

  * `base_url()`, retourne l'url de la racine de l'application

  * `relative_path()`, retourne chemin relatif de la requ�te

:Et encore...:

  * `set_content_type(content_type, filename=None)`, place l'en-t�te HTTP

    'Content-Type'

  * `get_header(header)`, retourne la valeur associ� � un en-t�te HTTP

    arbitraire de la requ�te

  * `set_header(header, value)`, ajoute un en-t�te HTTP arbitraire dans la

    r�ponse 

  * `cursor()` retourne un curseur RQL sur la session

  * `execute(*args, **kwargs)`, raccourci vers .cursor().execute()

  * `property_value(key)`, gestion des propri�t�s (`CWProperty`)

  * le dictionaire `data` pour stocker des donn�es pour partager de

    l'information entre les composants *durant l'�x�cution de la requ�te*.

A noter que cette classe est en r�alit� abstraite et qu'une impl�mentation

concr�te sera fournie par le *frontend* web utilis� (en l'occurent *twisted*

aujourd'hui). Enfin pour les vues ou autres qui sont �x�cut�s cot� serveur,

la majeure partie de l'interface de `Request` est d�finie sur la session

associ�e au client. 

La classe `AppObject`

---------------------

En g�n�ral :

* on n'h�rite pas directement des cette classe mais plut�t d'une classe

  plus sp�cifique comme par exemple `AnyEntity`, `EntityView`, `AnyRsetView`,

  `Action`...

* pour �tre enregistrable, un classe fille doit d�finir son registre (attribut

  `__registry__`) et son identifiant (attribut `id`). G�n�ralement on n'a pas �

  s'occuper du registre, uniquement de l'identifiant `id` :) 

On trouve un certain nombre d'attributs et de m�thodes d�finis dans cette classe

et donc commune � tous les objets de l'application :

A l'enregistrement, les attributs suivants sont ajout�s dynamiquement aux

*classes* filles:

* `vreg`, le `vregistry` de l'application

* `schema`, le sch�ma de l'application

* `config`, la configuration de l'application

On trouve �galement sur les instances les attributs :

* `req`, instance de `Request`

* `rset`, le "result set" associ� � l'objet le cas �ch�ant

* `cursor`, curseur rql sur la session

:Gestion d'URL:

  * `build_url(method=None, **kwargs)`, retourne une URL absolue construites �

    partir des arguments donn�s. Le *controleur* devant g�rer la r�ponse

    peut-�tre sp�cifi� via l'argument sp�cial `method` (le branchement est

    th�oriquement bien effectu� automatiquement :).

  * `datadir_url()`, retourne l'url du r�pertoire de donn�es de l'application

    (contenant les fichiers statiques tels que les images, css, js...)

  * `base_url()`, raccourci sur `req.base_url()`

  * `url_quote(value)`, version *unicode safe* de de la fonction `urllib.quote`

:Manipulation de donn�es:

  * `etype_rset(etype, size=1)`, raccourci vers `vreg.etype_rset()`

  * `eid_rset(eid, rql=None, descr=True)`, retourne un objet result set pour

    l'eid donn�

  * `entity(row, col=0)`, retourne l'entit� correspondant � la position donn�es

    du "result set" associ� � l'objet

  * `complete_entity(row, col=0, skip_bytes=True)`, �quivalent � `entity` mais

    appelle �galement la m�thode `complete()` sur l'entit� avant de la retourner

:Formattage de donn�es:

  * `format_date(date, date_format=None, time=False)`

  * `format_time(time)`,

:Et encore...:

  * `external_resource(rid, default=_MARKER)`, acc�de � une valeur d�finie dans

    le fichier de configuration `external_resource`

  * `tal_render(template, variables)`, 

**NOTE IMPORTANTE**

Lorsqu'on h�rite d'`AppObject` (m�me indirectement), il faut **toujours**

utiliser **super()** pour r�cup�rer les m�thodes et attributs des classes

parentes, et pas passer par l'identifiant de classe parente directement.

(sous peine de tomber sur des bugs bizarres lors du rechargement automatique

des vues). Par exemple, plut�t que d'�crire::

      class Truc(PrimaryView):

          def f(self, arg1):

              PrimaryView.f(self, arg1)

Il faut �crire::

      class Truc(PrimaryView):

          def f(self, arg1):

              super(Truc, self).f(arg1)

XXX FILLME diagramme interaction application/controller/template/view