include-pattern: Difference between revisions

From Microformats Wiki
Jump to navigation Jump to search
(added a href include example and proposal)
(removed type attribute usage on includes due to reasoning provide on microformats-discuss by Ryan King)
Line 34: Line 34:
<pre><nowiki>
<pre><nowiki>
<span class="vcard">
<span class="vcard">
  <object data="#j" class="include" type="text/html"></object>
  <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 56: Line 56:
Note 1: '''the object data attribute MUST be a local ID reference.'''  External references (which would require a consuming application to load an external resource) are currently not supported by this method.
Note 1: '''the object data attribute MUST be a local ID reference.'''  External references (which would require a consuming application to load an external resource) are currently not supported by this method.


Note 2: <code>type="text/html"</code> is used because that is the most common Content-Type of web pages. On pages served as "<code>application/xhtml+xml</code>", use that Content-Type for the <code>type</code> atribute on object includes on those pages.
Note 2: To avoid unsightly messes in Safari, you should include the following style rule in a style sheet for the page:
 
'''Proposal 2:''' "text/html" is for an entire HTML document, and not precisely correct for a well-formed fragment of (X)HTML.  "text/xml" would make sense if the HTML fragment happened to also be well-formed XML, but it also has the drawback of being semantically weak, that is, the fact that the fragment contains HTML with much more meaning than just XML is lost.  Thus the proposal is to use a new content-type, such as "text/html-frag", or "text/x-html-frag" if an unofficial "x-" version is preferred.
 
Note 3: To avoid unsightly messes in Safari, you should include the following style rule in a style sheet for the page:
<pre><nowiki>
<pre><nowiki>
object.include { width:0; height:0 }
object.include { width:0; height:0 }
</nowiki></pre>
</nowiki></pre>


Note 4: To prevent infinite loops a class="include" can not be a child-or-self of the ID it is refering too
Note 3: 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.


== hyperlink include example ==
== hyperlink include example ==
Line 73: Line 69:
<pre><nowiki>
<pre><nowiki>
<span class="vcard">
<span class="vcard">
  <a href="#j" class="include" type="text/html"></a>
  <a href="#j" class="include"></a>
  <span class="org">SimplyHired</span>
  <span class="org">SimplyHired</span>
  <span class="title">Microformat Brainstormer</span>
  <span class="title">Microformat Brainstormer</span>
Line 84: Line 80:
# ... that's it.  only 2 changes.  
# ... that's it.  only 2 changes.  


Following proposal 2, we can update the 'type' attribute as well:
<pre><nowiki>
<span class="vcard">
<a href="#j" class="include" type="text/html-frag"></a>
<span class="org">SimplyHired</span>
<span class="title">Microformat Brainstormer</span>
</span>
</nowiki></pre>


And just as in the object include example, the end effective result to the parser is the same, and the same '''Notes''' apply.
And just as in the object include example, the end effective result to the parser is the same, and the same '''Notes''' apply.

Revision as of 03:09, 11 July 2006

include pattern

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, hReview, hAtom etc.) need a mechanism to include a portion of data from 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.

Author
Tantek Çelik


Background

In 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 hCard reference via object technique.

class name "include"

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.

Proposal 1: Allow the use of <a href class="include"> as a secondary include-pattern mechanism, due to some browsers mishandling the object include-pattern. See include-pattern-feedback for details.

object include example

Here is an example of an 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:

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

Somewhere else on the page, you could have another hCard which would re-use that "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>

Thus a microformat parser would treat the above as follows, with the object include completely replaced by the subtree that it references:

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

Note 1: the object data attribute MUST be a local ID reference. External references (which would require a consuming application to load an external resource) are currently not supported by this method.

Note 2: To avoid unsightly messes in Safari, you should include the following style rule in a style sheet for the page:

object.include { width:0; height:0 }

Note 3: 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.

hyperlink include example

Per the proposal 1 above, here is how you would code the above object include example using the <a href> tag.

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

Changes:

  1. a open/close tag instead of object open/close tag
  2. href attribute instead of data attribute
  3. ... 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.

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

Acknowledgments

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

  • Introducing HInclude by Mark Nottingham.
    • HInclude is a markup extension + javascript library for including *external* files into an XHTML document.

Discussions

Q&A

  • If you have any questions about include-pattern, check the include-pattern FAQ, and if you don't find answers, add your questions to the end of the page!

Issues