hNews popup widget
==================

Written by Ben Campbell at the Media Standards Trust
June 2010

Source code at:
http://github.com/bcampbell/hnews_popup

Uses Dan Webb's Sumo microformat parser

Overview
--------

hnews_popup is a jquery plugin to provide a little popup box for pages
containing hNews markup. hNews is a draft microformat for marking up news
articles (or blogs), and is defined at http://microformats.org/wiki/hnews.

The general idea is that you'd have some little "hNews" badge on the page
(eg a little hNews logo image) and when the user hovers over it a box will
popup which summarises the hNews data present in the article).

Basic usage
-----------

By example:

    <link rel="stylesheet" type="text/css" href="hnews_popup.css" />
    <script type="text/javascript" src="jquery.hnews-popup-min.js" ></script>
    <script type="text/javascript">
      $(document).ready(function() {
      $('.hnews-icon').hnews_popup();
    });
    </script>

And somewhere in the article, you'd have:

  <img class="hnews-icon" alt="this article has hNews" src="hnews_icon.png"/>


Files
-----

The plugin (all packed up and minified):
 jquery.hnews-popup-min.js

An hnews icon
 hnews_icon.png

Default styling for the popup:
 hnews-popup.css
 hnews_popup_bg.gif


Options
-------

Like most jquery plugins, hnews_popup() can take an "options" parameter.
For most cases the default settings should be find, so you can omit the
options parameter altogether.

The available options are:

head_fn
  a function which returns a string of html to use to generate the
  head part of the popup box.

foot_fn
  a function which returns html for the foot of the box

row_fn
  a function to generate html to display one 'thing' of the hNews data
  (where a 'thing' might be a title, an author, a license... whatever)
  The function is passed parameters (label,content), where 'label' is
  a human-readable label of the hNews field to display, and 'content'
  is the value of the display. Both might be little html snippets.

fmt_hcard, fmt_link, fmt_date, fmt_geo
  all are functions to generate html fragments for individual bits of
  data. The defaults are simple and pretty bland. Override for fanciness.


Styling
-------

The default styling is determined by "hnews_popup.css" and by the
"head_fn", "row_fn" and "foot_fn" options passed into hnews_popup().

The default functions display the hNews data using a table. But this
not hard coded, so you can use whatever html you like.

If you want to customise the look and feel, probably the best thing is
to examine the default versions of the options in hnews_popup.js and
the styles in hnews_popup.css, then build your own replacements.


Issues
------

- the default styling could do with a little love...
- is the reliance on jquery an issue? Do we need a non-jquery version?
- add itchanged.org support back in - uses an API on itchanged.org to
  parse the hNews, and implicitly advertise that the story is
  hNews-enabled.

Examples
--------

The demo/ directory holds some examples:
- a couple of very basic mockup articles
- an example of multiple articles on a single page
- an example of the popup added to a real blog post