Visualisations and other utils that use data from OpenSpending to help people understand where and how money is being spent.
Just drop the most recent file in dist/ into your website (via a script tag) and start using the visualisations. You can read more about configurations for the different visualisations in src/README.md
We are currently in a migration stage in order to make contributions easier and more consistent, so the code base might be a little confusing. The best place to add your visualisation is src/. We're in the process of moving all of our visualisations and utils into that folder (to make the build process cleaner and simpler).
External libraries (requirements) are placed in lib/vendor/. There are a lot of files there at the moment. Some of those files are old versions of these libraries. We're in the process of cleaning these files up, removing unused files.
There are some conventions regarding the javascript files in the src directory to keep them consistent.
All of the visualisations should be constructed as jQuery plugins which make them really easy to use. jQuery is already used on a lot of sites (OpenSpending included), so this really makes it simple to use openspendingjs on many sites.
If you want them to be usable as plugins for other javascript frameworks (or as a standalone library), don't be afraid to contribute to openspendingjs.
Sometimes comments can be in the way but rarely they don't. Try to comment your code as much as possible. Sherlock-commenting (where code reader goes: "No shit, Sherlock!") is better than no commenting at all.
Openspendingjs is not only a usable library but it can also help new developers become more proficient in development, and encourages them to contribute to openspendingjs!
Openspendingjs is licensed under the Apache License, version 2.0. Each source file should include the Apache license notice. We recommend you assign the copyright to the Open Knowledge Foundation in the notice. The Open Knowledge Foundation will take utmost care to enforce the license conditions. Please help us track violation to the license.
We try to keep a list of contributors to openspendingjs in CONTRIBUTORS. It is extremely important that you get credit for your work even if the Open Knowledge Foundation is the custodian of the copyright as per the license. We value all contributions (so the list of contributors is in alphabetical order).
Openspendingjs doesn't use any module loaders or other means of managing requirements but listing them in a comment helps maintainers who want to upgrade libraries to find affected files (we don't have a good test framework in place at the moment so upgrading libraries should be done with care).
To make the clean up process simpler, when you add external libraries to the build process, list the individual files in the build file (Gruntfile.js). This also shows developers what will already be concatenated into the openspendingjs distribution file (since our lib/vendor directory might be slightly confusing).
To build openspendingjs we use Grunt version >= 0.4 which requires Node.js version >= 0.8. The build process is simple:
grunt
If you want to see the different sizes of the files you can use the report option:
grunt --report
This compiles all source files and their requirements (yes we add all libraries, watch out for conflicts) into two files in dist/:
- /openspending.js (where version is openspendingjs version number)
- /openspending.min.js (minified version of the above file)
The version number in package.json should of course be update for new releases.
The build process does the same for all css stylesheets (creates openspending.css and openspending.min.css) and copies all svg files into a subfolder of called icons.
The files are placed in a build folder.
To build a release you can runt:
grunt release
This cleans (removes) the build folder after creating both a tgz and a zip file for the version containing the built files.
If you want to run the tests use karma with grunt:
grunt karma
When developing it's good to set up virtual environments to manage dependencies instead of installing them into your system (and therefore possibly breaking other projects you're working on).
One way to create a virtual environment for Node.js is to use nodeenv. It can be installed in a python environment (using python's virtualenv).