hcard-design-methodology - Revision history

TomMorris: Reverted edits by Feecfyahoo.ca (Talk) to last version by Epizoic

2013-03-30T19:25:58Z

Reverted edits by Feecfyahoo.ca (Talk) to last version by Epizoic

Show changes

Feecfyahoo.ca at 19:17, 30 March 2013

2013-03-30T19:17:14Z

Show changes

Epizoic: Changed small typo

2010-02-05T14:33:50Z

Changed small typo

← Older revision		Revision as of 14:33, 5 February 2010
Line 35:		Line 35:
	* <code>BEGIN:VCARD</code> became <code>class="vcard"</code>		* <code>BEGIN:VCARD</code> became <code>class="vcard"</code>
	* <code>N:</code> became <code>class="n"</code>		* <code>N:</code> became <code>class="n"</code>
	* <code>FN:</code> ~~becamse~~ <code>class="fn"</code>		* <code>FN:</code> became <code>class="fn"</code>
	* ... etc.		* ... etc.

Tantek: note informative explanation.

2007-12-14T15:35:51Z

note informative explanation.

← Older revision		Revision as of 15:35, 14 December 2007
Line 1:		Line 1:
	<h1>hCard design methodology</h1>		<h1>hCard design methodology</h1>
			{{TOC-right}}
			This page is an ''informative'' explanatory section of the [[hcard\|hCard specification]].

	This page captures some of the design methodology that went into the [[hcard\|hCard microformat]].		This page captures some of the design methodology that went into the [[hcard\|hCard microformat]].

Tantek at 22:11, 21 October 2007

2007-10-21T22:11:15Z

← Older revision		Revision as of 22:11, 21 October 2007
Line 56:		Line 56:


	* Finally, if the format of the data according to the original schema is too long and/or not human-friendly, use <code><abbr></code> instead of a generic structural element, and place the literal data into the 'title' attribute (where abbr expansions go), and the more brief and human-readable equivalent into the element itself. Further informative explanation of this use of <code><abbr></code>: ~~[[abbr-design-pattern]],~~ [http://tantek.com/log/2005/01.html#d26t0100 Human vs. ISO8601 dates problem solved]~~, and [http://www.webstandards.org/2007/04/27/haccessibility/ hAccessibility] aka "abbr-design-pattern considered harmful~~."		* Finally, if the format of the data according to the original schema is too long and/or not human-friendly, use <code><abbr></code> instead of a generic structural element, and place the literal data into the 'title' attribute (where abbr expansions go), and the more brief and human-readable equivalent into the element itself. Further informative explanation of this use of <code><abbr></code>: [http://tantek.com/log/2005/01.html#d26t0100 Human vs. ISO8601 dates problem solved].

	Motivated originally by the development of [[hcalendar\|hCalendar]] which itself is based on [[icalendar\|iCalendar RFC2445]], which needed a way to capture and represent datetimes, this technique is similarly used in several instances in hCard, e.g.		Motivated originally by the development of [[hcalendar\|hCalendar]] which itself is based on [[icalendar\|iCalendar RFC2445]], which needed a way to capture and represent datetimes, this technique is similarly used in several instances in hCard, e.g.

Tantek: drafted

2007-10-21T21:42:19Z

drafted

New page

<h1>hCard design methodology</h1>

This page captures some of the design methodology that went into the [[hcard|hCard microformat]].

Most of the details of hCard were very deliberately designed based on principles. By capturing some of those principles and methodological techniques, hopefully future microformats can benefit by reusing some of this methodology.

;Author:[[User:Tantek|Tantek Çelik]]

== Semantic XHTML Design Principles ==

The [[semantic-xhtml-design-principles]] were largely created and captured as a result of explicit design decisions for how to best re-use [[vCard|vCard RFC2426]] terminology in the context of [[semantic XHTML]].

In particular:

* Reuse the schema (names, objects, properties, values, types, hierarchies, constraints) as much as possible from pre-existing, established, well-supported standards by reference. Avoid restating constraints expressed in the source standard. Informative mentions are ok.

For hCard, the pre-existing, established, well-supported standard re-used was/is vCard.

* Use class names based on names from the original schema, unless the [[semantic-xhtml|semantic XHTML]] building block precisely represents that part of the original schema. If names in the source schema are case-insensitive, then use an all lowercase equivalent. Components names implicit in prose (rather than explicit in the defined schema) should also use lowercase equivalents for ease of use. Spaces in component names become dash '-' characters.

vCard uses case-insensitive identifiers, but by convention most vCards have, and [[vcard-implementations|vCard implementations]] produce, all UPPERCASE identifiers, e.g. VCARD, N, FN etc. Since the HTML4 'class' attribute is case-sensitive, for microformats I had to pick a specific case to use for property names. I decided to explicitly follow the precedent and example set by XHTML from HTML4 of using the lowercase version of element names from HTML4 which itself similar to vCard had case-insensitive element names (due to its use of SGML) and by convention used all UPPERCASE element names in documentation.

Thus where HTML4 to XHTML looked like this:
* <code><HTML></code> became <code><html></code>
* <code><HEAD></code> became <code><head></code>
* <code><BODY></code> became <code><body></code>
* ... etc.

vCard to hCard looked like this:
* <code>BEGIN:VCARD</code> became <code>class="vcard"</code>
* <code>N:</code> became <code>class="n"</code>
* <code>FN:</code> becamse <code>class="fn"</code>
* ... etc.

* For types with multiple components, use nested elements with class names equivalent to the names of the components.

In the [[vCard]] specification, properties are referred to has "types", and thus the above principle invokes that same language to refer to such "types", specifically those that have some structure to them, with a set of values that relate specific semantics.

The primary example of this in hCard are the "n" and "adr" properties, each of which have sub-properties (e.g. "given-name", "family-name", etc. for "n", "street-address", "locality", etc. for "adr").

* Plural components are made singular, and thus multiple nested elements are used to represent multiple text values that are comma-delimited.

There are several properties in vCard that are either plural (e.g. CATEGORIES) or are simply defined to take multiple values (e.g. NICKNAME), or are sub-properties that are plural (e.g. additional names). As one of few exceptions to the "reuse names exactly" aka "don't change the names" design [[principle]], plural names of properties or sub-properties are explicitly changed to their singular equivalents, e.g.:
* CATEGORIES became "category"
* NICKNAME became "nickname"
* "additional names" became "additional-name"
And in all cases of such plural or multi-valued properties, the hCard specification permits multiple instances of the singular form which are then combined as appropriate to the equivalent property when transforming to vCard.

* Finally, if the format of the data according to the original schema is too long and/or not human-friendly, use <code><abbr></code> instead of a generic structural element, and place the literal data into the 'title' attribute (where abbr expansions go), and the more brief and human-readable equivalent into the element itself. Further informative explanation of this use of <code><abbr></code>: [[abbr-design-pattern]], [http://tantek.com/log/2005/01.html#d26t0100 Human vs. ISO8601 dates problem solved], and [http://www.webstandards.org/2007/04/27/haccessibility/ hAccessibility] aka "abbr-design-pattern considered harmful."

Motivated originally by the development of [[hcalendar|hCalendar]] which itself is based on [[icalendar|iCalendar RFC2445]], which needed a way to capture and represent datetimes, this technique is similarly used in several instances in hCard, e.g.
* the "bday" property, e.g.:
** <code><abbr class="bday" title="2005-06-20">June 20th</abbr></code>
* the "region" sub-property, e.g.:
** <code><abbr class="region" title="California">CA</abbr></code>
* the "country-name" sub-property, e.g.:
** <code><abbr class="country-name" title="United States of America">USA</abbr></code>

== see also ==
* [[hCard]]
* [[semantic XHTML]]
* [[semantic-xhtml-design-principles]]
* [[POSH]]
* [[process]]
* [[principles]]