The rails abstraction layer gem provides a series of common abstractions that are typically used when creating rails models that store carbon data in AMEE. This is an opinionated gem and whilst it will suit a lot of projects well it will not be right for every project. In those cases use the lower level amee-ruby gem (github.com/floppy/amee-ruby).

Installation

Command line installation:

sudo gem install amee_rails_layer

Configuration

For models that store carbon data in AMEE, several additional fields required in the database. Normally these would be:

* name (string) - a name for the object, often set by user but can be assigned automatically
* amee_profile_item_id (string) - the AMEE profile Item ID used to store the carbon data
* carbon_output_cache (float) - the amount of carbon produced
* units (string) - the units the amount field is in
* amount (float) - the amount of the thing being recorded, eg 6 (kg), 9 (litres)

with either:

* amee_profile (string) - the AMEE profile identifier under which all data is stored [optional]

Extra fields may also be required depending on the options used. See AmeeCarbonStore for full details

Usage

All data in AMEE is stored under a profile and there are two ways to encapsulate this knowledge in your application:

1) Models belong_to another object that has the amee_profile. Exactly what this parent will be called will depend on the application, but common examples will be Project or User. In this case it is up to the developer to add the has_amee_profile declaration to this class.

2) Each model has its own profile. The has_amee_profile declaration is handled automatically.

The best way to determine which approach to take is to read the AMEE documentation (link at end of README) and see which unit in the application logically maps to an AMEE profile. In either case the model will require an amee_profile field to store the profile identifier.

The models that are to store carbon data in AMEE need the has_carbon_data_stored_in_amee declaration with any appropriate options and must implement the amee_category method. For this, there are two main options:

1) If the model is always the same type just return a AmeeCategory with relevant options for where the data should be stored in AMEE

2) If the model has multiple types, for example a Journey that can be a Car, Bus Journey etc, a pattern like the following can be used:

class Journey < ActiveRecord::Base
  TYPE = {
    :bus => AmeeCategory.new("Bus", :journey_distance, "/transport/bus/generic/defra", :type => "typical"),
    :car => AmeeCategory.new("Car", :distance, "/transport/car/generic/defra/bysize", :fuel => "average", :size => "average"),
    ...
  }

  def amee_category
    TYPE[journey_type.to_sym]
  end
end

Note the need for a column called journey_type in the database to store the type of the Journey.

The database caches the carbon value returned by AMEE to keep the local application fast when displaying this data. As a result of this a cronjob should be run at a regular interval to update the carbon value. This is because AMEE alters the underlying calculations as more accurate data and formulas becomes available. See AmeeCarbonStore#update_carbon_caches for more details.

Further information on AMEE can be found at: my.amee.com/developers

Note on Patches/Pull Requests

  • Fork the project.

  • Make your feature addition or bug fix.

  • Add tests for it. This is important so I don’t break it in a future version unintentionally.

  • Commit, do not mess with rakefile, version, or history (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

  • Send me a pull request. Bonus points for topic branches.

TODO

  • Integrate rails.rb from amee-ruby In AmeeCarbonStore has_amee_profile call can be removed from the has_carbon_data_stored_in_amee method and connection_to_amee can be named back to the more logically amee_connection

  • Full test coverage

Copyright © 2010 AMEE UK ltd. See LICENSE for details.