1 .. -*- coding: utf-8 -*- |
|
2 |
|
3 |
|
4 Définition de vues |
|
5 ================== |
|
6 |
|
7 Les classes de base des vues |
|
8 ---------------------------- |
|
9 |
|
10 La class `View` (`cubicweb.common.view`) |
|
11 ````````````````````````````````````` |
|
12 Un vue écrit dans son flux de sortie via son attribut `w` (`UStreamIO`). |
|
13 |
|
14 L'interface de base des vues est la suivante : |
|
15 |
|
16 * `dispatch(**context)`, appelle ("rend") la vue en appellent `call` ou |
|
17 `cell_call` en fonction des arguments passé |
|
18 * `call(**kwargs)`, appelle la vue pour un result set complet ou nul |
|
19 * `cell_call(row, col, **kwargs)`, appelle la vue pour une cellule donnée d'un |
|
20 result set |
|
21 * `url()`, retourne l'url permettant d'obtenir cette vue avec le result set en |
|
22 cours |
|
23 * `view(__vid, rset, __fallback_vid=None, **kwargs)`, appelle la vue |
|
24 d'identificant `__vid` sur le result set donné. Il est possible de données un |
|
25 identificant de vue de "fallback" qui sera utilisé si la vue demandée n'est |
|
26 pas applicable au result set |
|
27 |
|
28 * `wview(__vid, rset, __fallback_vid=None, **kwargs)`, pareil que `view` mais |
|
29 passe automatiquement le flux en argument |
|
30 |
|
31 * `html_headers()`, retourne une liste d'en-tête HTML à placer par le template |
|
32 principal |
|
33 |
|
34 * `page_title()`, retourne le titre à utiliser dans l'en tête HTML `title` |
|
35 |
|
36 * `creator(eid)`, retourne l'eid et le login du créateur de l'entité ayant |
|
37 l'eid passé en argument |
|
38 |
|
39 Autres classes de base : |
|
40 |
|
41 * `EntityView`, vue s'appliquant à aux lignes ou cellule contenant une entité |
|
42 (eg un eid) |
|
43 * `StartupView`, vue de départ n'ayant pas besoin de result set |
|
44 * `AnyRsetView`, vue s'appliquant à n'importe quelle result set |
|
45 |
|
46 Le mecanisme de selection de vues |
|
47 --------------------------------- |
|
48 |
|
49 Pour un identifiant de vue donne, plusieurs vues peuvent etre definies. |
|
50 `CubicWeb` utilise un selecteur qui permet de calculer un score et d'identifier |
|
51 la vue la plus appropriee a appliquer dans le contexte. La librairie du selecteur |
|
52 se trouve dans ``cubicweb.common.selector`` et une librairie des methodes utilisees |
|
53 pour calculer les scores est dans ``cubicweb.vregistry.vreq``. |
|
54 |
|
55 |
|
56 [FILLME] |
|
57 |
|
58 Les templates ou patron |
|
59 ----------------------- |
|
60 |
|
61 Les patrons (ou *template*) sont des cas particulier de vue ne dépendant a |
|
62 priori pas d'un result set. La classe de base `Template` (`cubicweb.common.view`) |
|
63 est une classe dérivée de la classe `View`. |
|
64 |
|
65 Pour construire une page HTML, un *template principal* est utilisé. Généralement |
|
66 celui possédant l'identifiant 'main' est utilisé (ce n'est pas le cas lors |
|
67 d'erreur dans celui-ci ou pour le formulaire de login par exemple). Ce patron |
|
68 utilise d'autres patrons en plus des vues dépendants du contenu pour générer la |
|
69 page à renvoyer. |
|
70 |
|
71 C'est ce template qui est chargé : |
|
72 |
|
73 1. d'éxécuter la requête RQL des données à afficher le cas échéant |
|
74 2. éventuellement de déterminer la vue à utiliser pour l'afficher si non |
|
75 spécifiée |
|
76 3. de composer la page à retourner |
|
77 |
|
78 |
|
79 Le patron principal par défaut (`cubicweb.web.views.basetemplates.TheMainTemplate`) |
|
80 -------------------------------------------------------------------------------- |
|
81 |
|
82 Le template principal par défaut construit la page selon la décomposition |
|
83 suivante : |
|
84 |
|
85 .. image:: main_template_layout.png |
|
86 |
|
87 Le rectancle contenant le `view.dispatch()` représente l'emplacement où est |
|
88 inséré la vue de contenu à afficher. Les autres représentent des sous-templates |
|
89 appelé pour construire la page. Les implémentations par défaut de tout ces |
|
90 templates sont dans le module `cubicweb.web.views.basetemplates`. Vous pouvez |
|
91 évidemment surcharger l'un des sous-templates pour modifier l'aspect visuel |
|
92 d'une partie désirée de la page. |
|
93 |
|
94 On peut également contrôler certains comportements du template principal à |
|
95 l'aide des paramètres de formulaire suivante : |
|
96 |
|
97 * `__notemplate`, si présente (quelque soit la valeur associée), seule la vue de |
|
98 contenu est renvoyée |
|
99 * `__force_display`, si présente et contient une valeur non nulle, pas de |
|
100 navigation quelque soit le nombre d'entités à afficher |
|
101 * `__method`, si le result set à afficher ne contient qu'une entité et que ce |
|
102 paramètre est spécifié, celui-ci désigne une méthode à appeler sur l'entité |
|
103 en lui donnant en argument le dictionnaire des paramètres de formulaire, avant |
|
104 de reprendre le comportement classique (s'insère entre les étapes 1. et |
|
105 2. décrites ci-dessus) |
|
106 |
|
107 |
|
108 .. include:: sect_stdlib_vues.txt |
|
109 |
|
110 |
|
111 Vues xml, binaires... |
|
112 --------------------- |
|
113 Pour les vues générants autre que du html (une image générée dynamiquement par |
|
114 exemple), et qui ne peuvent donc généralement pas être incluse dans la page |
|
115 HTML générée par le template principal (voir ci-dessus), il faut : |
|
116 |
|
117 * placer l'attribut `templatable` de la classe à `False` |
|
118 * indiquer via l'attribut `content_type` de la classe le type MIME généré par la |
|
119 vue 'application/octet-stream' |
|
120 |
|
121 Pour les vues générants un contenu binaire (une image générée dynamiquement par |
|
122 exemple), il faut également placer l'attribut `binary` de la classe à `True` (ce |
|
123 qui implique `templatable == False` afin que l'attribut `w` de la vue soit |
|
124 remplacé par un flux binaire plutôt que unicode. |
|
125 |
|
126 |
|
127 Quelques trucs (X)HTML à respecter |
|
128 ---------------------------------- |
|
129 Certains navigateurs (dont firefox) n'aime pas les `<div>` vides (par vide |
|
130 j'entend sans contenu dans la balise, il peut y avoir des attributs), faut |
|
131 toujours mettre `<div></div>` même s'il n'y a rien dedans, et non `<div/>`. |
|