View source

You do not have permission to edit pages, for the following reasons:
This page has been locked to prevent editing.
The action you have requested is limited to users in the group Users.
You can view and copy the source of this page:
<h1>Include Pattern</h1>
{{TOC-right}}
Initially developed as part of [[resume-brainstorming]], the include pattern is a mechanism to include a portion of data from one area of a page into another area of the same page. The following is documentation for re-use of the pattern in other microformats, and for publishers working with it.

;Editors: Tantek Çelik
: Ben Ward

== background ==

[[hresume|hResume]] needed the ability to include a name from one hCard at the top of a resume — the person's contact details — into into the separate hCards used in the same person's employment history. Repeating so much data would be inconvenient to publishers, irritating to consumers and would not have matched the existing publishing techniques used in Resumes and Curriculum Vitæ. The include pattern is a mechanism to reference data from the same page, avoiding repetition.

== scope ==

The include pattern is strictly limited to the scope of the current page. It cannot be used to include content from other URLs.

== quick reference==

The include-pattern is a mechanism to include content from one microformat into another microformat elsewhere in the same document, using hyperlinks (recommended) or OBJECT. For example:

<pre><nowiki><a class="include" href="#author">Ben Ward</a></nowiki></pre>
<pre><nowiki><object class="include" data="#author"></object></nowiki></pre>

In specs which cite the include-pattern, either of the above code snippets will cause a microformats parser to replace the A or OBJECT element with class name "include" with the content fragment with ID "author". Full examples follow.

== in general==

To reference includes, use an include element with class name "include" and a document fragment identifier. The content to be included should have an ID attribute set, and that ID should be referenced from the HREF or DATA attribute at the point of inclusion.

The include element with class name "include" indicates a reference to a sub-tree elsewhere in the document which must be included in-place by microformat parsers. That is, the element with class "include" is _replaced_ in the DOM by the referenced sub-tree.

To prevent infinite loops, if a class="include" refers to itself or to an ancestor in the parse tree, then it is ignored and has no effect on the parser.

Per the [[include-pattern#Scope|scope]], the OBJECT 'data' attribute and hyperlink 'href' attribute MUST be local ID references when used as include pattern instances. External references (requiring a consuming application to load an external resource) are not supported by this method.

There are two HTML elements available to reference includes, hyperlink/Anchor and OBJECT. They are documented below.

These methods of property indirection via a hyperlink element can apply to any/all properties in class-based microformats, but should only be used where a microformat explicitly states that the include-pattern is a dependency. For example, [[XOXO]] does not reference the include-pattern at this time, so sub-trees cannot be included by reference in XOXO. [[hResume]] and [[hReview]] do reference the include pattern.

=== Hyperlink ===

The recommended way to reference includes within microformats is to use a hyperlink.

==== Hyperlink example====

Here is an [[hcard|hCard]] from the beginning of a resume, shown here as a verbose hCard.

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

Elsewhere on the page, a second hCard re-uses the "fn n" content from the first hCard:

<pre><nowiki>
<span class="vcard">
 <a href="#jl-name" class="include" title="James Levine"></a>
 <span class="org">SimplyHired</span>
 <span class="title">Microformat Brainstormer</span>
</span>
</nowiki></pre> 

A microformat parser must treat the second hCard as follows, with the hyperlink include element completely replaced (including inner-text) by the sub-tree that was referenced:

<pre><nowiki>
<span class="vcard">
 <span class="fn n" id="jl-name">
  <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>
</nowiki></pre> 

==== notes and issues ====

Note: The <code>id</code> attribute value in the example "jl-name" was chosen for demonstration purposes.  The text of the value has no semantic per the include-pattern other than to connect the source of the include to the destination.  Authors {{should}} use good {{POSH}} techniques to choose <code>id</code> and <code>class</code> names.

Using the hyperlink include pattern causes no known issues in any web browser. 

Authors {{should}} supply content text or at least <code>title</code> attribute text for the hyperlink itself. This can require repeating a small piece of information (such as a person's name in an hCard), or including generic text suitable for the context of the page. 

===== accessibility =====
There are two points of view on this. <span id="Accessibility_concerns">The first is that the user experience of Assistive Technology can(might?) be severely degraded by the presence of hyperlinks which do not contain text ('''citation needed''').</span>  The second is that the first claim is only a side effect of some Assistive Technologies extracting the hyperlinks in a document and presenting them as a list, and that such technologies / features have no right to do so, and therefore it is not your problem to worry about. See [http://joeclark.org/appearances/atmedia2007/#context Joe Clark: When accessibility is not your problem: Headings and links read out of context], in particular:
<blockquote><p>As writers, we are not authorizing you or Jaws to pull out our link text and remix it. Why don’t you rearrange the sentences, too?</p></blockquote>

=== Object ===

The Object Include Pattern is semantically superior to the Hyperlink Include; it is being used to embed content into the page. The <code>object</code> element based include was the original developed include pattern. However, there are serious browser compatibility issues that can affect some implementation scenarios and thus the above Hyperlink Include Pattern was developed and is now preferred.

==== Object example ====

Here is the same [[hcard|hCard]] from the beginning of the resume in the previous example.

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

Elsewhere on the page, a second hCard re-uses the "fn n" content from the first hCard:

<pre><nowiki>
<span class="vcard">
 <object data="#jl-name" class="include"></object>
 <span class="org">SimplyHired</span>
 <span class="title">Microformat Brainstormer</span>
</span>
</nowiki></pre> 

A microformat parser must treat the second hCard as follows, with the <code>object</code> include element completely replaced by the sub-tree that it referenced:

<pre><nowiki>
<span class="vcard">
 <span class="fn n" id="jl-name">
  <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>
</nowiki></pre>

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

=== notes and issues===
* Unlike the hyperlink pattern, the Object Include Pattern does not require any textual fallback. This makes it invisible to Assistive Technology with no adverse affect.
* Apple's Safari (WebKit-based) browser has some rendering issues with this use of <code>object</code>: You should set a width and height of "0" for the include elements to resolve this ('''version(s) affected needed''').
* Bugs have been reported in some web browsers (Internet Explorer, Safari, Firefox) that <code>object</code> elements referencing fragments of the same document erroneously cause the browser to make additional HTTP requests ('''version(s) affected needed'''). For scenarios where HTTP requests are a sensitive performance measure, this makes the Object Include Pattern inappropriate.
* Versions of Microsoft Internet Explorer with ActiveX controls disabled will throw a warning prompt upon finding an <code>object</code> element ('''version(s) affected needed''').

== acknowledgements ==

Thanks to discussions and brainstorms with a bunch of folks: [http://theryanking.com/ Ryan King], James Levine, the whole crowd at the [http://mashupcamp.com/index.cgi?HAtomFinalization Microformats specifications working session] at MashupCamp, [http://suda.co.uk/ Brian Suda], [http://randomchaos.com/ Scott Reynen], [http://allinthehead.com/ Drew McLellan].

== specifications using ==
* [[hresume|hResume]]
* [[hreview|hReview]]

=== considering ===
All class-based microformats {{should}} consider using and explicitly normatively stating support for the include pattern.
* [[hatom|hAtom]]
* [[hcalendar|hCalendar]]
* [[hcard|hCard]]

== implementations ==
* X2V implements the [[include-pattern]] when parsing [[hcard|hCards]] and [[hcalendar|hCalendars]] for both object.include and a.include.

== references ==

=== normative ===
* HTML 4.01

=== informative ===
* [[hcard|hCard]]
* [[hresume|hResume]]
* XHTML 1.0

== related pages==
{{include-pattern-related-pages}}
* See also [http://www.technorati.com/cosmos/referer.html blogs discussing this page].
Templates used on this page:
Return to include-pattern.
Retrieved from "http://microformats.org/wiki/include-pattern"
Views

Microformats Wiki

Toolbox

Hey! You're not logged in
