Microformats Wiki - User contributions [en]

include-pattern-feedback

2008-01-24T13:46:02Z

VinceVeselosky: /* Hyperlink Include - Screen Reader Testing */

<h1> Include Pattern Feedback </h1>
{{TOC-right}}
Feedback about [[include-pattern]].

== Objects and Browser Behavior ==

Over at Yahoo! Local, we were using the object include pattern for all our [[hreview|hReviews]] on business detail pages and review listings. That is, until we realized that Safari and Internet Explorer both try to embed the entire page with every OBJECT call. (Firefox correctly recognizes that it's a local object and doesn't reload anything.)

On a page with 20+ reviews, this means a substantial increase in load time and memory consumption. As a result of this (bad) browser behavior, we removed the objects entirely.

Any suggestions for workarounds or modifications to the pattern?

-- AndyBaio 29 Jun 2006

Can you use the hyperlink option with DHMTL/Ajax to perform replacements in advanced browsers? (Simon Willison's <code>[http://simon.incutio.com/archive/2003/03/25/getElementsBySelector getElementsBySelector()]</code> may be helpful)
<a href="#id" class="include" title=""></a>
with something like:
//Works only for linked include-pattern definition at microformats.org
//Requires Simon Willison's getElementsBySelector()
// and normal IE workaround for addEventListener()
addEventListener( window, 'load', function() {
var myIncludes = document.getElementsBySelector( 'a[href].include' ), a, e;
for( var i=0; a=myIncludes[i]; i++ ) if (a.href.charAt(0)=='#') {
e = document.getElementsBySelector( a.href )[0].cloneNode( true );
a.parentNode.replaceChild( e, a );
}
})
--[[User:RichHall|RichHall]] 00:51, 23 Oct 2006 (PDT)

It seems there is some confusion around this topic. I believe that the included data '''are not supposed to be actually included in the point of inclusion'''. I believe it is only meant to be a hint for the microformats parser; but the inclusion pattern should not affect how the page is rendered. If that is true, let's clear out this page:
* Remove the DHTML suggestion by Rich Hall.
* Change the IRC quote between Tantek and Kaply. Replace the quote ''"clone the dom node from the other vcard and replace the object with the corresponding nodes"'' with ''"look for objects in the vcard and check their corresponding nodes in the dom" [http://rbach.priv.at/Microformats-IRC/2007-01-03#T165941|IRC of 2007-01-03]'' or remove the IRC quote completely.

-- [[User:JiriKopsa]] 18 Mar 2007

:For clarification, it is true that the spec *does* call for a microformat include to be ignored (content-neutral) when its data isn't being accessed. My Ajax suggestion is valid for those of us extracting microformat data client-side, but feel free to use it from an XHR callback instead of a window load event. Also, it would seem that without adjusting the DOM by cloning the repeated nodes, implementers would have to roll their own smart traversal functions rather than using built-in or well-defined CSS, XPath, E4X, etc. My feedback is that it's usually easier/faster to complete the tree than leave it sparse and memory-efficient, but it would be nice if the spec could leave enough wiggle room for both alternatives.
:-- [[User:RichHall|RichHall]] 12:47, 17 Dec 2007 (PST)

My hResume page [http://robert.o-rourke.org seen here] caused Safari <ins>2.0</ins> some major issues. The page was jumping between object elements when a link was hovered eventually causing the browser to crash. You can follow the thread on the [http://www.mail-archive.com/listdad%40webstandardsgroup.org/msg06078.html WSG mail archive].

It seems that while the object element may be more semantically appropriate it <del>is not</del> <ins>may not be</ins> usable in lieu of the issues raised in Safari.

--[[User:SanchoTheFat|Robert O'Rourke]] 12:08, 3 Nov 2006 (PST)

Which version of Safari? Please be specific as many Safari OBJECT bugs were fixed in Safari 2.x.

-- [[User:Tantek|Tantek]] 13:39, 3 Nov 2006 (PST)

The issues with OBJECT in Internet Explorer & Safari and the lack of a good workaround example are a show stopper for me using this. I am now commenting it out. Hope someone can think of a workaround!

--[[User:WizardIsHungry|Jon Williams]] 10:21, 7 Feb 2007 (PST)

== Hyperlink Include - issues for keyboard users (including Screen Reader users) ==

Although invisible in visual user agents, and (according to the JAWS 7.0 test below) not spoken by screen readers (at least not by JAWS 7.0), empty links are still contained in the normal tab cycle. Users navigating via keyboard (or equivalent, e.g. switch access, puff/blow devices, etc) will still need to tab through the empty links (tested in Firefox 2.0, IE 6, IE 7; Opera 9.2 seems to remove empty links from tab cycle).

This can be verified by modifying the test page below, adding a regular link at the end of the 5 variations of empty links. It takes a user 6 tabs to arrive at the "real" link. It would therefore be advisable to rethink the approach, or scrap it completely.

-- [[User:PatrickLauke|Patrick H. Lauke]] 28 Apr 2007

== Hyperlink Include - Screen Reader Testing ==

Some [http://microformats.org/discuss/mail/microformats-discuss/2006-July/004693.html concerns have been raised] over the implications using empty hyperlinks may have on assistive devices such as screen readers. One concern is that an empty link may be read out, partially read out or result in some other confusing scenario for the user.

In response, a [http://allinthehead.com/demo/include.html test page] consisting of a number of empty hyperlinks in the style suggested by the pattern has been created. A 'good' result is that none of the links be read out.

=== Test Results from Yahoo! Accessibility ===
Tests by Mike Davies and members of the Yahoo! Accessibility Stakeholders group can be found at [http://yuiblog.com/blog/2008/01/23/empty-links/ Empty Links and Screen Readers].

<blockquote>The conclusion is that the most accessible link is one that contains link text. Different techniques of hiding links, from no link text, through to hiding by CSS can cause an accessibility barrier to screen reader users. Each screen reader presented its user with a different set of problems and barriers.
</blockquote>

The article contains tables describing the behaviors of different screen readers in a number of scenarios.

(added by: [[User:VinceVeselosky|VinceVeselosky]] 05:46, 24 Jan 2008 (PST) )

=== Test Results: JAWS 7.0 with Firefox 1.5/Win ===

Tested by [[User:Phae|Frances Berriman]] 2006-07-21.

Purpose of this test was to ascertain what JAWS 7.0 would verbally announce to a user visiting the test case.

* 31 dash include dash Mozilla Firefox
* Page has no links
* 31 dash include

Was keyboard access fully tested (see above)? This test is not conclusive, as JAWS 7.0's behavior may well differ from other access technology. Further testing with a wider range of readers is strongly recommended. -- [[User:PatrickLauke|Patrick H. Lauke]] 28 Apr 2007

The example above has been incorrectly stated, to be honest. Conclusion was just a conclusion for that verbal test, not overall. Therefore, removed "Conclusion" line so it's not misleading! I concur with additional tests are vital (by as many people/softwares/scenarios as possible!). [[User:Phae|Phae]] 04:10, 2 May 2007 (PDT)

=== Proprietary attribute ===
<s>
HTML tidy on the [http://allinthehead.com/demo/include.html test page] gives:
:Warning: <a> proprietary attribute "data"

The [http://validator.w3.org/check?verbose=1&uri=http%3A%2F%2Fallinthehead.com%2Fdemo%2Finclude.html W3C validator is similarly unimpressed].

[[User:AndyMabbett|AndyMabbett]] 14:22, 22 Oct 2006 (PDT)

==== Use href ====
To clarify, links on the [http://allinthehead.com/demo/include.html test page] should be changed to use the <code>href</code> attribute as described at [[include-pattern]] (without <code>href</code> attributes, the elements probably won't register as hyperlinks, but anchors). Set <code>title=""</code> to fix empty link behavior for many assistive devices. --[[User:RichHall|RichHall]] 23:31, 22 Oct 2006 (PDT)
</s>

==== Test page corrected ====
2006-10-25: This error has been corrected on the [http://allinthehead.com/demo/include.html test page]. Any tests should probably be re-run in light of this.

== Unclear status ==

It's not clear, either from the main Wiki page or [[include-pattern]], whether this is an agreed standard, a draft, or just a proposal. [[User:AndyMabbett|AndyMabbett]] 03:14, 18 Oct 2006 (PDT)

* [[include-pattern]] is not its own proposal, draft, or spec. It is a design pattern, as listed on the [[Main_Page|wiki home page]] that is included in other proposals, drafts. and specs. ''Recommend for adding to the [[include-pattern-faq]].
**And that is not clear, either from the main Wiki page or [[include-pattern]]. [[User:AndyMabbett|AndyMabbett]] 16:40, 18 Oct 2006 (PDT)
***ACCEPTED. Will further clarify relationship between patterns and formats. [[User:Tantek|Tantek]] 16:48, 18 Oct 2006 (PDT)

==Parsing for include-pattern==

''Note: this issue is obsolete. On a [http://rbach.priv.at/Microformats-IRC/2007-01-03#T165528 IRC conversation 2007-01-03], Mike Kaply admitted that he figured this out, which is to apply all includes first into the parse tree before looking for any properties. -Tantek''

''To be more specific, what finally occurred to me is that the object pattern is simply about grabbing nodes from another vcard and using them in this vcard. So the implementor responsibility is just to clone the dom node from the other vcard and replace the object with the corresponding nodes. Works great. (of course I also had to clone the entire vcard since I can't manipulate the DOM like that without changing the page) -mkaply''

In an [http://rbach.priv.at/Microformats-IRC/2007-01-02#T205847 IRC discussion] with [http://www.kaply.com/weblog/ Mike Kaply] (author of the [https://addons.mozilla.org/firefox/4106/ Operator] extension for Firefox) we discussed the difficulty of parsing for an [[include-pattern]] in [[hresume|hResume]]. Mike asks:
<blockquote>I'm really wondering why the <code>object</code> stuff doesn't point back to the entire vCard. I don't understand why the spec has it point to individual items.</blockquote>
The problem was thought to be a weakness in the specification, which doesn't specify what part of the data is in the content that is pointed to by the <code>object</code>.

Currently, to overcome this a parser needs to follow this logic:
::IF I don't find an <code>fn</code>, look for an <code>object</code>. IF there is an <code>object</code>, do a <code>getelementbyid</code> on that <code>ID</code>, but yet there was nothing about that <code>object</code> that said that the content I was looking for in the other card was an <code>fn</code>

Two things may help in overcoming this difficulty:

# Change the spec to have the include-pattern reference the entire vCard, with the intent that any data not found in this vCard use the other vCard
# Include the element of the reference, where the class attribute on <code><object></code> has "include" plus the element that needs to be included. For example:
<pre><nowiki><object
class="include fn" data="#vcard-name">myname</object> </nowiki></pre>

Additionally, I pointed out that using the <code><object></code> element to contain the reference makes Microsoft's Internet Explorer throw an error "Your current security settings prohibit ActiveX controls on this page. As a result, the page may not display correctly." Of course, there is no ActiveX content on an include-pattern.

[[User:Bob Jonkman|Bob Jonkman]] 21:15, 2 Jan 2007 (PST)#

==Concatenating values==

I feel that there should be a way to "include" data from two places, in one microformat property. For instance:

<pre><nowiki>Kidderminster Branch Indoor Meeting</nowiki></pre>
<pre><nowiki>Janaury</nowiki></pre>

and later

<pre><nowiki><object data="#summaryB+#summaryA" class="include"></object></nowiki></pre>

would give a summary of:

:'''January Kidderminster Branch Indoor Meeting'''

It may even be possible to include extra data:

<pre><nowiki>Fred Smith</nowiki></pre>

<pre><nowiki><object data="#summaryA+ with +#summaryC" class="include"></object></nowiki></pre>

to give:

:'''Kidderminster Branch Indoor Meeting with Fred Smith'''

[[User:AndyMabbett|Andy Mabbett]] 14:33, 8 Jan 2007 (PST)

Why not use

<pre><nowiki><object data="#summaryA" class="include"></object> with <object data="#summaryB" class="include"></object></nowiki></pre>

to build

:'''Kidderminster Branch Indoor Meeting with Fred Smith'''

[[User:DerrickPallas|Derrick Pallas]] 11:15, 31 Jan 2007 (PST)

:Neat solution! Can anyone say whether current parsers accept this? [[User:AndyMabbett|Andy Mabbett]] 12:18, 31 Jan 2007 (PST)

:Fully disclosure: My XSLT transformer supports this implicitly because it does include-pattern first, then pulls values. My only question would be what to do with nested @class="value" elements that could result from this. [[User:DerrickPallas|Derrick Pallas]] 12:35, 31 Jan 2007 (PST)

==Related Pages==
{{include-pattern-related-pages}}

include-pattern

2008-01-24T13:33:49Z

VinceVeselosky: /* notes and issues */

<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 the separate hCards used in the same person's employment history. Repeating name information would not have matched the existing publishing techniques 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 any 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 (recommended) or OBJECT. For example:

<pre><nowiki><a class="include" href="#author" title="James Levine"></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>


James Levine


</nowiki></pre>

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

<pre><nowiki>

<a href="#james-hcard-name" class="include" title="James Levine"></a>
SimplyHired
Microformat Brainstormer

</nowiki></pre>

Note that the lack of content inside the <code>a</code> element with <code>class="include"</code> is deliberate, as it reflects the design requirement from [[hresume|hResume]] of not having to repeat any name information with each job entry. The <code>title</code> attribute is used to aid useragents that wish to label the hyperlink outside its inline context.

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>


James Levine

SimplyHired
Microformat Brainstormer

</nowiki></pre>

==== notes and issues ====

Note: The <code>id</code> attribute value in the example "james-hcard-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, 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.

===== accessibility =====
Hyperlinks presented as an extracted list. There are two points of view on this. 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 (see [http://yuiblog.com/blog/2008/01/23/empty-links/ Empty Links and Screen Readers] for results of actual tests). 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>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?</blockquote>

Hyperlinks and tab focusing in common browsers. 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.

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.

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


James Levine


</nowiki></pre>

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

<pre><nowiki>

<object data="#james-hcard-name" class="include"></object>
SimplyHired
Microformat Brainstormer

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


James Levine

SimplyHired
Microformat Brainstormer

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