Don't Forget to Plant It!

Creating a Tails Script

A Tails Script is basically a very simple JavaScript file ending with the tails.js extension. To get started, you can build from the sample Tails script here.

Like a Greasemonkey user script, a Tails Script has a metadata section describing how to install the plugin. The metadata section starts with the // ==TailsScript== comment and ends with the // ==/TailsScript== comment. Metadata values are defined the comment format:

1

// @name value

The supported metadata values are:

  • name - The name of the script. This will be the text of the link if a URL is rendered.
  • namespace - The namespace of the script.
  • description - A description of the script. This will be displayed in the script management window.
  • include - The microformats that this script can operate on. Add multiple include lines for each microformat you support.

When a Tails Script is executed, the contents of the script is loaded within a JavaScript Hash object, so functions and variables must be defined with the name: (variable | function) syntax and separated by commas.

The only method that Tails requires in the script is the getURL function. This function does not have any parameters and should return the URL of the link to render in the Tails view. Not returning anything or returning null will result in the the link not rendering in the view. The method can access the current microformat object by accessing the object instance variable:

1

getURL: function() { if (this.object.__name == 'hcard'){ /* generate URL... */ } }

In addition to getURL(), you can also specify the following function to further customize the behavior of your script:

  • getLabel() - Returns the label for the generated link. If this method is not defined, the script name will be used instead.

The following instance variables are available to the script in addition to object:

  • sourceURL - The URL of the web page containing the current microformat.
  • label - The name of the script.

Data Object Members

The parsed microformat objects always contain the following member:

  • __name - The name of the microformat (hcard, hcalendar, etc.)

The following section lists the members variables/functions that might be available for that particular microformat. Although the specs might specify that some values are required, Tails is pretty forgiving and will more than likely create an object for it anyway. Just to be safe you should make sure that value is available before accessing it.

For the one-worded object members, you can access them with the standard object.name syntax (example: object.fn); However, since multi-word names are usually separated by a dash (-), you’ll need to use the object[“name”] syntax instead (example: object[“family-name”]).

hAtom

  • Basic member variables - entry-title, entry-content, entry-summary, bookmark
  • JavaScript Date values - updated_date, published_date
  • author_hcard - Post author as an hCard object (see hCard spec below).
  • getTagString() - Returns a comma seperated list of tag names.

hCalendar

  • Basic member variables - dtstart, dtend, summary, location, comment, description, contact, sequence, priority, dtstamp, last-modified, created, recurrence-id, attendee, organizer, url
  • JavaScript Date values - dtstart_date, dtend_date
  • location_hcard - The location as an hCard object (see hCard spec below).

hCard

  • Basic member variables - n, fn, given-name, family-name, title, note, org, locality, region, street-address, postal-code, country-name, email, logo, photo, url
  • tel - An array of telephone numbers (or undefined if none were specified). Each object in the array will at least a value member, and maybe a type member if specified.
  • toAddressString() - Method returning a prettied up version the address (street-address, locality, region, postal-code, country.
  • toStreetAddressLocalityRegionAndPostalCodeString() - Method returning a prettied up string containing street-address, locality, region, postal-code values.
  • toLocalityAndRegionString() - Method returning a prettied up string containing locality, region values.
  • toLocalityRegionAndPostalCodeString() - Method returning a prettied up string containing locality, region, postal-code values.
  • toLocalityRegionAndCountryString() - Method returning a prettied up string containing locality, region, country values.
  • toLocalityRegionPostalCodeAndCountryString() - Method returning a prettied up string containing locality, region, postal-code, country values.

hResume

  • Basic member variable - summary
  • contact_hcard - hCard of the person described in the resume.
  • education - An array or hCalendar events.
  • experience - An array or hCalendar events.
  • skill - An array of skills (String objects).
  • affiliation - An array of hCards.
  • publications - An array of publications (String objects).

hReview

  • Basic member variables - rating, description, summary, type, version, dtreviewed, url
  • JavaScript Date values - dtreviewed_date
  • item - item_hcard variable will be available if an hCard is present and item_hcalendar variable for hCalendar. Otherwise, item.fn, item.photo, or item.url if available. Finally, if none of those values are present, item will be a string of the node’s contents.
  • reviewer - hCard object of the reviewer

xFolk

  • Basic member variable - description
  • taggedlink - Object representing the bookmarked link, containing object members name and url.
  • tags - An array of tags. Each tag object will have object members name and url.

geo

  • Basic member variables - lattitude, longitude, lattitude_label, longitude_label, label.

Comments