include-pattern: Difference between revisions

From Microformats Wiki
Jump to navigation Jump to search
m (changed externally formated link to internal wiki link)
(Substantial update // Moved Hyperlink include above OBJECT include // Made examples consistent // Improved voice in some sections // Describes ‘replacement’ behaviour to address mkaply 's issue)
Line 1: Line 1:
<h1> include pattern </h1>
<h1>Include Pattern</h1>


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|hResume]], [[hreview|hReview]], [[hatom|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.
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.


; Author: Tantek Çelik
; Editors
  : Tantek Çelik
  : Ben Ward


__TOC__
__TOC__


== Background ==


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


In [[hresume|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 [[resume-brainstorming#hCard_reference_via_object|hCard reference via object technique]].
== Scope ==


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


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.
==Quick Reference==


== class name "include" ==
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:


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.
<pre><nowiki><a class="include" href="#author">Ben Ward</a></nowiki></pre>
<pre><nowiki><object class="include" data="#author"></object></nowiki></pre>


'''Proposal 1:''' Allow the use of <nowiki><a href class="include"></nowiki> as a secondary include-pattern mechanism, due to some browsers mishandling the object include-pattern.   See [[include-pattern-feedback]] for details.
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.


== object include example ==
==Include Pattern in General==


Here is an example of an [[hcard|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:
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 include===
 
The recommended way to reference includes within microformats is to use a hyperlink.
 
====HYPERLINK include example====
 
Here is an [[hcard|hCard]] from the beginning of a resume, shown here as a verbose hCard.


<pre><nowiki>
<pre><nowiki>
Line 34: Line 56:
</nowiki></pre>  
</nowiki></pre>  


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


<pre><nowiki>
<pre><nowiki>
<span class="vcard">
<span class="vcard">
  <object data="#j" class="include"></object>
  <a href="#j" class="include">Ben Ward</a>
  <span class="org">SimplyHired</span>
  <span class="org">SimplyHired</span>
  <span class="title">Microformat Brainstormer</span>
  <span class="title">Microformat Brainstormer</span>
Line 44: Line 66:
</nowiki></pre>  
</nowiki></pre>  


Thus a microformat parser would treat the above as follows, with the object include completely replaced by the subtree that it references:
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>
<pre><nowiki>
Line 56: Line 78:
</nowiki></pre>  
</nowiki></pre>  


This method of hCard property indirection via an object element can apply to any/all properties in class-based microformats.
====HYPERLINK include notes and issues====
 
Using the hyperlink include pattern causes no known issues in any web browser. However, it is necessary to supply inner-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. The user experience of Assistive Technology can be severely degraded by the presence of hyperlinks which do not contain text.
 
In most cases, publishers hide the include hyperlink from most browsers using CSS.
 
=== OBJECT include ===
 
The OBJECT include pattern is semantically superior to the hyperlink include; it is being used to embed content into the page. OBJECT was the original developed include pattern. However, there are serious browser compatibility issues that can affect some implementation scenarios.


Note 1: To avoid unsightly messes in Safari, you should include the following style rule in a style sheet for the page:
====OBJECT include example====
<pre><nowiki>
object.include { width:0; height:0 }
</nowiki></pre>


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.
Here is the same [[hcard|hCard]] from the beginning of the resume in the previous example.


== hyperlink include example ==
<pre><nowiki>
<span class="vcard">
<span class="fn n" id="j">
  <span class="given-name">James</span> <span class="family-name">Levine</span>
</span>
</span>
</nowiki></pre>


Per the proposal 1 above, here is how you would code the above object include example using the <nowiki><a href></nowiki> tag.
Elsewhere on the page, a second hCard re-uses the "fn n" content from the first hCard:


<pre><nowiki>
<pre><nowiki>
<span class="vcard">
<span class="vcard">
  <a href="#j" class="include"></a>
  <object data="#j" class="include"></object>
  <span class="org">SimplyHired</span>
  <span class="org">SimplyHired</span>
  <span class="title">Microformat Brainstormer</span>
  <span class="title">Microformat Brainstormer</span>
Line 77: Line 110:
</nowiki></pre>  
</nowiki></pre>  


Changes:
A microformat parser must treat the second hCard as follows, with the OBJECT include element completely replaced by the sub-tree that it referenced:
# a open/close tag instead of object open/close tag
# href attribute instead of data attribute
# ... 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.


<pre><nowiki>
<pre><nowiki>
Line 93: Line 120:
  <span class="title">Microformat Brainstormer</span>
  <span class="title">Microformat Brainstormer</span>
</span>
</span>
</nowiki></pre>  
</nowiki></pre>
 
This method of hCard property indirection via an object element can apply to any/all properties in class-based microformats.
 
===OBJECT include notes and issues===


== restrictions ==
* Unlike the hyperlink pattern, the OBJECT 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 OBJECT: You should set a width and height of "0" for the include elements to resolve this.
* Bugs have been reported in some web browsers (Internet Explorer, Safari, Firefox) that OBJECT elements referencing fragments of the same document erroneously cause the browser to make additional HTTP requests. For scenarios where HTTP requests are a sensitive performance measure, this makes the hyperlink pattern inappropriate.
* Versions of Microsoft Internet Explorer with ActiveX controls disabled will throw a warning prompt upon finding an OBJECT element.


Per the [[include-pattern#scope|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 ==
== 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].
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].

Revision as of 16:29, 6 November 2007

Include Pattern

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 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:

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

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.

Include Pattern 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 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 include

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

HYPERLINK include example

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

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

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

<span class="vcard">
 <a href="#j" class="include">Ben Ward</a>
 <span class="org">SimplyHired</span>
 <span class="title">Microformat Brainstormer</span>
</span>

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:

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

HYPERLINK include notes and issues

Using the hyperlink include pattern causes no known issues in any web browser. However, it is necessary to supply inner-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. The user experience of Assistive Technology can be severely degraded by the presence of hyperlinks which do not contain text.

In most cases, publishers hide the include hyperlink from most browsers using CSS.

OBJECT include

The OBJECT include pattern is semantically superior to the hyperlink include; it is being used to embed content into the page. OBJECT was the original developed include pattern. However, there are serious browser compatibility issues that can affect some implementation scenarios.

OBJECT include example

Here is the same hCard from the beginning of the resume in the previous example.

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

Elsewhere on the page, a second hCard re-uses the "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>

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

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

OBJECT include notes and issues

  • Unlike the hyperlink pattern, the OBJECT 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 OBJECT: You should set a width and height of "0" for the include elements to resolve this.
  • Bugs have been reported in some web browsers (Internet Explorer, Safari, Firefox) that OBJECT elements referencing fragments of the same document erroneously cause the browser to make additional HTTP requests. For scenarios where HTTP requests are a sensitive performance measure, this makes the hyperlink pattern inappropriate.
  • Versions of Microsoft Internet Explorer with ActiveX controls disabled will throw a warning prompt upon finding an OBJECT element.


Acknowledgements

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

Considering

Implementations

References

Normative

  • HTML 4.01
  • XHTML 1.0

Informative

Related Pages