Class: Ziya::Charts::Base

Inherits:
Object
  • Object
show all
Includes:
HtmlHelpers::Charts, YamlHelpers::Charts
Defined in:
lib/ziya/charts/base.rb

Overview

The mother ship of all charts. This abstract class figures out how to generate the correct xml to render the chart on the client side. It handles loading the look and feel via associated stylesheets. In order to customize the chart look and feel, you must create a theme directory in your application public/charts/themes dir. And reference it via the #add method using the :theme directive.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from YamlHelpers::Charts

#chart, #chart_url, #component, #drawing

Methods included from YamlHelpers::Base

#clazz, #indent

Methods included from HtmlHelpers::Charts

#_ziya_chart, #chart_path, #charts_swf, #charts_swf_base, #class_id, #codebase, #composite_base_url, #composite_url, #default_chart_options, #gen_composite_path, #gen_swf_path, #ziya_chart, #ziya_chart_js, #ziya_javascript_include_tag

Methods included from HtmlHelpers::Base

#escape_chars, #escape_once, #escape_url, #mime, #plugin_url, #setup_movie_size, #setup_wmode, #tag_options, #ziya_tag

Constructor Details

#initialize(license = nil, chart_id = nil) ⇒ Base

create a new chart. license – the XML/SWF charts license chart_id – the name of the chart style sheet. NOTE: If chart_id is specified the framework will attempt to load the chart styles from public/themes/theme_name/chart_id.yml



75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/ziya/charts/base.rb', line 75

def initialize( license=nil, chart_id=nil ) # :nodoc:
  @id          = chart_id
  @license     = license
  @options     = {}
  @series_desc = []
  @annotations = []
  @theme       = default_theme
  @render_mode = Base.mode_reset
  initialize_components
  load_helpers( Ziya.helpers_dir ) if Ziya.helpers_dir
end

Instance Attribute Details

#id ⇒ Object

:nodoc:



67
68
69
 
# File 'lib/ziya/charts/base.rb', line 67

def id
  @id
end

#license ⇒ Object

:nodoc:



67
68
69
 
# File 'lib/ziya/charts/base.rb', line 67

def license
  @license
end

#options ⇒ Object

:nodoc:



67
68
69
 
# File 'lib/ziya/charts/base.rb', line 67

def options
  @options
end

#size ⇒ Object

:nodoc:



67
68
69
 
# File 'lib/ziya/charts/base.rb', line 67

def size
  @size
end

#theme ⇒ Object

:nodoc:



67
68
69
 
# File 'lib/ziya/charts/base.rb', line 67

def theme
  @theme
end

#type ⇒ Object (readonly)

:nodoc:



68
69
70
 
# File 'lib/ziya/charts/base.rb', line 68

def type
  @type
end

Class Method Details

.components ⇒ Object

class component accessor…



88
89
90
 
# File 'lib/ziya/charts/base.rb', line 88

def self.components # :nodoc:
  @components
end

.mode_data ⇒ Object

don’t load stylesheets just gen code for chart..



93
94
95
 
# File 'lib/ziya/charts/base.rb', line 93

def self.mode_data() #:nodoc:
  1 
end

.mode_reset ⇒ Object

renders everything



98
99
100
 
# File 'lib/ziya/charts/base.rb', line 98

def self.mode_reset #:nodoc:
  0 
end

Instance Method Details

#add(*args) ⇒ Object

Add chart components to a given chart.

The args must contain certain keys for the chart to be displayed correctly.

Directives

  • :axis_category_text – Array of strings representing the x/y axis ticks dependending on the chart type. This value is required. In an x/y axis chart setup the category is the x axis unless the chart is a bar chart.

  • :axis_category_label – Array of strings representing the x axis labels. This is supported only for Scatter and Bubble charts. This value is optional. Specify nil for no label change.

  • :series – Specifies the series name and chart data points as an array. The series name will be used to display chart legends. You must have at least one of these tag defined. The data values may be specified as a straight up array of strings or numbers but also as an array of hash representing the data points and their attributes such as note, label, tooltip, effect, etc..

  • :axis_value_label – Array of strings representing the ticks on the x/y axis depending on the chart type. This is symmetrical to the axis_category_label tag for the opposite chart axis. Specify nil for no label change.

  • :user_data

    – Used to make user data available to the ERB templates in

    the chart stylesheet yaml file. You must specify a key symbol and an ad-hoc value. The key will be used with the @options hash to access the user data.

  • :composites – Embeds multiple charts within the given chart via the draw image component. You must specify a hash of chart_id/url pairs.

  • :chart_types – Specify the chart types per series. This option should

    only be used with Mixed Charts !!

  • :theme – Specify the use of a given named theme. The named theme must reside in a directory named equaly under your application public/charts/themes.

Examples

Setup the category axis to with 3 ticks namely 2004, 2005, 2006

my_chart.add( :axis_category_text, ['2004', '2005', '2006'] )

Plain old series with integer data points

my_chart.add( :series, "series A", [ 10, 20, 30] )

Specifying custom series labels. You may specify the following attributes in the data point hash : :note, :label, :tooltip and effects such as :shadow, :glow, etc…

my_chart.add( :series, "series A", [ { :value => 10, :label => 'l1' }, { :value => 20, :label => 'l2' } ] )



167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
 
# File 'lib/ziya/charts/base.rb', line 167

def add( *args )
  # TODO Validation categories = series, series = labels, etc...
  directive = args.shift
  case directive
    # BOZO !! Idea - could use a formatter object to specificy how you want to format this series
    when :axis_category_text
      categories = args.first.is_a?(Array) ? args.shift : []
      raise ArgumentError, "Must specify an array of categories" if categories.empty?
      # don't side effect the passed in categs
      categs = categories.clone
      categs.insert( 0, nil )
      @options[directive] = categs
    # BOZO !! Need to constrain this only scatter and bubble support this !!
    when :axis_category_label
      labels = args.first.is_a?(Array) ? args.shift : []
      raise ArgumentError, "Must specify an array of category labels" if labels.empty?
      @options[directive] = labels          
    when :composites
      composites = args.first.is_a?(Hash) ? args.shift: []
      raise ArgumentError, "Must specify a hash of id => url pairs for the composite chart(s)" if composites.empty?
      @options[directive] = composites
    when :axis_value_label
      values = args.first.is_a?(Array) ? args.shift : []
      raise ArgumentError, "Must specify an array of values" if values.empty?
      @options[directive] = values
    when :series
      series = {}
      legend = args.first.is_a?(String) ? args.shift : ""
      if args.first.is_a?( Array )
        points = args.shift || []
        raise ArgumentError, "Must specify an array of data points" if points.empty?
        # don't side effect the passed in series
        pts = points.clone
        pts.insert( 0, legend )
        series[:points] = pts
      else
        raise ArgumentError, "Must specify an array of data points"
      end
      url = args.shift          
      series[:url] = url if url
      @series_desc << series
    when :user_data
      key = args.first.is_a?(Symbol) ? args.shift : ""
      raise ArgumentError, "Must specify a key" if key.to_s.empty?
      value = args.shift
      # raise ArgumentError, "Must specify a value" if value.empty?
      @options[key] = value
    when :styles
      styles = args.first.is_a?(String) ? args.shift : ""
      raise ArgumentError, "Must specify a set of styles" if styles.to_s.empty?          
      @options[directive] = styles   
    when :chart_types
      types = args.first.is_a?(Array) ? args.shift : []
      raise ArgumentError, "Must specify a set of chart types" if types.empty?
      @options[directive] = types                        
    when :theme
      theme = args.first.is_a?(String) ? args.shift : ""
      raise ArgumentError, "Must specify a theme name" if theme.to_s.empty?          
      @theme = "#{Ziya.themes_dir}/#{theme}"
    when :mode
      @render_mode = args.first.is_a?(Integer) ? args.shift : -1
      raise ArgumentError, "Must specify a valid generation mode" if @render_mode == -1          
    else raise ArgumentError, "Invalid directive must be one of " + 
                             ":axis_category_text, :axis_value, :series, :user_data"
  end 
end

#default_theme ⇒ Object

default ZiYa theme



103
104
105
 
# File 'lib/ziya/charts/base.rb', line 103

def default_theme # :nodoc:
  File.join( Ziya.themes_dir, %w[default] )
end

#load_helpers(helper_dir) ⇒ Object

load up ERB style helpers



108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/ziya/charts/base.rb', line 108

def load_helpers( helper_dir ) # :nodoc:    
  Dir.foreach(helper_dir) do |helper_file| 
    next unless helper_file =~ /^([a-z][a-z_]*_helper).rb$/
    Ziya.logger.debug( ">>> ZiYa loading custom helper `#{$1}" )        
    # check rails env for autoloader ?
    if defined?(RAILS_ROOT) 
      require_dependency File.join(helper_dir, $1) 
    else
      require File.join(helper_dir, $1)
    end
    helper_module_name = "Ziya::" + $1.gsub(/(^|_)(.)/) { $2.upcase }        
    # helper_module_name = $1.to_s.gsub(/\/(.?)/) { "::" + $1.upcase }.gsub(/(^|_)(.)/) { $2.upcase }
    # if Ziya::Helpers.const_defined?(helper_module_name)
    Ziya.logger.debug( "Include module #{helper_module_name}")
    Ziya::Charts::Base.class_eval("include #{helper_module_name}") 
    # end
  end
end

#to_s(options = {}) ⇒ Object Also known as: to_xml

spews the graph specification to a string

:partial

You can specify this option to only update parts of the charts that have actually changed. This is useful for live update and link update where you may not need to redraw the whole chart.



238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
 
# File 'lib/ziya/charts/base.rb', line 238

def to_s( options={} )
  @partial = options[:partial] || false
  out     = ""
  @xml = Builder::XmlMarkup.new( :target => out )
  # Forces utf8 encoding on xml stream
  @xml.instruct! :xml, :version => "1.0", :encoding => "UTF-8"
  @xml.chart do
    @xml.license( @license ) unless @license.nil?
    if render_parents?
      if @type
        @xml.chart_type( @type )              
      elsif @options[:chart_types].is_a? Array and ! @options[:chart_types].empty?
        @xml.chart_type do   
          @options[:chart_types].each { |type| @xml.string( type ) }   
        end
      end
    end
    setup_lnf
    setup_series
  end
  @xml.to_s.gsub( /<to_s\/>/, '' )
  out
end