include-pattern

include pattern

Initially developed as part of resume-brainstorming, it has become clear from actual microformats markup experience with real world sites, that several microformats (e.g. hResume, hReview, hAtom etc.) need a mechanism to include a portion of data from area of a page into another area of a page. This page documents this pattern for re-use in those microformats and any others that need this feature.

Author

Tantek Çelik

Background

In hResume, we needed the ability to include the name from the hCard at the top of the resume for a person into their hCards in the middle of the resume which represented each of their job hCards (job title, organization name, address etc.), and thus developed the hCard reference via object technique.

class name "include"

In order to make this more explicit (helps forward compatibility for parsers), we are adding the class name "include" on the object element to indicate that that object refers to a subtree which should be included in its place by microformat parsers.

Proposal 1: Allow the use of <a href class="include"> as a secondary include-pattern mechanism, due to some browsers mishandling the object include-pattern. See include-pattern-feedback for details.

object include example

Here is an example of an hCard you could have at the top of a page, shown here also as a verbose hCard for purposes of illustration that the reference may be to a subtree, not just a text node:

<span class="vcard">
 <span class="fn n" id="j">
  <span class="given-name">James</span> <span class="family-name">Levine</span>
 </span>
</span>

Somewhere else on the page, you could have another hCard which would re-use that "fn n" content from the first hCard:

<span class="vcard">
 <object data="#j" class="include" type="text/html"></object>
 <span class="org">SimplyHired</span>
 <span class="title">Microformat Brainstormer</span>
</span>

Thus a microformat parser would treat the above as follows, with the object include completely replaced by the subtree that it references:

<span class="vcard">
 <span class="fn n" id="j">
  <span class="given-name">James</span> <span class="family-name">Levine</span>
 </span>
 <span class="org">SimplyHired</span>
 <span class="title">Microformat Brainstormer</span>
</span>

This method of hCard property indirection via an object element can apply to any/all properties in class-based microformats.

Note 1: the object data attribute MUST be a local ID reference. External references (which would require a consuming application to load an external resource) are currently not supported by this method.

Note 2: type="text/html" is used because that is the most common Content-Type of web pages. On pages served as "application/xhtml+xml", use that Content-Type for the type atribute on object includes on those pages.

Proposal 2: "text/html" is for an entire HTML document, and not precisely correct for a well-formed fragment of (X)HTML. "text/xml" would make sense if the HTML fragment happened to also be well-formed XML, but it also has the drawback of being semantically weak, that is, the fact that the fragment contains HTML with much more meaning than just XML is lost. Thus the proposal is to use a new content-type, such as "text/html-frag", or "text/x-html-frag" if an unofficial "x-" version is preferred.

Note 3: To avoid unsightly messes in Safari, you should include the following style rule in a style sheet for the page:

object.include { width:0; height:0 }

Note 4: To prevent infinite loops a class="include" can not be a child-or-self of the ID it is refering too

hyperlink include example

Per the proposal 1 above, here is how you would code the above object include example using the <a href> tag.

<span class="vcard">
 <a href="#j" class="include" type="text/html"></a>
 <span class="org">SimplyHired</span>
 <span class="title">Microformat Brainstormer</span>
</span>

Changes:

1. a open/close tag instead of object open/close tag
2. href attribute instead of data attribute
3. ... that's it. only 2 changes.

Following proposal 2, we can update the 'type' attribute as well:

<span class="vcard">
 <a href="#j" class="include" type="text/html-frag"></a>
 <span class="org">SimplyHired</span>
 <span class="title">Microformat Brainstormer</span>
</span>

And just as in the object include example, the end effective result to the parser is the same, and the same Notes apply.

<span class="vcard">
 <span class="fn n" id="j">
  <span class="given-name">James</span> <span class="family-name">Levine</span>
 </span>
 <span class="org">SimplyHired</span>
 <span class="title">Microformat Brainstormer</span>
</span>

Acknowledgments

Thanks to discussions and brainstorms with a bunch of folks: Ryan King, James Levine, the whole crowd at the Microformats specifications working session at MashupCamp, Brian Suda, Scott Reynen, Drew McLellan.

Specifications Using

• hResume
• hReview

Considering

• hAtom
• hCalendar
• hCard

Implementations

• X2V implements the include-pattern when parsing hCards and hCalendars for both object.include and a.include.

References

Normative

• HTML 4.01
• XHTML 1.0

Informative

• hCard

Related

• Introducing HInclude by Mark Nottingham.
  • HInclude is a markup extension + javascript library for including *external* files into an XHTML document.

Discussions

• Feedback is encouraged on the include-pattern-feedback page.
• See also blogs discussing this page.

Q&A

• If you have any questions about include-pattern, check the include-pattern FAQ, and if you don't find answers, add your questions to the end of the page!

Issues

• Please add any issues with the specification to the separate include-pattern issues document.