Payday is a library for rendering invoices. At present it supports rendering invoices to pdfs, but we're planning on adding support for other formats in the near future.
Payday is available as a Rubygem, so installing it is as easy as running:
gem install payday --pre
Or, using bundler:
gem "payday"
It's pretty easy to use Payday with the built in objects. We include the Invoice and LineItem classes, and with them you can get started pretty quickly.
Example:
invoice = Payday::Invoice.new(:invoice_number => 12)
invoice.line_items << LineItem.new(:price => 20, :quantity => 5, :description => "Pants")
invoice.line_items << LineItem.new(:price => 10, :quantity => 3, :description => "Shirts")
invoice.line_items << LineItem.new(:price => 5, :quantity => 200, :description => "Hats")
invoice.render_pdf_to_file("/path/to_file.pdf")
Documentation for the latest version of Payday is available at rdoc.info.
Payday::Config includes quite a few options for customizing your invoices, such as options for customizing the logo and company details on the invoice.
Example:
Payday::Config.default.invoice_log = "/path/to/company/logo.png"
Payday::Config.default.company_name = "Awesome Corp"
Payday::Config.default.company_details = "10 This Way\nManhattan, NY 10001\n800-111-2222\[email protected]"
Payday focuses on two main objects, an invoice and a line item, so to use Payday with ActiveRecord you'll want to create your own classes for those objects. We include the Payday::Invoiceable and Payday::LineItemable modules to help out with that.
Here's the simplest possible implementation of a custom invoice and line item with Payday:
In a new migration:
create_table :invoices do |t|
# invoices will work without anything but bill_to, but there are quite a few options for the fields you can save, like ship_to
# due_at, and paid_at
t.string :bill_to
t.timestamps
end
create_table :line_items do |t|
t.decimal :price
t.string :description
t.integer :quantity # can also be :decimal or :float - just needs to be numeric
t.integer :invoice_id
t.timestamps
end
In app/models/invoice.rb:
class Invoice < ActiveRecord::Base
include Payday::Invoiceable
has_many :line_items
end
In app/models/line_item.rb:
class LineItem < ActiveRecord::Base
include Payday::LineItemable
belongs_to :invoice
end
For a bit more fleshed out example, be sure to check out http://github.com/commondream/payday-example.
Payday's Invoiceable module includes methods for rendering pdfs to disk and for rendering them to a string. In a Rails controller, you can use the render to string method to render a pdf directly to the browser like this:
In config/initializers/mime_types.rb:
Mime::Type.register 'application/pdf', :pdf
In your controller:
respond_to do |format|
format.html
format.pdf do
send_data invoice.render_pdf, :filename => "Invoice #12.pdf", :type => "application/pdf", :disposition => "inline"
end
end
Be sure to restart your server after you edit the mime_types initializer. The updated setting won't take effect until you do.
Payday uses the i18n gem to provide support for custom labels and internationalized applications. You can change the default labels by
adding a YAML file in the config/locales directory of your Rails app. Here are the default labels you can customize :
payday:
status:
paid: PAID
overdue: OVERDUE
invoice:
bill_to: Bill To
ship_to: Ship To
invoice_no: "Invoice #:"
due_date: "Due Date:"
paid_date: "Paid Date:"
subtotal: "Subtotal:"
tax: "Tax:"
total: "Total:"
line_item:
description: Description
unit_price: Unit Price
quantity: Quantity
amount: Amount
Here's an example PDF Invoice
There's also an example Rails application running on Heroku at http://payday-example.heroku.com. You can check out the source at http://github.com/commondream/payday-example.
Payday is pretty young, so there's still a good bit of work to be done. I highly recommend sending me a message on GitHub before making too many changes, just to make sure that two folks aren't doing the same work, but beyond that feel free to fork the project, make some changes, and send a pull request. If you're unsure about what to work on but would like to help, send me a message on GitHub. I'd love the help!
We've had some awesome contributers:
- Sam Pizzey (pizzeys)
- Andrew Nordman (cadwallion)
- Pierre Olivier Martel (pomartel)
Here's what we're planning on working on with Payday in the near future:
-
Let some folks use it for a bit.
-
Release 1.0!
-
Actually get a designer to style the invoices.
-
Add support for Money gem or BigDecimal or general numerics (right now we support BigDecimal and general numerics)
-
Add support for blank line items
-
Add support for indented line items
-
Apply different tax rates to different line items
-
Add support for shipping either pre or post tax
-
Add invoice_details has for stuff under the invoice number
-
Add ability to show skus or product ids on each line item
-
Add page numbers
-
Ability to render invoice to html for web viewing
This wouldn't be possible without the amazing Prawn gem and the team behind it.
Copyright (C) 2011 by Alan Johnson
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.