User:Mkaply:Fx-Docs:Microformats/Architecture
From MozillaWiki
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);