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 an 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.

scope

The include pattern is strictly limited to the scope of the current page. This is by design in order to avoid multipage / multidomain etc. problems. Also "current page" uses cover the vast majority of use cases thus we are solving that problem first.

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"></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: 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 2: To prevent infinite loops, if a class="include" refers to itself or an ancestor in the parse tree, then it is ignored and has no effect on the parser.

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"></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.

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>

restrictions

Per the scope, the object 'data' attribute and a 'href' attribute MUST be local ID references when used as include pattern instances. External references (which would require a consuming application to load an external resource) are currently not supported by this method.

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
• currency
• measure

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!

Related pages

• include-pattern-examples - pages which use the include pattern.

Issues

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