container-brainstorming

This page exists to brainstorm around the concept of ‘containers’ in microformats.

What's a Container?

A ‘container’ is a root element that contains multiple microformat items within it. It groups those items together, but could also be used to provide additional or shared semantics between those items.

Some microformats already define containers: vcalendar hCalendar is a container for events, the hfeed container in hAtom contains entries, hAudio has a concept whereby haudio concepts may be nested, and an hCard vcard may be a container for agent vcards.

Why is this being explored?

There are a number of use cases for making better use of these container semantics, both in microformats like hCalendar that already have containers, and hReview, where no current container concept exists.

examples

As always it helps to start with examples of markup from actual websites that are already publishing container semantics. If this section gets too large, perhaps we can move it to container-examples.

container of reviews

The following website(s) contain a list of reviews which could/would benefit from a way of marking up not just the reviews as hReviews, but also the set of them as reviewing the same item.

SustainLane

http://www.sustainlane.com/ has pages that show multiple reviews of the same item. e.g.

http://www.sustainlane.com/reviews/aziza/TVLWN4ZKQLKTOIKFLWKBWFQ17DN8

Yelp

http://yelp.com/ has pages that show multiple reviews of the same item. e.g.

http://www.yelp.com/biz/coffee-to-the-people-san-francisco

Use cases

Here are some example use cases for sharing properties from a container into multiple child microformats:

Multiple reviews of the same item

As demonstrated by the above real world examples, many sites publish a page for a single item, listing multiple reviews of that item (e.g. Amazon, Kelkoo, Yelp, Yahoo! Location etc.). The item appears once at the top of the page. The reviews follow. hReview's current requirement is that the item be referenced from every review using the include-pattern. This requires duplicating some amount of content (most logically, the name of the reviewed item). This has raised objections by implementers, and usually imposes a CSS-dependency to hide the repeated content.

Reviews and review aggregate of the same item

Same as above, a single page includes a few reviews and a single reviews aggregate for a single business. In some implementations (yelp) the aggregate result number is contained inside the hcard. Reviews that use the include pattern to include the hcard of the business, are also including a second rating microformat, resulting in two ratings for the same hreview. Putting the reviews and review aggregates as siblings inside the same container, can solve this problem.

Shared hCalendar Properties

Yahoo! TV Listings marks up television programme listings using hCalendar. The location field of the event is the channel on which the show is broadcast: e.g. <span class='location'>BBC 1</span>.

• ‘BBC 1’ is the heading for that channels listing page. The information is published once in the page.
• Each scheduled programme on the page is a vevent
• Using current hCalendar semantics, the location must be included in every vevent

With the ‘BBC 1’ content at the top of the page, not part of the programme content, the content either has to be repeated and hidden in the presentation layer, or current microformats constructs such as the include-pattern need to be used to invisibly reference the original mention of ‘BBC 1’.

Repeating content is unacceptable, and the include-pattern is a messy, hacky mark-up pattern. Embracing the concept of the container would match the publishing pattern of the site, without repeating content or including invisible pointers.

ideally this markup proposal would be moved to the "markup proposals" section below, separate from the "Use Cases" section, so that multiple varying proposals could be grouped together to compare, rather than intermingling them with the list of use cases.

.e.g.

<div class='vcalendar'>
   <h1 class='location'>BBC 2</h1>

   <ul>
      <li class='vevent'>
        <h2 class='summary'>Gardener's World</h2>
        <p class='dtstart'><span class='value-title' title='2009-06-05T20:30:00+0100'> </span> 8:30pm</p>
      </li>
      <li class='vevent'>
        <h2 class='summary'>Have I Got News For You</h2>
        <p class='dtstart'><span class='value-title' title='2009-06-05T21:00:00+0100'> </span> 9:00pm</p>
      </li>
    </ul>
</div>

Here, the location is promoted to being a property of the vcalendar, and is the default location for all the contained events.

This could also apply to the organizer, attendees, and others. With further explanation and date-time separation, you could event declare the day of the week the the vcalendar and the time-of-day in the vevent. The basic principal is illustrated, though.

Uses for this pattern:

• Broadcast listings for a single channel/station
• Concert listings at a single venue
• Concert listings for a single act (e.g. ‘Doves in Concert’ is the event summary for multiple events at different locations)

This of course, extends the use of an existing container.

hAtom entries published together

hAtom already has parsing rules to look for an address in the page for a shared author, a container-like concept. It already has an hfeed parent node, and this could be used to share other features of the format. For example, a photo album (for which explicit creation datetimes are either unavailable or irrelevant) may be published just as having been taken on a single day. As such, the date will appear once at the head of the page, and each photograph (hentry) will not contain a unique updated date.

Shared Aspects of Containers

If containers become a more strongly adopted concept in microformats, they should behave consistently across formats (hence documenting these two examples here, rather than just as separate issues for both hReview and hCalendar).

Things that should be consistent and predictable:

• Inheriting an property into a microformat item within the container
• Contained items overriding one or more inherited property
• Alternatively, siblings cannot override properties of other siblings. Example: hcard of reviewer inside hreview cannot override any property of the item hcard (a sibling of the hreview). When a sibling specifies a property of another sibling, it is ignored (Example: hreview contains availability, availability is ignored).

markup proposals

Existing container elements

• vcalendar in hCalendar
• hfeed in hAtom
• hresume in hResume — hResume contains an hCard for the owner, which could indicate default properties (fn) for experience business cards.
• hreview-aggregate in hReview-aggregate can contain other hReviews, as such could be used as a container to share the item with each component hreview.
• hproduct in hProduct can contain one or more reviews (hReview or hReview-aggregate), this should allow the reviews to all use the containing hproduct as their item.

hreview-set

One solution to the problem of multiple reviews of the same item could be to wrap each hReview in a container (hypothetically, hreview-set. The item is a child of the set, and is inherited by each hreview contained within.

hCard as a container

vcard block can contain associated information like reviews and aggregates. hreviews inside an vcard do not need to specify item. This also extends to other microformats that may contain reviews, such as hproduct. Another option is that a vcard that contains other microformat must also specify additional tag, such as hcontainer, item or similar.

Problems

• hreview already contains child hCard. Since it can inherit aspects of hcard from its parent, there will be duplicate values. This makes the job of the parser more complex, and requires additional rules, such as "an hreview inside an hcard ignores all hCard properties that are not contained in it", etc.
• Include pattern from hreview to the container hCard can cause circular references, requiring more rules in the microformat specification and more rules for the parsers to follow.
• Generally it seems to me (Elli) that this pattern will require many parsing rules. Things are not "atomic". It also forces a rigid structure on the xhtml, which may defeat the purpose of containers.

<div class="vcard">
   <h1 class="fn">name</h1>
   <div class="hreview-aggregate">
      <div class="rating">
         <span class="average">4.4</span>
      </div> 
      <span class="count">1313</span> reviews
   </div>
   <div class="hreview"><!-- this hreview does not contain item --></div>
   <div class="hreview"><!-- this hreview does not contain item --></div>
</div>

hcontainer

A container microformat. Inside a container, a microformat that requires another microformat as a child (such as hreview requiring an item), can resolve this association by sibling relationship (as opposed to parent child relationship). When a container includes hreview or hreview-aggregate, it also requires a child item. This is similar to hreview-set proposal, with specific handling of aggregates.

In the example below, the item is hcard, similar examples can be written for products and events.

<!-- simple, all elements in the container are siblings -->
<div class="hcontainer">
   <h1 class="item vcard fn">name</h1>
   <div class="hreview-aggregate">
      <div class="rating">
         <span class="average">4.4</span>
      </div> 
      <span class="count">1313</span> reviews
   </div>
   <div class="hreview">...</div>
   <div class="hreview">...</div>
</div>
<!-- More complex case, nested elements in the container have additional parent child relationship -->
<div class="hcontainer">
   <div class="hreview-aggregate">
      <h1 class="item vcard fn">name</h1>
      <div class="rating">
         <span class="average">4.4</span>
      </div> 
      <span class="count">1313</span> reviews
   </div>
   <div class="hreview">...</div>
   <div class="hreview">...</div>
</div>

• Unconvinced by the generics here. Especially since a lot of microformats already have parent nodes (vcalendar, hfeed). Doesn't self-document. —BenWard 06:27, 30 July 2009 (UTC)
• In this case, hreview-aggregate could itself have container behaviour; the hreview-aggregate is a container for other hreveiw items, and the item is shared. —BenWard 06:27, 30 July 2009 (UTC)

item as a container

The item microformat is currently used inside hreviews. Use this existing micformat as a container as well. This makes the specification slightly more complicated, since item will be allowed as a parent of hreview as well as a child. This is basically the same proposal as above, but using the name item for the container, instead of a dedicated name.

Problems

• This defines two microformats that can be parent child of each other in both directions (hreview and item).

<div class="item">
   <h1 class="vcard fn">name</h1>
   <div class="hreview-aggregate">
      <div class="rating">
         <span class="average">4.4</span>
      </div> 
      <span class="count">1313</span> reviews
   </div>
   <div class="hreview"><!-- this hreview does not contain item --></div>
   <div class="hreview"><!-- this hreview does not contain item --></div>
</div>

• I don't really see that item makes sense as a container here. An item is a singular thing, a collection is wrapping a collection of things. In hReview, or hListing, or anything you'd have container as a structural parent of item. Repurposing item seems very confusing. --BenWard 06:21, 30 July 2009 (UTC)

hreview rating and hreview-aggregate rating use different names

Since the microformat rating is used for both, an hreview that includes an hcard which contains aggregates, effectively imports a second rating. This can be solved by having different names for hreview rating and hreview-aggregate rating. This is not really a container proposal, but it addresses issues of the hreview-aggregate which is currently a container for item.

Problems

• This may not be necessary for pages that can use a container microformat with minimal impact to the xhtml structure. Pages that cannot use container structure and use includes may still need a solution.

<div class="vcard item" id="review_item">
   <h1 class="fn">name</h1>
   <!-- average rating -->
   <span class="average-rating">5</span> stars
   based on <span class="review-count">1313</span> reviews
   <span class="type microformat_detail">business</span>
</div>
<div class="hreview">
   <!-- single rating -->
   <span class="rating">3</span> stars
   <!-- include pattern -->
   <a class="item microformat_detail" href="#review_item">Aziza</a>
</div>

Prefixes to indicate shared properties

A generic shared- prefix could be used to indicate that certain properties should be applied to all component microformats within a container. For example, if a vcard did not have any descendant elements with the class fn it would take its formatted name from a sibling element with the class shared-fn.

Sharing a location between multiple vevents within a vcalendar:

<div class="vcalendar">
  <h2 class="shared-location">The Music Venue</h2>
  <p class="summary">This summary does not have the shared- prefix, so it is ignored by the events.</p>
  <div class="vevent"> ... </div>
  <div class="vevent"> ... </div>
</div>

If the container was itself a microformat then the prefix would be used to determine which properties belonged to the container, which belonged to the component microformats and which were shared by both.

For example, an hReview-aggregate may contain many hReviews. Within the root hreview-aggregate element:

• An element with class item would provide the item for the hreview-aggregate.
• An element with class shared-item would provide the item for the individual hreviews.
• An element with both classes (item shared-item) would provide the item for the hreview-aggregate and the individual hreviews.

<div class="hreview-aggregate">
  <h2 class="item shared-item vcard"><span class="fn org">A Restaurant</span></h2>
  <div class="hreview"> ... </div>
  <div class="hreview"> ... </div>
</div>

see also

• hReview
• hCalendar
• hListing