[#2534] Tests pour l'utilisation du formulaire ailleurs que dans l'admin
[auf_django_references.git] / doc / etablissements.rst
CommitLineData
652c5d02
EMS
1Extension locale des établissements de référence
2================================================
3
4Il arrive qu'on veuille dresser une liste d'établissements qui contienne à la
5fois 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 à
7l'application. Le module ``auf.django.references`` fournit un mécanisme pour créer
8un modèle pour une liste d'établissements qui feront, pour certains, référence
9aux données de référence. Cette référence permettra leur mise à jour
10périodique.
11
12Pour 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
22auront 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
24l'exemple ci-haut, on définit en plus un champ ``recteur``. Ce champ s'ajoute au
25modèle, comme on peut s'y attendre.
26
27On peut créer des instances de ce nouveau modèle de deux façons différentes.
28Pour créer une instance qui fait référence à un établissement de référence, on
29fera, 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
35seront aussi mises à jour à chaque sauvegarde de l'instance.
36
37Pour créer une instance qui ne fait pas référence à un établissement de
38référence, on omettra le champ ``ref``::
39
40 uqam = Universite.objects.create(nom='UQAM', pays_id='CA', recteur='Benoît')
41
42Mise à jour des établissements avec les données de référence
43------------------------------------------------------------
44
45Comme on l'a remarqué plus haut, les données des établissements de référence
46sont copiées dans les établissements locaux qui y font référence lors de leur
47création et de leur sauvegarde. Pour s'assurer que d'éventuels changements
48aux données de référence soient propagés aux tables locales, il faut exécuter
49périodiquement la commande Django ``sync_references``::
50
51 bin/django sync_references
52
53Formulaire de création et d'édition des établissements
54------------------------------------------------------
55
56Le module ``auf.django.references`` fournit un formulaire d'édition des
57établissements qui offre en auto-complétion les établissements de référence
58lorsqu'on entre le nom de l'établissement. Si un établissement de référence est
59sé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
62Le 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
73Il importe d'inclure le champ ``ref`` dans le formulaire pour que la mécanique
74fonctionne. Le champ n'apparaîtra pas sur la page, mais sera utilisé pour
75communiquer la référence au besoin.
76
77Pour que l'auto-complétion fonctionne, il faut aussi inclure les url patterns
78d'``auf.django.references``. Dans votre ``urls.py``::
79
80 urlpatterns = patterns(
81 ...
82 (r'^references/', include('auf.django.references.urls')),
83 ...
84 )
85
86On peut utiliser ce formulaire dans l'admin Django. Il suffit de le spécifier
87dans 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)
b8abf60c
EMS
95
96On peut aussi utiliser le formulaire ailleurs. Dans ce cas, il faudra penser à
97inclure 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>