Tento článek je překladem anglického originálu na Mozilla Wiki. Autory původního textu jsou: Aza Raskin, Blair McBride, Abimanyu Raja, Jono DiCarlo a Atul Varma.

Velkou sílou Ubiquity je z pohledu vývojářů fakt, jak snadno v něm lze vytvářet příkazy. Pomocí několika řádků JavaSciptu umožní Ubiquity dokonce běžným webovým vývojářům zásadně vylepšit webový prohlížeč. Tento tutoriál vás provede od několikařádkových jednoduchých skriptů až po 50řádkový skript pro integraci s Twitterem.

Upozornění: Ubiquity se stále vyvíjí. API se pravděpodobně bude v budoucnu výrazně změnit. Ačkoliv to znamená, že příklady, které dnes napíšete, nemusí příští týden fungovat, také to znamená, že nám můžete zaslat váš feedback a ovlivnit tak směr, kterým se Ubiquity vydává. (Pozn. překl.: Některé příklady z původního textu v poslední verzi Ubiquity nefungovaly, místy jsme proto tutoriál upravili, aby fungoval i v aktuální verzi Ubiquity, tj. 0.1.5.)

Rychlý vývoj

Ubiquity po vás nebude požadovat restart Firefoxu během programování. Tomu jsme se snažili vyhnout. Místo toho Ubiquity načítá příkazy znovu pokaždé, když ho zavoláte. A pokud používáte zabudovaný editor, nemusíte dokonce nic ukládat.

Pokud chcete otevřít zabudovaný editor příkazů, zavolejte Ubiquity (control/alt + space) a vložte příkaz „command-editor“. Během tohoto tutoriálu, kdykoliv budeme chtít spustit příkaz v Ubiquity, napíšeme Ubiq, např. Ubiq „command-editor“.

Během následujících příkladů prostě pište do zabudovaného editoru. Příkazy se načtou, jakmile zavoláte Ubiquity.

Váš první příkaz: Hello World

Začneme tým nejtypičtějším příkladem: vypíšeme „Hello, World!“.

Do zabudovaného editoru napište:

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

Nyní zkuste Ubiq „hello-world“. Uvidíte, že se „Hello, World!“ hned zobrazí na obrazovce. Pokud používáte Mac OS X s nainstalovaným Growl, objeví se Growl zpráva. Pokud používáte Windows, objeví se klasická zpráva pravém dolním rohu obrazovky.

Na Ubuntu se zobrazí:

Pokud nepoužíváte OS X s Growl ani Windows XP/Vista nebo Ubuntu, pak žádné upozornění zatím neuvidíte. V dalších verzích Ubiqity tento problém vyřešíme.

Zpět k příkladu. Výkonnou složkou našeho příkazu je funkce displayMessage(), která zobrazí zprávu způsobem obvyklým ve vašem operačním systému.

Příkaz můžete pojmenovat prakticky jakkoliv, dokonce včetně ne-ASCII znaků.

Ve jmenném prostoru CmdUtils najdete řadu užitečných funkcí. Zatím nejsou všechny dokumentovány, ale s několika užitečnými se v tomto tutoriálu seznámíte. Více informace najdete na stránce s automaticky generovanou dokumentací nebo v cmdutils.js.

Přidáme náhled

Nyní k našemu příkazu přidáme náhled. Náhled dává uživateli zpětnou vazbu dříve, než je vlastní příkaz spuštěn. Může se jednat o vizuální feedback jako je grafická reprezentace atmosférických podmínek při použití příkaz weather výše. Náhledy mohou využívat veškerou sílu HTML včetně animací, takže s nimi můžete dokázat opravdu hodně.

Důležitá poznámka k návrhu: Kód náhledu by neměl mít žádný postranní efekt, tj. samotný náhled (bez zásahu uživatele) nikdy nesmí změnit stav systému.

V našem příkazu „hello-world“ nepotřebujeme dělat nic dramatického, prostě jen přidáme text sloužící pro nápovědu, který bude lepší než výchozí „Executes the hello-world command.“

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

V tomto případě jsme do vlastnosti preview vložili formátovaný HTML řetězec, ale můžeme do něj vložit i funkci. To si ukážeme v další části.

Druhý příkaz: datum

Nastavujeme výběr

Často zapomínám, co je dnes za den. Možná bych měl chodit častěji ven, ale stejně jako jiní programátoři raději řeším symptomy pomocí technologie než vlastní příčinu. Proto si vytvořím příkaz, který na pozici kurzoru vloží aktuální datum.

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

Použili jsme tu novou funkci setSelection(). Ta vloží text do stránky na pozici kurzoru. Pokud je kurzor v editovatelném poli, pak dojde k vložení textu. Pokud kurzor v takovém poli není, bude setSelection() přesto schopná text vložit. (Firefox si vždy uchovává pozici kurzoru. Zobrazíte si ji pomocí klávesy F7.) Zkuste si zobrazit nějakou stránku, označit v ní kus (neměnného) textu a spusťte náš příkaz. Funguje! Jedná se o obzvláště užitečnou funkci pro příkazy typu „přelož“, které vám přeloží texty na stránce.

Funkce toLocalDateString() je nativní funkce JavaScriptu. Pokud ji neznáte, podívejte se do dokumentace.

Lepší náhled

Nastal čas, abychom našemu příkazu date vytvořili lepší náhled. Přidáme tedy náhled, který nám zobrazí aktuální datum, aby uživatel viděl, co může po spuštění příkazu čekat. (Mimochodem uživatel nyní nebude dokonce muset náš příkaz spustit, aby zjistil, jaký den právě je.)

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() );
  }
}) 

V tomto příkladu jsme použili 2 nové věci. Tou první je vyčlenění kódu pro zjištění aktuálního data do funkce _date(), to proto, abychom neporušili pravidlo DRY. Všimněte si, že při přístupu k této funkci jsme použili klíčové slovo  this.

Tou druhou věcí je naše funkce pro náhled. Jejím prvním argumentem je DOM prvek, který bude zobrazen jako náhled našeho příkazu. Pokud upravíte obsah pblock, upravíte i náhled. V našem případě jsme jeho obsah upravili pomocí  innerHTML.

A ještě jedné zajímavé věci si všimněte, použili jsme formátování pomocí funkce renderTemplate(). Ta vezme řetězec se šablonou a provede příslušné záměny podle JSON objektu, který jí předáte. Šablony umí široké spektrum funkcí, pochází z projektu Trimpath. Na jejich webu najdete další dokumentaci. V dalších verzích plánujeme použít projekt MJT.

Náhled se zobrazí uživateli okamžitě. Pokud používáte náhled, který obsahuje AJAXové volání, aby získal potřebná data, může mu takové volání chvíli trvat. Během volání byste měli uživateli něco zobrazit, např.:

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

Do budoucna plánujeme tento krok ještě vylepšit.

Pokračování příště

V další části tutoriálu přidáme našemu příkazu metadata, dokumentaci a vysvětlíme si, jak jej můžete distribuovat dalším uživatelům.

Článek, který jste právě dočetli, je překladem anglického originálu a je zde publikován s laskavým svolením Mozilla Corporation.