third_party/webtreemap/src/README.markdown

   1 # webtreemap
   2
   3 A simple treemap implementation using web technologies (DOM nodes, CSS
   4 styling and transitions) rather than a big canvas/svg/plugin.
   5
   6 Play with a [demo][].
   7
   8 [demo]: http://martine.github.com/webtreemap/demo/demo.html
   9
  10 ## Creating your own
  11
  12 1. Create a page with a DOM node (i.e. a `<div>`) that will contain
  13    your treemap.
  14 2. Add the treemap to the node via something like
  15
  16         appendTreemap(document.getElementById('mynode'), mydata);
  17 3. Style the treemap using CSS.
  18
  19 ### Input format
  20
  21 The input data (`mydata` in the overview snippet) is a tree of nodes,
  22 likely imported via a separate JSON file.  Each node (including the
  23 root) should contain data in the following format.
  24
  25     {
  26       name: (HTML that is displayed via .innerHTML on the caption),
  27       data: {
  28         "$area": (a number, in arbitrary units)
  29       },
  30       children: (list of child tree nodes)
  31     }
  32
  33 (This strange format for data comes from the the [JavaScript InfoVis
  34 Toolkit][thejit].  I might change it in the future.)
  35
  36 The `$area` of a node should be the sum of the `$area` of all of its
  37 `children`.
  38
  39 (At runtime, tree nodes will dynamically will gain two extra
  40 attributes, `parent` and `dom`; this is only worth pointing out so
  41 that you don't accidentally conflict with them.)
  42
  43 ### CSS styling
  44
  45 The treemap is constructed with one `div` per region with a separate
  46 `div` for the caption.  Each div is styleable via the
  47 `webtreemap-node` CSS class.  The captions are stylable as
  48 `webtreemap-caption`.
  49
  50 Each level of the tree also gets a per-level CSS class,
  51 `webtreemap-level0` through `webtreemap-level4`.  These can be
  52 adjusted to e.g. made different levels different colors.  To control
  53 the caption on a per-level basis, use a CSS selector like
  54 `.webtreemap-level2 > .webtreemap-caption`.
  55
  56 Your best bet is to modify the included `webtreemap.css`, which
  57 contains comments about required and optional CSS attributes.
  58
  59 ## Related projects
  60
  61 * [JavaScript InfoVis Toolkit][thejit]
  62
  63 [thejit]: http://thejit.org/