Ajouter un bouton d'aide

Il y a plusieurs possibiltés pour insérer des textes d'aide au sein d'une extension.

La première est de l'insérer directement dans la boite de dialogue, sous les champs de formulaire, à condition qu'elle soit courte, deux ou trois lignes maximum.
Tout dépendra donc en fait de la complexité de l'extension, des différentes options qu'elle propose, qui peuvent demander des explications plus ou moins longues, le but étant de ne pas noyer les informations principales de l'interface dans un flot de texte parasite.

La deuxième est d'ajouter un bouton d'aide à l'interface.
Le bouton d'aide est un simple bouton de formulaire, mais nous ne pouvons pas l'insérer nous même. Il faut passer par une fonction spéciale de l'API de DW.

Bien que faisant partie de l'API des extensions, cette fonction doit être insérée manuellement. Elle n'est pas propre aux comportements serveur. Quelque soit le type d'extension que vous créez (objets, commandes etc), c'est par cette fonction que vous pourrez apporter une aide à une extension.  
A la fin du code Javascript du fichier HTM, rajoutez les lignes suivantes :

function displayHelp() {
  var theHelpFile;
  theHelpFile = dw.getConfigurationPath() + '/ExtensionsHelp/FlashXpress/ConvertirDate.htm';
  dreamweaver.browseDocument(theHelpFile);
}

L'insertion de la fonction displayHelp() provoque automatiquement l'apparition d'un bouton Aide, situé sous les boutons OK et Annuler .

Il s'agit ici de récupérer dans une variable (theHelpFile) le chemin d'accès au dossier Configuration de Dreamweaver grâce à dw.getConfigurationPath() puis de lui rajouter le chemin vers le dossier ExtensionsHelp avec éventuellement un sous-dossier dans lequel on stocke nos fichiers d'aide.
Le dossier ExtensionsHelp a été créé par MM dans votre profil utilisateur. Il est destiné justement à regrouper tous les fichiers d'aide que chaque extension est susceptible d'installer. Ces fichiers d'aide sont de simples fichiers HTML et il est de coutume de les stocker dans un sous-dossier approprié pour éviter une accumulation de fichiers dans le dossier principal, comme ici où je ai créé un dossier FXP : /ExtensionsHelp/FlashXpress. Sachant de plus que de nombreuses extensions installent des fichiers d'aide (avec leurs propres images), l'utilisateur peut s'y perdre facilement si on ne s'impose pas un mimimum de rigueur.

Dans le cas que nous venons d'exposer, le fichier d'aide est directement accessible sur le disque dur de l'utilsateur, en local. C'est à notre avis la meilleure solution car plutôt qu'un fichier en local, on aurait pu aussi préciser une URL sur un site distant, mais cette méthode oblige l'utilisateur a avoir une connexion ouverte (tout le monde - et loin de là d'ailleurs - n'a pas de connexion permanente, cable, ADSL..) et peut être pénalisante si le réseau est encombré.

Ici pour illustrer nos propos, nous avons ajouté un texte d'aide directement dans l'interface et ajouter aussi le bouton Aide .
Pour le texte d'aide, nous avons inséré un simple tableau sous le tableau principal. Notez que nous avons donné une couleur de fond différente au texte.
L'aide est le seul élément de l'interface qui puisse contenir une autre couleur que la couleur par défaut affectée par Dreamweaver. Macromedia recommande d'utiliser la couleur #D3D3D3, à savoir un gris plus sombre que le reste de la boite de dialogue. Notez aussi que nous en avons aussi profité pour glisser le logo ainsi que le nom de l'auteur :-)
Cela aussi, c'est le seul élément "externe" au comportement, que Macromedia permet de mettre en avant sur l'interface. L'image du logo a été incorporé non pas comme image simple (balise <IMG>) mais comme champ d'image (balise <INPUT>).

Figure 7.

Le logo peut avoir un lien amenant directement à votre site (ou même sur une page particulière dans votre site, pourquoi pas), mais vous ne pouvez pas utiliser de lien HTML classique :
<a href="http://www.monsite.com">Logo</a> ne fonctionnera pas dans l'environnement Dreamweaver.  Il nous faudra utiliser une fonction interne de l'API de Dream, destinée à de multiples usages, avec entre autres celui de permettre l'accès à une URL.

• Sélectionnez l'image, faites un clic droit, choisissez Modifier la balise <input>.
• Dans l'éditeur de balises, sélectionnez Evénements > onClick et rentrez la syntaxe suivante :
  

  onClick='dreamweaver.browseDocument("http://www.flashxpress.net")'

Figure 8.

Bien sur remplacez flashxpress.net par autre chose...

Les conseils de Macromedia pour l'interface

Les conseils qui suivent sont des lignes de conduite, en aucun cas obligatoires, mais que Macromedia recommande de suivre.
(Notamment si vous souhaitez plus tard soumettre votre extension sur le site Macromedia Exchange). Ces conseils sont d'ailleurs valables pour toutes les extensions que vous créez (objets, commandes, etc.).
L'objectif principal est de respecter l'environnement Dreamweaver afin de ne pas dérouter l'utilisateur. Votre extension doit s'intégrer harmonieusement au reste du logiciel.
L'utilisateur est habitué au design des autres comportements, il s'attend à trouver des interfaces semblables, des façons de présenter plus ou moins identiques.

• Pour régler la longueur des champs n'utilisez pas des syntaxes telles que size="40", utilisez des styles en ligne comme :
  <select style="width:150px" name="Recordset">
  ceci en raison de problèmes d'affichage sur les Mac.
  Vous pouvez même faire des styles internes.
• Si vous avez des champs de type boutons-radio, ou cases à cocher, au moins un devrait être coché par défaut. C'est un cas de figure qui peut revenir très souvent, quelque soit le type de champ : il s'agit simplement de proposer des valeurs par défaut à l'utilisateur.
• La taille globale de la boite de dialoque du comportement est déterminé par DMX, en fonction des objets qu'il y trouve. On peut contraindre les dimensions de cette fenêtre à l'aide de la fonction JS windowDimensions(), mais Macromedia déconseille de l'utiliser et conseille de laisser Dreamweaver gérer cela.
• Dreamweaver a généré un tableau HTML automatiquement pour le rendu du formulaire et des champs de formulaire. Il est déconseillé de forcer des valeurs pour ce tableau: hauteur, largeur, espacement des cellules, remplissage des cellules.  C'est DW qui doit le gérer (ceci dit il ne le fait pas touojurs correctement, dans ce cas vous pouvez faire vous-même les ajustements nécessaires).
  
• Ne pas utiliser de couleur de fond pour le tableau ou la page, à l'exception des tableaux contenant les textes d'aide. Pour que ces textes se distinguent clairement du reste de l'UI, Macromedia propose d'utiliser la couleur #D3D3D3.
• Les étiquettes des champs de formulaire doivent apparaitre à gauche du champ de formulaire, alignés à droite dans leur cellule et ne pas comporter de retour à la ligne. Chaque mot des étiquettes doit commencer par une majuscule (mais cette recommandation vient du fait que ce système de majuscule en début de mot est courant aux Etats-Unis, alors que ça n'existe pas dans nos standards européens).

 ConvertirDate.mxp (5.96 KB)