Créer de multiples fiches :
un formulaire de création

Si la mise à disposition d'une fiche vierge via l'arborescence des modèles est le mode le plus naturel dans Storga, il existe deux raisons de le faire plus classiquement, via la mise à disposition d'un formulaire de création d'une nouvelle fiche.
1. L'utilisation d'une fiche vierge mise à disposition dans l'arborescence des modèles nécessite de préalablement se déplacer dans l'arborescence vers la page ou sera stockée la nouvelle fiche, et donc éventuellement de créer à la main cette page. Dans certains cas, on préfère disposer d'un bouton qui va automatiquement créer la page au bon endroit et y ranger la fiche.
2. Certains utilisateurs, conditionnés par l'utilisation de bases de données traditionnelles, où la création d'une nouvelle fiche se fait toujours via un menu de création, peuvent avoir du mal à se familiariser avec l'utilisation de l'arborescence des modèles.

Dans cette leçon, nous allons donc étudier la mise à disposition d'un formulaire de création de fiche. Rappelez vous simplement que rien n'interdit de proposer les deux moyens.

Un formulaire de création

Voici un exemple de formulaire de création de la fiche organisation que nous avions étudiée lors d'une précédente leçon.

Si vous copiez cet exemple, le programme qu'il contient va se mettre en erreur : Unknown name 'organisations_list'.

if button_name="create"
  # vérifications initiales
  if organisation=""
    error "Vous devez indiquer le nom de la nouvelle organisation"
  if (lookup_form_id @organisations_list organisation organisation)<>""
    error "Cette fiche organisation existe déjà"
  # créer la nouvelle fiche, dans la bonne sous page, y copier le champ 'organisation' et afficher la nouvelle fiche
  new_form @organisation_model page @organisations_folders subpage (organisation 0 1) (organisation 0 1) subpage organisation organisation url_call copy_fields
    void
  # réinitialiser les champs du formulaire de création
  organisation := ""

Pour visualiser le contenu du programme, en mode éditer, cliquez sur '✸' pour sélectionner le programme, puis sur le bouton 'Listing' de son menu contextuel. On constate que ce programme utilise trois noms de blocs, qui sont 'organisations_list', 'organisation_model' et 'organisations_folders'. On remarque aussi immédiatement que dans un programme, les noms sont précédés du symbole '@'.
Nous allons revenir plus en détail sur ce programme un peu plus loin, mais constatons dès à présent que pour fonctionner, le programme nécessite des ressources supplémentaires qui sont l'état listant les organisations déjà crées, une fiche organisation vierge, et une page où ranger les nouvelles fiches organisations.

L'état est celui que nous avons créé lors d'une leçon précédente, auquel nous avons donné le nom 'organisations_list'.

Voici maintenant le modèle, qui porte le nom 'organisation_model' :

Et voici enfin la page qui défini l'arborescence dans laquelle ranger les nouvelles fiches organisations. Elle porte le nom 'organisations_folders' :

Une fois installés ces trois éléments, le formulaire de création devrait fonctionner.

Détail du programme

Cette partie est un peu longue, parce que c'est la première fois, au niveau de ce cours d'autoformation, que l'on commente un programme réel, donc il y a beaucoup d'éléments à voir, même s'il s'agit d'un programme assez simple. Les personnes ayant des notions de programmation pourront lire plus rapidement.

Commençons par remarquer que le formulaire de création d'une fiche organisation est lui même un formulaire, auquel il est habituel de donner le type 'applet' ce qui signifie que le formulaire ne contient pas des données réelles que l'on pourrait souhaiter collecter dans des états, mais juste des champs de paramètres, ici le nom de la nouvelle organisation.

Revenons maintenant au programme, élément par élément :

if button_name="create"
  ...

Cette première ligne permet de tester que l'on a bien pressé le bouton 'Créer la fiche'.
Dans le programme, 'button_name' n'est pas entre double guillements parce qu'il s'agit d'un nom de variable, ou d'un mot clé du langage. A l'inverse, le mot 'create' est placé entre doubles guillemets parce qu'il s'agit d'une valeur littérale de type chaîne de caractères.

De plus, concernant cette première ligne, dans Storga on n'écrit pas 'if ... endif' comme dans certains langages. On se contente d'indenter le code conditionnel, c'est à dire le décaler vers la droite.
Par exemple, si l'on écrit :

if a=3
  b := 5
c := 6

le programme se lit : si 'a' vaut 3, alors mettre 5 dans 'b', et dans tous les cas, mettre 6 dans 'c'. Ce programme montre aussi que dans Storga, le signe '=' représente la comparaison, et qu'une affectation est spécifiée par le symbole ':='.

Continuons la lecture de notre programme initial :

# vérifications initiales

sur une ligne, tout ce qui suit le signe '#' est un simple commentaire (sauf si le signe '#' se trouve à l'intérieur d'une chaîne de caractères littérale).

Continuons :

if organisation=""
  error "Vous devez indiquer le nom de la nouvelle organisation"

se lit : si le champ 'organisation' est vide, alors affichons le message d'erreur 'Vous devez indiquer le nom de la nouvelle organisation'.
Remarquez à nouveau que le signe '=' signifie une comparaison dans Storga.
Les deux doubles guillemets à la suite représentent la chaîne de caractère vide.

Continuons :

if (lookup_form_id @organisations_list organisation organisation)<>""
  error "Cette fiche organisation existe déjà"

'lookup_form_id' est une fonction qui cherche la ligne d'un état pour laquelle la valeur d'une colonne donnée correspond à la valeur donnée, et retourne le code Storga de la fiche correspondante, ou la chaîne vide si la valeur demandée n'a pas été trouvée. Rappelez vous que dans Storga, chaque bloc, donc chaque fiche, se voit attribuer un code unique et permanent au moment de sa création.
Voici le détail des paramètres de la fonction 'lookup_form_id' :

Dans cet extrait de code le second et troisième paramètre passés à la fonction 'lookup_form_id' sont identiques, en l'occurrence l'identifiant 'organisation', mais il n'ont pas pour autant la même signification. Pour le second paramètre, il s'agit du nom d'une colonne que Storga cherchera dans l'état. Pour le troisième, il s'agit de la valeur à chercher, qui est celle du champ 'organisation' du formulaire de création.
Donc l'instruction 'lookup_form_id' dans ce programme peut se lire sous la forme : dans l'état dont le nom est 'organisations_list', c'est à dire la liste des organisations, chercher le code de la fiche dont le champ 'organisation' correspond à celui du formulaire de création dans lequel se trouve le présent programme.
Ensuite, la condition '<>""' sur la fin de la ligne peut se lire : est-ce que la fiche existe, c'est à dire est-ce que le nom d'organisation existe déjà. D'où le fait que si si la condition est vraie, on affiche le message d'erreur 'Cette fiche organisation existe déjà'.

Remarquez aussi qu'avec Storga, le parenthèsage d'une fonction englobe aussi le nom de la fonction comme dans le langage informatique LISP, et pas seulement la liste de ses paramètres comme en mathématiques ou dans la majorité des langages informatiques.

Pas de panique si cette instruction 'lookup_form_id' n'est pas compréhensible pour vous lors de la première lecture. Le but est pour l'instant de juste avoir une idée de ce que font les programmes Storga mis à votre disposition. C'est petit à petit que vous écrirez vos propres programmes, au début par analogie et légère adaptation de programmes existants. De plus, on peut déjà faire beaucoup de choses avec Storga sans écrire des programmes, juste avec quelques formules simples au niveau des états.

Continuons la lecture de ce premier programme :

new_form @organisation_model page @organisations_folders subpage (organisation 0 1) (organisation 0 1) subpage organisation organisation url_call copy_fields
  void

L'instruction 'new_form' crée la nouvelle fiche.
Son premier paramètre, ici '@organisation_model' désigne le modèle de fiche à utiliser.
Les paramètres suivants sont optionnels.

Ici, 'page @organisations_folders' demande de créer la fiche dans la page dont le nom est indiqué, ou plus exactement :
'subpage (organisation 0 1) (organisation 0 1)' demande de créer une première sous page dans cette page, dont le nom et le code seront tous deux '(organisation 0 1)' qui signifie la première lettre du nom de l'organisation.
En effet, dans Storga, si 'c' est une châine de caractère, alors '(c x y)' désigne la sous chaîne de caractères commençant au caractère 'x' et comprenant au plus 'y' caractères, sachant que dans une chaîne de caractères Storga, comme c'est classiquement le cas en informatique, le premier caractère porte l'indice zéro et nom l'indice un.
Les paramètre suivant sont 'subpage organisation organisation' qui demande de créer une nouvelle sous page, dont le code et le titre seront le nom de l'organisation.
L'ensemble 'page @organisations_folders subpage (organisation 0 1) (organisation 0 1) subpage organisation organisation' signifie donc, à partir de la page dont le nom est 'organisations_folders', créer un premier niveau de sous page dont le nom est le premier caractère du nom de la nouvelle organisation, comme dans un agenda papier, puis une page de second niveau, portant le nom de l'organisation, dans laquelle on place la nouvelle fiche.

'url_call' signifie une fois que la fiche aura été créée, on fait comme si un lien y menant avait été activé. Ceci permet d'accéder automatiquement au contenu de la nouvelle fiche, par exemple en vue de la compléter, ou d'ajouter de nouveaux éléments dans la nouvelle page correspondant à cette fiche. On revient ensuite au formulaire de création via le bouton de retour arrière de Storga.

'copy_fields', le dernier paramètre optionnel de l'instruction 'new_form', signifie copier la valeur des champs qui existent à la fois au niveau du formulaire de création et de la nouvelle fiche. Ici, il s'agit de l'unique champ 'organisation' qui indique le nom de l'organisation.

Sous l'instruction 'new_form', on retrouve habituellement, indenté vers la droite, le code servant à remplir cette fiche au moment de la création. Ici, nous trouvons simplement 'void' qui signifie ne rien faire.

On aurait par exemple pu écrire, a titre de pur exemple :

new_form @organisation_model page @organisations_folders subpage (organisation 0 1) (organisation 0 1) subpage organisation organisation url_call copy_fields
  field Str siret
  siret := "... ... ..."

et dans ce cas, la ligne 'field Str siret' déclare que la nouvelle fiche contient un champ 'siret' de type chaîne de caractères, et la seconde initialise ce champ avec la valeur '... ... ...'.

Terminons la lecture de ce premier programme de création d'une nouvelle fiche :

organisation := ""

'organisation' désigne le champ 'Organisation' du formulaire de création, que l'on remet à vide.

Travaux pratiques