User:Mkaply:Fx-Docs:Microformats/Architecture

Access to microformats and the microformats APIs will be via the global Microformats object. Access to this object will be via the new JS script loader. To load Microformats, you would need this at the top:

Components.utils.import("resource://gre/modules/Microformats.js");

The following APIs will be available for accessing microformat content from a web page:

 /**
  * Retrieves microformats objects of the given type from a document
  * 
  * @param  name          The name of the microformat (required)
  * @param  rootElement   The DOM element at which to start searching (required)
  * @param  recurseFrames Whether or not to search child frames for microformats (optional - defaults to true)
  * @param  microformats  An array of microformat objects to which is added the results (optional)
  * @return A new array of microformat objects or the passed in microformat 
  *         object array with the new objects added
  */
 Microformats.get(name, rootElement, recurseFrames, microformats);

 /**
  * Counts microformats objects of the given type from a document
  * 
  * @param  name          The name of the microformat (required)
  * @param  rootElement   The DOM element at which to start searching (optional - defaults to content.document)
  * @param  recurseFrames Whether or not to search child frames for microformats (optional - defaults to true)
  * @param  count         The current count
  * @return The new count
  */
 Microformats.count(name, rootElement, recurseFrames, count);

 /**
  * Returns true if the passed in node is a microformat. Does NOT return true
  * if the passed in node is a child of a microformat.
  *
  * @param  node          DOM node to check
  * @return true if the node is a microformat, false if it is not
  */
 Microformats.isMicroformat(node);

 /**
  * If the passed in node is contained in a microformat, this function returns
  * the microformat that contains it. If the passed in node is a microformat,
  * it still returns the parent.
  *
  * @param  node          DOM node to check
  * @return If the node is contained in a microformat, it returns the parent
  *         DOM node, otherwise returns nothing
  */
 Microformats.getParent(node);

 /**
  * If the passed in node is a microformat, this function returns a space 
  * separated list of the microformat names that correspond to this node
  *
  * @param  node          DOM node to check
  * @return If the node is a microformat, a space separated list of microformat
  *         names, otherwise returns nothing
  */
 Microformats.getNamesFromNode(node);

The following APIs will be available as helper APIs, primarily for working with the data in a microformat. These will mainly be used by actions.

 /**
  * Converts an ISO8601 date into a JavaScript date object, honoring the TZ
  * offset and Z if present to convert the date to local time
  * NOTE: I'm using an extra parameter on the date object for this function.
  * I set date.time to true if there is a date, otherwise date.time is false.
  * 
  * @param  string ISO8601 formatted date
  * @return JavaScript date object that represents the ISO date. 
  */
 Microformats.dateFromISO8601(string);

 /**
  * Converts a Javascript date object into an ISO 8601 formatted date
  * NOTE: I'm using an extra parameter on the date object for this function.
  * If date.time is NOT true, this function only outputs the date.
  * 
  * @param  date        Javascript Date object
  * @param  punctuation true if the date should have -/:
  * @return string with the ISO date. 
  */
 Microformats.iso8601FromDate(date, punctuation);

The following APIs are specific to the creation of new microformats. They are used in the definition of microformats to retrieve data. Most of these APIs are on the parser object in Microformats.

 /**
  * Adds microformats to the microformat module
  * 
  * @param  microformat           The name of the microformat that is being added
  * @param  microformatDefinition A JavaScript structure describing the microformat
  *
  * Note: we always replace an existing definition with a new one.
  * The structure of the microformat definition will be documented separately.
  */
 Microformats.add(microformat, microformatDefinition);

   /**
    * Uses the microformat patterns to decide what the correct text for a
    * given microformat property is. This includes looking at things like
    * abbr, img/alt, area/alt and value excerpting.
    *
    * @param  propnode   The DOMNode to check
    * @param  parentnode The parent node of the property. If it is a subproperty,
    *                    this is the parent property node. If it is not, this is the
    *                    microformat node.
    * @return A string with the value of the property
    */
   Microformats.parser.defaultGetter(propnode, parentnode);

   /**
    * Used to specifically retrieve a date in a microformat node.
    * After getting the default text, it normalizes it to an ISO8601 date.
    *
    * @param  propnode   The DOMNode to check
    * @param  parentnode The parent node of the property. If it is a subproperty,
    *                    this is the parent property node. If it is not, this is the
    *                    microformat node.
    * @return A string with the normalized date.
    */
   Microformats.parser.dateTimeGetter(propnode, parentnode);

   /**
    * Used to specifically retrieve a URI in a microformat node. This includes
    * looking at an href/img/object/area to get the fully qualified URI.
    *
    * @param  propnode   The DOMNode to check
    * @param  parentnode The parent node of the property. If it is a subproperty,
    *                    this is the parent property node. If it is not, this is the
    *                    microformat node.
    * @return A string with the fully qualified URI.
    */
   Microformats.parser.uriGetter(propnode, parentnode);

   /**
    * Used to specifically retrieve a telephone number in a microformat node.
    * Basically this is to handle weird value excerpting
    *
    * @param  propnode   The DOMNode to check
    * @param  parentnode The parent node of the property. If it is a subproperty,
    *                    this is the parent property node. If it is not, this is the
    *                    microformat node.
    * @return A string with the telephone number
    */
   Microformats.parser.telGetter(propnode, parentnode);

   /**
    * Used to specifically retrieve an email address in a microformat node.
    * This includes at an href, as well as removing subject if specified and
    * the mailto prefix.
    *
    * @param  propnode   The DOMNode to check
    * @param  parentnode The parent node of the property. If it is a subproperty,
    *                    this is the parent property node. If it is not, this is the
    *                    microformat node.
    * @return A string with the email address.
    */
   Microformats.parser.emailGetter(propnode, parentnode);

   /**
    * Used to specifically retrieve HTML in a microformat node.
    *
    * @param  propnode   The DOMNode to check
    * @param  parentnode The parent node of the property. If it is a subproperty,
    *                    this is the parent property node. If it is not, this is the
    *                    microformat node.
    * @return A string with the HTML including all tags.
    */
   Microformats.parser.HTMLGetter(propnode, parentnode);