Microformats Wiki - User contributions [en]

User:JiriKopsa

2007-03-19T18:53:25Z

JiriKopsa:

Jiri Kopsa
* http://blogs.sun.com

hcard-parsing

2007-03-19T06:14:38Z

JiriKopsa: /* Include Pattern and Table Headers */

<h1>hCard parsing</h1>

by [http://tantek.com/log/ Tantek Çelik]

== introduction ==

When I first conceived of [[hcard|hCard]], it was clear to me how to unambiguously parse both for the existence of hCards in arbitrary (X)HTML (and anywhere that arbitrary (X)HTML can be embedded, e.g. RSS, Atom, "generic XML"), and hCard properties and values.

I worked directly with Brian Suda to capture these thoughts in an implementation, and Brian wrote X2V, an XSLT script that converts hCards to vCards, thus simultaneously demonstrating the parsability of hCards, and the immediate utility of hCard content interoperating with widespread existing vCard applications.

I am now documenting those thoughts directly here so that additional implementations, rather than having to reverse engineer X2V, can be built directly from these elementary concepts.
__TOC__

== scope ==

Although this page is written specifically to explain how to parse [[hcard|hCard]], the concepts and algorithms contained therein serve as an example for how other [[compound-microformat|compound microformats]] are to be parsed.

== URL handling ==

An hCard parser may begin with a URL to retrieve.

If the URL lacks a fragment identifier, then the parser should parse the entire retrieved resource for hCards.

If the URL has a fragment identifier, then the parser should parse ''only'' the node indicated by the fragment identifier and its descendants, looking for hCards, starting with the indicated node, which may itself be a single hCard.

== root class name ==

Each compound microformat starts with a root element with a relatively unique class name. By that I mean a class name which isn't simply a common word, and is unlikely to have been used outside the context of the microformat. By choosing such a root class name the microformat avoids (for all practical purposes) colliding with existing class names that may exist within the (X)HTML context. This is essential to enabling such compound microformats to be ''embedded'' inside current, existing content, as well as future content.

Fortunately this is not a new problem to solve. The root object names chosen for vCard (RFC 2426) and iCalendar (RFC 2445) similarly had to avoid such collisions and did so by choosing names that were unlikely to have been introduced into a MIME object context. The principle of ''reuse'' dictates that we should reuse the names for these root objects in those RFCs rather than invent our own. Given the same semantics, a design should reuse the names, rather than inventing a second name for the same semantic (a common design mistake made in environments that require namespaces).

In the vCard specification, the names are case-insensitive due to the (lack of) requirements of their context. (X)HTML class names are case sensitive per those specifications. Thus we are required to pick a canonical case for the class name equivalents of vCard object and property names. All lowercase is chosen to follow the precedent (i.e. ''reuse'' the pattern) set by XHTML, which similarly had to canonicalize the case of element and attribute names that it took from HTML4, which itself was case-insensitive due to its context (SGML). Additionally, reasons for avoiding mixed-case (e.g. camel case) in the context of class names may be found in the essay [http://tantek.com/log/2002/12.html#L20021216t2238 A Touch of Class], specifically, the section titled [http://tantek.com/log/2002/12.html#atoc_csensitivity Class sensitivity].

Thus the root class name of an [[hcard|hCard]] is "vcard".

== finding hCards ==

An (X)HTML document indicates that it may contain hCards by referencing the [[hcard-profile|hCard XMDP profile]]. See [http://gmpg.org/xmdp/description XMDP] for more details.

A parser finds hCards in an (X)HTML context by looking for elements with the root class name "vcard" just as the following CSS class selector does:
<pre>
.vcard
</pre>

For example, the following CSS style rule sets the background of all hCards to green:
<pre>
.vcard { background: green; }
</pre>

Note that the (X)HTML class attribute is a space separated set of class names.

Thus all of the following are valid hCard root elements:
* <code><div class="vcard"> </div></code>
* <code><span class="attendee vcard"> </span></code>
* <code><address class="vcard author"> </address></code>
* <code><li class="reviewer vcard first"> </li></code>

Once the root element of an hCard is found, that element and all its descendants are all that is needed to parse the hCard.

Thus it is possible for a well-formed hCard to be extracted from an overall non well-formed context, if the parser has the ability to find elements by class name within that non well-formed context.

== hCard properties ==

The complete list of class names for hCard properties are documented in the [[hcard-profile|hCard profile]].

=== forward compatible parsing ===

When parsing the contents of an hCard, any unrecognized class names must be ignored.

Similarly, unrecognized values for hCard properties must also be ignored.

=== finding hCard properties ===

To parse an hCard for an hCard property (e.g. "fn"), the parser simply looks for the first element with that class name inside the hCard.

This can also be expressed as the first element that matches this CSS selector:

<pre>
.vcard .fn
</pre>

Some properties, like "fn", should only appear once, and thus the parser stops looking for the property after it has found the first occurrence in document order. Additional occurrences are ignored.

Other properties, like "adr", "email", "url", "tel", etc., may (and often do) appear more than once, and thus the parser continues to look for each occurrence within the contents of the hCard.

=== parsing hCard properties and values ===

In general, once an element for a property is found, that element is used for the value.

In particular, once an element for a property is found:
# first, look for [[hcard-parsing#class_value_handling|class value children]] and use them as [[hcard-parsing#class_value_handling|described below]]
# otherwise, if there is a [[hcard-parsing#more_semantic_exceptions|more semantic exception]], use that as [[hcard-parsing#more_semantic_exceptions|described below]]
# finally, always fallback to using the contents of the element for the value

==== class value handling ====

For all properties, if the element for a property has one or more children with a class name of "value", then concatenate the node values for all those child elements with class name of "value", in their document order, and use that concatenation as the value of the property.

==== more semantic exceptions ====

There are several exceptions to accomodate [http://microformats.org/wiki/hcard#Semantic_XHTML_Design_Principles semantic XHTML and more semantic equivalents].

For the "email" property in particular, when the element is:
* <code><a href="mailto:..."></code> OR <code><area href="mailto:..."></code> : parse the value of the 'href' attribute, omitting the "mailto:" prefix and any "?" query suffix (if present), in the attribute. For details on the "mailto:" URL scheme, see RFC 2368.

For properties that may take type URL or URI parsers MUST handle relative URLs/URIs and normalize them to their respective absolute URLs/URIs, following the containing document's language's rules for resolving relative URLs/URIs (e.g. <base> for HTML, xml:base for XML).

For properties that may take type URL, URI, or UID, when the element for that property is:
* <code><a href></code> OR <code><area href></code> : use the value of the 'href' attribute.
* <code><img src></code> : use the value of the 'src' attribute. If the 'src' is a "data:" URL, use the MIME type in that "data:" URL for the TYPE subproperty, otherwise if the the 'type' attribute is present, us that for the TYPE subproperty.
* <code><object data></code> : use the value of the 'data' attribute for the value. If the 'data' is a "data:" URL, use the MIME type in that "data:" URL for the TYPE subproperty, otherwise if the the 'type' attribute is present, us that for the TYPE subproperty.

For properties with values NOT of type URL, URI, or UID, when the element for a property is:
* <code><img alt></code> OR <code><area alt></code> : use the value of the 'alt' attribute.

For all properties, when the element for a property is:
* <code><abbr title></code>: use the value of the 'title' attribute. If there is no 'title' attribute then use the contents of the element.
** For properties which take an ISO8601 datetime value, parsers *should* pad any necessary precision (e.g. seconds), and *should* normalize any datetimes with timezone offsets, (e.g. <code>20050814T2305-0700</code>) into UTC (<code>20050815T060500Z</code>). Note that floating dates and times MUST NOT be made into UTC/Z absolute time zoned values.
* <code><br /></code> OR <code><hr /></code>: the value is the empty string. These two elements do not represent any semantics and thus it is probably an error (at least an abuse) for an author to use them with microformats class names. Nonetheless, if found, treat the value as empty.

==== white-space handling ====

hCard parsers should handle white-space parsing per XML white-space handling rules, with the following two additions:

# <code><pre></code> handling. Any content parsed as part of an hCard property that is inside a <pre> element must preserve all white-space per XML white-space preservation rules.
# <code><br /></code> handling. Any occurrence of a <code><br /></code> inside the element(s) for a value must be treated as a carriage-return (\n) in the respective location in the value.

=== hCard sub-properties ===

There are some hCard properties whose values themselves have structure (AKA structured type value) and are composed of multiple pieces, which we refer to as sub-properties.

For example, the "n" property consists of the sub-properties "family-name", "given-name", "additional-name", "honorific-prefix", and "honorific-suffix".

E.g. from section 3.1.2 of RFC 2426, modified to include Ph.D.

<pre>
N:Public;John;Quinlan;Mr.;Esq.,Ph.D.
</pre>

In hCard this "n" property would be marked up as

<pre>
<span class="n">
<span class="honorific-prefix">Mr.</span>
<span class="given-name">John</span>
<span class="additional-name">Quinlan</span>
<span class="family-name">Public</span>,
<span class="honorific-suffix">Esq.</span>,
<span class="honorific-suffix">Ph.D.</span>
</span>
</pre>

Which would be rendered as:

Mr. John Quinlan Public, Esq., Ph.D.

=== hCard property parameters ===

Some hCard properties have one or more parameters, most often "type", with an enumerated set of values. We represent the specific ''value'' of the parameter as a class name on an element inside the element representing the property.

For example, the "adr" property has a type parameter which takes the values: "dom", "intl", "post", "parcel", "home", "work", "pref".

The "type" parameter is treated like a sub-property.

To encode the "type" of an "adr" property, a nested element with class="type" is used to markup the value of the type parameter.

Example with the "tel" property with a value of type "work":

<pre>
<span class="tel">
<span class="type">work</span>:
<span class="value">+1.123.456.7890</span>
</span>
</pre>

=== Value excerpting ===

Note the element with class="value" used in the above example.

Sometimes only part of an element which is the equivalent for a property should be used for the value of the property. This typically occurs when a property has a subtype, like TEL. For this purpose, the special class name "value" is introduced to excerpt out the subset of the element that is the value of the property.

== Include Pattern and Table Headers ==

When processing elements from the [[include-pattern]] or table headers inclusion methods, such elements should be processed as if they were inline.

== Proposed Additions ==
These are proposed additions to hCard parsing. Implementations MAY follow these conventions in order to gain implementation experience, and SHOULD report back on the results.

=== DEL element handling ===

When dealing with an HTML document that is hCard encoded, the parser SHOULD honor the <code><del></code> element.

There are two possibilities here (adopting both may be possible):

1. Skip any occurences of <code><del></code> elements and their contents entirely inside the contents of a property.

2. If the <code><del></code> element is used for a property itself, it could be useful as a way communication the of tombstoning / obsoleting of that particular property value, and thus while a parser that is converting to a vCard SHOULD simply do what is indicated in (1), applications which parsed hCard directly (rather than only supporting vCard) COULD treat such occurences of <code><del></code> elements as a way to remove obsolete information (with user confirmation of course) from a local contact information store.

=== Plain Text Formatting of Structural/Semantic HTML ===
There are several structural/semantic elements in HTML which have useful default styling which could be converted into ASCII (AKA Plain Text) equivalents as a low resolution way of communicating that structure. Note that <code><br /></code> and <code><pre></code> are already handled in the section above titled [http://microformats.org/wiki/hcard-parsing#white-space_handling White-space Handling].

When parsing the DESCRIPTION property, hierarchically convert the following HTML tags into their plain text styling equivalents.

* <code><div></code>, <code></div></code>, <code><dl></code>, <code></dl></code>, <code><dt></code>, <code></li></code>, <code></dd></code> - Append a soft <code>\n</code> to the output. By "soft <code>\n</code>", we mean only do so if there isn't already a line break (in contrast to a "hard" (implied by default) <code>\n</code>). Two things in particular order to ensure that <code><div> <div></code> does not result in two <code>\n</code> characters in a row:
*# only output the <code>\n</code> if something other than whitespace (including <code>\n</code>) was outputted immediately previously.
*# omit any immediately subsequent whitespace characters.
* <code><li></code> - Append a soft <code>\n</code> and then </code> * </code>. (Note: Indenting the contents of the list item is not particularly practical, since that would require line-breaking, and that would depend on knowing the width of when the plain text is rendered. Wrapping to 70 characters may be a good assumption for plain text email, but is probably a very bad assumption for vCard output).
* <code></dt></code> - Append <code>:\n</code>
* <code><dd></code> - Append a soft <code>\n</code> and then </code> </code> (two space ASCII 32 characters).
* <code><h1></code>, <code></h1></code>, <code><h2></code>, <code></h2></code>, <code><h3></code>, <code></h3></code>, <code><h4></code>, <code></h4></code>, <code><h5></code>, <code></h5></code>, <code><h6></code>, <code></h6></code> - Append a soft <code>\n</code> followed by a hard <code>\n</code>. (Note: we may want to consider some conventions to indicate the heading level. Perhaps only the relative heading level inside the property matters, e.g. whatever level HTML heading is seen first is treated as a first level heading, then any subsequent HTML heading elements are treated relative to that original heading (this is because it is likely that the property is embedded somewhere deep inside an HTML document following higher heading levels). Any subsequent higher level headings should perhaps cause a warning, and then simply be treated as a first level heading. Given that, the [http://microformats.org/wiki/wiki-formats#straw_proposals straw proposal for heading syntax] from Ian Hickson is one reasonable possibility, with the only issue being that for first and second level headings, how wide to make the line of '-'s or '='s, which is a similar problem to the line-breaking problem noted above when considering indenting the contents of list-items. Thus perhaps it might be sufficient to simply set a first level heading in ALL CAPS (same as the third level heading in Ian's proposed syntax), and let second and deeper level headings be simply implied by the "one line of text with two line breaks both before and after" convention. Rarely has there been more than one level of heading found within a DESCRIPTION property, and I've never seen more than two even if it is possible.)
* <code><p></code>, <code></p></code> - Append a soft <code>\n</code> followed by a hard <code>\n</code>. (Note: Typical books indent the start of a paragraph approximately three spaces "<code> </code>", and implementations may wish to consider doing so as well. Keep in mind that on the Web, typical paragraphs do not start with a first line indent.)
* <code><q></code>, <code></q></code> - Append a double-quote '"' character.
* <code><sub></code> - Append an open parenthesis "("
* <code></sub></code> - Append a a close parenthesis ")".
* <code><sup></code> - Append an open bracket "["
* <code></sup></code> - Append a a close bracket "[". <code><sup></code> are often used for footnotes which in plain text are often formatted as bracketed numbers.
* <code><table></code>, <code></table></code>, <code><tbodygt;</code>, <code></tbody></code>, <code><thead></code>, <code></thead></code>, <code><tfoot></code>, <code></tfoot></code>, <code><tr></code>, <code></tr></code>, <code><caption></code>, <code></caption></code> - Append a soft <code>\n</code>. Of course one could try to do a lot more with representing the structure of the table, but that is almost certainly more work than it is worth, nevermind the complexities introduced by COLSPAN, ROWSPAN etc. At least by approximating the table sections and rows the table may be more readable.
* <code></td></code>, <code></th></code> - Append a space and a tab character (ASCII 32, ASCII 9 respectively). It's not clear that what subsequent application would be able to make use of this visually, but at least the tabular nature of the structure is indicated and it makes it possible to copy and paste the table into something that handles tabular content like a spreadsheet and have the tabular structure reflected.

==== More challenging elements ====
* <code><ol></code> - it would be nice to number list items inside an ordered list rather than bullet them, but keeping track of list item numbers/counts is a non-trivial piece of state information for the parser to deal with, and thus we are omitting this behavior for now.

==== Use of CSS computed styles instead of HTML default styles ====
Rather than assuming the default presentation for these elements, and using that for the basis of plain text formatting, a parser could use the respective equivalent computed style properties and use those instead. However, requiring an hCard parser to also implement Cascading Style Sheets (e.g. CSS1) is out of scope. Some environments (i.e. a browser DOM) may already provide this information, and in that case, it may be easy for an hCard parser (e.g. a clientside javascript parser) to use computed style properties. E.g. instead of the elements above, the following computed styles could be used:
* display:block - Append a soft <code>\n</code>
** text-indent (non-zero value, on an element with display:block or display:list-item) - Append a number of spaces equivalent to value of the text-ident property divided by the computed font-size property of the element.
** margin-top, margin-bottom (non-zero value, on an element with display:block or display:list-item) - Append a number of "\n" equivalent to the value divided by the computed font-size property of the element. Obviously this won't properly collapse vertical margins.
* display:list-item - Append a soft <code>\n</code> followed by " * "
* etc.
This is enough extra work that I'm not sure it is worth spending the time documenting more equivalents. The above are sufficient to illustrate the possibility.

== Outstanding Issues ==

=== Issues 3 ===

Might be worth considering defining the parsing in terms of the DOM, so that it applies to HTML and XHTML equally without ambiguity.

== Resolved Issues ==

This section is informative.

The following issues have been explored and resolved inline in the text of hcard-parsing above.

=== Resolved as of 2005-09-16 ===

==== ISSUE 1 ====

Should we make plural sub-property names into singular versions and simply allow multiple instances? I.e. the singular honorific prefix would make more sense if it was classed as such, and the list implied by the value for honorific-suffixes could be made more explicit (and thus more easily machine parseable):

<pre>
<span class="n">
<span class="honorific-prefix">Mr.</span>
<span class="given-name">John</span>
<span class="additional-names">Quinlan</span>
<span class="family-name">Public</span>,
<span class="honorific-suffix">Esq.</span>,
<span class="honorific-suffix">Ph.D.</span>
</span>
</pre>

RESOLUTION: Adopt singular class name equivalents for plural property and sub-property names.

==== ISSUE 2 ====

Restricting the "type" sub-property values to being expressed in class names seems less than ideal. It's taking a piece of information which is very often visible in the content, and forcing it to be invisible.

Here is an example of an extensive bit of contact information on a web page:

http://www.patchlink.com/company/contact.html

<pre>
Mailing Address
3370 N. Hayden Road, #123-175
Scottsdale, AZ 85251-6632

Physical Address
8515 E Anderson
Scottsdale, AZ 85255
</pre>

Note that the type information for each "adr" is explicit in the content. This content could be marked up like this:

<pre>
<div class="adr">
<abbr style="display:block" class="type" title="postal,parcel">Mailing Address</abbr>
<div class="street-address">3370 N. Hayden Road, #123-175</div>
<span class="locality">Scottsdale</span>, <span class="region">AZ</span>
<span class="postal-code">85251-6632</span>
</div>
<div class="adr">
<abbr style="display:block" class="type" title="work,pref">Physical Address</abbr>
<div class="street-address">8515 E Anderson</div>
<span class="locality">Scottsdale</span>, <span class="region">AZ</span>
<span class="postal-code">85255</span>
</div>
</pre>

RESOLUTION: The "type" parameter MUST be marked-up when content is available (like the above two examples). We are ditching the type-value-as-another class name pattern.

In addition since there are some potentical problems with the "type" parameter for TEL and EMAIL properties. Since there are no defined sub-properties (unlike ADR's post-code, locality, etc) the entire node-value of TEL is taken as the value. For example:
<pre>
<span class="tel">+1.123.456.7890 <abbr class="type" title="work">(work)</abbr></span>
</pre>
would be represented in vCard as:
<pre>
TEL;TYPE=work:+123.456.7890 (work)
</pre>

We are introducing another sub-property class="value" to enable excerpting of a the value of an element of for a property.

<pre>
<span class="tel"><span class="value">+1.123.456.7890</span> <abbr class="type" title="work">(work)</abbr></span>
</pre>

Then parsers would first need to look for class="value" and take the node value of that if it exists rather than class="tel".

If one or more child elements with the class name of "value" are present inside the element for a property, then concatenate the node values of those child elements (in the order found) and use that as the value of the property. This would be before using the node value of the element for a property itself.

== References ==

=== Normative References ===
* [[hcard|hCard]]
* vCard (RFC 2426)
* [http://w3.org/TR/XHTML1 XHTML 1.0 Recommendation]
* [http://w3.org/TR/html401 HTML 4.01 Recommendation]
* [http://gmpg.org/xmdp/ XMDP]

=== Informative References ===
* [http://w3.org/TR/REC-CSS1 CSS1 Recommendation]

== Related Pages ==
{{hcard-related-pages}}

User:JiriKopsa

2007-03-19T05:43:21Z

JiriKopsa:

Jiri Kopsa
* [http://blogs.sun.com/rfe]

include-pattern-feedback

2007-03-19T04:59:00Z

JiriKopsa: /* Objects and Browser Behavior */

= Include Pattern Feedback =

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

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 - 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: JAWS 7.0 with Firefox 1.5/Win ===

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

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

Conclusion: the hyperlink include pattern presented no usability issues for this screen reader.

=== Proprietary attribute ===
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)

==== 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><span id="summaryA" class="summary">Kidderminster Branch Indoor Meeting</span></nowiki></pre>
<pre><nowiki><span id="summaryB>Janaury</span></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><span id="summaryC>Fred Smith</span></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><span class="value"><object data="#summaryA" class="include"></object> with <object data="#summaryB" class="include"></object></span></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}}