tommeier-dynamic_reports 0.0.4

Sign up to get free protection for your applications and to get access to all the features.
Files changed (4) hide show
  1. data/HISTORY +2 -0
  2. data/README +189 -0
  3. data/gemspec.rb +25 -0
  4. metadata +57 -0
data/HISTORY ADDED
@@ -0,0 +1,2 @@
1
+ 0.0.0
2
+ - Initial dynamic reports codebase.
data/README ADDED
@@ -0,0 +1,189 @@
1
+ = Dynamic Reports
2
+
3
+ A dynamic reporting engine for Ruby / Rails
4
+
5
+ == Reports
6
+
7
+ The dynamic reports gem was created to fill a HUGE hole that we felt existed in the
8
+ Ruby community - the ability to QUICKLY create stylized admin reports and charts for
9
+ people to use to view key metrics and data.
10
+
11
+ Sample uses include the ability to quickly display sales data if your an eShop, our
12
+ site metrics if you are recording your own site visits, or user feedback if you are storing
13
+ feedback in a model somewhere.
14
+
15
+ Basically, with DR you can create a stylized table of ANY information found in a model
16
+ (kind of like looking at the grid output from a GUI query analyzer) as well as add Google
17
+ Charts API powered line, pie, bar or column charts of any numeric data. All this can
18
+ be done by simply creating a report definition and feeding it your data.
19
+
20
+ While this library is usable in any Ruby application it was made mainly with Rails in mind.
21
+ Suppose we have an online store and we wish to add reporting to the admin area quickly and easily.
22
+ First we define a report in app/reports/orders_report.rb, something like:
23
+
24
+ class OrdersReport < DynamicReports::Report
25
+ title "Orders Report"
26
+ sub_title "All orders recorded in database"
27
+ columns :total, :created_at
28
+ end
29
+
30
+ Then in our admin/reports controller (this can be any controller) we define an action to deliver the report:
31
+
32
+ def orders
33
+ @orders = Order.find(:all, :limit => 25)
34
+ render :text => OrdersReport.on(@orders).to_html, :layout => "application"
35
+ end
36
+
37
+ This will render an html table containing some basic styling and containing the columns 'total' and 'created_at' from the order objects.
38
+ Note that the report Title will be "Orders Report" and it's name will be :orders_report
39
+ Report#on expects that it receives an object that responds to #each and
40
+ That each object that it iterates over is either a
41
+ * An object
42
+ * A Hash
43
+ that responds to a method / has keys for each column defined within the report.
44
+
45
+
46
+ Templating engines may also be specified, currently :erb and :haml are supported (we will soon be adding :csv and :pdf) like so:
47
+
48
+ render :text => OrdersReport.on(@orders).to_html(:engine => :haml), :layout => "application"
49
+
50
+ Note that erb is the default templating engine since it is available by default in Ruby.
51
+
52
+ Now let us extend our report definition to specify a template to use!
53
+
54
+ class OrdersReport < DynamicReports::Report
55
+ title "Orders Report"
56
+ sub_title "All orders recorded in database"
57
+ columns :total, :created_at
58
+
59
+ template :my_custom_template
60
+ end
61
+
62
+ This will look in app/views/reports/ for a template named "my_custom_template.html.erb" by default.
63
+ If you specify :engine => :haml then it will look for "my_custom_template.html.haml"
64
+
65
+ If you happen to have your report templates in a different location you can specify this as follows:
66
+
67
+ class OrdersReport < DynamicReports::Report
68
+ title "Orders Report"
69
+ sub_title "All orders recorded in database"
70
+ columns :total, :created_at
71
+
72
+ template :my_custom_template
73
+ views "app/views/admin/reports/"
74
+ end
75
+
76
+ And DynamicReports will look for the specified template in app/views/reports as well as app/views/admin/reports.
77
+
78
+ It is also worth pointing out that you can have as many dynamic reports in a view as you wish, simply include
79
+ each report render where desired within the view.
80
+
81
+ == Charts
82
+
83
+ Charts can be defined on a report easily. Let's say we wish to chart the total versus the item quantity sold for our Orders Report exmaple:
84
+
85
+ class OrdersReport < DynamicReports::Report
86
+ title "Orders Report"
87
+ sub_title "All orders recorded in database"
88
+ columns :total, :created_at
89
+
90
+ chart :total_vs_quantity do
91
+ columns :total, :quantity
92
+ label_column "created_at"
93
+ end
94
+ end
95
+
96
+ This will render a *line* chart by default displaying the columns total and quantity.
97
+ Chart types may be specified easily:
98
+
99
+ type :bar
100
+
101
+ Available chart types are:
102
+
103
+ * :line (default)
104
+ * :bar
105
+ * :pie
106
+
107
+ Since DynamicReport's charts utilize the Google Chart API, you can easily extend each chart by passing a hash of chart options as part
108
+ of the block. The options are appended onto the request to the API so they should follow the Google's API commands (http://code.google.com/apis/chart/)
109
+
110
+ For example, to add min, max and average labels to the example chart, you would do something like this:
111
+
112
+ chart :total_vs_quantity, {:chxt => "r", :chxl => "0:|min|average|max"} do
113
+ columns :total, :quantity
114
+ label_column "created_at"
115
+ end
116
+
117
+ == Stylizing
118
+
119
+ The reports are, by default, stylized with an inline style sheet. The styles produce a nicely formatted grid with
120
+ a white on black header row and black on white columns with a gray border througout.
121
+
122
+ You can create your own styles by simply adding a class_name object to the report definition as such:
123
+
124
+ class OrdersReport < DynamicReports::Report
125
+ title "Orders Report"
126
+ sub_title "All orders recorded in database"
127
+ columns :total, :created_at
128
+
129
+ class_name "my_class_name"
130
+ end
131
+
132
+ This will cause DR to simply not include the inline style. From there you can customer the styles using the
133
+ following sub-classes for your class name, for example:
134
+
135
+ .my_class_name .report_title {}
136
+ .my_class_name .report_subtitle {}
137
+ .my_class_name table tr th {}
138
+ .my_class_name table tr td {}
139
+ .my_class_name .report_charts {} // all charts are displayed within this div
140
+ .my_class_name .report_chart {} // represents an individual chart
141
+
142
+ == Rails Usage
143
+
144
+ Inside the initializer block in config/environment.rb
145
+
146
+ config.gem "dynamic_reports"
147
+
148
+ Then define your reports (as exampled above) in app/reports/*_report.rb
149
+ If you would like to customize the default report simply create your report templates
150
+ within app/views/reports/*_report.<content-type>.<engine>.
151
+
152
+ Two Rails features that we are currently working on are:
153
+
154
+ * generator
155
+ * render extensions
156
+
157
+ == Optional Dependencies
158
+
159
+ We are currently examining solutions for csv, pdf and charting.
160
+
161
+ * Fastercsv # csv
162
+ * Prawn # pdf
163
+ * flying saucer # html => PDF - if jRuby available
164
+ * amcharts # Charting, note that default is built in google charts.
165
+
166
+ These will be defined/implemented using DynamicReports plugin API (not implemented yet)
167
+ Which allows for user defined plugins of arbitrary types beyond html,csv,pdf,xml
168
+
169
+ == Contact / Feedback
170
+
171
+ If you have any suggestions on improvement please send us an email.
172
+
173
+ == Authors (alphabetically)
174
+
175
+ Joshua Lippiner (jlippiner@gmail.com)
176
+
177
+ Wayne E. Seguin (wayneeseguin@gmail.com, irc: wayneeseguin)
178
+
179
+ == Thanks To
180
+
181
+ * Daniel Neighman
182
+ * Kenneth Kalmer (And his friend :))
183
+ * Yehuda Katz
184
+
185
+ For their encouragement, feedback and advise.
186
+
187
+ == Source
188
+ http://github.com/wayneeseguin/dynamic_reports
189
+
data/gemspec.rb ADDED
@@ -0,0 +1,25 @@
1
+ require "rubygems"
2
+
3
+ library="dynamic_reports"
4
+ version="0.0.2"
5
+
6
+ Gem::Specification::new do |spec|
7
+ $VERBOSE = nil
8
+ spec.name = library
9
+ spec.summary = library
10
+ spec.version = version
11
+ spec.description = "Dynamic Ruby Reporting Engine with support for Charts"
12
+ spec.platform = Gem::Platform::RUBY
13
+ spec.files = ["HISTORY", "README", "gemspec.rb", Dir::glob("lib/**/**")].flatten
14
+ spec.executables = Dir::glob("bin/*").map{ |script| File::basename script }
15
+ spec.require_path = "lib"
16
+ spec.has_rdoc = File::exist?("doc")
17
+ spec.author = "Wayne E. Seguin & Joshua Lippiner"
18
+ spec.email = "wayneeseguin@gmail.com, jlippiner@gmail.com"
19
+ spec.homepage = "http://github.com/wayneeseguin/direct_reports"
20
+ # spec.test_suite_file = "test/#{library}.rb" if File::directory?("test")
21
+ #spec.add_dependency "", ">= 0.0"
22
+ spec.extensions << "extconf.rb" if File::exists?("extconf.rb")
23
+ spec.rubyforge_project = library
24
+ end
25
+
metadata ADDED
@@ -0,0 +1,57 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: tommeier-dynamic_reports
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.0.4
5
+ platform: ruby
6
+ authors:
7
+ - Wayne E.Seguin
8
+ - Joshua Lippiner
9
+ autorequire:
10
+ bindir: bin
11
+ cert_chain: []
12
+
13
+ date: 2009-06-28 00:00:00 -07:00
14
+ default_executable:
15
+ dependencies: []
16
+
17
+ description: Dynamic Ruby Reporting Engine with support for Charts
18
+ email: wayneeseguin@gmail.com
19
+ executables: []
20
+
21
+ extensions: []
22
+
23
+ extra_rdoc_files: []
24
+
25
+ files:
26
+ - HISTORY
27
+ - README
28
+ - gemspec.rb
29
+ has_rdoc: true
30
+ homepage: http://github.com/wayneeseguin/direct_reports
31
+ post_install_message:
32
+ rdoc_options:
33
+ - --inline-source
34
+ - --charset=UTF-8
35
+ require_paths:
36
+ - lib
37
+ required_ruby_version: !ruby/object:Gem::Requirement
38
+ requirements:
39
+ - - ">="
40
+ - !ruby/object:Gem::Version
41
+ version: "0"
42
+ version:
43
+ required_rubygems_version: !ruby/object:Gem::Requirement
44
+ requirements:
45
+ - - ">="
46
+ - !ruby/object:Gem::Version
47
+ version: "0"
48
+ version:
49
+ requirements: []
50
+
51
+ rubyforge_project: dynamic_reports
52
+ rubygems_version: 1.2.0
53
+ signing_key:
54
+ specification_version: 2
55
+ summary: Dynamic Ruby Reporting Engine with support for Charts
56
+ test_files: []
57
+