Amaya

## Éditer avec des modèles

### Qu'est-ce qu'un modèle ?

Les modèles sont utilisés pour produire plusieurs documents du même type. Un modèle est un squelette représentant ce type de document, exprimé dans le format du document final à produire (par exemple XHTML). Le format du document final est appelé le langage cible et doit être un langage XML.

Dans un modèle, le squelette du document contient des déclarations, exprimées dans le langage XTiger (eXtensible Templates for Interactive Guided Editing of Resources), qui spécifient comment le document minimal peut évoluer et grossir, en respectant le type de document final désiré.

Les documents produits à partir de ce squelette en suivant les déclarations XTiger sont appelés des instances du modèle. Certaines parties du modèle peuvent être figées, si elles doivent apparaître dans les instances telles quelles. Certaines parties peuvent être modifiées quand une instance de document est produite, certaines autres peuvent être ajoutées, librement ou sous certaines contraintes.

Le fichier contenant le modèle doit avoir l'extension `.xtd`.

Un modèle est souvent accompagné d'un ensemble de ressources attachées (images, feuilles de style, scripts). Un modèle est une ressource web, qui peut être stockée dans le système de fichiers local ou partagé sur un serveur web.

### Créer un modèle

Vous pouvez créer vos propres modèles, en utilisant le langage XTiger. Cependant, Amaya fournit un support spécifique pour la création et la mise à jour des modèles.

L'approche proposée est de :

- Créer d'abord un squelette d'instance de document (fichier .html) vous voulez engendrer.
- Sélectionner l'onglet Modèle (Tpl) de l'outil Eléments et cliquer sur la première entrée "Créer un modèle depuis le document courant" pour engendrer un modèle (fichier .xtd) à partir du squelette de document.
- Vous pouvez aussi créer une nouvelle librairie XTiger (fichier .xtl) vide avec l'entrée "Créer une librairie".
- Quand un document modèle ou une librairie XTiger est sélectionné, plusieurs entrées de l'outil Modèle sont disponibles :
  - L'entrée "Créer un composant" engendre un élément `component` qui sera affiché dans la section `head` du document modèle.

    Si la sélection n'est pas vide, le contenu de la sélection devient le contenu du composant. Un élément `use` est créé à la position courante du document pour indiquer que composant est utilisé à cette position. La sélection doit être valide (seulement des éléments complets ou une chaîne de caractères). La commande demande à l'utilisateur de saisir le nom du `component`. Ce nom doit être unique et est utilisé pour afficher la structure des documents instances du modèle.

    Note : Le contenu du composant ne pourra pas être édité dans les instances du modèle. L'utilisateur doit insérer des éléments `use` et/ou `bag` dans le composant pour définir des zones éditables. Ces zones peuvent être définies avant ou après la création du composant.

  - L'entrée "Créer une nouvelle union de types" engendre un élément `union` qui définit un nouveau type comme le choix entre des types de base (`number`, `string`), ou des éléments du langage cible (div, h1, h2, p, ...) et des noms de `component`. La sélection courante n'a aucun effet. La commande demande à l'utilisateur de saisir le nom de l'`union`. Ce nom doit être unique.

  - L'entrée "Importer une librairie" engendre un élément `import` qui insère les déclarations de la librairie référencée à cette position.

  - L'entrée "Créer une zone de texte" engendre un élément `use` qui permet d'insérer une chaîne de caractères dans les instances du modèles. La commande demande à l'utilisateur un label. Ce label est libre et est utilisé pour afficher la structure des documents instances du modèle. La sélection doit être une chaîne de caractères qui devient la valeur initiale de l'élément `use`.

  - L'entrée "Utiliser un composant ou un élément" engendre un nouveau élément `use`.

    Si la sélection est vide, un dialogue propose la liste des éléments qui peuvent être insérés à cette position et demande à l'utilisateur le label associé à élément `use` (comme pour l'entrée précédente). Un élément `use` vide est engendré.

    Si un élément du langage cible (div, h1, h2, p, ...) est sélectionné, un élément `use` qui permet d'insérer ce type d'élément est engendré à cette position. L''élément sélectionné devient le contenu initial de l'élément `use`. La commande demande seulement à l'utilisateur un label.

  - L'entrée "Répéter l'utilisation courante" engendre une répétition (`repeat`) de l'élément `use` sélectionné. La commande demande à l'utilisateur un label. Ce label est libre et est utilisé pour noter la répétition dans la structure des documents instances du modèle.

  - L'entrée "Créer et répéter un composant" engendre à la fois un élément `use` et un élément `repeat`.

  - L'entrée "Créer une zone d'édition libre" engendre un élément `bag`. La commande demande à l'utilisateur un label. Ce label est libre et est utilisé pour afficher la structure des documents instances du modèle.

    Par défaut l'élément `bag` autorise l'insertion multiple de n'importe quel élément du langage cible et de tous les composants définis dans le modèle (`types="any"`). L'utilisateur doit éditer l'attribut `types` dans le panneau Attributs pour modifier cette valeur par défaut.

- Le modèle ou la librairie XTiger créé peut être enregistré n'importe où, dans votre système de fichiers local ou à distance.

### Visualisation des éléments du modèle

Quand un modèle est affiché, Amaya montre les éléments XTiger sous la forme de cadres colorés qui englobent les éléments XHTML.

- L'élément head qui englobe les éléments `component`, `union`, and `import` est affiché avec un fond gris.
- Un élément `use` est une boîte avec un cadre hachuré bleu. Quand son contenu est du texte, la boîte a un fond bleu clair.
- Un élément `bag` est une boîte à fond vert clair avec un cadre hachuré vert.
- Un élément `repeat` est une boîte avec une icône en haut à gauche.
- Un élément `attribute` n'est pas affiché dans la Vue formatée.

Les éléments XTiger peuvent aussi être vus dans la Vue structure (ouvrez cette vue avec l'entrée Montrer la structure dans le menu Affichage). Dans la Vue structure, les éléments XTiger sont affichés en doré, alors que les éléments XHTML sont affichés en bleu. Les éléments XTiger sont aussi montrés dans la vue source, mais sans couleur spéciale.

Un autre moyen de comprendre la structure imbriquée des éléments XTiger avec les éléments XHTML est le chemin de la sélection affiché dans la barre de statut (en bas de la fenêtre). Là, vous pouvez voir tous les éléments de la structure du document depuis l'élément racine jusqu'à la sélection. Ce chemin est mis à jour chaque fois que la sélection change. Dans ce chemin, les éléments XTiger sont affichés en doré et les éléments XHTML sont affichés en noir. Pour les éléments XTiger, ce n'est pas le nom de l'élément qui est affiché ici (`use`, `bag`, `repeat`) mais le label attaché à ces éléments, comme déclaré dans le modèle.

### Sélectionner un modèle

Vous pouvez sélectionner vos propres modèles ou utiliser les modèles disponibles sur le site web d'Amaya http://www.w3.org/Amaya/Templates/.

Pour faciliter la sélection parmi vos modèles préférés, il y a une section Modèles dans le dialogue des Préférences (Édition/Préférences, ou amaya/Préférences sous Mac OS X). Utilisez ces préférences pour enregistrer les modèles qu'Amaya proposera quand vous créerez un nouveau document.

Quand vous voulez enregistrer un modèle local, vous pouvez appeler l'explorateur de fichiers avec le bouton pour localiser et sélectionner les modèles à ajouter. Vous pouvez aussi entrer l'URI des modèles distants dans la zone d'entrée en dessous de la liste. Utilisez les boutons situés sur le côté droit de la liste pour retirer le modèle sélectionné ou changer l'ordre dans la liste des modèles.

L'enregistrement des modèles n'est pas obligatoire. Quand vous créez une nouvelle instance, vous pouvez aussi choisir un modèle qui n'est pas dans cette liste.

### Créer une instance de document

Pour créer un nouveau document depuis un modèle, utilisez l'entrée Nouveau/Nouveau document du menu Fichier. Un dialogue s'affiche dans lequel vous pouvez sélectionner :

- Le modèle, soit en sélectionnant dans la liste des modèles enregistrés, soit en tapant l'URI ou le nom de fichier d'un modèle qui n'est pas dans la liste,
- L'URI ou le nom du fichier du document instance à créer,
- Où ouvrir le nouveau document (Remplacer le document courant, Dans un nouvel onglet, Dans une nouvelle fenêtre),
- Le titre du nouveau document qui sera affiché par les navigateurs (un titre par défaut est engendré quand l'utilisateur le ne spécifie pas).

### Editer un document instance

Quand une instance de modèle est créée ou ouverte, Amaya affiche côte à côte la Vue formatée et la Vue structure du document.

Dans la Vue formatée :

L'édition n'est autorisée que dans les éléments `repeat`, `use`, et `bag`, c'est-à-dire dans les boîtes colorées hachurées. Le reste du document est la partie figée du modèle et ne peut pas être modifié.

- Les zones où l'utilisateur peut éditer sont entourées de cadres colorés :
  - Un cadre bleu entoure une zone où l'utilisateur peut insérer du texte (élément `use`).
  - Un cadre vert entoure une zone où l'utilisateur peut insérer des éléments ou des chaînes de caractères (élément `bag`).
- Des boutons + permettent d'afficher un menu et insérer un des nouveaux éléments proposés dans le menu à la position courante (dans des éléments `repeat` ou `bag`).
- Les éléments `attribute` agissent seulement sur l'outil Attributs.

Dans la Vue structure :

- Les labels des éléments XTiger sont affichés sur un fond coloré :
  - Un fond gris pour des éléments `use` non actifs.
  - Un fond doré pour des éléments `use` actifs.
  - Un fond doré clair pour des éléments `repeat` actifs.
  - Un fond vert clair pour des éléments `bag` actifs.
- Avec les éléments actifs,
  - Un clic sur le label, ou la moitié haute de la barre verticale associée, affiche un menu qui permet d'insérer un nouvel élément proposé avant.
  - Un clic sur la moitié basse de la barre verticale associée, affiche un menu qui permet d'insérer un nouvel élément proposé après.

#### Edition dans un élément `repeat`

Dans une boîte `repeat`, vous pouvez créer de nouvelles instances de la structure répétée ou en détruire une. Ceci est contrôlé par le modèle, qui peut imposer un nombre minimum et/ou maximum d'occurrences de la structure répétée.

Quand la création de nouvelles occurrences de la structure répétée est autorisée, des icônes + sont affichées aux emplacements où cette création est possible. Cliquez sur une des ces icônes pour créer une nouvelle occurrence. Un menu vous donne la liste des éléments qui peuvent être créés à cette position. En sélectionnant une entrée de ce menu, vous créez une nouvelle occurrence du type correspondant. Dans certains cas, le modèle n'offre qu'un seul type. Le menu ne contient alors qu'une seule entrée, pour clairement informer l'utilisateur de ce qui va être créé. Si vous cliquez en dehors du menu, rien ne sera créé.

Une autre façon de créer des occurrences de la structure répétée est de sélectionner une occurrence existante, ou d'ajouter un point d'insertion à la fin d'une occurrence, et d'appuyer sur la touche `Entrée`. Une nouvelle instance de la structure répétée est ainsi créée, à condition que le nombre maximum d'occurrences ne soit pas déjà atteint. La nouvelle occurrence créée est alors du même type que l'occurrence sélectionnée quand on a appuyé sur la touche `Entrée`.

Quand une occurrence existante est vide ou complètement sélectionnée et que la touche `Arrière` ou `Suppr` est pressée, l'élément est détruit, à condition que le nombre minimum d'occurrences de la structure répétée ne soit pas déjà atteint.

#### Edition dans un élément `use`

La plupart des éléments `use` (bleu) vous permettent juste d'insérer du texte libre ou de remplacer/éditer le texte existant. D'autres éléments `use` offrent le choix parmi différents types d'éléments qui peuvent être insérés à cette position. Dans ce cas, une icône triangulaire bleue est affichée dans le coin haut gauche de la boîte. En cliquant sur cette icône, vous pouvez choisir un de ces types dans le menu affiché. Quand le type est choisi, la structure correspondante est engendrée et vous pouvez librement éditer son contenu.

#### Edition dans un élément `bag`

Dans une boîte `bag` (verte), vous pouvez insérer n'importe quel nombre d'éléments des types spécifiés par le modèle. Quand vous voulez insérer un élément XHTML, faite le de la façon habituelle, à condition que le modèle autorise ce type d'élément. Il se peut que des éléments ne soient pas autorisés. Les éléments autorisés sont proposés dans les sous-menus Insérer et Ajouter du menu contextuel. Les composants définis par le modèle sont aussi proposés dans les sous-menus Insérer et Ajouter du menu contextuel.