Ruport is a extension that provides Ruport based reporting for Spree.
Basic functionality currently includes 3 types of reports:
- Product sales report
- Orders report
- Total sales report
And export to 3 formats:
- pdf (Using prawn for pdf generation)
- csv (only parts of reports can be exported this way due to format's limited functionality)
- html (with custom overridable template)
With time (and hopefully money) the functionality will be extended (plans include more reports and export formats like xml and json)
Author: Marcin Raczkowski with contributions from Brian Quinn
Work on original extension was sponsored by netbird.pl
For git users:
git submodule add git://github.com/swistak/spree-ruport.git vendor/extensions/ruport
for others (or git users that don't like submodules):
ruby script/extension install git://github.com/swistak/spree-ruport.git
You can set logo for pdf reports with
Spree::Config.set(:pdf_logo => '/images/admin/bg/spree_logo_pdf.png')
in your migration.
WARNING prawn expects image will have proper dpi (72 by default) othervise your image will be incorrectly enlarged, and will look ugly and pixelated.
I'll gladly include more report types and output formats, but remember to:
- Read documentation of proper classes, and this readme.
- Check if report type would be usefull to public.
- Check if report isn't tied to your extension functionality (will it work without it?)
- Write unit tests
- Commit changes in clear path sets (before submiting pull request, you can rebase your changes into separate branch)
If your report type is tied to your extension functionality you can include it in your own extension. More on how to do it bellow.
If you plan on introducing new features here's the TODO:
- Optional generation of monthly reports when month ends with whenever
- Generating report once, saving to file, and later serving it from file
Creating new report types
When creating new reports you have to provide two classes:
- Model (in app/models)
- Ruport Controller (in app/reports)
Model should inherit from Report and provide preferences needed to generate the report.
Model is usually empty, but if your report requires special parameters you can use the preferences system to add typed attributes to your model, they'll be automatically available in your report controller (the'll be merged with attributes into #options)
Controller should be named exactly like model, but with Controller suffix and inherit from BaseRuportController
WARNING! Controller is not a standard rails controller, instead it's Ruport controller and all conventions and options of ruport controller apply.
If you need help understanding how it works, please read http://ruportbook.com especialy:
Default formatters provided with ruport extension are customized version of ruport formaters, adjusted for spree. In case of pdf formatter it was completelly rewritten to support prawn instead of pdf::writer
Default formatters provide following stages:
Providing reports in your extensions
If you're providing a report in your own extension (it's tied to extension functionality) there are few things you need to consider.
Since ruport extension might not be available you need to add guards to your models and controllers for model
if defined?(Report) your model code here end
if defined?(BaseRuportController) Controller code here end
In your extension #activate method you also need to activate report by adding it to Report::AVAILABLE_REPORTS set.
Then you have to decide if you want to use default formaters or custom ones. If you choose custome ones you have to provide them for pdf, html, and csv. If you choose default ones, you have to select them for rendering your report with:
Formatter::Pdf.renders :pdf, :for => MyCustomReport Formatter::Html.renders :html, :for => MyCustomReport Formatter::Csv.renders :csv, :for => MyCustomReport