Difference between revisions of "h-adr"

From Microformats Wiki
Jump to navigation Jump to search
(dumped h-item spec)
m (Replace <entry-title> with {{DISPLAYTITLE:}})
 
(31 intermediate revisions by 5 users not shown)
Line 1: Line 1:
<entry-title>h-item</entry-title>
+
{{DISPLAYTITLE:h-adr}}
 
<span class="h-card vcard"><span class="p-name fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="p-role role">Editor</span>)</span>
 
<span class="h-card vcard"><span class="p-name fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="p-role role">Editor</span>)</span>
 
----
 
----
<dfn style="font-style:normal;font-weight:bold">h-item</dfn> is a simple, open format for publishing details about arbitrary items on the web. h-item is one of several open [[microformats|microformat]] draft standards suitable for embedding data in HTML/HTML5.
+
<dfn style="font-style:normal;font-weight:bold">h-adr</dfn> is a simple, open format for publishing structured locations such as addresses, physical and/or postal. h-adr is one of several open [[microformats|microformat]] draft standards suitable for embedding data in HTML.
  
In practise, h-item is almost never used on it’s own, but rather as the '''p-item''' in a [[h-review]] as a generic fallback if the item being reviewed cannot be accurately represented by either an [[h-card]], [[h-product]], [[h-event]], [[h-adr]] or [[h-geo]].
+
h-adr is the [[microformats-2]] update to [[adr]]. It is most commonly used as part of an [[h-card]] or [[h-event]].
 +
 
 +
For named addresses, e.g. people or venues, use [[h-card]].
 +
 
 +
{{cc0-owfa-license}}
  
 
== Example ==
 
== Example ==
 +
Here is a simple postal address example:
 +
 +
<source lang=html4strict>
 +
<p class="h-adr">
 +
  <span class="p-street-address">17 Austerstræti</span>
 +
  <span class="p-locality">Reykjavík</span>
 +
  <span class="p-country-name">Iceland</span>
 +
  <span class="p-postal-code">107</span>
 +
</p>
 +
</source>
  
As the only properties defined by h-item are '''p-name''', '''u-url''' and '''u-photo''', in practise only the root classname is ever actually required (thanks to [[microformats-2-implied-properties]]) unless perhaps you have some unusual markup structure.
+
Parsed JSON:
  
<source lang=html4strict>
+
<source lang=javascript>
<a class="h-item" href="http://example.org/items/1">
+
{
  <img src="http://example.org/items/1/photo.png" alt="" />
+
  "items": [
   The Item Name
+
    {
</a>
+
      "type": [
 +
        "h-adr"
 +
      ],
 +
      "properties": {
 +
        "street-address": [
 +
          "17 Austerstræti"
 +
        ],
 +
        "locality": [
 +
          "Reykjavík"
 +
        ],
 +
        "country-name": [
 +
          "Iceland"
 +
        ],
 +
        "postal-code": [
 +
          "107"
 +
        ],
 +
        "name": [
 +
          "17 Austerstræti Reykjavík Iceland 107"
 +
        ]
 +
      }
 +
    }
 +
   ]
 +
}
 
</source>
 
</source>
 +
 +
The implicit "name" property that is generated from parsing an h-adr is there for consuming applications to have a simple flattened string representation of an h-adr.
 +
 +
For an explicitly named address (such as a mailing address to a specific person), use [[h-card]].
 +
 +
=== Get started ===
 +
The class '''<code>h-adr</code>''' is a ''root class name'' that indicates the presence of an h-adr.
 +
 +
'''p-street-address''', '''p-locality''', '''p-country-name''', '''p-postal-code''' and all the other h-adr property class names listed below define properties of the h-adr.
 +
 +
See [[microformats-2-parsing]] to learn more about property class names.
  
 
== Properties ==
 
== Properties ==
 +
h-adr properties, inside an element with class '''h-adr''':
 +
* '''<code>p-street-address</code>''' - house/apartment number, floor, street name
 +
* '''<code>p-extended-address</code>''' - additional street details
 +
* '''<code>p-post-office-box</code>''' - post office mailbox
 +
* '''<code>p-locality</code>''' - city/town/village
 +
* '''<code>p-region</code>''' - state/county/province
 +
* '''<code>p-postal-code</code>''' - postal code, e.g. ZIP in the US
 +
* '''<code>p-country-name</code>''' - should be full name of country, country code ok
 +
* '''<code>p-label</code>''' - a mailing label, plain text, perhaps with preformatting
 +
* '''<code>p-geo</code>''' (or u-geo with a RFC 5870 geo: URL), optionally embedded [[h-geo]]
 +
* '''<code>p-latitude</code>''' - decimal latitude
 +
* '''<code>p-longitude</code>''' - decimal longitude
 +
* '''<code>p-altitude</code>''' - decimal altitude - new in vCard4 (RFC6350)
 +
 +
All properties are optional.
  
* '''<code>p-name</code>''' - item name
+
* '''<code>p-name</code>''' - there is no "p-name" property in h-adr. If your address has an explicit name, it's likely a venue, and you should use [[h-card]] instead.
* '''<code>u-url</code>''' - permalink URL
 
* '''<code>u-photo</code>''' - photo URL
 
  
 
== Status ==
 
== Status ==
 +
'''h-adr''' is a microformats.org draft specification. Public discussion on h-adr takes place on [[h-adr-feedback]] and the #microformats [[irc]] channel on irc.freenode.net.
  
'''h-item''' is a microformats.org draft specification. Public discussion on h-item takes place on [[h-item-feedback]], the #microformats [[irc]] channel on irc.freenode.net, and [http://microformats.org/discuss/mail/microformats-new/ microformats-new mailing list].
+
h-adr is ready to use and implemented in the wild, but for backwards compatibility you should also mark h-adrs up with classic [[adr]] classnames.
  
 
== Property Details ==
 
== Property Details ==
 
 
(stub, add any property explanations here)
 
(stub, add any property explanations here)
  
 
== Examples in the Wild ==
 
== Examples in the Wild ==
 +
* … add any h-adr examples you find in the wild
 +
 +
== Validating ==
 +
{{h-spec-section-validating}}
 +
 +
== Backward Compatibility ==
 +
=== Publisher Compatibility ===
 +
For backward compatibility, you may wish to use classic [[adr]] classnames in addition to the more future-proof h-adr properties, for example:
 +
 +
<source lang=html4strict>
 +
<p class="h-adr adr">
 +
  <span class="p-street-address street-address">123 Main St.</span>,
 +
  <span class="p-locality locality">Pleasantville</span>
 +
  ...
 +
</p>
 +
</source>
 +
 +
The class '''<code>adr</code>''' is a ''backward compatible root class name'' that indicates the presence of an [[adr]].
 +
 +
'''street-address''', '''locality''', and all the other backward compatibility adr property class names are listed below.
 +
 +
=== Parser Compatibility ===
 +
Microformats parsers should detect classic properties only if a classic root class name is found and parse them as microformats2 properties.
 +
 +
If an "h-adr" is found, don't look for an "adr" on the same element.
 +
 +
Compatibility root class name: adr
 +
 +
Properties: (parsed as p- plain text unless otherwise specified)
 +
 +
* post-office-box
 +
* extended-address
 +
* street-address
 +
* locality
 +
* region
 +
* postal-code
 +
* country-name
 +
 +
== FAQ ==
 +
=== What about country codes ===
 +
Q: When marking up an address, can p-country-name be used to markup two letter country codes like "UK"? Or others like 3 letter Olympic country codes?
 +
 +
A: In short yes. You can do:
 +
<source lang=html4strict>
 +
<span class="p-country-name">UK</span>
 +
</source>
 +
However it's better if you mark it up with the <code>abbr</code> element and provide the full name as well, e.g.
 +
<source lang=html4strict>
 +
<abbr class="p-country-name" title="United Kingdom">UK</abbr>
 +
</source>
  
* … add any h-item examples you find in the wild
+
Consuming applications may interpret any 2-3 character country-name per the table of 2-3 character [http://en.wikipedia.org/wiki/ISO_3166-1#Officially_assigned_code_elements country codes in ISO3166].
  
 
== Background ==
 
== Background ==
 
+
h-adr is based on the existing [[adr]] specification, which was extracted from [[hCard]] in order to allow it to be used for applications other than contact information.
h-item was extracted from the classic [[hReview]] microformat as a way of referring to arbitrary reviewed items which cannot be represented by other microformats but which required a “shell” microformat due to the flat property requirement of microformats 2.
 
  
 
== See Also ==
 
== See Also ==
 +
* [[microformats2]]
 +
* [[h-geo]] can be embedded in h-adr
 +
* [[h-card]] and [[h-event]] often contain h-adr
 +
* [[vcard]] (most recently vCard4 RFC6350) vocabulary is re-used by h-adr.
 +
* [[address-formats]]
  
* [[microformats-2]]
+
[[Category:Draft Specifications]]
* [[h-review]]
 

Latest revision as of 16:23, 18 July 2020

Tantek Çelik (Editor)


h-adr is a simple, open format for publishing structured locations such as addresses, physical and/or postal. h-adr is one of several open microformat draft standards suitable for embedding data in HTML.

h-adr is the microformats2 update to adr. It is most commonly used as part of an h-card or h-event.

For named addresses, e.g. people or venues, use h-card.

Per CC0, to the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work. In addition, as of 2021-05-08, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0.

Example

Here is a simple postal address example:

<p class="h-adr">
  <span class="p-street-address">17 Austerstræti</span>
  <span class="p-locality">Reykjavík</span>
  <span class="p-country-name">Iceland</span>
  <span class="p-postal-code">107</span>
</p>

Parsed JSON:

{
  "items": [
    {
      "type": [
        "h-adr"
      ],
      "properties": {
        "street-address": [
          "17 Austerstræti"
        ],
        "locality": [
          "Reykjavík"
        ],
        "country-name": [
          "Iceland"
        ],
        "postal-code": [
          "107"
        ],
        "name": [
          "17 Austerstræti Reykjavík Iceland 107"
        ]
      }
    }
  ]
}

The implicit "name" property that is generated from parsing an h-adr is there for consuming applications to have a simple flattened string representation of an h-adr.

For an explicitly named address (such as a mailing address to a specific person), use h-card.

Get started

The class h-adr is a root class name that indicates the presence of an h-adr.

p-street-address, p-locality, p-country-name, p-postal-code and all the other h-adr property class names listed below define properties of the h-adr.

See microformats2 parsing specification to learn more about property class names.

Properties

h-adr properties, inside an element with class h-adr:

  • p-street-address - house/apartment number, floor, street name
  • p-extended-address - additional street details
  • p-post-office-box - post office mailbox
  • p-locality - city/town/village
  • p-region - state/county/province
  • p-postal-code - postal code, e.g. ZIP in the US
  • p-country-name - should be full name of country, country code ok
  • p-label - a mailing label, plain text, perhaps with preformatting
  • p-geo (or u-geo with a RFC 5870 geo: URL), optionally embedded h-geo
  • p-latitude - decimal latitude
  • p-longitude - decimal longitude
  • p-altitude - decimal altitude - new in vCard4 (RFC6350)

All properties are optional.

  • p-name - there is no "p-name" property in h-adr. If your address has an explicit name, it's likely a venue, and you should use h-card instead.

Status

h-adr is a microformats.org draft specification. Public discussion on h-adr takes place on h-adr-feedback and the #microformats #microformats on freenode channel on irc.freenode.net.

h-adr is ready to use and implemented in the wild, but for backwards compatibility you should also mark h-adrs up with classic adr classnames.

Property Details

(stub, add any property explanations here)

Examples in the Wild

  • … add any h-adr examples you find in the wild

Validating

Main article: microformats validators

Test and validate microformats2 markup in general with:

Backward Compatibility

Publisher Compatibility

For backward compatibility, you may wish to use classic adr classnames in addition to the more future-proof h-adr properties, for example:

<p class="h-adr adr">
  <span class="p-street-address street-address">123 Main St.</span>, 
  <span class="p-locality locality">Pleasantville</span>
  ...
</p>

The class adr is a backward compatible root class name that indicates the presence of an adr.

street-address, locality, and all the other backward compatibility adr property class names are listed below.

Parser Compatibility

Microformats parsers should detect classic properties only if a classic root class name is found and parse them as microformats2 properties.

If an "h-adr" is found, don't look for an "adr" on the same element.

Compatibility root class name: adr

Properties: (parsed as p- plain text unless otherwise specified)

  • post-office-box
  • extended-address
  • street-address
  • locality
  • region
  • postal-code
  • country-name

FAQ

What about country codes

Q: When marking up an address, can p-country-name be used to markup two letter country codes like "UK"? Or others like 3 letter Olympic country codes?

A: In short yes. You can do:

<span class="p-country-name">UK</span>

However it's better if you mark it up with the abbr element and provide the full name as well, e.g.

<abbr class="p-country-name" title="United Kingdom">UK</abbr>

Consuming applications may interpret any 2-3 character country-name per the table of 2-3 character country codes in ISO3166.

Background

h-adr is based on the existing adr specification, which was extracted from hCard 1.0 in order to allow it to be used for applications other than contact information.

See Also