Django Microformat Application (alpha)

(c) 2009 Nicholas H.Tollervey and others

See the file AUTHORS.txt and LICENSE.txt for the licensing terms and conditions.

Description

This Django application makes it easier to integrate and use Microformats in your web-application.

Microformats (http://microformats.org/) are a means of adding semantic information that is both human and machine readable to a web-site. In order to work with Microformats you need to use a toolkit such as Oomph (included as a javascript plugin with the unit tests - see http://visitmix.com/Lab/oomph) or the Operator Add-on for Firefox (that supports more types of microformat) - see https://addons.mozilla.org/en-US/firefox/addon/4106.

This application attempts to help in two ways:

1. You get models: so you can store data relating to the supported microformats (you don't have to use these models - see below for more information)

2. You get markup: there are some example templates for the supported microformats in the /microformats/templates directory and I've written some template filters that wrap around these templates so you get a convenient shortcut.

Currently the supported microformats are:

• hCard - for representing people or organizations
• geo - for representing a geolocation
• adr - for representing an address
• hCalendar - for representing an event
• hListing - for representing an advertisement
• hReview - for representing an opinion
• XFN - for representing friends and relationships
• hAtom - for syndicated content
• hNews - for online journalism

In the code, you get the following:

• Models relating to the geo, hCard, adr, hCalendar, hListing, hReview, hAtom and XFN microformats (models.py). hCard has two models:

  1. hCard - a "flat" model containing only the most common fields

  2. hCardComplete - a full implementation of the vCard specification (and related tables)

• Simplified forms for the geo, hCard, adr, org, email, tel and hCalendar, hListing, hReview, hFeed, hEntry and hNews microformats and fragments (forms.py).

• Some useful admin functionality (admin.py).

• Template filters for the geo, hCard, adr, hCalendar, hListing, hReview and XFN microformats (templatetags/microformat_extras.py).

• Some example templates for rendering the microformats (templates/*.html)

A Note About Versions

The structure of this branch (poswald/microformats) is substantially different than the original project (ntoll/microformats). Please be careful when updating.

Changes to the database or API will be reflected in an incrementing minor number:

microformats-0.X.0

Relatively small changes will be reflected in the micro number:

microformats-0.0.X

The current code release number will be pulled from tags on the git repo or in packaged versions will be determined by a RELEASE-VERSION file. Please do not check in the RELEASE-VERSION file.

Installation

Use pip to install the application. You can install directly from a github repo:

$ pip install -e git+git://github.com/poswald/microformats.git#egg=microformats

Once installed, you can check the version:

$ pip freeze | grep microformats
-e git+git@github.com:poswald/microformats.git@caeba...#egg=microformats-0.0.2-py2.6-dev

You can see it is pointing to a particular commit in github. If you want to do development work on this project in particular, you can install a git project from the local filesystem instead:

$ cd Projects/microformats
$ pip install -e .

Add the microformats project into your settings.py:

INSTALLED_APPS = (
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.sites',
'django.contrib.admin',
'django.contrib.admindocs',
...
'microformats',
...)

And now, simply run syncdb:

$ ./manage.py syncdb
Syncing...
Creating table microformats_hcard
Creating table microformats_hcalendar_organizers
Creating table microformats_hcalendar_contacts
...

You should now be ready to go.

Usage

To use the template filters you need to add:

{% load microformat_extras %}

to the top of the template you're using in your application.

If you have an instance of a microformat model in your context you can use the appropriate template filter to display it:

{{ hCardInstance|hcard }}

will result in:

<div id="hcard_1" class="vcard">
    <div class="fn n">
        <a href="http://acme.com/" class="url">
            <span class="honorific-prefix">Mr</span>
            <span class="given-name">Joe</span>
            <span class="additional-name">Arthur</span>
            <span class="family-name">Blogs</span>
            <span class="honorific-suffix">PhD</span>
        </a>
    </div>
    <span class="title">Vice President</span>
    <div class="org">Acme Corp.</div>
    <a class="email" href="mailto:joe.blogs@acme.com">joe.blogs@acme.com</a> [work]<br/>
    <a class="email" href="mailto:joeblogs2000@home-isp.com">joeblogs2000@home-isp.com</a> [home]<br/>
    <div class="adr">
    <div class="street-address">5445 N.  27th Street</div>
        <span class="locality">Milwaukee</span>&nbsp;
        <span class="region">WI</span>&nbsp;
        <span class="postal-code">53209</span>&nbsp;
        <span class="country-name">United States</span>
    </div>
    <div class="tel"><span class="value">+44(0)1234 567890</span> [<abbr class="type" title="work">work</abbr>]</div>
    <div class="tel"><span class="value">+44(0)1324 234123</span> [<abbr class="type" title="home">home</abbr>]</div>
</div>

(This markup is based upon that produced by the hCard creator found at http://microformats.org/code/hcard/creator)

In addition you can pass individual fields thus:

{{hCardInstance.role|hcard:'role'}}

Which will result in the following markup:

<span class="role">Vice President</span>

(An example of the class-design-pattern: http://microformats.org/wiki/class-design-pattern)

The template filters are clever enough to deal with different "types" of field. For example, if you pass a datetime value like this:

{{ datetimeInstance|hcal:'dtstart' }}

You'll get this:

<abbr class="dtstart" title="2009-04-11T13:30:00">Sat 11 Apr 2009 1:30 p.m.</abbr>

(An example of the datetime-design-pattern: http://microformats.org/wiki/datetime-design-pattern)

You can even do this:

{{ datetimeInstance|hcal:'dtstart %B %d %Y" }}

To get this:

<abbr class="dtstart" title="1944-06-06T00:00:00">June 06 1944</abbr>

(Notice the passing of arguments for strftime.)

If you pass a valid email address or URI then the span element will be replaced with an anchor with the appropriate href attribute. For example, if you do something like this:

{{ hReview.url|hreview:'url' }}

You'll get this:

<a class="url" href="http://www.acme.com">http://www.acme.com</a>

You don't even have to pass instances of the microformat models for the template filters to work. The templates the filters wrap around simply assume the same field names as found in the microformat specifications (where '-' is replaced with the more Pythonic '_' so 'given-name' becomes 'given_name').

For example, you could create a dictionary thus:

hc = dict()
hc['honorific_prefix'] = 'Mr'
hc['given_name'] = 'Joe'
hc['additional_name'] = 'Arthur'
hc['family_name'] = 'Blogs'
hc['honorific_suffix'] = 'PhD'
hc['url'] = 'http://acme.com/'
hc['email_work'] = 'joe.blogs@acme.com'
hc['email_home'] = 'joe.blogs@home-isp.com'
hc['tel_work'] = '+44(0)1234 567876'
hc['tel_home'] = '+44(0)1543 234345'
hc['street_address'] = '5445 N.  27th Street'
hc['extended_address'] = ''
hc['locality'] = 'Milwaukee'
hc['region'] = 'WI'
hc['country_name'] = 'US'
hc['postal_code'] = '53209'
hc['title'] = 'Vice President'
hc['org'] = 'Acme Corp.'

And pass it to the 'hcard' template filter to get similar markup to that shown above.

Finally, you don't even have to use the supplied microformat templates for the filters. You can use your own by adding a reference to the appropriate template in the following constants in the settings.py file of your project:

GEO_MICROFORMAT_TEMPLATE
HCARD_MICROFORMAT_TEMPLATE
HCAL_MICROFORMAT_TEMPLATE
HLISTING_MICROFORMAT_TEMPLATE
HREVIEW_MICROFORMAT_TEMPLATE
ADR_MICROFORMAT_TEMPLATE
HFEED_MICROFORMAT_TEMPLATE
HENTRY_MICROFORMAT_TEMPLATE
HNEWS_MICROFROMAT_TEMPLATE

For more examples check out the end of the following test file:

microformats/tests/test_templatetags.py

and take a look at:

microformats/templates/test.html

Running the unit tests (./manage.py test microformats) will result in an example file demonstrating the HTML markup produced by the template filters:

microformats/tests/html_test/microformat_test.html

The Oomph javascript library has been included so you can play with the microformats.

Please see http://microformats.org/wiki/browsers for a list of browser extensions

Feedback is most welcome