Docs: custom index, custom ids

4 files changed, 221 insertions, 37 deletions

diff --git a/docs/fr/source/annexe-tech-3-variables.rst b/docs/fr/source/annexe-tech-3-variables.rst
new file mode 100644
index 000000000..bd17a6636
--- /dev/null
+++ b/docs/fr/source/annexe-tech-3-variables.rst
@@ -0,0 +1,155 @@
+.. -*- coding: utf-8 -*-
+
+.. _annexe-technique-3-variables:
+
+==============================
+Annexe technique 3 - Variables
+==============================
+
+:Auteur: Étienne Loks
+:Date: 2020-11-24
+:Copyright: CC-BY 3.0
+
+----------------------------------
+
+Ces variables sont utilisées pour les configurations des imports, les patrons de documents et la configuration des identifiants, des index personnalisés.
+
+Ces variables correspondent aux noms des champs utilisés en base de données (exemple : ``code_patriarche`` pour accéder au code patriarche d'une opération) ainsi que des « facilitateurs » qui permettent de disposer de champs plus évolués (exemple : ``get_next_index`` pour accéder au prochain numéro d'index).
+
+On peut passer d'un élément lié à un autre (par exemple, accéder à l'opération d'une unité d'enregistrement) avec la notation double tiret `__` et ensuite accéder aux variables de l'élément lié (exemple : ``operation__code_patriarche`` permet d'accéder au code patriarche de l'opération ).
+
+Ci-dessous la liste des variables pour chaque type d'éléments.
+
+Champs adresse
+==============
+
+Les champs adresse sont une liste de variables partagées par plusieurs éléments :
+
+- `address` : 
+- `address_complement` : 
+- `postal_code` : 
+- `town` : 
+- `precise_town` : 
+- `country` : 
+- `alt_address` : 
+- `alt_address_complement` : 
+- `alt_postal_code` : 
+- `alt_town` : 
+- `alt_country` : 
+- `phone` : 
+- `phone_desc` : 
+- `phone2` : 
+- `phone_desc2` : 
+- `phone3` : 
+- `phone_desc3` : 
+- `raw_phone` : 
+- `mobile_phone` : 
+- `email` : 
+- `alt_address_is_prefered` : 
+
+
+Champs géographiques
+====================
+
+Les champs géographiques sont une liste de variables partagées par plusieurs éléments :
+
+- `x` : 
+- `y` : 
+- `z` : 
+- `estimated_error_x` : 
+- `estimated_error_y` : 
+- `estimated_error_z` : 
+- `spatial_reference_system` : 
+- `point` : 
+- `point_2d` : 
+- `point_source` : 
+- `point_source_item` : 
+- `multi_polygon` : 
+- `multi_polygon_source` : 
+- `multi_polygon_source_item` : 
+
+
+
+Personne
+========
+
+Chaque personne dispose des champs adresse (cf. ci-dessus), ainsi que des champs suivants :
+
+- `title` : titre
+- `salutation` : formule d'appel
+- `surname` : prénom
+- `name` : nom
+- `raw_name` : nom + prénom
+- `contact_type__` : type de contact (`label` libellé, `txt_idx` identifiant textuel)
+- `comment` : commentaire
+- `person_types__` : types de personnes
+- `attached_to__` : organisation actuelle (-> organisation)
+- `cached_label` : nom généré depuis la formule `person_raw_name` du profil
+
+
+Opération
+=========
+
+Chaque opération dispose des champs géographiques (cf. ci-dessus), ainsi que des champs suivants :
+
+- `code_patriarche` : code patriarche (ou équivalent)
+- `year` : année de l'opération
+- `common_name` : nom générique
+- `operation_code` : code de l'opération
+- `start_date` : date de début du chantier
+- `excavation_end_date` : date de fin du chantier
+- `end_date` : date de cloture de l'opération
+- `report_delivery_date` : date de livraison du rapport
+- `scientist__` : responsable d'opération (-> personne)
+- `operator__` : opérateur (-> organisation)
+- `in_charge__` : responsable
+- `collaborators__` : collaborateurs
+- `creation_date` : date de création de l'élément en base de données
+- `associated_file__` : dossier archéologique associé (-> dossier archéologique)
+- `operation_type__` : type d'opération (`label` libellé, `txt_idx` identifiant textuel)
+- `surface` : surface totale (m²)
+- `remains__` : vestiges (`label` libellé, `txt_idx`: identifiant textuel)
+- `cached_remains` : cache textuel de la liste des vestiges - à utiliser pour l'affichage
+- `towns` : 
+- `cost` : 
+- `periods` : 
+- `scheduled_man_days` : 
+- `optional_man_days` : 
+- `effective_man_days` : 
+- `report_processing` : 
+- `old_code` : 
+- `fnap_financing` : 
+- `fnap_cost` : 
+- `zoning_prescription bool` : 
+- `large_area_prescription bool` : 
+- `geoarchaeological_context_prescription bool` : 
+- `cira_rapporteur` : 
+- `negative_result bool` : 
+- `cira_date` : 
+- `operator_reference` : 
+- `address` : 
+- `comment` : 
+- `scientific_documentation_comment` : 
+- `documents__` : 
+- `main_image__` : 
+- `cached_label` : 
+- `archaeological_sites` : 
+- `top_sites` : 
+- `virtual_operation bool` : 
+- `record_quality_type__` : 
+- `abstract` : 
+- `documentation_deadline` : 
+- `documentation_received` : 
+- `finds_deadline` : 
+- `finds_received bool` : 
+- `drassm_code` : 
+- `seizure_name` : 
+- `official_report_number` : 
+- `protagonist__` : 
+- `applicant_authority__` : 
+- `minutes_writer__` : 
+- `cached_towns_label` : 
+- `cached_periods` : 
+- `complete_identifier` : 
+- `custom_index` : 
+- `qrcode` : 
diff --git a/docs/fr/source/index.rst b/docs/fr/source/index.rst
index 8940b595d..96139b462 100644
--- a/docs/fr/source/index.rst
+++ b/docs/fr/source/index.rst
@@ -21,3 +21,4 @@ Contents:
    annexe-4-doc-normes
    annexe-tech-1-insee-communes
    annexe-tech-2-ign-communes
+   annexe-tech-3-variables
diff --git a/docs/fr/source/interface-administrateur.rst b/docs/fr/source/interface-administrateur.rst
index cf8057274..b9d8859ca 100644
--- a/docs/fr/source/interface-administrateur.rst
+++ b/docs/fr/source/interface-administrateur.rst
@@ -37,7 +37,7 @@ Dans les pages d'administration, les listes de types se retrouvent sous les dén
 Dans Ishtar, chaque type est défini au minimum par les champs suivants :
 
 - **Dénomination**
-- **Identifiant textuel** : L'identifiant textuel est une version standardisée du nom. Il ne contient que des lettres en minuscule non accentuées, des nombres et des tirets (-). Chaque identifiant textuel doit être unique dans la liste de types. Ces identifiants sont des clés permettant les échanges entre bases de données et pour des traductions. Ces identifiants peuvent être utilisés dans le code source de l'application. Une fois créés il ne faut a priori pas changer ces identifiants textuels.
+- **Identifiant textuel** : L'identifiant textuel est une version standardisée du nom. Il ne contient que des lettres en minuscules non accentuées, des nombres et des tirets (-). Chaque identifiant textuel doit être unique dans la liste de types. Ces identifiants sont des clés permettant les échanges entre bases de données et pour des traductions. Ces identifiants peuvent être utilisés dans le code source de l'application. Une fois créés il ne faut a priori pas changer ces identifiants textuels.
 - **Commentaire** : Le contenu du commentaire est affiché dans l'aide en ligne sur les formulaires.
 - **Disponibilité** : Décocher ce champ rend indisponible ce type dans les formulaires, sans détruire l'information pour ce qui est déjà présent en base ; l'information est toujours visible dans les fiches.
 - **Ordre** : Dans les listes les champs sont ordonnés par ce numéro d'ordre et en cas d'égalité par ordre alphabétique.
@@ -73,7 +73,7 @@ Les différentes données à rentrer sont :
   * Date : un composant permettant le choix de date depuis un calendrier est proposé,
   * Choix : un composant en autocomplétion sur les valeurs existantes est proposé. L'utilisateur a la possibilité de rentrer librement de nouvelles valeurs.
 
-* **Ordre** : Le numéro saisie permet d'ordonner par défaut ce champ par rapport aux autres champs.
+* **Ordre** : Le numéro saisi permet d'ordonner par défaut ce champ par rapport aux autres champs.
 * **Section** : La section correspond à un titre de section pour présenter ce champ sur la fiche et permettre des regroupements.
 * **Utiliser dans les index de recherche** : Si cette case est cochée, la recherche libre indexera le contenu de ce champ.
 * **Afficher** : Si cette case n'est pas cochée, ce champ ne sera pas affiché sur la fiche.
@@ -96,7 +96,7 @@ La création se fait en deux temps, d'abord un paramétrage des champs de base p
 Le paramétrage de base demande les champs suivants :
 
 * **Nom** : le nom correspondant au formulaire personnalisé. Ce nom ne sera visible qu'en administration mais pour s'y retrouver, il doit à la fois reprendre le nom du formulaire ainsi que le contexte pour lequel il a été défini. Par exemple : « Mobilier - 020 - Général - Tout utilisateur » ou « Mobilier - 030 - Conservation - Saisie terrain ».
-* **Formulaire** : le formulaire à personnaliser. Le nom utilisé permet d'identifier assez simplement le formulaire correspondant car il correspond dans l'ordre (séparé par des tirets) au :
+* **Formulaire** : le formulaire à personnaliser. Le nom utilisé permet d'identifier assez simplement le formulaire correspondant, car il correspond dans l'ordre (séparé par des tirets) au :
 
   * type d'objet concerné (par exemple : « Mobilier »),
   * éventuellement, le numéro d'ordre dans les formulaires successifs,
@@ -110,7 +110,7 @@ Le paramétrage de base demande les champs suivants :
 Une fois ce paramétrage de base enregistré, la configuration précise du formulaire peut se faire :
 
 * **champs à exclure** : chaque champ de base présent dans le formulaire actuel peut être sélectionné dans la liste pour être écarté de la saisie.
-* **champs JSON** : tous les champs JSON préalablement paramétrés concernant l'élément courant (mobilier, OA, ...) peuvent être sélectionnés. La dénomination permet éventuellement de surcharger le nom par défaut du champ JSON. L'ordre permet de placer le champ dans le formulaire. L'aide permet éventuellement d'ajouter un texte pour aider à la saisie.
+* **champs JSON** : tous les champs JSON préalablement paramétrés concernant l'élément courant (mobilier, OA...) peuvent être sélectionnés. La dénomination permet éventuellement de surcharger le nom par défaut du champ JSON. L'ordre permet de placer le champ dans le formulaire. L'aide permet éventuellement d'ajouter un texte pour aider à la saisie.
 
 .. warning:: Sur les formulaires de création, il est impératif de ne pas exclure des champs obligatoires sans quoi la création devient impossible.
 
@@ -140,7 +140,7 @@ Les permissions dans Ishtar sont essentiellement gérées par « Type de profil
 
 La création/configuration d'un type de profil se fait via : *Ishtar - Commun › Types de profil* :
 
-- **dénomination** : ce champ doit être explicite car il va être retrouvé au niveau de l'interface utilisateur.
+- **dénomination** : ce champ doit être explicite, car il va être retrouvé au niveau de l'interface utilisateur.
 - **identifiant textuel** : rempli selon les règles habituelles des identifiants textuels.
 - **groupes** : listes des groupes auxquels le profil est rattaché.
 
@@ -150,7 +150,7 @@ Chaque groupe correspond à un type de permission pour un élément précis de l
 - droit d'ajout ;
 - droit de modification/suppression.
 
-Chacun de ces droit est décliné en deux modalités :
+Chacun de ces droits est décliné en deux modalités :
 
 - droits sur tous les éléments ;
 - droit sur les éléments rattachés.
@@ -182,9 +182,9 @@ Patrons de documents
 Principes de base
 *****************
 
-Ishtar propose une génération automatisée de document. Depuis un patron au format LibreOffice (ODT), les données relatives à un élément (acte administratif, mobilier, ...) remplacent les variables du patron pour obtenir le document désiré.
+Ishtar propose une génération automatisée de document. Depuis un patron au format LibreOffice (ODT), les données relatives à un élément (acte administratif, mobilier...) remplacent les variables du patron pour obtenir le document désiré.
 
-On créé le patron au format ODT avec un contenu adapté, puis depuis l'interface d'administration, sous l'entrée *Ishtar - Commun › Patrons de document › Document de référence*, on créé un patron de document avec ce fichier ODT associé au type d'élément pour lequel il est destiné.
+On crée le patron au format ODT avec un contenu adapté, puis depuis l'interface d'administration, sous l'entrée *Ishtar - Commun › Patrons de document › Document de référence*, on créé un patron de document avec ce fichier ODT associé au type d'élément pour lequel il est destiné.
 
 Le document peut alors être généré depuis n'importe quelle fiche de l'élément concerné (en haut à droite sous « Documents »).
 
@@ -203,19 +203,65 @@ Ensuite, il faut récupérer un document de référence généré depuis la fich
 
 On ouvre ce document sous LibreOffice. Le document produit contient une liste de clé avec la valeur associée concernant l'élément que l'on a choisi.
 
-Les différentes clés vont permettre de constituer un patron répondant à ce qui est attendu. Pour cela reprendre un exemple du document que l'on souhaite générer (toujours au format ODT) et remplacer chaque occurence d'une valeur par la clé entourée de deux acccolades, exemple : ::
+Les différentes clés vont permettre de constituer un patron répondant à ce qui est attendu. Pour cela reprendre un exemple du document que l'on souhaite générer (toujours au format ODT) et remplacer chaque occurence d'une valeur par la clé en reprenant la :ref:`syntaxe Jinja <formules-syntaxe-jinja>` (Jinja est le nom de la bibliothèque utilisée).
+Une fois quelques substitutions faites, on peut l'enregistrer et créer le patron dans l'interface d'administration Ishtar. Ce premier patron est alors disponible depuis la fiche des éléments.
 
-        Je, sousigné, {{nom_de_ma_clef_1}}, vous accorde un prêt de {{nom_ma_clef_2}}.
 
-Une fois quelques substitutions faites, on peut l'enregistrer et créer le patron dans l'interface d'administration Ishtar. Ce premier patron est alors disponible depuis la fiche des éléments.
+.. _configuration-instance-ishtar:
+
+Configuration du profil d'instance Ishtar
+-----------------------------------------
+
+*En cours de rédaction...*
+
+Identifiants et index personnalisés
+***********************************
+
+Pour chaque type d'élément principal, il est possible de configurer le profil Ishtar pour personnaliser :
+
+- l'identifiant externe : c'est un identifiant textuel unique dans la base qui permet de faire des rapprochements de manière non ambiguë. Il est souvent utilisé pour les imports. Par exemple, un identifiant externe pour les unités d'enregistrement peut être "code patriarche de l'opération-identifiant de l'unité d'enregistrement" ou alors "code patriarche de l'opération-section parcelle-numéro parcelle-identifiant de l'unité d'enregistrement". Des identifiants externes sont paramétrés par défaut pour chaque type d'élément principale. Note : l'identifiant externe de l'opération est toujours le code patriarche et n'est pas paramétrable.
+- l'identifiant complet (optionnel) : cet identifiant est un identifiant de gestion paramétrable. Cet identifiant peut par exemple se distinguer de l'identifiant externe pour incorporer des codes matières.
+- clés pour index personnalisé : un index personnalisé peut être défini en fonction d'une ou plusieurs clés reprenant les champs. Par exemple une clé opération peut être utilisée pour générer un index numérotant de 1 à n le mobilier sur une opération.
+
+Pour définir identifiant externes et identifiant complet, on utilise des formules. Deux types de syntaxes sont utilisées : une :ref:`syntaxe simple <formules-syntaxe-simple>` et une :ref:`syntaxe Jinja <formules-syntaxe-jinja>` (nom de la bibliothèque utilisée). Ces deux syntaxes utilisent des variables relatives à l'élément. L'utilisation de ces variables est explicitée dans l':ref:`annexe technique 3 - variables <annexe-technique-3-variables>`.
+
+
+
+Formules
+--------
+
+.. _formules-syntaxe-simple:
+
+Syntaxe simple
+**************
+
+Cette syntaxe permet d'utiliser directement les variables en utilisant la notation accolade simple ``{}``. Par exemple : ::
+
+   OA-{code_patriarche}
+
+Cette notation se traduira ainsi par des rendus comme : `OA-061234` ou `OA-44789`.
+
+
+.. _formules-syntaxe-jinja:
+
+Syntaxe Jinja
+*************
+
+Cette syntaxe permet de faire de faire des substitutions de manière plus fine qu'avec la syntaxe simple. Cette syntaxe est utilisée systématiquement pour les patrons de document, un sous-ensemble de cette syntaxe (variables et structures conditionnelles) peut-être utilisée optionnellement pour les identifiants personnalisés.
+
+Variables
++++++++++
+
+L'accès aux `variables <annexe-technique-3-variables>` se fait par la notation double accolade ``{{ }}``.
+Ainsi par exemple, pour accéder aux variables `nom_de_ma_clef_1` et `nom_de_ma_clef_2` : ::
+
+        Je, soussigné, {{nom_de_ma_clef_1}}, vous accorde un prêt de {{nom_ma_clef_2}}.
 
-Notions avancées
-****************
 
 Conditions
 ++++++++++
 
-Des structures conditionnelles peuvent être mise en place. Cela permet notamment de tester si une valeur a été renseignée et de permettre de contextualiser l'affichage en fonction de cela. Exemple : ::
+Des structures conditionnelles peuvent être mises en place. Cela permet notamment de tester si une valeur a été renseignée et de permettre de contextualiser l'affichage en fonction de cela. Exemple : ::
 
         Ce traitement sous
         {% if responsable %}la responsabilité de {{responsable}}
@@ -224,11 +270,6 @@ Des structures conditionnelles peuvent être mise en place. Cela permet notammen
 
 Les structures conditionnelles se structurent autour des mots clés ``if``, ``else`` et ``endif``. On utilise ``{%`` et ``%}`` autour de ces mots clés. La section ``else`` est facultative.
 
-Attributs
-+++++++++
-
-Les valeurs utilisées dans les patrons peuvent avoir des attributs correspondant aux noms des colonnes des tables d'éléments utilisés en base de données. Ces attributs sont accédés avec la notation ``.`` . Par exemple, si l'élément a un attribut ``nom``, on accède à la valeur de cet élément avec ``{{element.nom}}``.
-
 
 Parcours de liste
 +++++++++++++++++
@@ -242,17 +283,16 @@ Certaines clés peuvent parfois renvoyer à des listes d'éléments, chacun ayan
 Cela se structure autour des mots clés ``for``, ``in`` et ``endfor``. Au lieu de doubles accolades, ``{%`` et ``%}`` encadrent ces mots clés.
 
 .. 
+  Filtres
+  +++++++
+  {{|filtre}}
+
+..
   Images
   ++++++
-
   Il est possible d'utiliser des images dans les patrons. Pour cela il faut placer une image dans le document du patron et modifier son attribut nom sous LibreOffice (clic droit sur l'image, « Propriétés... » et l'onglet « Options ») par une chaîne sous la forme ``{{ mon_image|image }}``. ``mon_image`` correspond au champ image
 
-.. _configuration-instance-ishtar:
 
-Configuration du profil d'instance Ishtar
------------------------------------------
-
-*En cours de rédaction...*
 
 .. 
   TODO: Profil d'instance Ishtar
diff --git a/docs/fr/source/principes.rst b/docs/fr/source/principes.rst
index 772899ce7..542b9307d 100644
--- a/docs/fr/source/principes.rst
+++ b/docs/fr/source/principes.rst
@@ -175,18 +175,6 @@ Notions avancées
 ================
 
 
-Identifiants et index personnalisés
------------------------------------
-
-Pour chaque type d'élément principal, il est possible de configurer le profil Ishtar pour personnaliser :
-
-- l'identifiant externe : c'est un identifiant textuel unique dans la base qui permet de faire des rapprochements de manière non ambigu. Il est souvent utilisé pour les imports. Par exemple, un identifant externe pour les unités d'enregistrement peut être "code patriarche de l'opération-identifiant de l'unité d'enregistrement" ou alors "code patriarche de l'opération-section parcelle-numéro parcelle-identifiant de l'unité d'enregistrement". Des identifiants externes sont paramétrés par défaut pour chaque type d'élément principale. Note : l'identifiant externe de l'opération est toujours le code patriarche et n'est pas paramétrable.
-- l'identifiant complet (optionnel) : cet identifiant est un identifiant de gestion paramétrable. Cet identifiant peut par exemple se distinguer de l'identifiant externe pour incorporer des codes matières.
-- clés pour index personnalisé : un index personnalisé peut être défini en fonction d'une ou plusieurs clés reprenant les champs. Par exemple une clé opération peut être utilisée pour générer un index numérotant de 1 à n le mobilier sur une opération.
-
-
-
-
 Données géographiques
 ---------------------