Part III: Marking up People

The Challenge

When you first begin exploring the notion of meaningful markup (semantic HTML) you begin to notice that tags have meaning. To write successful semantic HTML you must ask yourself everytime you begin to type an HTML tag, "Is this the best tag for this job? Or is there another tag that better describes this information?" You make that decision based on what the tag means, not how the tag will render (thanks to CSS).

Eventually when it becomes a habit to write meaningful markup, you may begin to notice that HTML lacks tags for certain things. Sure, there is the p tag for paragraphs. There are tags for headings and for lists. But there is no "person" tag.

Since there isn't one, what's the big deal? Well, in the real estate web design industry, we encounter people (or organizations) frequently -- our agents and brokers! And because meaningful HTML has so many potential benefits, this is a great opportunity to enhance using microformats. So for our first major introduction to a specific microformat, we'll write the HTML to mark up a real estate agent.

The "Vocabulary"

As we've discussed before, if you encounter a situation where you find that HTML is insufficient to fully communicate the meaning of your content, you want to start by researching vocabularies. It is best if you can find an established vocabulary that fits your needs. When a microformat is widely used and widely understood, that is when you get the most benefit from using it, too.

Remember, our challenge here is to mark up a person. Based on a little research (and what we've learned already) we can find several different vocabulary options:

• Microformats - hCard, adr, XFN
• RDFa Vocabularies - FOAF (Friend of a Friend), vCard
• Google Vocabularies - Person, Organization

The "Specification"

We're going to move forward using the vocabulary from hCard for several reasons. It's widely used and it's a microformat, which is the focus of this tutorial. It's also based a popular format for contacts used by desktop software. We're also obviously going to choose to add the vocabulary to our HTML using a Microformat design pattern, but let's review our three "specification" options before we dive in.

• Microformat
  • Support?
    • Google
    • Browser Plugins
  • Old, well-established specification.
  • Popular and easy to use.
• Microdata
  • Support?
    • Google
  • New, incomplete specification.
  • Part of HTML5, so should be forward-compatible.
• RDFa
  • Support?
    • Google
    • Third party sites
  • Arguably the most robust specification.
  • Arguably the most advanced specification.
  • Best when used with XHTML.
  • Unfortunately, does not have the "mass-appeal" of Microformats.

Assessing the "Data"

Now we've decided to address our challenge using the hCard Microformat. So let's take a look at the sort of information we'll be working with. Take some basic information about an imaginary real estate agent:

Janice Smithington
Tepidpool Realty Brokerage
123 Address St.
Citytown, Florida 33333

First we need to be able to identify the information we have. What "data" do we have to mark up with HTML?

• Name
  • First Name
  • Last Name
• Office Name
• Address
  • Street Adress
  • City
  • State
  • Zip
  • (Implied) Country

We have some basic information about this person including their name and business affiliation. What other information might we also have available?

• A photo
• A job title -- like buyer's agent
• Designations -- like SRES
• E-mail address
• Phone number(s)
• Website address(es)

Starting the HTML Markup

We'll be drawing our dos and don'ts both from experimentation and from the hCard Microformat. As you read the specification you will note that a particular vocabulary term (like a "first name") is consistently referred to as a "property" (the "given-name property"). This terminology will be used throughout the rest of the tutorial.

Even though I'll be calling them "properties", you'll probably also recognize something mentioned in previous tutorials: for the hCard Microformat, the vocabulary is primarily placed into the class attribute.

According to the documentation, the first thing we must do to begin using the hCard Microformat is make sure all our hCard-related HTML is inside a tag with the class "vcard."

<div class="vcard">
</div>

Name

First, our agent has a name we can mark up. If we refer the hCard Microformat we can find out about the name-related vocabulary ("name properties").

• fn
• n (family-name, given-name, additional-name, honorific-prefix, honorific-suffix)

The n property refers exclusively to a person's name. That property also has some optional sub-properties, like "given-name." By marking up a tag with the class n we can communicate a lot of specification information about a person's name.

<div class="vcard">
	<div class="n">
		<span class="given-name">Janice</span>
		<span class="family-name">Smithington</span>
	</div>
</div>

Business Affiliation

Our agent can be associated with a business -- such as a real estate brokerage. Our agent can also have a job title or a role within their organization.

• org (organization-name, organization-unit)
• role
• title

<div class="vcard">
	<div class="n">
		<span class="given-name">Janice</span>
		<span class="family-name">Smithington</span>
	</div>
	<div class="org">
		<span class="organization-name">Tepidpool Realty Brokerage</span>
	</div>
</div>

Pause #1: Shorthand

The way I have organized the code above reflects the exact (expanded) structure of the hCard Microformat vocabulary. However, it's not necessary to write out all sub-properties every time! As long as you satisfy the requirements of the hCard vocabulary, you can use whatever limited information you have available. For example, the code so far could also be written:

<div class="vcard">
	<span class="n">Janice Smithington</span>
	<span class="org">Tepidpool Realty Brokerage</span>
</div>

Required Properties

Unfortunately, the code from the last example actually doesn't meet the requirements of the hCard Microformat. There's a required property I listed when we were initially looking at the n property required that we have not yet used!

• fn

As you read the hCard Microformat it will become clear that fn can apply to a person or an organization -- whichever the hCard is for. It expresses, "this is the preferred name for the primary person (or organization) I'm describing." In this case, we are describing a person and fn is presumably the same as n!

<div class="vcard">
	<div class="fn n">
		<span class="given-name">Janice</span>
		<span class="family-name">Smithington</span>
	</div>
	<div class="org">
		<span class="organization-name">Tepidpool Realty Brokerage</span>
	</div>
</div>

Pause #2: Logical containers

I also mentioned two properties when we were looking at organizations above which we haven't added to our HTML yet. "role" and "title" are properties that are related to a person's occupation and business affiliation. So, although they are not sub-properties of org I generally to to group them with the other organization-related information.

<div class="vcard">
	<div class="fn n">
		<span class="given-name">Janice</span>
		<span class="family-name">Smithington</span>
	</div>
	<div class="org">
		<span class="role">Real Estate Agent</span>
		<span class="title">Buyer's Agent</span>
		<span class="organization-name">Tepidpool Realty Brokerage</span>
	</div>
</div>

Pause #3: Sub-Properties & Nesting

When a property has sub-properties, those sub-properties should be nested!

Take for an example the "given-name" sub-property. It is a sub-property of the "n" property. That is why I have nested it inside. In some cases this may not give you any trouble when attempting to parse your HTML, but it is best to make a habit of nesting your tags properly.

In respect to my suggestion for "logical containers", you may wonder if nesting things that are not sub-properties will cause issues. The answer is: not that I've encountered so far. But you ought to be specific when you do so -- and make sure you test it to make certain the results are what you're hoping for! This should be done in moderation and in scenarios that make sense.

Address

We also have the agent's address available for the hCard, so let's add that now...

• adr (post-office-box, extended-address, street-address, locality, region, postal-code, country-name, type, value)
• geo (latitude, longitude)

Because addresses are meaningful by themselves and because they can be related to so many other things (people, organizations, events, etc.) addresses are being split into their own Microformat -- adr.

<div class="vcard">
	<div class="fn n">
		<span class="given-name">Janice</span>
		<span class="family-name">Smithington</span>
	</div>
	<div class="org">
		<span class="role">Real Estate Agent</span>
		<span class="title">Buyer's Agent</span>
		<span class="organization-name">Tepidpool Realty Brokerage</span>
	</div>
	<div class="adr">
		<span class="street-address">123 Address St.</span>
		<span class="locality">Citytown</span>,
		<span class="region">State</span>
		<span class="postal-code">33333</span>
	</div>
</div>

Even a meticulously written address can be insufficient to pinpoint a location in a program (like Google Maps). That's why there's also the geo Microformat, which specifies locations by latitude and longitude. In the example below, remember that "geo" is not a sub-property of "adr" -- I have grouped them together because they are logically related.

<div class="vcard">
	<div class="fn n">
		<span class="given-name">Janice</span>
		<span class="family-name">Smithington</span>
	</div>
	<div class="org">
		<span class="role">Real Estate Agent</span>
		<span class="title">Buyer's Agent</span>
		<span class="organization-name">Tepidpool Realty Brokerage</span>
	</div>
	<div class="adr">
		<span class="street-address">123 Address St.</span>
		<span class="locality">Citytown</span>,
		<span class="region">State</span>
		<span class="postal-code">33333</span>
		<div class="geo">
			<span class="latitude">30.38</span>
			<span class="longitude">84.37</span>
		</div>
	</div>
</div>

Photographs

Photos were mentioned earlier as an example of something we'd commonly have to include in agent information. And, yes, photos are part of the hCard Microformat!

• photo

<div class="vcard">
	<img src="photo.jpg" width="100" height="100" alt="" class="photo" />
	<div class="fn n">
		<span class="given-name">Janice</span>
		<span class="family-name">Smithington</span>
	</div>
	<div class="org">
		<span class="role">Real Estate Agent</span>
		<span class="title">Buyer's Agent</span>
		<span class="organization-name">Tepidpool Realty Brokerage</span>
	</div>
	<div class="adr">
		<span class="street-address">123 Address St.</span>
		<span class="locality">Citytown</span>,
		<span class="region">State</span>
		<span class="postal-code">33333</span>
		<div class="geo">
			<span class="latitude">30.38</span>
			<span class="longitude">84.37</span>
		</div>
	</div>
</div>

Contact Info

Most of the time we'll also have some contact information, such as a phone number, e-mail address, or website address for an agent.

• email (type, value)
• tel (type, value)
• url

<div class="vcard">
	<img src="photo.jpg" width="100" height="100" alt="" class="photo" />
	<div class="fn n">
		<span class="given-name">Janice</span>
		<span class="family-name">Smithington</span>
	</div>
	<div class="org">
		<span class="role">Real Estate Agent</span>
		<span class="title">Buyer's Agent</span>
		<span class="organization-name">Tepidpool Realty Brokerage</span>
	</div>
	<div class="adr">
		<span class="street-address">123 Address St.</span>
		<span class="locality">Citytown</span>,
		<span class="region">State</span>
		<span class="postal-code">33333</span>
		<div class="geo">
			<span class="latitude">30.38</span>
			<span class="longitude">84.37</span>
		</div>
	</div>
	<a href="..." class="url">Website</a>
	<a href="..." class="email">E-Mail</a>
	<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>

Pause #4: Questions

Can you add more than one website address? How can you note what the website address is for if there is more than one?

Yes, you can add more than one website address. The "url" property does not have "type" and "value" sub-properties like "email" and "tel" do. You cannot precisely label a "url" in the hCard, but you can describe the relationship the "url" has with the person using XFN. We'll go over this a little more in the next class, but it looks something like this:

<div class="vcard">
	<a href="..." class="url" rel="me">Website</a>
	<a href="..." class="url" rel="friend">Website</a>
	<a href="..." class="url" rel="co-worker">Website</a>
</div>

Viewing & Debugging

Alright, enough of looking at the code. What does microformat-ed content look like? How can you debug it? Well, first we can take a look at how the HTML is rendered. I have included a few basic styles in my stylesheet, using the microformat classes, so this is what I end up with:

Janice Smithington

Real Estate Agent Buyer's Agent Tepidpool Realty Brokerage

123 Address St. Citytown, State 33333

30.38 84.37

Website E-Mail

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

Or we can use a tool to parse the code. By using a tool to parse the code, we can spot any areas we might have made a mistake or might wish to make alterations to adjust the parsing. This is the best way to debug!

• hCard Validator
• Google Rich Snippet Tester
• Firefox Operator Plugin

<div class="vcard">
	<img src="photo.jpg" width="100" height="100" alt="" class="photo" />
	<div class="fn n">
		<span class="given-name">Janice</span>
		<span class="family-name">Smithington</span>
	</div>
	<div class="org">
		<span class="role">Real Estate Agent</span>
		<span class="title">Buyer's Agent</span>
		<span class="organization-name">Tepidpool Realty Brokerage</span>
	</div>
	<div class="adr">
		<span class="street-address">123 Address St.</span>
		<span class="locality">Citytown</span>,
		<span class="region">State</span>
		<span class="postal-code">33333</span>
		<div class="geo">
			<span class="latitude">30.38</span>
			<span class="longitude">84.37</span>
		</div>
	</div>
	<a href="http://www.homes.com" class="url">Website</a>
	<a href="mailto:test@example.org" class="email">E-Mail</a>
	<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>