[openspending-dev] OpenSpendingJS refactoring/clean-up

Fri May 31 14:00:26 UTC 2013

On mán 27.maí 2013 23:50, Tryggvi Björgvinsson wrote:
> * Can we make the project structure simpler/readable? (or at least
> document it?)
> * Will it break anything (external) if we refactor/clean-up openspendingjs?
> * Can we make it easy for visualisation creators to add visualisations
> to openspendingjs?

I've taken a stab at this and created a build process for openspendingjs
using Gruntjs (http://gruntjs.com). To make the build process clean I'm
working from a new directory structure (that sits besides the current
one). What I envision we will have in the end is something like many of
the open source / javascript libraries out there:

openspendingjs
    |
    |- dist/ (where build results go so we'll have versioning, examples
below)
    |     |- openspending-<version>.js (concatenated javascript files)
    |     |- openspending-<version>.min.js (minified javascript files)
    |     |- openspending-<version>.css (concatenated css files)
    |     `- openspending-<version>.min.css (minified css files)
    |
    |- lib/ (where we put external libraries, examples below)
    |    |- kartograph-<version>.js
    |    `- raphael-<version>.js
    |
    |- src/
    |     |
    |     |- utils (various openspendingjs utils, examples below)
    |     |     |- openspending.amounts.js (utils for dealing with amounts)
    |     |     |- openspending.colors.js (utils for managing colors)
    |     |     |- openspending.aggregator.js (API aggregator)
    |     |     `- README.md (information about the utils)
    |     |
    |     |- visualisations (where visualisation files go, examples below)
    |     |     |- jquery.choropleth.js (jquery plugin to create a
choropleth map)
    |     |     |- jquery.treemap.js (jquery plugin to create a treemap)
    |     |     `- README.md (information about the visualisations)
    |     |
    |     `- css (where stylesheets go, example below)
    |           `- treemap.css
    |
    |- package.json (information about the package)
    |- README.md (information about the project)
    |- CONTRIBUTORS (who has contributued)
    |- LICENSE (license for the project)
    `- Gruntfile.js (build configurations)

Like I said, I've taken a stab at this and created a branch with this
structure (without touching the other structure - I even still use
lib/vendor/ instead of lib). I deleted some things (like the flash
folder). Here's the branch on github if you want to take a look:
  https://github.com/openspending/openspendingjs/tree/build-process

There are some new things there like how the visualisations are managed.
I moved them into being jquery plugins. They don't have to be, we could
use our OpenSpending object, but I did this when I felt visualisations
shouldn't be a core part of OpenSpending (I felt the utils should be).
So I thought having them as jquery plugins might maybe result in more
visualisation contributions (in retrospect I think I should move them
back under OpenSpending so we'll be famous!). However it is cool that in
order to create a treemap on a site one can now either do:

    <div class="treemap" data-dataset="uppgjor-rikissjods"></div>

or:

    $(some selector).treemap({data:{dataset:'uppgjor-rikissjods'}})

Plus a bunch of other options (it just feels natural when you've worked
a lot with bootstrap). Of course you need to load the
openspending-<version>.min.js and openspending-<version>.min.css files.
This approach might make a plugin creation (e.g. for WordPress) a lot
simpler (drop in the js and the css files, make a simple parser with the
configurations to create a new div).

I'm really interested in hearing your opinions. I've probably made some
weird decisions here and there while trying to keep all of those balls
up in the air, but this is how I think the openspendingjs library could be.

I'm especially interested in hearing from visualisation experts out
there. Would this make contributing new and fresh visualisations easier?

-- 

Tryggvi Björgvinsson

Technical Lead, OpenSpending

The Open Knowledge Foundation <http://okfn.org>

/Empowering through Open Knowledge/

http://okfn.org/ | @okfn <http://twitter.com/OKFN> | OKF on Facebook
<https://facebook.com/OKFNetwork> | Blog <http://blog.okfn.org/> |
Newsletter <http://okfn.org/about/newsletter>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.okfn.org/pipermail/openspending-dev/attachments/20130531/45753e42/attachment.html>