HACKING

GETTING THE LATEST SOURCE CODE

The source code for this project is at:
http://github.com/decc/twenty-fifty

WHAT IS THIS WRITTEN IN

The code is written in:

1. Ruby, using the 'bundler' gem to sort out dependencies and the 'sinatra' framework for the server and the 'haml' framework for templates
2. Coffeescript, to create the javascript that the user sees
3. SCSS, to create the stylesheets that the user sees

OVERVIEW

The server is setup in config.ru. This:
1. Maps /assets to a set of code that will compile the javascripts in src/javascripts and the stylesheets in src/stylesheets. It is only used in 'development' mode.
2. Loads three sinatra modules, all of which are in the src/ directory:
  1. redirect_old_versions.rb - looks for urls that relate to previous versions of this code, and redirects them to new urls
  2. serve_model_data.rb - looks for urls that end in /data and then returns the relevant model data which is contained in the decc_2050_model gem
  3. serve_html.rb - if in 'production' mode this always returns public/default.html. In 'development' mode it compiles the haml template in src/default.html.haml

All of the underlying model calculations are in the decc_2050_model gem and not in this code.

The javascripts in src/javascripts contain almost all of the important code. Once a change has been made to this code, then please run:
    
    rake html

to make sure all those changes will appear in the production version of this code.


UPDATING THE UNDERLYING EXCEL MODEL

The calculating engine of this tool is contained in the decc_2050_model gem. Find out more about that at:
http://github.com/decc/decc_2050_model

Once done. The next step will be to change into this directory and in 

    Gemfile

update the version number of the decc_2050_model gem. Then:

    bundle update
    rake

UPDATING THE VIEWS

Most of the meaningful code is in the src/javascripts folder. Most of it is written in coffescript, a variant of javascript.

1. pathways.js.coffee - contains the code that loads the model data and ensures the correct view is displayed.
2. model_structure.js.erb - contains some javascript variables that are set based on the structure of the model, as detailed in the decc_2050_model gem
3. primary_energy.js.coffee describes the main view. Other views are also in the folder, one file per view. The relationship between view and url is set in window.twentyfifty.views at the bottom of each file.

Each view in a class with the same rough format:
1. setup() - is called when the webpage is ready for the chart to be drawn
2. teardown() - is called when the user has selected a different view. It should remove all html that has been added in setup.
3. updateResults(pathway) - is called when the data for a pathway has been received. It should update the results on the web page.

UPDATING THE EXAMPLE PATHWAYS

The example pathways are listed in:

    src/helper.rb

UPDATING THE ONE PAGE NOTES

The one page notes are separate pdf files in:

    public/assets/onepage

If the order of the controls is changed, or a new control is added, then the mapping in the underlying decc_2050_model code also needs to be changed:

  In this code:  

    http://github.com/decc/decc_2050_model

  Look in this file:

    lib/decc_2050_model/model_choice.rb

  And change the NUMBER_TO_DOC_MAP. The left hand number is a counter, based on the row number in the Excel Control worksheet. 0 is the first row of the controls (Nuclear power). The right hand number or text is the filename of the relevant one page note pdf in app/assets/images/onepage

REPORTING A BUG

Please report bugs using the tool at:
http://github.com/tamc/twenty-fifty/issues

SENDING A PATCH

Please fork the project and then push changes using the methodology described here:
http://help.github.com/forking/