Part V: hListing

The Challenge

Another ubiquitous presence on real estate websites is, unsurprisingly, listings. Homes for sale, apartments for rent, real estate listings (as our SEO department might say). How can we add meaning to the HTML we use to mark up listings?

"There's a microformat for that!" and it's called hListing. Now, hListing is still a draft (note the red), which means it's not finalized and its requirements might change.
The "Vocabulary"

So far as I know, the only vocabulary around for listings is hListing at this time. hListing is best combined with other microformats like adr, hCard, and hCalendar for optimal effect.
- hListing
The "Specification"

Because hListing is a vocabulary native to Microformats.org and because Microformats are our primary focus, that's how we'll be learning to use hListing. That means we'll be using some or all of the Microformat design patterns that we've looked at in previous tutorials.
Assessing the "Data"

Let's take a look at the sort of information we'd commonly have for a listing.
```
123 Address Street
Citytownvillage, Florida 33333
2-story ranch home for sale
$210,000
This charming 3 bed/3.5 bath ranch home has a large back yard -- perfect for families!
Linda Realtorman, Agent
Tepidpool Realty Brokerage
(850) 423-3321
```
What sort of information do we have here?
- Listing Address
- Style of the home
- Price
- It's for sale (rather than rent)
- Brief text description
- Number of bedrooms
- Number of bathrooms
- Listing Agent
- Listing Office
- Contact phone number
What other sorts of information might we have for a listing?
- Property features
- Size: square footage, acreage
- School zones
- etc.
"Invoking" hListing

Like hCard, hListing has a "root property," that is a required class that indicates where the listing starts.
- hlisting
```
<div class="hlisting">
	
</div>
```
hListing Requirements

hListing has some required properties. Using only the required properties creates the most basic hListing, but all hListings must use the required properties. Currently the following are required.
- lister (vcard)
  - fn
- description
```
<div class="hlisting">
	<div class="description">
		This charming 3 bed/3.5 bath ranch home has a large back yard -- perfect for families!
	</div>
	<div class="lister vcard">
		<span class="fn">Linda Realtorman</span>
	</div>
</div>
```
Note that the lister is representing using hCard, the Microformat we learned in the last two tutorials.

The above may be a valid hListing according to the specification (as of right now), but it's not terribly useful to a consumer or to our customers. There's no way to see what home is for sale and no way to contact the listing agent.

But the specification is a draft and the text indicates it originally had a different set of requirements. (When you read it now, you'll see that not all the information has been edited to reflect the new requirements, so it's hard to be 100% sure what they are meant to be.) Some portions of the hListing draft still mention these properties as "required":
- item (vcard, adr, etc.)
  - fn
- type
- action
Like telephone number types from hCard, there is a supplied list of keywords for type and action. By adding these and the item name, we actually add a lot of useful information to our listing:
```
<div class="hlisting">
	<div class="item">
		<div class="fn">
			123 Address St. Citytownvillage, Florida 33333
		</div>
	</div> 
	<div class="offer sale">
		2-story ranch home for sale
	</div>
	<div class="description">
		This charming 3 bed/3.5 bath ranch home has a large back yard -- perfect for families!
	</div>
	<div class="lister vcard">
		<span class="fn">Linda Realtorman</span>
	</div>
</div> 
```
Either of those would be a minimal, valid hListing. Since it's a draft it's subject to change again, however. Personally, I'm hoping they rethink that bit aboust listing types and actions. I drew my interpretation from various examples and I'm not sure I like the "collapsed" class token(s). When I marked up the listings on NUMBER1EXPERT, I used value-class-pattern, like this:
```
...
<span class="action">
	<span class="value-title" title="sale"></span>
	for sale
</span>
...
```
That probably needs to be adjusted, because I'm not sure if it's "valid" right now. I also don't know how it will end up when hListing moves out of the draft stage. Personally, I have a notion I want to experiment with; that since there is a listing type, a listing action, an item type, and item tags, they could all be marked up as tags. But I digress...
Other hListing Properties

So we've got the basic requirements out of the way -- but there's more to hListing.

Summary

Sometimes listings have "lead lines" or "headings."When there is a title or lead line, hListing has a property called "summary" which serves as the title for a listing.
- summary
```
<div class="hlisting">
	<div class="item">
		<h1 class="fn">
			123 Address St. Citytownvillage, Florida 33333
		</h1>
	</div> 
	<div class="description">
		<h2 class="offer sale summary">
			2-story ranch home for sale
		</h2>
		<p>This charming 3 bed/3.5 bath ranch home has a large back yard -- perfect for families!</p>
	</div>
	<div class="lister vcard">
		<span class="fn">Linda Realtorman</span>
	</div>
</div> 
```
In the example above I have shifted some of the div tags to h* tags. In both cases these function as headings for the listing, so this is a better way to semantically mark up a listing. I have also moved "summary" inside of "description" because of the "logical container" principle.
hListing Properties with Nested Microformats

In the last tutorial we talked about nesting microformats and looked at a few examples. hListing makes heavy use of nesting to describe many of its properties.

Dates

Listings also have dates associated with them: the date they were originally posted, the date they were last updated, and/or the date they expire. Dates can be added to a listing and are done so using a Microformat design pattern, the datetime-design-pattern. This pattern is used to represent dates in both a machine-readable and human-friendly formats. That's why the title attribute contains a very specific date/time. (Remember that design patterns aren't microformats per se, but in this case it's close enough.)
- dtlisted
- dtexpired
```
...
<div>
	<span>
		Posted <abbr class="dtlisted" title="2010-01-12T12:00:00+00:00">Jan 12, 2010</abbr>
	</span> 
	<span>
		Expires <abbr class="dtexpired" title="2011-02-24T12:00:00+00:00">Feb 24, 2011</abbr>
	</span>
</div>
...
```
The HTML in the example above doesn't have any classes because it's not necessary for the hListing Microformat. I think it's legitimate to (mis)use the "dtlisted" property on "last updated" dates.

Price

Our example listing also has a price, which is also a part of hListing.
- price
```
...
<span class="price">$210,000</span>
...
```
Price by itself is quite simple. But "price" can also contain a nested microformat. It's optional but possible to make use of the currency Microformat, like this:
```
...
<span class="price money">
	<abbr class="currency" title="US Dollars">$</abbr>
	<span class="amount">210,000</span>
</span>
...
```
Permalink

For a listing thumbnail or distributed listings, there may be a link included on the listing that links to the listing details (or the original source of the listing). hListing includes the "permalink" property for this purpose. In this case the rel-self Microformat is used to denote the permalink.
- permalink (rel-self)
```
...
<a href="#" class="permalink" rel="self bookmark">Listing Details</a>
...
```
I have used the class "permalink" but doing so is optional, the important part is rel="self bookmark". "self" as in "this is a link to the listing itself" and "bookmark" as in "this the page you should bookmark for this listing."

Tags

You can also associate rel-tag tags with a listing. I might use this on property types, property styles, property statuses, or property features.
- tags (rel-tag)
```
...
<ul class="tags">
	<li>
		<a href="#" rel="tag">a tag</a>
	</li>
</ul>
...
```
Location

There's also a "location" propery in hListing. Inside the "location" property you would nest a microformat for places like adr or geo.
- location (adr or geo)
```
...
<div class="location adr">
	<span class="street-address">123 Address St.</span>
	<span class="locality">Citytownvillage</span>,
	<span class="region">Florida</span>
	<span class="postal-code">33333</span>
</div>
...
```
Lister

We looked at the "lister" property earlier. As I mentioned, it's an hCard. The only required sub-property is "fn," but you can use any hCard markup.
- lister (vcard)
```
...
<div class="lister vcard">
	<div class="fn n">
		<span class="given-name">Linda</span>
		<span class="family-name">Realtorman</span>
	</div>
	<div class="org">Tepidpool Realty Brokerage</div>
	<ul>
		<li class="tel">
			<span class="type">Work</span>
			<span class="value">(850) 333-2222</span>
		</li>
		<li class="tel">
			<span class="type">Home</span>
			<span class="value">(850) 222-6677</span>
		</li>
	</ul>
</div>
...
```

Viewing & Debugging

hListing in the browser

123 Address St. Citytownvillage, Florida 33333

$ 210,000

2-story ranch home for sale

This charming 3 bed/3.5 bath ranch home has a large back yard -- perfect for families!

Linda Realtorman

Tepidpool Realty Brokerage

Listing Agent

Work (850) 333-2222
Home (850) 222-6677

Posted Jan 12, 2010 Expires Feb 24, 2011

Final hListing Mark-Up

<div class="hlisting">
	<div class="item">
		<h1 class="fn">
			<div class="location adr">
				<span class="street-address">123 Address St.</span>
				<span class="locality">Citytownvillage</span>,
				<span class="region">Florida</span>
				<span class="postal-code">33333</span>
			</div>
		</h1>
	</div> <!--/ .item -->
	<div class="price money">
		<abbr class="currency" title="US Dollars">$</abbr>
		<span class="amount">210,000</span>
	</div>
	<div class="description">
		<h2 class="offer sale summary">
			2-story ranch home for sale
		</h2>
		<p>This charming 3 bed/3.5 bath ranch home has a large back yard -- perfect for families!</p>
	</div>
	<ul class="tags">
		<li>
			<a href="#" rel="tag">3 beds</a>
		</li>
		<li>
			<a href="#" rel="tag">3.5 baths</a>
		</li>
		<li>
			<a href="#" rel="tag">Ranch</a>
		</li>
		<li>
			<a href="#" rel="tag">2 Story</a>
		</li>
	</ul>
	<div class="lister vcard">
		<div class="fn n">
			<span class="given-name">Linda</span>
			<span class="family-name">Realtorman</span>
		</div>
		<div class="org">Tepidpool Realty Brokerage</div>
		<div class="role">Listing Agent</div>
		<ul>
			<li class="tel">
				<span class="type">Work</span>
				<span class="value">(850) 333-2222</span>
			</li>
			<li class="tel">
				<span class="type">Home</span>
				<span class="value">(850) 222-6677</span>
			</li>
		</ul>
	</div>
	<div>
		<span>
			Posted <abbr class="dtlisted" title="2010-01-12T12:00:00+00:00">Jan 12, 2010</abbr>
		</span> 
		<span>
			Expires <abbr class="dtexpired" title="2011-02-24T12:00:00+00:00">Feb 24, 2011</abbr>
		</span>
	</div>
</div> <!--/ .hlisting -->

The Challenge

The "Vocabulary"

The "Specification"

Assessing the "Data"

"Invoking" hListing

hListing Requirements

Other hListing Properties

Summary

hListing Properties with Nested Microformats

Dates

Price

Permalink

Tags

Location

Lister

Viewing & Debugging

hListing in the browser

123 Address St. Citytownvillage, Florida 33333

2-story ranch home for sale

Final hListing Mark-Up