[reledit] do NOT propose to edit composite-related entities (unlinking would destroy the other side)
.. -*- 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`.