Labs/Ubiquity/Ubiquity 0.5 Locked-Down Feed Tutorial

	THIS PAGE IS A WORKING DRAFT
	The page may be difficult to navigate, and some information on its subject might be incomplete and/or evolving rapidly. If you have any questions or ideas, please add them as a new topic on the discussion page.

This version is for the latest source version of Ubiquity 0.5. Click here for the 0.1 version of this page

TODO

Edit tutorial to reflect new command API.

Introduction

Locked-Down Feeds, or LD Feeds, are just one way to write functionality that can be used from anywhere. The advantage of of this kind of feed is that all code is run in a very restricted sandbox that has minimal access to the outside environment—for instance, it can't access the network or the local filesystem. This means that subscribing to such feeds is worry-free: unlike regular command feeds, there's no scary warning page to read. Instead, subscribing to a LD Feed results in the following unintrusive confirmation:

The downside, of course, is that this safety comes at the cost of flexibility: put simply, you can't do nearly as much with LD Feeds as you can with regular feeds, but it can still be used to make a variety of useful commands.

Note that Locked-Down Feeds are just one example of a feed type—they're not replacing regular feeds, but instead coexist alongside them. They're part of the Ubiquity team's explorations into different kinds of security models; for more information, check out Atul's blog post.

The rest of this tutorial assumes that you've at least skimmed through the Ubiquity Author Tutorial.

A Lot Like Regular Feeds

LD Feeds are best thought of as a strict subset of regular feeds. For instance, commands are created using CmdUtils.CreateCommand() and displayMessage() works too, so the code for our "Hello World" example is exactly the same as it is for regular feeds:

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

Setting the selection works the same way too, as does documentation and metadata:

CmdUtils.CreateCommand({
  name: "date",
  homepage: "http://azarask.in/",
  author: {name: "Aza Raskin", email: "aza@mozilla.com"},
  contributors: ["Atul Varma"],
  license: "MPL",
  description: "Inserts today's date.",
  help: ("If you're in an editable text area, inserts " +
         "today's date, formatted for the current locale."),

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

Telling Ubiquity The Feed Type

The only thing we really need to change is to tell Ubiquity that it should interpret the code as a LD Feed instead of a regular one. You can do this in Ubiquity's built-in command editor by specifying "locked-down-commands" in the feed type drop-down menu. When sharing it with the world, you use a value of locked-down-commands for the rel attribute in the link tag:

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

Direct Objects and Modifiers

Commands in LD Feeds can use direct objects and modifiers, but they can only be specified using regular expressions: the noun types available in regular feeds aren't available here.

For instance, here's a "replace" command that allows the user to perform a find-replace operation on their selection via Ubiquity:

/* This is a template command. */
CmdUtils.CreateCommand({
  name: "replace",
  takes: {"input": /.*/},
  modifiers: {"with": /.*/, "in": /.*/},
  preview: function(pblock, input, mods) {
    var stuff = mods['in'].text;
    var regExp = new RegExp(input.text, "g");
    var replacer = mods['with'].text;
    if (!replacer || !stuff || !input.text) {
      pblock.innerHTML = ("Replaces the given text in the given " +
                          "selection with something different.");
    } else {
      var newText = stuff.replace(regExp, replacer);
      pblock.innerHTML = newText;
    }
  },
  execute: function(input, mods) {
    var stuff = mods['in'].text;
    var regExp = new RegExp(input.text, "g");
    var replacer = mods['with'].text;

    CmdUtils.setSelection(stuff.replace(regExp, replacer));
  }
});

Limitations

Because LD feeds are so secure, they have lots of limitations. For instance:

• Any HTML content inserted into the current selection, the preview area, or anything else is automatically sanitized to prevent against code injection attacks. This means that lots of types of HTML elements can't be used, e.g. the <img> tag.

• No access to the network can be made, though this restriction may be lifted in the future.

• It's not possible to cite other JS files as dependencies, though this restriction may be lifted in the future.

• It's not possible for commands to run on page load or startup.

Where To Go From Here

For more information on what's available in LD Feeds, check out the Locked-Down Feed Reference Documentation.

Sharing your LD Feeds is encouraged, especially since they're so safe. Clicking the "share" button in the command editor when editing a LD Feed automatically pastes your feed to the LD Feed Playground, where it's automatically given the proper <link rel> tag, so feel free to use that to publish your commands and link to them from the Commands In The Wild page.