Retour à Labs/Ubiquity.

Author: Aza Raskin, Blair McBride, Abimanyu Raja, Jono DiCarlo, Atul Varma

Dans d'autres langues

Cette page est une traduction de la version anglaise du tutoriel. D'autre traduction sont disponibles :

• 简体中文l
• 日本語で
• En español
• Mr मराठी (Marathi)
• Hi हिंदी (Hindi)
• Auf Deutsch
• In het Nederlands
• Em português

Si le français n'est pas votre langue maternelle, vous pouvez lire le tutoriel dans votre propre langue. Si celle-ci n'existe pas encore, n'hésitez pas à la créer et traduisant une version existante.

Tutoriel des commandes d'Ubiquity 0.1

L'énorme pouvoir d'Ubiquity—du point de vue d'un développeur—est qu'il est simple de créer des commandes. Avec seulement quelques de lignes de Javascript, Ubiquity permet à chaque développeur web d'améliorer radicalement les caractéristiques du navigateur. D'une commande de 8 lignes qui insère l'adresse e-mail d'un contact dans un champ de texte, à une intégration de Twitter de 50 lignes, ce tutoriel va vous accompagner dans le processus de création de commandes avec Ubiquity.

AVERTISSEMENT: Ubiquity est en développement permanent, actuellement en version 0.1. L'API pourrait changer radicalement dans les prochaines révisions. D'un côté ceci signifie que ce que vous écrivez aujourd'hui peut ne plus marcher demain, mais de d'un autre côté en écrivant des commandes et en nous donnant vos retours, vous pourrez influencer directement la direction que prend Ubiquity.

Le reste de cette page explique l'API de développement de commandes dans la dernière version publiée, Ubiquity 0.1.1. Cependant si vous avez récupéré les dernières sources, vous aurez une API plus récente avec des fonctions additionnelles qui ne sont pas dans la 0.1.1. Vous pouvez en apprendre plus à ce sujet à Ubiquity Source Tip Author Tutorial.

Développement en temps réel

Ubiquity ne nécessite pas que vous redémarriez Firefox pendant que vous développez. C'est un acte barbare et on ne veut pas en entendre parler. A la place, Ubiquity recharge les commandes à chaque invocation. Lorsque vous utilisez l'éditeur inclus, vous n'avez même pas besoin de sauvegarder!

Pour ouvrir l'éditeur de commandes d'Ubiquity, invoquez Ubiquity (control/alt + espace) et entrez la commande "command-editor". Tout au long de ce tutorial, lorsque nous voudrons que vous exécutiez une commande dans Ubiquity, nous dirons simplement de l'Ubiquer. Par exemple, pour ouvrir l'éditeur de commande, Ubiquez "command-editor".

Dans les exemples qui suivent, écrivez juste dans cet éditeur. Les mises à jours seront effectives dès que vous invoquerez Ubiquity.

Hello World: La première commande

Juste une fonction : dur de faire plus simple

Commençons par le premier programme standard : afficher "Hello, World!". Dans Ubiquity, les commandes sont simplement des fonctions avec divers attributs appliqués. Nous débuterons en écrivant une fonction à la main, mais nous en viendrons très rapidement à utiliser une méthode plus élégante.

Dans l'éditeur de commande entrez les lignes suivantes :

function cmd_hello_world() {
  displayMessage( "Hello, World!");
}

Maintenant essayez d'Ubiquer "hello-world". Vous verrez que "Hello, World!" apparait immédiatement à l'écran. Si vous êtes sous Mac OSX avec Growl installé, le message apparaitra comme une notification Growl. Si vous êtes sous windows, alors il apparaitra comme une notification standard "grille-pain" dans le coin en bas à droite de l'écran.

Dans Ubuntu 8.04 (Hardy Heron) cela donne:

Si Growl n'est pas installé sur votre OSX, ou que vous n'êtes pas sur un Windows XP ou Vista ni sur Ubuntu Hardy ou Intrepid, vous n'aurez pas de notification. C'est quelque chose qui doit être amélioré dans les futures versions d'Ubiquity.

Il n'y a pas grand chose dans cette commande, attaquons directement. Toute fonction qui commence par cmd_ devient automatiquement une commande Ubiquity. C'est un peu la magie du namespace qui rend le développement super simple.

Il y a d'autres préfixes qui ont d'autres effets, comme faire exécuter du code au chargement de la page (pageLoad_), ou au démarrage (startup_), mais ce sera pour un tutorial différent.

Retour à l'exemple. Le cœur de la commande est dans la fonction displayMessage(), qui affiche le message à la manière dont l'OS peut le faire.

Vous devez vous demander pourquoi il y a un trait d'union dans le nom plutot qu'un espace. C'est parce que le parseur du language d'Ubiquity n'est pas encore assez intelligent pour supporter les commandes à plusieurs mots. C'est quelque chose sur lequel nous travaillerons prochainement.

Utiliser CreateCommand

Pour les commandes plus élaborées que notre simple commande "hello-world", vous pouvez utiliser la fonction pratique CmdUtils.CreateCommand(), qui regroupe un dictionnaire d'options. Pour refaire la commande "hello-world" nous écririons:

CmdUtils.CreateCommand({
  name: "hello-world",
  execute: function() {
    displayMessage( "Hello, World!" );
  }
})

Cela peut sembler ne pas apporter grand chose (ce qui est le cas pour les commandes simples), mais alors que les commandes deviendront plus complexes, vous verrez que ça aide beaucoup. Simplement déjà parce que vous êtes plus libre au niveau du nom de commande — les caractères unicode non-anglais sont maintenant utilisables.

Il y a beaucoup d'autres fonctions utiles dans le namespace CmdUtils. Nous n'avons pas encore de documentation complète pour ces commandes, mais vous aurez un aperçu des plus utiles dans ce tutorial. Pour de plus amples informations, jetez un coup d'oeil à la documentation générée automatiquement ou cmdutils.js

Adding a Preview

Ajoutons une preview à notre nouvelle commande. Les previews donnent à l'utilisateur un retour de ce que la commande fait avant qu'elle soit réellement éxecutée. Les previews sont très utiles pour fournir un retour visuel comme par exemple l'affichage d'une représentation graphique des conditions atmosphériques lorsque l'on utilise la commande weather (voir ci-dessus). Les previews ont la pleine puissance d'expression du HTML en incluant les animations, donc on peut en tirer pas mal de choses.

Un commentaire de conception : Le code d'une preview ne doit jamais avoir d'effet secondaire. Plus précisement, une preview ne devrait jamais (sans intervention de l'utilisateur) changer l'état du système.

Pour la commande "hello-world", nous n'avons pas besoin d'un truc extraordinaire : un simple texte explicatif plus explicite que "Executes la commande "hello-world".

CmdUtils.CreateCommand({
  name: "hello-world",
  preview: "Displays a <i>salutary</i> greeting to the planet.",
  execute: function() {
    displayMessage( "Hello, World!" );
  }
})

Ici, la preview est une chaine au format HTML. La preview peut également être une fonction, nous verrons ça dans le prochain chapitre.

La commande Date : La seconde commande

Etablir la sélection

J'ai toujours du mal à me rappeler quel jour on est. Peut-être parce que je devrais sortir de chez moi plus souvent, mais, comme tout programmeur, je résout généralement les symptomes de mes problèmes par la technologie plutot qu'en m'attaquant à la racine du problème. Ma solution est de créer une commande qui insère la date à l'emplacement du curseur.

CmdUtils.CreateCommand({
  name: "date",
  execute: function() {
    var date = new Date();
    CmdUtils.setSelection( date.toLocaleDateString() );
  }
})

La nouvelle fonction ici est setSelection(). Elle insère le texte qui lui est passé dans la page à l'endroit où se trouve le curseur. Si le curseur est dans un champ de texte éditable ou de rich-text, le texte est alors balancé là. Si le curseur n'est pas dans une zone éditable, setSelection() pourra quand même insérer le texte. NB : Même quand il n'est pas affiché, Firefox garde toujours la position du curseur. Pour le voir, tappez F7. Essayez d'aller sur une page, sélectionnez du texte non éditable, et utilisez la commande. Vous voyez, ça marche ! C'est particulièrement pratique pour les commandes comme "translate" (traduction), où vous voulez remplacer du texte non-éditable par sa traduction.

La fonction toLocalDateString() est une fonction native Javascript, si vous n'êtes pas familiers, allez faire un tour dans la documentation Javascript de l'objet Date.

Améliorer la prévisualisation

Il est temps d'ajouter une meilleure preview à la commande date. Faisons que la preview montre la date, de manière à ce que l'utilisateur sache quoi attendre quand il exécute la commande. (Avec en bonus le fait que l'utilisateur n'aura même pas besoin d'exécuter la commande pour jeter un coup d'oeil à la date du jour).

CmdUtils.CreateCommand({
  name: "date",
  
  _date: function(){
    var date = new Date();
    return date.toLocaleDateString();
  },
  
  preview: function( pblock ) {
    var msg = 'Inserts todays date: "<i>${date}</i>"';
    pblock.innerHTML = CmdUtils.renderTemplate( msg, {date: this._date()} );
  },
  
  execute: function() {
    CmdUtils.setSelection( this._date() );
  }
})

Nous avons fait deux choses ici. La première était de factoriser le code pour obtenir la date dans la fonction _date(). Celà évite d'enfreindre le DRY en repétant du code dans les fonctions de previsualisation et d'exécutions. Remarquez que pour accéder à _date(), on utilise le mot-clé this.

La seconde chose que l'on a faite est d'avoir ajouter une fonction preview. Le premier argument est l'élément DOM qui est affiché comme preview de la commande. Modifiez pblock et vous modifierez la preview. Dans ce cas, on assigne au innerHTML du bloc de prévisualisation le message que l'on veut.

Ah, j'ai aussi fait du formattage de chaine en utilisant la fonction renderTemplate(). Celle ci prend une template de chaine et réalise les substitutions appropriées en fonction de l'objet JSON qui lui est passé. Les templates supportent une large plage de fonctionnalités comme on utilise les JavascriptTemplates de TrimPath. Vous devriez lire leur site pour plus de documentation. Bien que les JavascriptTemplates on des propriétés intéressantes, nous considérons le remplacement par MJT un de ces jours.

Les previews affichent un résultat intéressant et immédiat pour l'utilisateur. Si vous avez des previews qui utilisent des requêtes AJAX—disons pour aller chercher les résulats d'une recherche—cet appel peut prendre un certain temps. Pendant ce temps, votre commande devrait afficher une preview de remplacement pour donner un retour à l'utilisateur.

  preview: function( pblock ) {
    pblock.innerHTML = "This will show until the AJAX request returns";
    // AJAX request
    pblock.innerHTML = getFromServer();
  },

Dans le futur, nous travaillerons sûrement sur la rationalisation [NDTR: streamlining] de ce procédé.

Documentation et Metadata

Avant de partager votre commande avec le monde, vous devriez penser à ajouter quelques informations au code:

CmdUtils.CreateCommand({
  name: "date",
  homepage: "http://azarask.in/",
  author: { name: "Aza Raskin", email: "aza@mozilla.com"},
  contributors: ["Atul Varma"],
  license: "MPL",
  
  /* THE REST OF THE CODE HERE */
})

Et vous devriez absolument ajouter de la documentation:

CmdUtils.CreateCommand({
  name: "date",
  homepage: "http://azarask.in/",
  author: { name: "Aza Raskin", email: "aza@mozilla.com"},
  contributors: ["Atul Varma"],
  license: "MPL",
  description: "Insère la date du jour.",
  help: "Insère la date du jour, formattée pour la locale actuelle, si vous êtes dans un champ de texte éditable.",
  
  /* THE REST OF THE CODE HERE */
})

Les attributs .description et .help sont tous deux affichés automatiquement à la suite du nom de votre commande sur la page de liste des commandes (L'utilisateur peut se rendre à cette page à n'importe quel moment avec la commande "command-list"). Les tags HTML peuvent être utilisés dans ces 2 chaines.

Description est un résumé d'une ligne de ce que la commande fait, alors que Help est une description plus longue qui peut inclure des examples, avertissements, etc. Si votre commande est suffisamment simple pour que tout ce que vous ayez à en dire rentre dans une ligne, c'est OK si vous utilisez juste Description et pas Help.

Partager avec le monde entier

Maintenant que l'on a notre super nouvelle commande "date", partageons là. Tout ce que vous avez à faire pour ça est de mettre le fichier javascript quelque part sur le web, et de faire un lien html vers celui ci avec "link rel".

<link rel="commands" href="http://path-to-js" name="Title Goes Here" />

NB: Votre serveur web doit servir les fichier .js en temps que 'application/x-javascript'. Le type mime 'text/javascript' sera silencieusement ignoré.

N'importe quel utilisateur d'Ubiquity qui visitera votre page recevra un message lui proposant de souscrire à votre commande.

Si l'utilisateur choisit de souscrire à une commande d'une source douteuse, il recevra un avertissement de sécurité avant de pouvoir installer la commande (et dans Ubiquity 0.1, TOUTES les sources sont considérées douteuses, donc ne le prenez pas pour vous!). Comme les commandes Ubiquity peuvent exécuter du javascript ave des privilèges chrome, souscrire à une commande d'un site web signifie autoriser ce site web à faire ce qu'il veut avec votre navigateur. Nous voulons être sûrs que les gens comprennent les dangers avant de souscrire à des commandes, donc l'avertissement est plutot inquiétant:

PAGE UNDER CONSTRUCTION