plutus 0.5.2 → 0.7.0

data/README.markdown

@@ -1,10 +1,10 @@
 Plutus
 =================
+[![Build Status](https://secure.travis-ci.org/mbulat/plutus.png?branch=master)](http://travis-ci.org/mbulat/plutus)
 
-This plutus plugin is a Ruby on Rails Engine which provides a double entry accounting system for your application.
+The Plutus plugin is a Ruby on Rails Engine which provides a double entry accounting system for your application.
 
-NOTE: This version of Plutus is compatable with RAILS 3
-=======================================================
+### NOTE: This version of Plutus is compatible with RAILS 3.1
 
 For the rails 2 version, you can go here:
 
@@ -26,37 +26,46 @@ Overview
 
 The plutus plugin provides a complete double entry accounting system for use in any Ruby on Rails application. The plugin follows general [Double Entry Bookkeeping](http://en.wikipedia.org/wiki/Double-entry_bookkeeping_system) practices. All calculations are done using [BigDecimal](http://www.ensta.fr/~diam/ruby/online/ruby-doc-stdlib/libdoc/bigdecimal/rdoc/classes/BigDecimal.html) in order to prevent floating point rounding errors. The plugin requires a decimal type on your database as well.
 
-The system consists of a table that maintains your accounts and a table for recording transactions. Transactions are the recording of debits and credits to various accounts. The transaction table, which records your business transactions is, essentially, your accounting  [Journal](http://en.wikipedia.org/wiki/Journal_entry) 
+The system consists of tables that maintains your accounts, transactions and debits and credits. Each transaction can have many debits and credits. The transaction table, which records your business transactions is, essentially, your accounting  [Journal](http://en.wikipedia.org/wiki/Journal_entry).
 
-Posting to a [Ledger](http://en.wikipedia.org/wiki/General_ledger) can be considered to happen automatically, since Accounts have the reverse `has_many` relationship to either its credit or debit transactions 
+Posting to a [Ledger](http://en.wikipedia.org/wiki/General_ledger) can be considered to happen automatically, since Accounts have the reverse `has_many` relationship to either its credit or debit transactions.
 
 Accounts
 --------
 
-The Account class represents accounts in the system. The Account table uses single table inheritance to store information on each type of account (Asset, Liability, Equity, Revenue, Expense). Each account must be subclassed as one of the following types:
+The Account class represents accounts in the system. The Account table uses single table inheritance to store information on each type of account (Asset, Liability, Equity, Revenue, Expense). Each account must be sub-classed as one of the following types:
 
-	TYPE        | NORMAL BALANCE    | DESCRIPTION
-	--------------------------------------------------------------------------
-	Asset       | Debit             | Resources owned by the Business Entity
-	Liability   | Credit            | Debts owed to outsiders
-	Equity      | Credit            | Owners rights to the Assets
-	Revenue     | Credit            | Increases in owners equity
-	Expense     | Debit             | Assets or services consumed in the generation of revenue
+    TYPE        | NORMAL BALANCE    | DESCRIPTION
+    --------------------------------------------------------------------------
+    Asset       | Debit             | Resources owned by the Business Entity
+    Liability   | Credit            | Debts owed to outsiders
+    Equity      | Credit            | Owners rights to the Assets
+    Revenue     | Credit            | Increases in owners equity
+    Expense     | Debit             | Assets or services consumed in the generation of revenue
+
+Your Book of Accounts needs to be created prior to recording any transactions. The simplest method is to have a number of create methods in your db/seeds.rb file like so:
+
+    Plutus::Asset.create(:name => "Accounts Receivable")
+    Plutus::Asset.create(:name => "Cash")
+    Plutus::Revenue.create(:name => "Sales Revenue")
+    Plutus::Liability.create(:name => "Unearned Revenue")
+    Plutus::Liability.create(:name => "Sales Tax Payable")
+    etc...
+
+Then simply run `rake db:seed`
 
 Each account can also be marked as a "Contra Account". A contra account will have its normal balance swapped. For example, to remove equity, a "Drawing" account may be created as a contra equity account as follows:
 
-	Equity.create(:name => "Drawing", contra => true)
+    Plutus::Equity.create(:name => "Drawing", contra => true)
 
 At all times the balance of all accounts should conform to the [Accounting
 Equation](http://en.wikipedia.org/wiki/Accounting_equation)
 
-	Assets = Liabilties + Owner's Equity
+    Assets = Liabilities + Owner's Equity
 
 Every account object has a `has_many` association of credit and debit transactions, which means that each account object also acts as its own [Ledger](http://en.wikipedia.org/wiki/General_ledger), and exposes a method to calculate the balance of the account.  
 
-See the {Account} and {Transaction} classes for more information.
-
-
+See the {Plutus::Account}, {Plutus::Transaction}, and {Plutus::Amount} classes for more information.
 
 Examples
 ========
@@ -64,17 +73,47 @@ Examples
 Recording a Transaction
 -----------------------
 
-Let's assume we're accounting on an [Accrual basis](http://en.wikipedia.org/wiki/Accounting_methods). We've just taken a customer's order for some widgets, which we've also billed him for. At this point we've actually added a liability to the company until we deliver the goods. To record this transaction we'd need two accounts.
+Let's assume we're accounting on an [Accrual basis](http://en.wikipedia.org/wiki/Accounting_methods). We've just taken a customer's order for some widgets, which we've also billed him for. At this point we've actually added a liability to the company until we deliver the goods. To record this transaction we'd need two accounts:
+
+    >> Plutus::Asset.create(:name => "Cash")
+    >> Plutus::Liability.create(:name => "Unearned Revenue")
 
-	>> Liability.create(:name => "Unearned Revenue")
-	>> Asset.create(:name => "Cash")
+Next we'll build the transaction we want to record. Plutus provides a simple interface to build the transaction. 
 
-We'd then record the following transaction.
+    transaction = Plutus::Transaction.build(
+                    :description => "Order placed for widgets",
+                    :debits => [
+                      {:account => "Cash", :amount => 100.00}], 
+                    :credits => [
+                      {:account => "Unearned Revenue", :amount => 100.00}])
+
+The build method takes a hash consisting of a description, and an array of debits and credits. Each debit and credit item is a hash that specifies the amount, and the account to be debited or credited. Simply pass in the string name you used when you created the account. 
+
+Finally, save the transaction.
+
+    >> transaction.save
+
+If there are any issues with your credit and debit amounts, the save will fail and return false. You can inspect the errors via `transaction.errors`. Because we are doing double-entry accounting, your credit and debit amounts must always cancel out to keep the accounts in balance.
+
+Recording a Transaction with multiple accounts
+----------------------------------------------
 
-	>> Transaction.create(:description => "Order placed for widgets", 
-                        :credit_account => Liability.find_by_name("Unearned Revenue"),
-                        :debit_account => Asset.find_by_name("Cash"),
-                        :amount => 1000)
+Often times a single transaction requires more than one type of account. A classic example would be a transaction in which a tax is charged. We'll assume that we have not yet received payment for the order, so we'll need an "Accounts Receivable" Asset:
+
+    >> Plutus::Asset.create(:name => "Accounts Receivable")
+    >> Plutus::Revenue.create(:name => "Sales Revenue")
+    >> Plutus::Liability.create(:name => "Sales Tax Payable")
+
+And here's the transaction:
+
+    transaction = Plutus::Transaction.build(
+                    :description => "Sold some widgets",
+                    :debits => [
+                      {:account => "Accounts Receivable", :amount => 50}], 
+                    :credits => [
+                      {:account => "Sales Revenue", :amount => 45},
+                      {:account => "Sales Tax Payable", :amount => 5}])
+    transaction.save
                        
 Associating Documents
 ---------------------
@@ -83,19 +122,19 @@ Although Plutus does not provide a mechanism for generating invoices or orders,
 
 Suppose we pull up our latest invoice in order to generate a transaction for plutus (we'll assume you already have an Invoice model):
 
-	>> invoice = Invoice.last
+    >> invoice = Invoice.last
 
-We'll also assume that we have not yet received payment for the order, so we'll need an "Accounts Receivable" Asset:
+Let's assume we're using the same transaction from the last example
 
-	>> Asset.create(:name => "Accounts Receivable")
-
-Next, we'll go ahead and create a transaction for this invoice:
-
-	>> Transaction.create(:description => "Order placed for widgets", 
-                        :credit_account => Liability.find_by_name("Unearned Revenue"),
-                        :debit_account => Asset.find_by_name("Accounts Receivable"),
-                        :amount => invoice.amount,
-                        :commercial_document => invoice)
+    transaction = Plutus::Transaction.build(
+                    :description => "Sold some widgets",
+                    :commercial_document => invoice,
+                    :debits => [
+                      {:account => "Accounts Receivable", :amount => invoice.total_amount}], 
+                    :credits => [
+                      {:account => "Sales Revenue", :amount => invoice.sales_amount},
+                      {:account => "Sales Tax Payable", :amount => invoice.tax_amount}])
+    transaction.save
 
 The commercial document attribute on the transaction is a polymorphic association allowing you to associate any record from your models with a transaction (i.e. Bills, Invoices, Receipts, Returns, etc.)
 
@@ -104,9 +143,9 @@ Checking the Balance of an  Individual Account
   
 Each account can report on its own balance. This number should normally be positive. If the number is negative, you may have a problem.
 
-	>> cash = Asset.find_by_name("Cash")
-	>> cash.balance
-	=> #<BigDecimal:103259bb8,'0.2E4',4(12)>
+    >> cash = Plutus::Asset.find_by_name("Cash")
+    >> cash.balance
+    => #<BigDecimal:103259bb8,'0.2E4',4(12)>
 
     
 Checking the Balance of an Account Type
@@ -114,48 +153,53 @@ Checking the Balance of an Account Type
 
 Each subclass of accounts can report on the total balance of all the accounts of that type. This number should normally be positive. If the number is negative, you may have a problem.
 
-	>> Asset.balance
-	=> #<BigDecimal:103259bb8,'0.2E4',4(12)>    
+    >> Plutus::Asset.balance
+    => #<BigDecimal:103259bb8,'0.2E4',4(12)>    
     
 Calculating the Trial Balance
 -----------------------------
 
 The [Trial Balance](http://en.wikipedia.org/wiki/Trial_balance) for all accounts on the system can be found through the abstract Account class. This value should be 0 unless there is an error in the system.
 
-	>> Account.trial_balance
-	=> #<BigDecimal:1031c0d28,'0.0',4(12)>
+    >> Plutus::Account.trial_balance
+    => #<BigDecimal:1031c0d28,'0.0',4(12)>
 
 Contra Accounts and Complex Transactions
 ----------------------------------------
 
 For complex transaction, you should always ensure that you are balancing your accounts via the [Accounting Equation](http://en.wikipedia.org/wiki/Accounting_equation).
 
-	Assets = Liabilties + Owner's Equity
+    Assets = Liabilities + Owner's Equity
 
-For example, let's assume the owner of a business wants to withdraw cash. First we'll assume that we have an asset account for "Cash" which the funds will be drawn from. We'll then need an Equity account to record where the funds are going, however, in this case, we can't simply create a regular Equity account. The "Cash" account must be credited for the decrease in its balance since it's an Asset. Likewise, Equity accounts are typically credited when there is an increase in their balance. Equity is considered an owner's rights to Assets in the business. In this case however, we are not simply increasing the owners right's to assets within the business; we are actually removing capital from the business altogether. Hence both sides of our accounting equation will see a decrease. In order to accomplish this, we need to create a Contra-Equity account we'll call "Drawings". Since Equity accounts normally have credit balances, a Contra-Equity account will have a debit balance, which is what we need for our transaction. 
+For example, let's assume the owner of a business wants to withdraw cash. First we'll assume that we have an asset account for "Cash" which the funds will be drawn from. We'll then need an Equity account to record where the funds are going, however, in this case, we can't simply create a regular Equity account. The "Cash" account must be credited for the decrease in its balance since it's an Asset. Likewise, Equity accounts are typically credited when there is an increase in their balance. Equity is considered an owner's rights to Assets in the business. In this case however, we are not simply increasing the owner's rights to assets within the business; we are actually removing capital from the business altogether. Hence both sides of our accounting equation will see a decrease. In order to accomplish this, we need to create a Contra-Equity account we'll call "Drawings". Since Equity accounts normally have credit balances, a Contra-Equity account will have a debit balance, which is what we need for our transaction. 
+
+    >> Plutus::Equity.create(:name => "Drawing", :contra => true)
+    >> Plutus::Asset.create(:name => "Cash")
 
-	>> Equity.create(:name => "Drawing", :contra => true)
-	>> Asset.create(:name => "Cash")
-  
 We would then create the following transaction:
 
-	>> Transaction.create(:description => "Owner withdrawing cash", 
-                        :credit_account => Asset.find_by_name("Cash"),
-                        :debit_account => Equity.find_by_name("Drawing"), 
-                        :amount => 1000.00)
+    transaction = Plutus::Transaction.build(
+                    :description => "Owner withdrawing cash",
+                    :debits => [
+                      {:account => "Drawing", :amount => 1000}], 
+                    :credits => [
+                      {:account => "Cash", :amount => 1000}])
+    transaction.save
 
 To make the example clearer, imagine instead that the owner decides to invest his money into the business in exchange for some type of equity security. In this case we might have the following accounts:
 
-
-	>> Equity.create(:name => "Common Stock")
-	>> Asset.create(:name => "Cash")
+    >> Plutus::Equity.create(:name => "Common Stock")
+    >> Plutus::Asset.create(:name => "Cash")
 
 And out transaction would be:
 
-	>> Transaction.create(:description => "Owner investing cash", 
-                        :credit_account => Equity.find_by_name("Common Stock"),
-                        :debit_account => Asset.find_by_name("Cash"), 
-                        :amount => 1000.00)
+    transaction = Plutus::Transaction.build(
+                    :description => "Owner investing cash",
+                    :debits => [
+                      {:account => "Cash", :amount => 1000}], 
+                    :credits => [
+                      {:account => "Common Stock", :amount => 1000}])
+    transaction.save
 
 In this case, we've increase our cash Asset, and simultaneously increased the other side of our accounting equation in
 Equity, keeping everything balanced.
@@ -163,26 +207,29 @@ Equity, keeping everything balanced.
 Access & Security
 =================
 
-The Engine provides controllers and views for viewing Accounts and Transactions via the {AccountsController} and {TransactionsController}  classes. The controllers will render HTML, XML and JSON, and are compatible with [ActiveResource](http://api.rubyonrails.org/classes/ActiveResource/Base.html)
+The Engine provides controllers and views for viewing Accounts and Transactions via the {Plutus::AccountsController} and {Plutus::TransactionsController} classes. The controllers will render HTML, XML and JSON, and are compatible with [ActiveResource](http://api.rubyonrails.org/classes/ActiveResource/Base.html)
+
+These controllers are read-only for reporting purposes. It is assumed transaction creation will occur within your applications code.
+
+Routing is supplied via an engine mount point. Plutus can be mounted on a subpath in your existing Rails 3 app by adding the following to your routes.rb:
+
+    mount Plutus::Engine => "/plutus", :as => "plutus"
 
-Routing is NOT supplied by the engine. You can add routes to your application in your config/routes.rb with something like the following
+*NOTE: If you enable routing, you should ensure that your ApplicationController enforces its own authentication and authorization, which this controller will inherit.*
 
-	map.resources :transactions, :only => [:index, :show], :conditions => { :method => :get }
-	map.resources :accounts, :only => [:index, :show], :conditions => { :method => :get }
+Sample stylesheets can also be applied by adding the following to your application layout:
 
-*NOTE: If you enable routing, you should ensure that your ApplicationController enforces its own authentication and authorization, which this controller will inherit.*  
+    <%= stylesheet_link_tag    "plutus/application" %>
 
 Testing
 =======
 
-[Rspec](http://rspec.info/) tests are provided. Install both the rpsec and rspec-rails gems, and install this plugin
-into a working rails application to run the tests.
+[Rspec](http://rspec.info/) tests are provided. Run `bundle install` then `rake`.  
 
 ToDo
 ====
 
 * Better views, including paging and ledgers
-* Namespacing to allow overriding engine classes
 * Reference for common accounting transactions
 
 Reference
@@ -194,4 +241,4 @@ For a complete reference on Accounting principles, we recommend the following te
 
 * * *
 
-Copyright (c) 2010 Michael Bulat
+Copyright (c) 2010-2012 Michael Bulat

data/Rakefile

@@ -1,24 +1,11 @@
-require 'rake'
-require 'yard'
+require 'bundler/setup'
 
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gem|
-    gem.name = "plutus"
-    gem.summary = "A Plugin providing a Double Entry Accounting Engine for Rails"
-		gem.description = "The plutus plugin provides a complete double entry accounting system for use in any Ruby on Rails application. The plugin follows general Double Entry Bookkeeping practices. All calculations are done using BigDecimal in order to prevent floating point rounding errors. The plugin requires a decimal type on your database as well."
-    gem.email = "mbulat@crazydogsoftware.com"
-    gem.homepage = "http://github.com/mbulat/Plutus"
-    gem.authors = ["Michael Bulat"]
-    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
-  end
+require 'rspec/core/rake_task'
 
-rescue LoadError
-  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+desc "run specs"
+RSpec::Core::RakeTask.new do |t|
+  t.rspec_opts = ["-c", "-f d", "-r ./spec/spec_helper.rb"]
+  t.pattern = 'spec/**/*_spec.rb'
 end
 
-desc 'Generate documentation for the plutus plugin.'
-YARD::Rake::YardocTask.new do |t|
-  t.files   = ['lib/**/*.rb', 'app/**/*.rb']   # optional
-  t.options = [] # optional
-end
+task :default  => :spec

data/app/assets/javascripts/plutus/application.js

@@ -0,0 +1,15 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
+// or vendor/assets/javascripts of plugins, if any, can be referenced here using a relative path.
+//
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// the compiled file.
+//
+// WARNING: THE FIRST BLANK LINE MARKS THE END OF WHAT'S TO BE PROCESSED, ANY BLANK LINE SHOULD
+// GO AFTER THE REQUIRES BELOW.
+//
+//= require jquery
+//= require jquery_ujs
+//= require_tree .

data/app/assets/stylesheets/plutus/application.css

@@ -0,0 +1,13 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or vendor/assets/stylesheets of plugins, if any, can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the top of the
+ * compiled file, but it's generally better to create a new file per style scope.
+ *
+ *= require_self
+ *= require_tree .
+*/

data/app/assets/stylesheets/plutus/main.css.scss

@@ -0,0 +1,86 @@
+.plutus_container {
+
+  /* CSS from http://wptheming.com/2011/01/simple-table-css3/ */
+  
+  margin:0;
+  padding:0;
+  border:0;
+  font-family: "Helvetica Neue",Arial, Helvetica, sans-serif;
+  
+  /*
+  Pretty Table Styling
+  CSS Tricks also has a nice writeup: http://css-tricks.com/feature-table-design/
+  */
+  
+  table {
+    overflow:hidden;
+    border:1px solid #d3d3d3;
+    background:#fefefe;
+    width:70%;
+    margin:5% auto 0;
+    -moz-border-radius:5px; /* FF1+ */
+    -webkit-border-radius:5px; /* Saf3-4 */
+    border-radius:5px;
+    -moz-box-shadow: 0 0 4px rgba(0, 0, 0, 0.2);
+    -webkit-box-shadow: 0 0 4px rgba(0, 0, 0, 0.2);
+  }
+  
+  th, td {padding:10px 18px 10px; }
+  
+  th {padding-top:22px; text-shadow: 1px 1px 1px #fff; background:#e8eaeb;}
+  
+  td {border-top:1px solid #e0e0e0; border-right:1px solid #e0e0e0;}
+  
+  tr.even td {background:#f6f6f6;}
+  
+  td.first, th.first {text-align:left}
+  
+  td.last {border-right:none;}
+  
+  /*
+  Background gradients are completely unnessary but a neat effect.
+  */
+  
+  td {
+    background: -moz-linear-gradient(100% 25% 90deg, #fefefe, #f9f9f9);
+    background: -webkit-gradient(linear, 0% 0%, 0% 25%, from(#f9f9f9), to(#fefefe));
+  }
+  
+  tr.even td {
+    background: -moz-linear-gradient(100% 25% 90deg, #f6f6f6, #f1f1f1);
+    background: -webkit-gradient(linear, 0% 0%, 0% 25%, from(#f1f1f1), to(#f6f6f6));
+  }
+  
+  th {
+    background: -moz-linear-gradient(100% 20% 90deg, #e8eaeb, #ededed);
+    background: -webkit-gradient(linear, 0% 0%, 0% 20%, from(#ededed), to(#e8eaeb));
+  }
+  
+  /*
+  I know this is annoying, but we need dditional styling so webkit will recognize rounded corners on background elements.
+  Nice write up of this issue: http://www.onenaught.com/posts/266/css-inner-elements-breaking-border-radius
+  
+  And, since we've applied the background colors to td/th element because of IE, Gecko browsers also need it.
+  */
+  
+  tr:first-child th.first {
+    -moz-border-radius-topleft:5px;
+    -webkit-border-top-left-radius:5px; /* Saf3-4 */
+  }
+  
+  tr:first-child th.last {
+    -moz-border-radius-topright:5px;
+    -webkit-border-top-right-radius:5px; /* Saf3-4 */
+  }
+  
+  tr:last-child td.first {
+    -moz-border-radius-bottomleft:5px;
+    -webkit-border-bottom-left-radius:5px; /* Saf3-4 */
+  }
+  
+  tr:last-child td.last {
+    -moz-border-radius-bottomright:5px;
+    -webkit-border-bottom-right-radius:5px; /* Saf3-4 */
+  }
+
+}

data/app/controllers/plutus/accounts_controller.rb

@@ -0,0 +1,45 @@
+module Plutus
+  # This controller provides restful route handling for Accounts.
+  #
+  # The controller supports ActiveResource, and provides for
+  # HMTL, XML, and JSON presentation.
+  #
+  # == Security:
+  # Only GET requests are supported. You should ensure that your application
+  # controller enforces its own authentication and authorization, which this
+  # controller will inherit.
+  #
+  # @author Michael Bulat
+  class AccountsController < ApplicationController
+    unloadable
+
+    # @example
+    #   GET /accounts
+    #   GET /accounts.xml
+    #   GET /accounts.json
+    def index
+      @accounts = Account.all
+
+      respond_to do |format|
+        format.html # index.html.erb
+        format.xml  { render :xml => @accounts }
+        format.json  { render :json => @accounts }
+      end
+    end
+
+    # @example
+    #   GET /accounts/1
+    #   GET /accounts/1.xml
+    #   GET /accounts/1.json
+    def show
+      @account = Account.find(params[:id])
+
+      respond_to do |format|
+        format.html # show.html.erb
+        format.xml  { render :xml => @account }
+        format.json  { render :json => @account }
+      end
+    end
+
+  end
+end