Class: SVG::Graph::Graph

Inherits:
Object
  • Object
show all
Includes:
REXML
Defined in:
lib/SVG/Graph/Graph.rb

Overview

Base object for generating SVG Graphs

Synopsis

This class is only used as a superclass of specialized charts. Do not attempt to use this class directly, unless creating a new chart type.

For examples of how to subclass this class, see the existing specific subclasses, such as SVG::Graph::Pie.

Examples

For examples of how to use this package, see either the test files, or the documentation for the specific class you want to use.

  • file:test/plot.rb

  • file:test/single.rb

  • file:test/test.rb

  • file:test/timeseries.rb

Description

This package should be used as a base for creating SVG graphs.

Acknowledgements

Leo Lapworth for creating the SVG::TT::Graph package which this Ruby port is based on.

Stephen Morgan for creating the TT template and SVG.

See

  • SVG::Graph::BarHorizontal

  • SVG::Graph::Bar

  • SVG::Graph::Line

  • SVG::Graph::Pie

  • SVG::Graph::Plot

  • SVG::Graph::TimeSeries

Author

Sean E. Russell <serATgermaneHYPHENsoftwareDOTcom>

Copyright 2004 Sean E. Russell This software is available under the Ruby license

Direct Known Subclasses

BarBase, Line, Schedule

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(config) ⇒ Graph

Initialize the graph object with the graph settings. You won’t instantiate this class directly; see the subclass for options.

width

500

height

300

x_axis_position

nil

y_axis_position

nil

show_x_guidelines

false

show_y_guidelines

true

show_data_values

true

min_scale_value

0

show_x_labels

true

stagger_x_labels

false

rotate_x_labels

false

step_x_labels

1

step_include_first_x_label

true

show_y_labels

true

rotate_y_labels

false

scale_integers

false

show_x_title

false

x_title

‘X Field names’

x_title_location

:middle | :end

show_y_title

false

y_title_text_direction

:bt | :tb

y_title

‘Y Scale’

y_title_location

:middle | :end

show_graph_title

false

graph_title

‘Graph Title’

show_graph_subtitle

false

graph_subtitle

‘Graph Sub Title’

key

true,

key_position

:right, # bottom or righ

font_size

12

title_font_size

16

subtitle_font_size

14

x_label_font_size

12

x_title_font_size

14

y_label_font_size

12

y_title_font_size

14

key_font_size

10

no_css

false

add_popups

false

number_format

‘%.2f’



104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/SVG/Graph/Graph.rb', line 104

def initialize( config )
  @config = config
  # array of Hash
  @data = []
  #self.top_align = self.top_font = 0
  #self.right_align = self.right_font = 0

  init_with({
    :width                => 500,
    :height               => 300,
    :show_x_guidelines    => false,
    :show_y_guidelines    => true,
    :show_data_values     => true,

    :x_axis_position      => nil,
    :y_axis_position      => nil,

    :min_scale_value      => nil,

    :show_x_labels        => true,
    :stagger_x_labels     => false,
    :rotate_x_labels      => false,
    :step_x_labels        => 1,
    :step_include_first_x_label => true,

    :show_y_labels        => true,
    :rotate_y_labels      => false,
    :stagger_y_labels     => false,
    :scale_integers       => false,

    :show_x_title         => false,
    :x_title              => 'X Field names',
    :x_title_location     => :middle,  # or :end

    :show_y_title         => false,
    :y_title_text_direction => :bt,  # other option is :tb
    :y_title              => 'Y Scale',
    :y_title_location     => :middle,  # or :end

    :show_graph_title      => false,
    :graph_title          => 'Graph Title',
    :show_graph_subtitle  => false,
    :graph_subtitle        => 'Graph Sub Title',
    :key                  => true,
    :key_width             => nil,
    :key_position          => :right, # bottom or right

    :font_size            => 12,
    :title_font_size      => 16,
    :subtitle_font_size   => 14,
    :x_label_font_size    => 12,
    :y_label_font_size    => 12,
    :x_title_font_size    => 14,
    :y_title_font_size    => 14,
    :key_font_size        => 10,
    :key_box_size         => 12,
    :key_spacing          => 5,

    :no_css               => false,
    :add_popups           => false,
    :popup_radius         => 10,
    :number_format        => '%.2f',
    :style_sheet          => '',
    :inline_style_sheet   => ''
  })
  set_defaults if self.respond_to? :set_defaults
  # override default values with user supplied values
  init_with config
end

Instance Attribute Details

#add_popups ⇒ Object

Add popups for the data points on some graphs, default is false.



451
452
453
 
# File 'lib/SVG/Graph/Graph.rb', line 451

def add_popups
  @add_popups
end

#font_size ⇒ Object

Set the font size (in points) of the data point labels. Defaults to 12.



420
421
422
 
# File 'lib/SVG/Graph/Graph.rb', line 420

def font_size
  @font_size
end

#graph_subtitle ⇒ Object

What the subtitle on the graph should be.



404
405
406
 
# File 'lib/SVG/Graph/Graph.rb', line 404

def graph_subtitle
  @graph_subtitle
end

#graph_title ⇒ Object

What the title on the graph should be.



399
400
401
 
# File 'lib/SVG/Graph/Graph.rb', line 399

def graph_title
  @graph_title
end

#height ⇒ Object

Set the height of the graph box, this is the total height

of the SVG box created - not the graph it self which auto
scales to fix the space.



292
293
294
 
# File 'lib/SVG/Graph/Graph.rb', line 292

def height
  @height
end

#inline_style_sheet ⇒ Object

Define as String the stylesheet contents to be inlined, set to ” to disable.

This can be used, when referring to a url via :style_sheet is not suitable.
E.g. in situations where there will be no internet access or the graph must
consist of only one file.

If not empty, the :style_sheet parameter (url) above will be ignored and is
not written to the file
see also https://github.com/erullmann/svg-graph2/commit/55eb6e983f6fcc69cc5a110d0ee6e05f906f639a
Default: ''



313
314
315
 
# File 'lib/SVG/Graph/Graph.rb', line 313

def inline_style_sheet
  @inline_style_sheet
end

#key ⇒ Object

Whether to show a key (legend), defaults to true, set to

false if you want to hide it.



407
408
409
 
# File 'lib/SVG/Graph/Graph.rb', line 407

def key
  @key
end

#key_box_size ⇒ Object

Returns the value of attribute key_box_size.



412
413
414
 
# File 'lib/SVG/Graph/Graph.rb', line 412

def key_box_size
  @key_box_size
end

#key_font_size ⇒ Object

Set the key font size. Defaults to 10.



441
442
443
 
# File 'lib/SVG/Graph/Graph.rb', line 441

def key_font_size
  @key_font_size
end

#key_position ⇒ Object

Where the key should be positioned, defaults to

:right, set to :bottom if you want to move it.



410
411
412
 
# File 'lib/SVG/Graph/Graph.rb', line 410

def key_position
  @key_position
end

#key_spacing ⇒ Object

Returns the value of attribute key_spacing.



414
415
416
 
# File 'lib/SVG/Graph/Graph.rb', line 414

def key_spacing
  @key_spacing
end

#key_width ⇒ Object

Returns the value of attribute key_width.



416
417
418
 
# File 'lib/SVG/Graph/Graph.rb', line 416

def key_width
  @key_width
end

#min_scale_value ⇒ Object

The point at which the Y axis starts, defaults to nil,

if set to nil it will default to the minimum data value.



331
332
333
 
# File 'lib/SVG/Graph/Graph.rb', line 331

def min_scale_value
  @min_scale_value
end

#no_css ⇒ Object

Do not use CSS if set to true. Many SVG viewers do not support CSS, but not using CSS can result in larger SVGs as well as making it impossible to change colors after the chart is generated. Defaults to false.



449
450
451
 
# File 'lib/SVG/Graph/Graph.rb', line 449

def no_css
  @no_css
end

#number_format ⇒ Object

Number format values and Y axis representation like 1.2345667 represent as 1.23, Any valid format accepted by sprintf can be specified. If you don’t want to change the format in any way you can use “%s”. Defaults to “%.2f”



457
458
459
 
# File 'lib/SVG/Graph/Graph.rb', line 457

def number_format
  @number_format
end

#popup_radius ⇒ Object

Customize popup radius



453
454
455
 
# File 'lib/SVG/Graph/Graph.rb', line 453

def popup_radius
  @popup_radius
end

#rotate_x_labels ⇒ Object

This turns the X axis labels by 90 degrees when true or by a custom

amount when a numeric value is given.
Default is false, to turn on set to true.



346
347
348
 
# File 'lib/SVG/Graph/Graph.rb', line 346

def rotate_x_labels
  @rotate_x_labels
end

#rotate_y_labels ⇒ Object

This turns the Y axis labels by 90 degrees when true or by a custom

amount when a numeric value is given.
Default is false, to turn on set to true or numeric value.



350
351
352
 
# File 'lib/SVG/Graph/Graph.rb', line 350

def rotate_y_labels
  @rotate_y_labels
end

#scale_divisions ⇒ Object

This defines the gap between markers on the Y axis,

default is a 10th of the max_value, e.g. you will have
10 markers on the Y axis. NOTE: do not set this too
low - you are limited to 999 markers, after that the
graph won't generate.



374
375
376
 
# File 'lib/SVG/Graph/Graph.rb', line 374

def scale_divisions
  @scale_divisions
end

#scale_integers ⇒ Object

Ensures only whole numbers are used as the scale divisions.

Default is false, to turn on set to true. This has no effect if
scale divisions are less than 1.



368
369
370
 
# File 'lib/SVG/Graph/Graph.rb', line 368

def scale_integers
  @scale_integers
end

#show_data_values ⇒ Object

(Bool) Show the value of each element of data on the graph



315
316
317
 
# File 'lib/SVG/Graph/Graph.rb', line 315

def show_data_values
  @show_data_values
end

#show_graph_subtitle ⇒ Object

Whether to show a subtitle on the graph, defaults

to false, set to true to show.



402
403
404
 
# File 'lib/SVG/Graph/Graph.rb', line 402

def show_graph_subtitle
  @show_graph_subtitle
end

#show_graph_title ⇒ Object

Whether to show a title on the graph, defaults

to false, set to true to show.



397
398
399
 
# File 'lib/SVG/Graph/Graph.rb', line 397

def show_graph_title
  @show_graph_title
end

#show_x_guidelines ⇒ Object

Show guidelines for the X axis, default is false



443
444
445
 
# File 'lib/SVG/Graph/Graph.rb', line 443

def show_x_guidelines
  @show_x_guidelines
end

#show_x_labels ⇒ Object

Whether to show labels on the X axis or not, defaults

to true, set to false if you want to turn them off.



334
335
336
 
# File 'lib/SVG/Graph/Graph.rb', line 334

def show_x_labels
  @show_x_labels
end

#show_x_title ⇒ Object

Whether to show the title under the X axis labels,

default is false, set to true to show.



377
378
379
 
# File 'lib/SVG/Graph/Graph.rb', line 377

def show_x_title
  @show_x_title
end

#show_y_guidelines ⇒ Object

Show guidelines for the Y axis, default is true



445
446
447
 
# File 'lib/SVG/Graph/Graph.rb', line 445

def show_y_guidelines
  @show_y_guidelines
end

#show_y_labels ⇒ Object

Whether to show labels on the Y axis or not, defaults

to true, set to false if you want to turn them off.



364
365
366
 
# File 'lib/SVG/Graph/Graph.rb', line 364

def show_y_labels
  @show_y_labels
end

#show_y_title ⇒ Object

Whether to show the title under the Y axis labels,

default is false, set to true to show.



385
386
387
 
# File 'lib/SVG/Graph/Graph.rb', line 385

def show_y_title
  @show_y_title
end

#stagger_x_labels ⇒ Object

This puts the X labels at alternative levels so if they

are long field names they will not overlap so easily.
Default is false, to turn on set to true.



338
339
340
 
# File 'lib/SVG/Graph/Graph.rb', line 338

def stagger_x_labels
  @stagger_x_labels
end

#stagger_y_labels ⇒ Object

This puts the Y labels at alternative levels so if they

are long field names they will not overlap so easily.
Default is false, to turn on set to true.



342
343
344
 
# File 'lib/SVG/Graph/Graph.rb', line 342

def stagger_y_labels
  @stagger_y_labels
end

#step_include_first_x_label ⇒ Object

Whether to (when taking “steps” between X axis labels) step from

the first label (i.e. always include the first label) or step from
the X axis origin (i.e. start with a gap if step_x_labels is greater
than one).



361
362
363
 
# File 'lib/SVG/Graph/Graph.rb', line 361

def step_include_first_x_label
  @step_include_first_x_label
end

#step_x_labels ⇒ Object

How many “steps” to use between displayed X axis labels,

a step of one means display every label, a step of two results
in every other label being displayed (label <gap> label <gap> label),
a step of three results in every third label being displayed
(label <gap> <gap> label <gap> <gap> label) and so on.



356
357
358
 
# File 'lib/SVG/Graph/Graph.rb', line 356

def step_x_labels
  @step_x_labels
end

#style_sheet ⇒ Object

Set the path/url to an external stylesheet, set to ” if

you want to revert back to using the defaut internal version.

To create an external stylesheet create a graph using the
default internal version and copy the stylesheet section to
an external file and edit from there.



303
304
305
 
# File 'lib/SVG/Graph/Graph.rb', line 303

def style_sheet
  @style_sheet
end

#subtitle_font_size ⇒ Object

Set the subtitle font size. Defaults to 14.



438
439
440
 
# File 'lib/SVG/Graph/Graph.rb', line 438

def subtitle_font_size
  @subtitle_font_size
end

#title_font_size ⇒ Object

Set the title font size. Defaults to 16.



435
436
437
 
# File 'lib/SVG/Graph/Graph.rb', line 435

def title_font_size
  @title_font_size
end

#width ⇒ Object

Set the width of the graph box, this is the total width

of the SVG box created - not the graph it self which auto
scales to fix the space.



296
297
298
 
# File 'lib/SVG/Graph/Graph.rb', line 296

def width
  @width
end

#x_axis_position ⇒ Object

By default (nil/undefined) the x-axis is at the bottom of the graph.

With this property a custom position for the x-axis can be defined.
Valid values are between :min_scale_value and maximum value of the
data.
Default: nil



321
322
323
 
# File 'lib/SVG/Graph/Graph.rb', line 321

def x_axis_position
  @x_axis_position
end

#x_label_font_size ⇒ Object

Set the font size of the X axis labels. Defaults to 12.



423
424
425
 
# File 'lib/SVG/Graph/Graph.rb', line 423

def x_label_font_size
  @x_label_font_size
end

#x_title ⇒ Object

What the title under X axis should be, e.g. ‘Months’.



379
380
381
 
# File 'lib/SVG/Graph/Graph.rb', line 379

def x_title
  @x_title
end

#x_title_font_size ⇒ Object

Set the font size of the X axis title. Defaults to 14.



426
427
428
 
# File 'lib/SVG/Graph/Graph.rb', line 426

def x_title_font_size
  @x_title_font_size
end

#x_title_location ⇒ Object

Where the x_title should be positioned, either in the :middle of the axis or

at the :end of the axis. Defaults to :middle



382
383
384
 
# File 'lib/SVG/Graph/Graph.rb', line 382

def x_title_location
  @x_title_location
end

#y_axis_position ⇒ Object

By default (nil/undefined) the y-axis is the left border of the graph.

With this property a custom position for the y-axis can be defined.
Valid values are any values in the range of x-values (in case of a
Plot) or any of the :fields values (in case of Line/Bar Graphs, note
the '==' operator is used to find at which value to draw the axis).
Default: nil



328
329
330
 
# File 'lib/SVG/Graph/Graph.rb', line 328

def y_axis_position
  @y_axis_position
end

#y_label_font_size ⇒ Object

Set the font size of the Y axis labels. Defaults to 12.



429
430
431
 
# File 'lib/SVG/Graph/Graph.rb', line 429

def y_label_font_size
  @y_label_font_size
end

#y_title ⇒ Object

What the title under Y axis should be, e.g. ‘Sales in thousands’.



391
392
393
 
# File 'lib/SVG/Graph/Graph.rb', line 391

def y_title
  @y_title
end

#y_title_font_size ⇒ Object

Set the font size of the Y axis title. Defaults to 14.



432
433
434
 
# File 'lib/SVG/Graph/Graph.rb', line 432

def y_title_font_size
  @y_title_font_size
end

#y_title_location ⇒ Object

Where the y_title should be positioned, either in the :middle of the axis or

at the :end of the axis. Defaults to :middle



394
395
396
 
# File 'lib/SVG/Graph/Graph.rb', line 394

def y_title_location
  @y_title_location
end

#y_title_text_direction ⇒ Object

Aligns writing mode for Y axis label.

Defaults to :bt (Bottom to Top).
Change to :tb (Top to Bottom) to reverse.



389
390
391
 
# File 'lib/SVG/Graph/Graph.rb', line 389

def y_title_text_direction
  @y_title_text_direction
end

Instance Method Details

#add_data(conf) ⇒ Object

This method allows you do add data to the graph object. It can be called several times to add more data sets in.

data_sales_02 = [12, 45, 21];

graph.add_data({
  :data => data_sales_02,
  :title => 'Sales 2002'
})

Parameters:

  • conf (Hash) —

    with the following keys: :data [Array] mandatory :title [String] mandatory name of data series for legend of graph :description [Array<String>] (optional) if given, description for each datapoint (shown in popups) :shape [Array<String>] (optional) if given, DataPoint shape is chosen based on this string instead of description :url [Array<String>] (optional) if given, link will be added to each datapoint



190
191
192
193
194
195
196
 
# File 'lib/SVG/Graph/Graph.rb', line 190

def add_data(conf)
  @data ||= []
  raise "No data provided by #{conf.inspect}" unless conf[:data].is_a?(Array)

  add_data_init_or_check_optional_keys(conf, conf[:data].size)
  @data << conf
end

#add_data_init_or_check_optional_keys(conf, datasize) ⇒ Object

Checks all optional keys of the add_data method



199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
 
# File 'lib/SVG/Graph/Graph.rb', line 199

def add_data_init_or_check_optional_keys(conf, datasize)
  conf[:description] ||= Array.new(datasize)
  conf[:shape] ||= Array.new(datasize)
  conf[:url] ||= Array.new(datasize)

  if conf[:description].size != datasize
    raise "Description for popups does not have same size as provided data: #{conf[:description].size} vs #{conf[:data].size/2}"
  end

  if conf[:shape].size != datasize
    raise "Shapes for points do not have same size as provided data: #{conf[:shape].size} vs #{conf[:data].size/2}"
  end

  if conf[:url].size != datasize
    raise "URLs for points do not have same size as provided data: #{conf[:url].size} vs #{conf[:data].size/2}"
  end
end

#burn ⇒ Object

This method processes the template with the data and config which has been set and returns the resulting SVG.

This method will croak unless at least one data set has been added to the graph object.

print graph.burn



234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
 
# File 'lib/SVG/Graph/Graph.rb', line 234

def burn
  raise "No data available" unless @data.size > 0

  start_svg
  calculate_graph_dimensions
  @foreground = Element.new( "g" )
  draw_graph
  draw_titles
  draw_legend
  draw_data  # this method needs to be implemented by child classes
  @graph.add_element( @foreground )
  style

  data = ""
  @doc.write( data, 0 )

  if @config[:compress]
    if defined?(Zlib)
      inp, out = IO.pipe
      gz = Zlib::GzipWriter.new( out )
      gz.write data
      gz.close
      data = inp.read
    else
      data << "<!-- Ruby Zlib not available for SVGZ -->";
    end
  end

  return data
end

#burn_svg_only ⇒ String

Burns the graph but returns only the <svg> node as String without the Doctype and XML Declaration. This allows easy integration into existing xml documents.

Returns:

  • (String) —

    the SVG node which represents the Graph



270
271
272
273
274
275
276
277
278
 
# File 'lib/SVG/Graph/Graph.rb', line 270

def burn_svg_only
  # initialize all instance variables by burning the graph
  burn
  f = REXML::Formatters::Pretty.new(0)
  f.compact = true
  out = ''
  f.write(@root, out)
  return out
end

#clear_data ⇒ Object

This method removes all data from the object so that you can reuse it to create a new graph but with the same config options.

graph.clear_data



221
222
223
 
# File 'lib/SVG/Graph/Graph.rb', line 221

def clear_data
  @data = []
end

#to_iruby ⇒ Array

Burns the graph to an SVG string and returns it with a text/html mime type to be displayed in IRuby.

Returns:

  • (Array) —

    A 2-dimension array containing the SVg string and a mime-type. This is the format expected by IRuby.



284
285
286
 
# File 'lib/SVG/Graph/Graph.rb', line 284

def to_iruby
  ["text/html", burn_svg_only]
end