README

This project is an attempt to process json data streams entirely on the client side
without requiring any client side processing.  This is most useful for rendering
listing of items (ex: story listings from newspapers, aggregators, etc.).

This project is an extension and generalization of work done with NewsTrust (http://newstrust.net).
The ideas in this project were first tested during the development of NewsTrust's widgets
which can be seen at: http://newstrust.net/widgets.  NewsTrust relies a lot on these
widgets on its own site as well as on a lot of partner sites.  Thanks to NewsTrust for
letting me use that code as the basis for this FOSS project.

* Read NOTES for the rough ideas that inform this project.

* jsWidget.ultracompressible.js is the uncompressed (but compressible) version of
  this widget engine.  This code is pushed through Yahoo's JS compressor and my own
  custom compresser to generate the compact jsWidget.js code as follows:

     java -jar PATH-TO-JAR/yuicompressor-2.3.5.jar jsWidget.ultracompressible.js | perl compress.js.pl > jsWidget.js

  This compression technique is just legacy and how I have done it in the past -- this
  can be stripped out to use any other compression techique.

* This is standalone javascript and does not depend on any other javascript library and
  as such can be embedded on any site easily.  It can be used on static HTML pages or within
  CMSes or pretty much anywhere you want to use it.

* Last I verified, this code used to work well on Firefox, IE, and Safari.  I haven't recently 
  tested this on IE or on other browsers.

* formats/* has sample format files for consuming data streams from different services
  (ex: Digg, Delicious, Twitter, NewsTrust, NewsRack) and rendering HTML.

* jsw.demo.html gives you examples of how to use the widget formats and the engine to process
  a json data stream.  As is clear, you can embed multiple widgets on the same page without
  them interfering with each other.

Sites currently using this widget engine:
-----------------------------------------
* http://esgindia.org
* http://hindi.indiawaterportal.org/content/%E0%A4%B8%E0%A4%AE%E0%A4%BE%E0%A4%9A%E0%A4%BE%E0%A4%B0
* http://bangalore.citizenmatters.in/citynews
* http://pinkslipmedia.org/

Some preliminary notes for writing widget formats
-------------------------------------------------
I am yet to write up a spec for this format, but till such time, some preliminary notes here.

* You can provide css settings either via inline styles (which is what is commonly used on most of 
  the widget formats -- so as to tightly control the rendering without being impacted by the styles
  of the site on which this is embedded) or via css class names (which are expected to be present
  on the page within which the widget is embedded).

  digg.json is an example that uses css classes (and the css defns. for these classes are provided
  in jsw.demo.html).

* For each section of the widget (which is specified by an array -- self-explanatory when you look
  at some widget formats), you provide a base css style/class + the elements to be generated for
  the data object being processed by this section.  This spec (dom_nodes) is basically an array of hashes,
  where each element of the array (a hash of properties) specifies an individual DOM node.  It says
  what needs to be rendered, and how it needs to be rendered.  You can nest this arbitrarily using
  the 'dom_tree' node type (see formats/nt.json) for an example.
  
  - You can do conditional rendering of an item in this array via the if_true property. 
  - '$' provides you access to the data object that is currently being processed.  
  - '$util' provides you access to helpers defined within the javascript engine.  
  - This engine can be extended with say '$extern' to let you access arbitrary javascript code, if necessary.

* You can combine multiple distinct formats and consume multiple data streams within the same widget easily
  See formats/mashup.json for an example of this and jsw.demo.html for how it is used there.