En-têtes XML
Cette page détaille le fonctionnement des en-têtes XML personnalisables. Cette puissante fonctionnalité permet d’intégrer les documents GWrite dans un flux XML avec un haut degré d’automatisme et de sécurité.Définition des éléments
Les éléments d’en-tête sont définis dans le fichier “Custom Headers.plist” que GWrite crée automatiquement dans le dossier (utilisateur)/Application Support/GWrite/ lors de son premier lancement. Ce fichier XML utilise le format “key/value” que l’on retrouve dans la plupart des fichiers de préférences sous Mac OS X. Il peut être ouvert et modifié avec TextEdit ou tout autre éditeur mieux approprié (TextWrangler, BBEdit...).En cas de fausse manœuvre conduisant à un XML illisible, il suffit de quitter GWrite, glisser le fichier à la corbeille et relancer GWrite. L’application recréera le fichier par défaut.
Les propriétés des différents éléments d’interface sont décrites plus bas dans cette page.
Important : le nom d’un élément (attribut “name”) doit être unique. Si plusieurs éléments ont le même nom, les attributs du derniers écraseront ceux des précédents.
Une fois définis, les éléments deviennent autant d’éléments XML ajoutés dans l’en-tête du document GWrite. Les éléments à valeur unique font l’objet d’une entrée simple, par exemple :
<motcle>valeur choisie</motcle>
Les éléments à valeurs multiples voient autant d’éléments XML que de valeurs, par exemple :
<motcle>première valeur</motcle>
<motcle>seconde valeur</motcle>
<motcle>troisième valeur</motcle>
Si l’élément fonctionne en mode automatique (voir ci-dessous), un élément XML complémentaire précise si sa valeur est le résultat du mode automatique ou si elle a été modifiée manuellement par l’opérateur. Le nom de cet élément complémentaire est “autoFillStatus_xxx” où xxx est le nom de l’élément, par exemple :
<autoFillStatus_motcle>auto</autoFillStatus_motcle> (mode automatique)
<autoFillStatus_motcle>manual</autoFillStatus_motcle> (valeur modifiée manuellement)
Utilisation : mode auto, mode manuel
Lors de la création d’un document, puis lors de son enregistrement, GWrite examine les en-têtes et effectue automatiquement un certain nombre d’actions. Les valeurs par défaut sont renseignées, puis le contenu du document est examiné et comparé aux mots-clés prédéfinis pour renseigner les champs correspondants sans intervention de l’utilisateur.Celui-ci conserve néanmoins la possibilité d’intervenir en utilisant la commande “Mots-clés…” du menu Outils (ou en cliquant sur le bouton correspondant de la barre d’outils qui peut être installé en personnalisant celle-ci). Cette commande affiche un dialogue qui montre les valeurs courantes des en-têtes et permet de les modifier.
Mode auto : les éléments qui doivent être renseignés automatiquement sont traités par défaut en mode automatique. Ils passent en mode manuel de façon transparente si l’utilisateur les modifie dans le dialogue. GWrite ajoute un élément XML dans l’en-tête du document, précisant dans quel mode se trouve chaque élément.
Mise à jour automatique : les éléments
en mode auto sont mis à jour lors de chaque affichage du
dialogue, ainsi que lors de chaque
enregistrement du document. Ils reflètent ainsi
en permanence le contenu actualisé du document.
Choix des mots-clés retenus : les éléments de type “textArea” (champ de texte à valeurs multiples) sont traités de façon particulière, puisqu’ils peuvent contenir plusieurs valeurs, une valeur par ligne. Si un tel élément reçoit des mots-clés pris dans une liste prédéfinie, en mode automatique il contiendra tous les mots-clés trouvés dans le document. A contrario, les autres éléments ne peuvent prendre qu’une seule valeur, c’est donc le mot-clé apparaissant le plus grand nombre de fois dans le document qui sera pris.
Si le nom de l’élément XML est “exemple”, le nom de
l’élément ajouté est “autoFillStatus_exemple” et sa valeur
sera “auto” ou “manual”. Cet élément est à usage interne de
GWrite, mais peut être exploité en aval s’il est utile de
vérifier que la valeur d’un élément a été renseignée
manuellement ou automatiquement.
Choix des mots-clés retenus : les éléments de type “textArea” (champ de texte à valeurs multiples) sont traités de façon particulière, puisqu’ils peuvent contenir plusieurs valeurs, une valeur par ligne. Si un tel élément reçoit des mots-clés pris dans une liste prédéfinie, en mode automatique il contiendra tous les mots-clés trouvés dans le document. A contrario, les autres éléments ne peuvent prendre qu’une seule valeur, c’est donc le mot-clé apparaissant le plus grand nombre de fois dans le document qui sera pris.
Tous les éléments peuvent bénéficier de cet automatisme, à l’exception des cases à cocher, et bien sûr des éléments servant à définir les groupes qui n’ont aucun attribut informationnel.
Option de vérification obligatoire : lorsque l’option “forceUserCheck” est mise à “true”, lors de la fermeture d’un document, GWrite vérifie que le dialogue des mots-clés a globalement été visité au moins une fois. Si ce n’est pas le cas, un bip avertit l’utilisateur et le dialogue apparaît automatiquement. Cette option n’est pas active par défaut.
Option interdisant un élément vide : indépendamment de l’option précédente, chaque élément peut recevoir un attribut “emptyForbidden” qui interdit à l’utilisateur de le laisser vide. Cette option n’a de sens que si l’élément peut être laissé vide, elle n’est donc pas disponible pour les cases à cocher et les menus popup.
Définition d’un fichier modèle
L’administrateur peut optionnellement définir, dans les préférences de GWrite, l’emplacement d’un modèle de définition des en-têtes (voir le chapitre sur les préférences pour plus de détails). Cet emplacement se défini sous la forme d’un URL complet. Le nom du fichier est libre, mais doit être de type “.plist” et sa structure conforme à ce format. Seuls sont supportés les URL de type “file://” pour accéder à un fichier local (par exemple sur un serveur dont le volume est monté), ou de type “http://” pour accéder au fichier à travers un serveur web, ce qui peut être utile pour distribuer le paramétrage des en-têtes aux correspondants distants.Lors de son lancement, GWrite cherche à accéder au modèle s’il est défini. S’il existe, sa version est comparée à celle en cours d’utilisation. Si elle est plus récente, GWrite recopie le nouveau modèle dans son propre fichier “Custom Headers.plist” et l’utilise immédiatement. L’indication de version à l’intérieur du fichier, telle qu’elle existe dans le fichier par défaut, est obligatoire pour que cette comparaison puisse fonctionner ; en son absence GWrite affichera une alerte.
La version initialement contenue dans les ressources de GWrite 3.1 est proche de 100. Les numéros de versions inférieurs à 1000 sont réservés pour GWrite. Si vous souhaitez créer un modèle personnalisé comme il est décrit ci-dessus, son numéro de version doit impérativement être à 1000 ou plus. Ainsi, dans le cas où une mise à jour de GWrite apporte une nouvelle version (101, 102...) du modèle interne, celle-ci ne remplacera l’ancienne que si aucun modèle personnalisé externe n’a été défini avec un numéro de version supérieur.
Propriétés des éléments
GWrite permet l’utilisation de divers éléments d’interface, à choisir en fonction des besoins :— le champ de texte simple,
— le champ de texte à valeurs multiple,
— le menu popup,
— le menu popup combiné à un champ de texte, simple ou multiple,
— les cases à cocher et les boutons radios.
Par ailleurs, deux éléments spécifiques permettent d’ouvrir et fermer des groupes d’éléments pour les différencier visuellement, et un dernier élément sert de séparateur vertical.
Tous les éléments ont un type, qui définit leur rôle et leur apparence. Presque tous correspondent à un élément XML qui sera créé dans l’en-tête du document GWrite. Le nom de cet élément XML peut en théorie contenir n’importe quel caractère unicode, mais en pratique, il est prudent de s’obliger à n’utiliser que des minuscules sans accent et sans espace, pour prévenir tout problème de compatibilité avec le flux XML en aval.
| Champ de texte simple | ||
| Nom de la propriété | Contenu | Notes |
| type | textField | obligatoire |
| name | (libre) | obligatoire, nom de la balise XML |
| title | (libre) | obligatoire, libellé du champ dans le dialogue |
| defaultValue | (libre) | facultatif, valeur par défaut |
| useAutoFill | true/false | facultatif, utiliser ou non le mode auto |
| emptyForbidden | true/false | facultatif, interdire de laisser vide |
| proposedValuesOnly | true/false | facultatif, limiter ou non aux valeurs prédéfinies |
| proposedValues | (table de valeurs) | obligatoire si useAutoFill ou proposedValuesOnly, valeurs prédéfinies |
| Champ de texte à valeurs multiples | ||
| Nom de la propriété | Contenu | Notes |
| type | textArea | obligatoire |
| name | (libre) | obligatoire, nom de la balise XML |
| title | (libre) | obligatoire, libellé du champ dans le dialogue |
| defaultValues | (table de valeurs) | facultatif, valeurs par défaut (notez le pluriel sur le nom de la propriété) |
| useAutoFill | true/false | facultatif, utiliser ou non le mode auto |
| emptyForbidden | true/false | facultatif, interdire de laisser vide |
| proposedValuesOnly | true/false | facultatif, limiter ou non aux valeurs prédéfinies |
| proposedValues | (table de valeurs) | obligatoire si useAutoFill ou proposedValuesOnly, valeurs prédéfinies |
| Menu popup | ||
| Nom de la propriété | Contenu | Notes |
| type | popupMenu | obligatoire |
| name | (libre) | obligatoire, nom de la balise XML |
| title | (libre) | obligatoire, libellé de l’élément dans le dialogue |
| defaultValue | (l’une des valeurs) | obligatoire, valeur par défaut (l’une des proposedValues obligatoirement) |
| useAutoFill | true/false | facultatif, utiliser ou non le mode auto |
| proposedValuesOnly | true | facultatif, forcément true |
| proposedValues | (table de valeurs) | obligatoire, valeurs prédéfinies apparaissant dans le menu |
Dans cet élément, de même que dans les autres éléments utilisant un menu popup, le nombre maximum de valeurs est de 200. Il est déconseillé de présenter aux utilisateurs des menus très longs, qui peuvent être sources d’erreurs.
Il est possible de créer des séparateurs dans le menu en insérant un article dont le titre commence par deux traits d’union, par exemple “-- Presse --” (les traits d’union de la fin sont optionnels et purement décoratifs). Cet article pourra être utilisé comme titre de groupe et ne sera pas sélectionnable dans le menu.
| Champ de texte simple avec menu popup | ||
| Nom de la propriété | Contenu | Notes |
| type | textFieldWithPopupMenu | obligatoire |
| name | (libre) | obligatoire, nom de la balise XML |
| title | (libre) | obligatoire, libellé du champ dans le dialogue |
| defaultValue | (libre) | facultatif, valeur par défaut |
| useAutoFill | true/false | facultatif, utiliser ou non le mode auto |
| emptyForbidden | true/false | facultatif, interdire de laisser vide |
| proposedValuesOnly | true/false | facultatif, limiter ou non aux valeurs prédéfinies |
| proposedValues | (table de valeurs) | obligatoire, valeurs prédéfinies apparaissant dans le menu |
| Champ de texte à valeurs multiples avec menu popup | ||
| Nom de la propriété | Contenu | Notes |
| type | textAreaWithPopupMenu | obligatoire |
| name | (libre) | obligatoire, nom de la balise XML |
| title | (libre) | obligatoire, libellé du champ dans le dialogue |
| defaultValues | (table de valeurs) | facultatif, valeurs par défaut (notez le pluriel sur le nom de la propriété) |
| useAutoFill | true/false | facultatif, utiliser ou non le mode auto |
| emptyForbidden | true/false | facultatif, interdire de laisser vide |
| proposedValuesOnly | true/false | facultatif, limiter ou non aux valeurs prédéfinies |
| proposedValues | (table de valeurs) | obligatoire, valeurs prédéfinies apparaissant dans le menu |
| Case à cocher | ||
| Nom de la propriété | Contenu | Notes |
| type | checkbox | obligatoire |
| name | (libre) | obligatoire, nom de la balise XML |
| title | (libre) | obligatoire, libellé de l’option dans le dialogue |
| defaultValue | YES/NO | facultatif, valeur par défaut (en l’absence, “NO” par défaut) |
| Note : la case à cocher ne peut pas utiliser le mode automatique “useAutoFill”, ni l’option “emptyForbidden”. | ||
| Boutons radios | ||
| Nom de la propriété | Contenu | Notes |
| type | radioGroup | obligatoire |
| name | (libre) | obligatoire, nom de la balise XML |
| title | (libre) | obligatoire, libellé du groupe de boutons dans le dialogue |
| defaultValue | (l’une des valeurs) | obligatoire, valeur par défaut (l’une des proposedValues obligatoirement) |
| useAutoFill | true/false | facultatif, utiliser ou non le mode auto |
| emptyForbidden | true/false | facultatif, interdire de laisser vide |
| proposedValuesOnly | true | facultatif, forcément true |
| proposedValues | (table de valeurs) | obligatoire, valeurs prédéfinies apparaissant sur les boutons radios |
Groupage et séparation des éléments
| Début de groupe | ||
| Nom de la propriété | Contenu | Notes |
| type | beginGroup | obligatoire |
| title | (libre) | obligatoire, titre du groupe dans le dialogue |
| Fin de groupe | ||
| Nom de la propriété | Contenu | Notes |
| type | endGroup | obligatoire |
| Séparateur vertical | ||
| Nom de la propriété | Contenu | Notes |
| type | separator | obligatoire |
| Note : le séparateur fait descendre l’élément suivant, mais n’est pas visible en lui-même. | ||
Dans les menus popup, il est possible de créer des groupes d’éléments séparés par des titres, ceux-ci étant inactifs dans le menu. Exemple :
<key>proposedValues</key>
<array>
<string>--(Fruits)--</string>
<string>Pommes</string>
<string>Poires</string>
<string>Bananes</string>
<string>Oranges</string>
<string>--(Légumes)--</string>
<string>Carottes</string>
<string>Épinards</string>
<string>Choux</string>
</array>
Dans le menu défini ci-dessus, les articles “Fruits” et “Légumes”, commençant par “--(” servent de titres de groupes et ne sont pas sélectionnables.