.. -*- coding: utf-8 -*-

Gestion de formulaires

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

Contrôle de la génération automatique de formulaire pour les entités manipulée

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

XXX FILLME

* les formulaires 'edition' et 'creation'

Le formulaire généré par défaut ne vous convient pas ? Vous êtes peut-être pas

obligé de le refaire à la main ! :)

* rtags primary, secondary, generated, generic,

  `Entity.relation_category(rtype, x='subject')`

* inline_view (now a rtag?)

* spécification widget

Fonctionnement du contrôleur d'édition par défaut (id: 'edit')

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

Contrôle de l'édition

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

Prérequis: les paramètres liés aux entités à éditer sont spécifiés de la forme ::

  <nom de champ>:<eid de l'entité>

où l'eid de l'entité pourra être une lettre dans le cas d'une entité à créer. On

dénommera ces paramètres comme *qualifié*.

1. récupération des entités à éditer en cherchant les paramètres de formulaire

   commençant par 'eid:' ayant également un paramètre '__type' associé

   (également *qualifié* par l'eid évidemment)

2. pour tous les attributs et relations de chaque entité à éditer

   1. recherche d'un paramètre 'edits-<nom relation>' ou 'edito-<nom relation>'

      qualifié dans le cas d'une relation dont l'entité est objet

   2. si trouvé, la valeur récupérée est considérée comme la valeur originale

      pour cette relation, et on cherche la (ou les) nouvelle(s) valeur(s) dans

      le paramètre <nom relation> (qualifié)

   3. si la valeur est différente de l'originale, une requête de modification en

      base est effectuée

3. pour chaque entité à éditer

   1. si un paramètre `__linkto` qualifié est spécifié, sa valeur doit être une

      chaine (ou une liste de chaine) de la forme : ::

        <relation type>:<eids>:<target>

      où <target> vaut 'subject' ou 'object' et chaque eid peut-être séparé d'un

      autre par un '_'. Target spécifie *l'entité éditée* est sujet ou objet de la

      relation et chaque relation ainsi spécifiée sera insérée.

   2. si un paramètre `__cloned_eid` qualifié est spécifié pour une entité, les

      relations de l'entité spécifiée en valeur de cette argument sont copiées sur

      l'entité éditée

   3. si un paramètre `__delete` qualifié est spécifié, sa valeur doit être une

      chaine (ou une liste de chaine) de la forme : ::

	<subject eids>:<relation type>:<object eids>

      où chaque eid sujet ou objet peut-être séparé d'un autre par un '_'. Chaque

      relation ainsi spécifiée sera supprimée.

   4. si un paramètre `__insert` qualifié est spécifié, sa valeur doit être de

      même format que pour `__delete`, mais chaque relation ainsi spécifiée sera 

      insérée.

4. si les paramètres `__insert` et/ou  `__delete` sont trouvés non qualifiés,

   ils sont interprétés comme décrit ci-dessus (quelque soit le nombre d'entité

   édité)

5. si aucune entité n'est éditée mais que le formulaire contient les paramètres

   `__linkto` et `eid`, celui-ci est interprété en prenant la valeur spécifié

   par le paramètre `eid` pour désigner l'entité sur laquelle ajouter les

   relations

A noter que :

* si le paramètre `__action_delete` est trouvé, toutes les entités comme

  spécifiées à éditer seront supprimées

* si le paramètre `__action_cancel` est trouvé, aucune action n'est effectuée

* si le paramètre `__action_apply` est trouvé, l'édition est effectuée

  normalement mais la redirection sera effectuée sur le formulaire (cf `Contrôle

  de la redirection`_)

* le paramètre `__method` est également supporté comme sur le template principal

  (XXX not very consistent, maybe __method should be dealed in the view controller) 

* si aucune entité à éditer n'est trouvée et qu'il n'y a pas de paramètre

  `__action_delete`, `__action_cancel`, `__linkto`, `__delete` ou `__insert`,

  une erreur est levée

* placer dans le formulaire le paramètre `__message` permettra d'utiliser la

  valeur de ce paramètre comme message d'information à l'utilisateur une fois

  l'édition effectuée.

Contrôle de la redirection

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

Une fois que l'édition s'est bien passé, reste un problème : c'est bien beau

tout ça, mais où qu'on va maintenant ?? Si rien n'est spécifié, le controlleur

se débrouille, mais comme il fait pas toujours ce qu'on voudrait, on peut

controller ça en utilisant les paramètres suivant :

* `__redirectpath`: chemin de l'url (relatif à la racine du site, sans paramètre

  de formulaire

* `__redirectparams`: paramètres de formulaires à ajouter au chemin

* `__redirectrql`: requête RQL de redirection

* `__redirectvid`: identifiant de vue de redirection

* `__errorurl`: url du formulaire original, utilisé pour la redirection en cas

  d'erreur de validation pendant l'édition. Si celui-ci n'est pas spécifié, une

  page d'erreur sera présentée plutot qu'un retour sur le formulaire (qui est le

  cas échéant responsable d'afficher les erreurs)

* `__form_id`: identifiant de vue du formulaire original, utilisée si

  `__action_apply` est trouvé

En général on utilise soit `__redirectpath et `__redirectparams` soit

`__redirectrql` et `__redirectvid`.