fr:manuals:freemedforms:xmlforms:itemscript
Keywords: fr:freemedforms,fr:usermanual,needsupdate
Date: 2012-01-08T22:03:38+0100

freemedforms, usermanual, needsupdate

# Rendre les formulaires dynamiques

- Vous pouvez rendre vos formulaires dynamiques et intelligents grâce à l'utilisation de scripts.
- Le language de script de FreeMedForms est basé sur le standard ECMAScript. [Extrait de la documentation anglaise de Qt] Microsoft's JScript, and Netscape's JavaScript are also based on the ECMAScript standard. For an overview of ECMAScript, see the ECMAScript reference. If you are not familiar with the ECMAScript language, there are several existing tutorials and books that cover this subject, such as JavaScript: The Definitive Guide.
- Les scripts sont exécutés à différents moments de l'édition et le codage XML vous permet de définir au mieux vos besoins.

## Code XML

- Le bloc XML d'un item de formulaire se présente de la sorte :

        <Item>
          ...
          <Script>
            <OnLoad>
              ...
            </OnLoad>
            <PostLoad>
              ...
            </PostLoad>
            <OnValueChanged>
              ...
            </OnValueChanged>
          </Script>
        </Item>

- Attention vous ne devez pas utiliser le caractère “<“ à l'intérieur de vos fichiers XML sous peine de les rendre illisible. Vous devez utiliser l'équivalent HTML, à savoir ”&lt;”. Vous pouvez à la place inclure des fichiers de script dans lequel vous n'êtes soumis à aucune limitation.

      <file type="script" name="onload">./scripts/xx/script.js</file>

- Il existe plusieurs sortes de scripts :
  - les scripts exécutés au moment du chargement des formulaires patient : onload ;
  - les scripts exécutés après le chargement des formulaires patient : postload ;
  - les scripts exécutés à chaque modification de valeur d'un item : onValueChanged ;
  - Ces différents scripts ne sont pas supposés retourner de valeur.

- Techniques de mise en place :
  - Nous recommandons l'utilisation des scripts externalisés (sauvegardés dans un fichier propre) ;
  - La structure de l'arborescence des formulaires devrait comprendre un répertoire scripts puis un répertoire pour chaque langage xx représentant tous les langages.
  - Exemple:
    - subforms/
      - scripttest/
        - scripts/
          - fr/
          - en/
          - xx/
  - Les noms de fichiers doivent terminer par *.js
  - Nous recommandons d'utiliser des artifices créant des espaces de nom dans vos scripts afin d'éviter les conflits (cf infra).
  - Utilisez le tag file après le bloc de description pour inclure un fichier js comprenant toutes les fonctions utilisées.
  - Dans le formulaire, contentez-vous d'appeler les fonctions enregistrées.
  - Exemple:

          <formdescription>
            ...
          </formdescription>
          <file type="script" name="onload">./scripts/xx/myglobalscripts.js</file>
          ...
          <Item>
            ...
            <script>
              <onValueChanged>my.name.space.onItemValueChanged();</onValueChanged>
            </script>
          </Item>

  - N'utilisez pas les fonctions signal/slot de Qt pour connecter les changements de valeur d'un item, laissez FreeMedForms décider quand il convient d'appeler ces fonctions.
  - Ne déclenchez pas de calculs trop intensifs pour que l'utilisateur ne perde pas la main de l'application.

## Utilisation des espaces de noms et espace de nom pour FreeMedForms

- Le moteur de script de FreeMedForms vous propose une interface pour déclarer vos espaces de nom.
- Cette interface est celle de Mike Koss. La documentation est disponbile sur ce site.
- Les objets de FreeMedForms sont déclarés dans l'espace de nom : namespace.com.freemedforms ou son alias freemedforms.

## Accéder aux items des formulaires

- L'objet freemedforms.forms est accessible en lecture et écriture. Il possède les propriétés suivantes.

Nom | Valeur | Lecture | Ecriture
--- | --- | --- | ---
areLoaded | return true if all forms are loaded | oui | non
logItemSearch | console login of form item serach (debugging purpose) | oui | oui
namespaceInUse | Modifie l'espace de nom en cours | oui | oui
item(“xxxx”) | Retourne l'item dont l'uuid est xxxx | oui | non

- Accéder aux items : exemple de code

        // Sans définir au préalable l'espace de nom
        var monItem = freemedforms.forms.item("Mon::Namespace::MonItem");
        if (monItem.isValid) {
            ....
        }

        // Avec définition de l'espace de nom
        freemedforms.forms.namespaceInUse = "Mon::Namespace::";  // Vous pouvez omettre le séparateur d'espace de nom à la fin
        var monItem2 = freemedforms.forms.item("MonItem2");
        if (monItem2.isValid) {
            ....
        }

## Accéder aux données des items de formulaire

- Les objets items récupérés par le biais de l'appel de la fonction item() de l'objet freemedforms.forms, donnent accès aux différents données de l'item en lecture et en écriture.

Nom | Valeur | Lecture | Ecriture
--- | --- | --- | ---
isValid | (bool) validité de l'item | oui | non
uuid | (string) uuid complet de l'item | oui | non
type | (string) Type d'item | oui | non
currentValue | (variant) Valeur courante de l'item | oui | oui
currentText | (string) Valeur courante textuelle de l'item | oui | oui
currentUuid | (string) Uuid courante de l'item (pour les combos cela représente l'index courant) | oui | oui
enabled | (bool) Etat d'accessibilité de l'item | oui | oui
checked | (bool) Item coché | oui | oui

## Accéder aux données patient

- L'object freemedforms.patient est accessible en lecture comme en écriture. Il possède les propriétés suivantes.

Nom | Valeur | Lecture | Ecriture
--- | --- | --- | ---
fullName | nom complet incluant le titre | oui | non
isActive | le patient est défini | oui | non
dateOfBirth | Date de naissance | oui | non
yearsOld | Age en années | oui | non
isMale | sexe masculin | oui | non
isFemale | sexe féminin | oui | non
weight | Poids (valeur) | oui | non
weightUnit | Poids (unités) | oui | non
height | Taille (valeur) | oui | non
heightUnit | Taille (unités) | oui | non
creatinine | Créatinine (dernière valeur) | oui | non
creatinineUnit | Créatinine (unités) | oui | non
clearanceCreatinine | Clairance de la créatinine (dernière valeur) | oui | non
clearanceCreatinineUnit | Clairance de la créatinine (unités) | oui | non

- Exemple d'utilisation

      var years = freemedforms.patient.yearsOld;

## Accéder et modifier les éléments de la vue (UI)

- L'objet freemedforms.uiTools vous permet d'interagir avec les éléments de la vue (sans passer par la structure des items au sens de FreeMedForms).
- Fonctions disponibles:
  - addItem(widget, string) : ajoute un item au widget.
    - Fonctionne pour les QListView, QComboBox
  - addItems(widget, stringlist) : ajoute plusieurs items au widget.
    - Fonctionne pour les QListView, QComboBox
  - addJoinedItem(widget, stringitems, separator) : ajoute plusieurs items au widget.
    - Fonctionne avec QListView, QComboBox.
    - stringitems est une string qui contient les items séparés par le séparateur. Les items seront extraits de cette string.
  - clear() : efface le contenu du widget.
    - Fonctionne pour les toutes les QAbstractItemView, QComboBox
  - Array selectedItems(widget) : Retourne tous les items sélectionnés (texte visible de l'item)
    - Fonctionne avec toutes les itemviews, QComboBox.
  - showScreenshot(formUid, fileName) : affiche un screenshot pour le formulaire dont l'uuid est formUid et dont le nom est fileName. Exemple:

        freemedforms.uiTools.showScreenshot("__subForms__/myMMSE","xx/drawing.png");

## Accéder aux données de l'utilisateur courant