Creating a Microformat Action User Script (Basic)

All user scripts consist of a JavaScript object that contains details about the action or microformat to be added, and then a call to add that object to the list of either actions or microformats. So step one is to create the JavaScript object that describes our action. We're going to create an action that finds the nearest Domino's Pizza to a given adr (Address) microformat on a web page. To do this, we're going to use the site located here: http://www.dominos.com/Public-EN/Site+Content/Primary/Find+A+Dominos/. You'll notice that when you search for an address, the address is encoded in the URL. This makes our job much easier. The primary thing that you can do with an action is construct a URL and have Operator load it, although you could also write data to the hard drive or create a POST of some data as well. Our example will focus on loading a URL. Here's the completed example for reference.

Looking at the example, the first thing we did was define our JavaScript object called dominos and define a description for it. This step is pretty straightforward:

var dominos = {
 description: "Find the nearest Domino's Pizza",
 shortDescription: "Domino's",
...
}

If we want to have our description in multiple languages, we can do this by creating an array that contains the different translations as Unicode escape sequences:
var dominos = {
 description:
  "en-US": "Find the nearest Domino's Pizza",
  "fr-FR": "Trouvez la pizza du domino le plus proche",
...
}

You can also specify an icon for your action if you want. Domino's doesn't have a favicon, but if it did, we could specify:

icon: "http://www.dominos.com/favicon.ico",

Next we define something called the "semantic scope." This concept sounds strange, but it's just the best terminology I could come up with. Semantic scope defines which microformat a given action acts on and which properties must be present in order for it to be available. For instance, an action that added an event to a calendar might require that a there be a start date for the event. If you don't require any specific property in the microformat, you just specify the name of the microformat on both sides. Note that if the property you specify as a required property can be present more than once in the microformat (like the url in an hCard for instance), you will have the opportunity to specify an action for each property (more on that later). So here's our semantic scope for our action:

scope: {
 semantic: {
  "adr" : "adr"
 }
},

This is as simple as semantic scope could be. If we wanted to work with only addresses that had postal codes, for instance, we would specify:

scope: {
 semantic: {
  "adr" : "postal-code"
 }
},

If the microformat for which you are creating an action has subproperties, we can specify those in the semantic scope as well. So if we wanted an action that only worked with hCards that had addresses that had postal codes, it would look like this:

scope: {
 semantic: {
  "hCard" : "adr.postal-code"
 }
},

There are other types of scope as well. For instance, there is a url scope that we can use if we want our action to only work on certain domains. The cork'd user script uses this technique.

 scope: {
  url: "http://corkd.com"
 },

Now that we've defined when this action should be used, we'll actually create the function that executes the action. For this, we have a function called doAction:

doAction: function(semanticObject, semanticObjectType, propertyIndex)
{
}

The first parameter, semanticObject, is a JavaScript object that represents the microformat. Since our action is an adr, it has members like street-address, region, locality and postal-code. These can be accessed the same way as any other member of a JavaScript object - semanticObject.region, semanticObject.locality. Note that if the properties contain a dash (-), they need to be accessed like this: semanticObject["street-address"].

The second parameter is semanticObjectType. If our action handles multiple microformats, this tells us the type of the semanticObject in the first parameter. In our case, it will always be "adr."

The third parameter is an optional parameter called propertyIndex. If we specified a required property that has more than one instance, propertyIndex will indicate for which instance this action is being invoked.

The doAction function itself has one primary responsibility in our action - to construct a URL and return it. When Operator receives a URL from an action, it simply invokes the URL. If your action is going to do something other than invoke a URL, it should return true to indicate that it handled the action. I'll leave it up to you to look at the example to see the doAction.

The final step is to actually add the action to or list of actions. This is accomplished by calling the function add on our global SemanticActions object. Note the first parameter is an internal name for the action. It doesn't have to be the same as the name of the object.

SemanticActions.add("dominos", dominos);

If you need more examples of user scripts to use for a guide, check out Operator User Scripts.

Now that we've covered the basic user script, next we'll cover creating a user script that changes the name of the action, as well as a user script that acts on all microformats on a given page.

Please note: I reserve the right to delete comments that are offensive or off-topic.

Leave a Reply

Your email address will not be published. Required fields are marked *

7 thoughts on “Creating a Microformat Action User Script (Basic)

  1. The mutli-language support is really cool. Now I can add start adding descriptions in Spanish.
    The documentation makes easier to write extensions for Operator.

  2. Thanks for this great tutorial. I've used Operator for awhile now, but I had not yet had the urge to write a user script. I am definitely inspired to do so after reading this. I look forward to your upcoming article on how to write a script that acts on all microformats on the page.

  3. Once I searched for it, I found that "Operator" meant the add-on. I had never seen it. If this was an introductory article, can you try to include a little more introduction.

    thanx.