D�finition de vues

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

Les classes de base des vues

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

La class `View` (`cubicweb.common.view`)

`````````````````````````````````````

Un vue �crit dans son flux de sortie via son attribut `w` (`UStreamIO`).

L'interface de base des vues est la suivante :

* `dispatch(**context)`, appelle ("rend") la vue en appellent `call` ou

  `cell_call` en fonction des arguments pass�

* `call(**kwargs)`, appelle la vue pour un result set complet ou nul

* `cell_call(row, col, **kwargs)`, appelle la vue pour une cellule donn�e d'un

  result set

* `url()`, retourne l'url permettant d'obtenir cette vue avec le result set en

  cours 

* `view(__vid, rset, __fallback_vid=None, **kwargs)`, appelle la vue

  d'identificant `__vid` sur le result set donn�. Il est possible de donn�es un

  identificant de vue de "fallback" qui sera utilis� si la vue demand�e n'est

  pas applicable au result set

* `wview(__vid, rset, __fallback_vid=None, **kwargs)`, pareil que `view` mais

  passe automatiquement le flux en argument

* `html_headers()`, retourne une liste d'en-t�te HTML � placer par le template

  principal 

* `page_title()`, retourne le titre � utiliser dans l'en t�te HTML `title`

* `creator(eid)`, retourne l'eid et le login du cr�ateur de l'entit� ayant

  l'eid pass� en argument

Autres classes de base :

* `EntityView`, vue s'appliquant � aux lignes ou cellule contenant une entit�

  (eg un eid)

* `StartupView`, vue de d�part n'ayant pas besoin de result set

* `AnyRsetView`, vue s'appliquant � n'importe quelle result set

Les templates ou patron

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

Les patrons (ou *template*) sont des cas particulier de vue ne d�pendant a

priori pas d'un result set. La classe de base `Template` (`cubicweb.common.view`)

est une classe d�riv�e de la classe `View`.

Pour construire une page HTML, un *template principal* est utilis�. G�n�ralement

celui poss�dant l'identifiant 'main' est utilis� (ce n'est pas le cas lors

d'erreur dans celui-ci ou pour le formulaire de login par exemple). Ce patron

utilise d'autres patrons en plus des vues d�pendants du contenu pour g�n�rer la

page � renvoyer.

C'est ce template qui est charg� :

1. d'�x�cuter la requ�te RQL des donn�es � afficher le cas �ch�ant

2. �ventuellement de d�terminer la vue � utiliser pour l'afficher si non

   sp�cifi�e

3. de composer la page � retourner

Le patron principal par d�faut (`cubicweb.web.views.basetemplates.TheMainTemplate`)

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

Le template principal par d�faut construit la page selon la d�composition

suivante :

.. image:: main_template_layout.png

Le rectancle contenant le `view.dispatch()` repr�sente l'emplacement o� est

ins�r� la vue de contenu � afficher. Les autres repr�sentent des sous-templates

appel� pour construire la page. Les impl�mentations par d�faut de tout ces

templates sont dans le module `cubicweb.web.views.basetemplates`. Vous pouvez

�videmment surcharger l'un des sous-templates pour modifier l'aspect visuel

d'une partie d�sir�e de la page.

On peut �galement contr�ler certains comportements du template principal �

l'aide des param�tres de formulaire suivante :

* `__notemplate`, si pr�sente (quelque soit la valeur associ�e), seule la vue de

  contenu est renvoy�e

* `__force_display`, si pr�sente et contient une valeur non nulle, pas de

  navigation quelque soit le nombre d'entit�s � afficher

* `__method`, si le result set � afficher ne contient qu'une entit� et que ce

  param�tre est sp�cifi�, celui-ci d�signe une m�thode � appeler sur l'entit�

  en lui donnant en argument le dictionnaire des param�tres de formulaire, avant

  de reprendre le comportement classique (s'ins�re entre les �tapes 1. et

  2. d�crites ci-dessus)

.. include:: sect_stdlib_vues.txt

Vues xml, binaires...

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

Pour les vues g�n�rants autre que du html  (une image g�n�r�e dynamiquement par

exemple), et qui ne peuvent donc g�n�ralement pas �tre incluse dans la page

HTML g�n�r�e par le template principal (voir ci-dessus), il faut :

* placer l'attribut `templatable` de la classe � `False`

* indiquer via l'attribut `content_type` de la classe le type MIME g�n�r� par la

  vue 'application/octet-stream'

Pour les vues g�n�rants un contenu binaire (une image g�n�r�e dynamiquement par

exemple), il faut �galement placer l'attribut `binary` de la classe � `True` (ce

qui implique `templatable == False` afin que l'attribut `w` de la vue soit

remplac� par un flux binaire plut�t que unicode.

Quelques trucs (X)HTML � respecter

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

Certains navigateurs (dont firefox) n'aime pas les `<div>` vides (par vide

j'entend sans contenu dans la balise, il peut y avoir des attributs), faut

toujours mettre `<div></div>` m�me s'il n'y a rien dedans, et non `<div/>`.