This extension provides a model Spree::BookkeepingDocument
, which generates PDFs from any Spree Object with the help of View objects that translate between different object structures and PDF templates. It stores a "number" string as well as first name, last name, email, and amount with each document for convenient searching in the backend.
The Gem contains an example implementation for Invoices for Spree::Orders
. The basic structure looks like this:
Spree::BookkeepingDocument
takes as constructor arguments a printable
(polymorphic AR object) and a template
(string). It then passes on all actual data generation to a ViewObject. You can find these objects in app/spree/printables/#{printable}/#{template}_view.rb
. The object will be instantiated upon PDF generation (look at the Spree::BookkeepingDocument#pdf
method to see how it's done).
Spree::Order
is patched so that it generates both an invoice and a packaging_slip on completion.
In the Spree::Admin::OrdersController#edit
view, you'll find an additional button Documents
, where all printable documents will be listed. Additionally, you can find all available Documents in a "Documents" tab in the main menu.
Add to your Gemfile
gem 'spree_print_invoice', github: 'ShopFelixGray/spree_print_invoice', branch: 'master'
Run
bundle && exec rails g spree_print_invoice:install
Enjoy! Now you can generate invoices and packaging slips with sequential numbers from arbitrary Spree objects.
- Set the logo path preference to include your store / company logo.
Spree::PrintInvoice::Config.set(logo_path: '/path/to/public/images/company-logo.png')
-
Add your own own footer texts to the locale. The current footer works with
:footer_left1
,:footer_left2
and:footer_right1
,:footer_right2
where the 1 version is on the left in bold, and the 2 version the "value" on the right. -
Override any of the partial templates.
-
Many european countries requires numeric and sequential invoices numbers. To use invoices sequential number fill the specific field in "General Settings" or by setting:
Spree::PrintInvoice::Config.set(next_number: [1|'your current next invoice number'])
The next invoice number will be the one that you specified. You will able to increase it in any moment, for example, to re-sync invoices number if you are making invoices also in other programs for the same business name.
- Set page/document options with:
Spree::PrintInvoice::Config.set(prawn_options: { page_layout: :landscape, page_size: 'A4', margin: [50, 100, 150, 200] })
- Enable PDF storage feature
PDF files can be stored to disk. This is very handy if you want to send these files as email attachment.
Spree::PrintInvoice::Config.set(store_pdf: true) # Default: false
Spree::PrintInvoice::Config.set(storage_path: 'pdfs/orders') # Default: tmp/order_prints
Inside the storage_path
a folder for each template will be created. Files will be saved with order number respectively invoice number as file name.
In order to customize the build in invoice and packaging slip templates you need to copy them into your app:
$ bundle exec rails g spree_print_invoice:templates
You can then customize them in the app/views/spree/printables
directory.
From previous versions of spree_print_invoice
, the syntax and location of the prawn
templates has changed. Please copy new templates using rails g spree_print_invoice:templates
and adapt according to your needs.
In order to create a packaging slip for Spree::Shipment
s, do the following:
-
Create a View object in
app/models/printables/shipments/packagin_slip_view.rb
:module Spree class Printables::Shipment::PackagingSlipView < Printables::BaseView def number @printable.number end # [ ... more code here, look at the BaseView to see what to implement ] end end
-
Create a
prawn
template inapp/views/spree/printables/shipment/packaging_slip.pdf.prawn
. You can find orientation on the format and syntax of the template by looking at the packaging slip template forSpree::Orders
inapp/views/spree/printables/orders/invoice.pdf.prawn
. Some familiarity with Rails templates will help a lot, as well as reading theprawn
docs. -
Decorate the shipment model to generate a packaging slip at some point in its life cycle. You could go with a simple
after_create
Callback, or hook yourself into one of Spree's various state machines. Again, take the suppliedapp/models/order_decorator.rb
as inspiration.
This Gem uses the prawn-rails
to generate templates.
Name PDF view files like foo.pdf.prawn
. Inside, use the pdf
method to access a Prawn::Document
object:
pdf.bounding_box [100, 600], width: 200 do
pdf.text 'The rain in spain falls mainly on the plains ' * 5
pdf.stroke do
pdf.line pdf.bounds.top_left, pdf.bounds.top_right
pdf.line pdf.bounds.bottom_left, pdf.bounds.bottom_right
end
end
When you customize templates and you get the message "You have reached the end of the graphics stack", any one of the objects you're trying to place on your template is too big for the surrounding bounding_box
. A common source of this is a missing translation, so make sure your translations are up-to-date.
See corresponding guidelines
Copyright (c) 2011-2015 Spree Commerce, and other contributors, released under the New BSD License