include-pattern: Difference between revisions

From Microformats Wiki
Jump to navigation Jump to search
(warning, only for classic microformats)
 
(26 intermediate revisions by 13 users not shown)
Line 1: Line 1:
{{warning|This is a classic microformats building block and has not been updated for [[microformats2]].}}
<h1>Include Pattern</h1>
<h1>Include Pattern</h1>
{{TOC-right}}
{{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.
The include pattern is a microformat design pattern, providing a mechanism to include a portion of data from one area of a page into another area of the same page, allowing the data to be reused by multiple microformats, independent of content order, without repeating all the information. The following is documentation for re-use of the pattern in other microformats, and for publishers working with it.


;Editors: Tantek Çelik
;Editors: Tantek Çelik
Line 8: Line 9:
== 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.
[[hresume|hResume]] needed the ability to include a name from one hCard at the top of a resume — the person's contact details — into the separate hCards used in the same person's employment history. Repeating name information would not have matched the existing publishing practices used in Resumes and Curriculum Vitæ, would be inconvenient to publishers, and irritating to consumers. The include pattern is a mechanism to reference data from the same page, avoiding repetition, or duplicate visible information.


== scope ==
== scope ==
Line 16: Line 17:
== quick reference==
== 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:
The include-pattern is a mechanism to include content from one microformat into another microformat elsewhere in the same document, using hyperlinks or <code>object</code>. For example:


<pre><nowiki><a class="include" href="#author" title="James Levine"></a></nowiki></pre>
<source lang=html4strict><a class="include" href="#author">James Levine</a></source>
<pre><nowiki><object class="include" data="#author"></object></nowiki></pre>
<source lang=html4strict><object class="include" data="#author"></object></source>


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 specifications which cite the include-pattern, either of the above code snippets {{must}} cause a microformats parser to replace the <code>A</code> or <code>object</code> element with class name "include" with the content fragment with ID "author". Full examples follow.


== in general==
== in general==
Line 27: Line 28:
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.
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.
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. Note that this means all other class names on the include element are discarded. Microformat class names should be included on the target of the include, not on the include element itself.


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.
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.
Per the [[include-pattern#Scope|scope]], the <code>object</code> '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.
There are two HTML elements available to reference includes, hyperlink/Anchor and <code>object</code>. 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.
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.
Line 43: Line 44:
==== Hyperlink example====
==== Hyperlink example====


Here is an [[hcard|hCard]] from the beginning of a resume, shown here as a verbose hCard.
Here is an [[hcard|hCard]] for a bar, included at the top of a reviews page, shown here as a verbose hCard.


<pre><nowiki>
<source lang=html4strict>
<span class="vcard">
<div class="vcard" id="bricklayers-card">
<span class="fn n" id="jl-name">
  <div class="fn org">The Bricklayers Arms</div>
  <span class="given-name">James</span> <span class="family-name">Levine</span>
  <div class="adr">
</span>
    <span class="street-address">31 Gresse Street</span>,
</span>
    <span class="locality">Fitzrovia</span>
</nowiki></pre>  
    <span class="region">London</span>
    <span class="postal-code">W1T 1QS</span>
  </div>
</div>
</source>
 
Elsewhere on the page, a number of reviews reference the hcard in the item property. Rather than repeat all the verbose detail, only the name is reprinted and the detailed hcard referenced using the include-pattern.
 
<source lang=html4strict>
<div class="hreview">
  <h1 class="summary">A great venue for monthly gatherings!</h1>
  <div class="item"><a class="include" href="#bricklayers-card">The Bricklayers Arms</a></div>
  <p class="description">Wonderful pub, cheap beer, open fire to warm mince pies at Christmas.</p>
</div>
 
<div class="hreview">
  <h1 class="summary">Takes a while to thin out, but!</h1>
  <div class="item"><a class="include" href="#bricklayers-card">The Bricklayers Arms</a></div>
  <p class="rating"><span class="value">5</span>/<span class="best">5</span></p>
</div>
</source>  


Elsewhere on the page, a second hCard re-uses the "fn n" content from the first hCard:
Note that you {{must}} include content within the anchor element. See the notes and issues below.


<pre><nowiki>
A microformat parser {{must}} treat each review as follows, with the hyperlink include element completely replaced (including inner-text) by the sub-tree that was referenced:
<span class="vcard">
<a href="#jl-name" class="include">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:
<source lang=html4strict>
<div class="hreview">
  <h1 class="summary">A great venue for monthly gatherings!</h1>
  <div class="item">
      <div class="vcard" id="bricklayers-card">
        <div class="fn org">The Bricklayers Arms</div>
        <div class="adr">
          <span class="street-address">31 Gresse Street</span>,
          <span class="locality">Fitzrovia</span>
          <span class="region">London</span>
          <span class="postal-code">W1T 1QS</span>
        </div>
      </div>
  </div>
  <p class="description">Wonderful pub, cheap beer, open fire to warm mince pies at Christmas.</p>
</div>


<pre><nowiki>
</source>  
<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 ====
==== 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.
Note: The <code>id</code> attribute value in the example "bricklayers-card" 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, as long as hyperlink includes without content are hidden with CSS. See below for details.


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.  
Authors {{must}} supply content 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 as appropriate to the context of the page.  


===== accessibility =====
===== accessibility =====
<strong>Hyperlinks presented as an extracted list.</strong> 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>


<strong>Hyperlinks and tab focusing in common browsers</strong>. As noted in the [http://microformats.org/wiki/include-pattern-feedback include-pattern feedback page], any visible hyperlink used with an <code>href</code> attribute ends up in the browser's tab cycle. This affects all keyboard users (both sighted users that can't/don't operate a mouse, or screen reader users in the extreme case). Even empty hyperlinks receive focus. This can be tested by modifying the code of the original [http://allinthehead.com/demo/include.html a@include test page] to visually follow the tabbing from one hyperlink to the next (using CSS or, for test purposes, subtly changing the <code>href</code>, tabbing through the page, and observing the change in the URL displayed in the browser's status bar). Hyperlinks hidden with CSS <code>display:none</code> do not end up in the browser's tab cycle.
* Testing indicates that the only way to guarantee accessibility of hyperlinks to users of assistive technology (such as screen readers) is to include inner-text. [http://yuiblog.com/blog/2008/01/23/empty-links/ See: Empty Links and Screen Readers]
* You {{must}} include inner-text in the hyperlink element.
* You MAY enhance the rendered user experience (depending on the context of your page) by hiding the include element using CSS <code>display: none</code>
* Where you wish to hide the content of the include element, you {{should not}} hide the include element using a CSS negative margin offset as the hidden link will remain in the tab order of the document. Use <code>display: none</code> instead.


Thus it is recommended that Hyperlink Include Pattern hyperlinks lacking inline content {{should}} be hidden with CSS.  As they have no content, this stylistic change has no net effect on the document's content semantics from a user's perspective.
Where a publishing constraint prevents putting content within the include-pattern, you {{must}} use the <code>object</code> element pattern instead of a hyperlink.


=== Object ===
=== 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.
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 some browser compatibility issues that can affect some implementation scenarios and thus the above Hyperlink Include Pattern is preferred.


==== Object example ====
==== Object example ====


Here is the same [[hcard|hCard]] from the beginning of the resume in the previous example.
The [[hcard|hCard]] from the beginning of a resumé describes the person who's resumé it is:


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


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


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


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:
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>
<source lang=html4strict>
<span class="vcard">
<span class="vcard">
<span class="fn n" id="jl-name">
  <span class="fn n" id="james-hcard-name">
  <span class="given-name">James</span> <span class="family-name">Levine</span>
    <span class="given-name">James</span> <span class="family-name">Levine</span>
</span>
  </span>
<span class="org">SimplyHired</span>
  <span class="org">SimplyHired</span>
<span class="title">Microformat Brainstormer</span>
  <span class="title">Microformat Brainstormer</span>
</span>
</span>
</nowiki></pre>
</source>


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


=== notes and issues===
=== 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''').
* Unlike the hyperlink pattern, the <code>object</code> is not believed to cause problems in assistive technology when fallback text is absent. ('''research 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.
* Apple's Safari 1.x browser has some rendering issues with this use of <code>object</code>: Publishers {{should}} style a width and height of "0" for the include elements to resolve this ('''clarification of issue 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 performance issue, publishers {{should}} use the hyperlink pattern instead.
* 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''').
* 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 ==
== 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]. Thanks to [http://www.isolani.co.uk/ Mike Davies] for accessibility research.


== specifications using ==
== specifications using ==

Latest revision as of 22:56, 10 December 2020

⚠️ Warning: This is a classic microformats building block and has not been updated for microformats2.

Include Pattern

The include pattern is a microformat design pattern, providing a mechanism to include a portion of data from one area of a page into another area of the same page, allowing the data to be reused by multiple microformats, independent of content order, without repeating all the information. 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 the separate hCards used in the same person's employment history. Repeating name information would not have matched the existing publishing practices used in Resumes and Curriculum Vitæ, would be inconvenient to publishers, and irritating to consumers. The include pattern is a mechanism to reference data from the same page, avoiding repetition, or duplicate visible information.

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 or object. For example:

<a class="include" href="#author">James Levine</a>
<object class="include" data="#author"></object>

In specifications which cite the include-pattern, either of the above code snippets MUST 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. Note that this means all other class names on the include element are discarded. Microformat class names should be included on the target of the include, not on the include element itself.

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

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

Hyperlink example

Here is an hCard for a bar, included at the top of a reviews page, shown here as a verbose hCard.

<div class="vcard" id="bricklayers-card">
  <div class="fn org">The Bricklayers Arms</div>
  <div class="adr">
     <span class="street-address">31 Gresse Street</span>,
     <span class="locality">Fitzrovia</span>
     <span class="region">London</span>
     <span class="postal-code">W1T 1QS</span>
  </div>
</div>

Elsewhere on the page, a number of reviews reference the hcard in the item property. Rather than repeat all the verbose detail, only the name is reprinted and the detailed hcard referenced using the include-pattern.

<div class="hreview">
   <h1 class="summary">A great venue for monthly gatherings!</h1>
   <div class="item"><a class="include" href="#bricklayers-card">The Bricklayers Arms</a></div>
   <p class="description">Wonderful pub, cheap beer, open fire to warm mince pies at Christmas.</p>
</div>

<div class="hreview">
   <h1 class="summary">Takes a while to thin out, but!</h1>
   <div class="item"><a class="include" href="#bricklayers-card">The Bricklayers Arms</a></div>
   <p class="rating"><span class="value">5</span>/<span class="best">5</span></p>
</div>

Note that you MUST include content within the anchor element. See the notes and issues below.

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

<div class="hreview">
   <h1 class="summary">A great venue for monthly gatherings!</h1>
   <div class="item">
      <div class="vcard" id="bricklayers-card">
        <div class="fn org">The Bricklayers Arms</div>
        <div class="adr">
           <span class="street-address">31 Gresse Street</span>,
           <span class="locality">Fitzrovia</span>
           <span class="region">London</span>
           <span class="postal-code">W1T 1QS</span>
        </div>
      </div>
   </div>
   <p class="description">Wonderful pub, cheap beer, open fire to warm mince pies at Christmas.</p>
</div>

notes and issues

Note: The id attribute value in the example "bricklayers-card" 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 id and class names.

Authors MUST supply content 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 as appropriate to the context of the page.

accessibility
  • Testing indicates that the only way to guarantee accessibility of hyperlinks to users of assistive technology (such as screen readers) is to include inner-text. See: Empty Links and Screen Readers
  • You MUST include inner-text in the hyperlink element.
  • You MAY enhance the rendered user experience (depending on the context of your page) by hiding the include element using CSS display: none
  • Where you wish to hide the content of the include element, you SHOULD NOT hide the include element using a CSS negative margin offset as the hidden link will remain in the tab order of the document. Use display: none instead.

Where a publishing constraint prevents putting content within the include-pattern, you MUST use the object element pattern instead of a hyperlink.

Object

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

Object example

The hCard from the beginning of a resumé describes the person who's resumé it is:

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

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

<span class="vcard">
 <object class="include" data="#james-hcard-name"></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="james-hcard-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>

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 is not believed to cause problems in assistive technology when fallback text is absent. (research needed)
  • Apple's Safari 1.x browser has some rendering issues with this use of object: Publishers SHOULD style a width and height of "0" for the include elements to resolve this (clarification of issue needed).
  • 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 (version(s) affected needed). For scenarios where HTTP requests are a performance issue, publishers SHOULD use the hyperlink pattern instead.
  • Versions of Microsoft Internet Explorer with ActiveX controls disabled will throw a warning prompt upon finding an object element (version(s) affected needed).

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. Thanks to Mike Davies for accessibility research.

specifications using

considering

All class-based microformats SHOULD consider using and explicitly normatively stating support for the include pattern.

implementations

references

normative

  • HTML 4.01

informative

related pages