[#2534] Tests pour l'utilisation du formulaire ailleurs que dans l'admin
[auf_django_references.git] / doc / etablissements.rst
1 Extension locale des établissements de référence
2 ================================================
3
4 Il arrive qu'on veuille dresser une liste d'établissements qui contienne à la
5 fois des établissements provenant des données de référence et d'autres
6 établissements dont les données seront conservées dans une table locale à
7 l'application. Le module ``auf.django.references`` fournit un mécanisme pour créer
8 un modèle pour une liste d'établissements qui feront, pour certains, référence
9 aux données de référence.  Cette référence permettra leur mise à jour
10 périodique.
11
12 Pour créer le modèle, il suffit de créer une sous-classe de
13 ``auf.django.references.models.EtablissementBase``, comme ceci::
14
15     from auf.django.references import models as ref
16     from django.db import models
17
18     class Universite(ref.EtablissementBase):
19         recteur = models.CharField(max_length=200)
20
21 ``EtablissementBase`` est un modèle abstrait. Les modèles qui en héritent
22 auront tous les champs qu'un établissement de référence contient, plus un champ
23 ``ref`` qui sera le pointeur optionnel vers l'établissement de référence. Dans
24 l'exemple ci-haut, on définit en plus un champ ``recteur``. Ce champ s'ajoute au
25 modèle, comme on peut s'y attendre.
26
27 On peut créer des instances de ce nouveau modèle de deux façons différentes.
28 Pour créer une instance qui fait référence à un établissement de référence, on
29 fera, par exemple::
30
31     udem_ref = ref.Etablissement.objects.get(nom='Université de Montréal')
32     udem = Universite.objects.create(ref=udem_ref, recteur='Alice')
33
34 À la création, les données de ``udem_ref`` seront copiées dans ``udem``. Elles
35 seront aussi mises à jour à chaque sauvegarde de l'instance.
36
37 Pour créer une instance qui ne fait pas référence à un établissement de
38 référence, on omettra le champ ``ref``::
39
40     uqam = Universite.objects.create(nom='UQAM', pays_id='CA', recteur='Benoît')
41
42 Mise à jour des établissements avec les données de référence
43 ------------------------------------------------------------
44
45 Comme on l'a remarqué plus haut, les données des établissements de référence
46 sont copiées dans les établissements locaux qui y font référence lors de leur
47 création et de leur sauvegarde. Pour s'assurer que d'éventuels changements
48 aux données de référence soient propagés aux tables locales, il faut exécuter
49 périodiquement la commande Django ``sync_references``::
50
51     bin/django sync_references
52
53 Formulaire de création et d'édition des établissements
54 ------------------------------------------------------
55
56 Le module ``auf.django.references`` fournit un formulaire d'édition des
57 établissements qui offre en auto-complétion les établissements de référence
58 lorsqu'on entre le nom de l'établissement. Si un établissement de référence est
59 sélectionné, le champ ``ref`` est renseigné et les champs propres aux
60 établissements de référence sont pré-remplis et désactivés.
61
62 Le formulaire ``auf.django.references.forms.EtablissementForm`` est conçu pour
63 être sous-classé. En voici un exemple d'utilisation::
64
65     from auf.django.references.forms import EtablissementForm
66
67     class UniversiteForm(EtablissementForm):
68
69         class Meta(EtablissementForm.Meta):
70             model = Universite
71             fields = ('pays', 'nom', 'region', 'ville', 'recteur', 'ref')
72
73 Il importe d'inclure le champ ``ref`` dans le formulaire pour que la mécanique
74 fonctionne. Le champ n'apparaîtra pas sur la page, mais sera utilisé pour
75 communiquer la référence au besoin.
76
77 Pour que l'auto-complétion fonctionne, il faut aussi inclure les url patterns
78 d'``auf.django.references``. Dans votre ``urls.py``::
79
80     urlpatterns = patterns(
81         ...
82         (r'^references/', include('auf.django.references.urls')),
83         ...
84     )
85
86 On peut utiliser ce formulaire dans l'admin Django. Il suffit de le spécifier
87 dans la configuration de l'admin::
88
89     from django.contrib import admin
90
91     class UniversiteAdmin(admin.ModelAdmin):
92         form = UniversiteForm
93
94     admin.register(Universite, UniversiteForm)
95
96 On peut aussi utiliser le formulaire ailleurs. Dans ce cas, il faudra penser à
97 inclure les "media" associés pour que le javascript fonctionne. Par exemple:
98
99 .. code-block:: html+django
100
101     <html>
102       <head>
103         {{ form.media }}
104       </head>
105       <body>
106         <form action="" method="post">
107           <table>
108             {{ form }}
109           </table>
110         </form>
111       </body>
112     </html>