Ziya

ZiYa Plugin

Contributors: Fernand Galiana (fernand.galiana@gmail.com) – Conception and Initial implementation Delynn Berry ( delynn@gmail.com) – Conception and implementation

=== Plugin Description

ZiYa allows you to easily display graphs in your rails application by leveraging SWF Charts (http://www.maani.us/xml_charts/index.php). This plugin bundles version 4.5 of the flash library. Incorporating flash graphs in your app relieves the server by allowing for delegating graph rendering to the client side. Using this plugin, you will be able to easily create great looking charts for your application. You will also be able to use the charts has a navigation scheme by embedding various link in the chart components thus bring to the table an ideal scheme for reporting and dashboard like applications. Your managers will love you for it !!

Checkout the demo: http://ziya.liquidrail.com
Video            : http://www.youtube.com/watch?v=axIMmMHdXzo
Documentation    : http://ziya.liquidrail.com/rdoc
Forum            : http://groups.google.com/group/ziya-plugin

A Sample charting rails application can be found here:

svn co svn://rubyforge.org/var/svn/liquidrail/samples/charting

Just add mongrel ;-)

=== Plugin Releases - 0.001 Initial Drop - 0.002 – Fix issue with running on Edge – Fix issue with passing multiple params in refresh url - 0.003 – Fix – XML rendering removed trailing <to_s /> on to_s method – Added Mixed Charts ( See sample and rdocs ) – Deprecated gen_chart in favor of ziya_chart flash object tag generator – Changed flash object generation to remove embed tag. – Added support for transparent background via ziya_chart – Converted charting sample to rails 1.2 – Renamed 3D charts xxx_3D_chart to xxx_threed_chart - 0.004 – Added “-” for proper YAML class declaration – Added to_xml method. Now you should be able to have render :xml => chart.to_xml – Minor styles cleanup - 0.005 – Added wmode parameter support on ziya_chart helper. – Valid values are window/opaque/transparent. - 0.006 – Added chart stylesheets for 3D charts to the themes default and commando. – Renamed Pie3D to PieThreed for consistency - 0.007 – Added option :swf_path on ZiyaHelper to specify xml/swf root directory path - 0.008 – Added logic to not automatically prepend _chart for theme style file name if the chart class name already ends with Chart. - 0.009 – Added option on ziya_chart helper to specify :size as “400×300”. Contributed by Sam Livingston-Gray - 0.010 – Added :partial option to the to_xml method on the Chart object to facilitate chart partial updates as in live_update or link_update. This allows you to only alter part of the chart that have changed by generating a fragment of the chart and not having to drop to the raw xml. - 0.011 – Added :cache option on ziya_chart helper to attempt to cure the issue with IE displaying the chart in the middle of the canvas. Not sure if this will do it but looks promising from the limited experiments. In order to enable this option just pass in :cache => true in the ziya_chart call. The default is false. – Added :timeout option on ziya_chart helper to set a different timeout should the server call takes a long time. ex :timeout => 60 # Sets the chart timeout to 60secs - 0.012 – Printing. This is an attempt to correct the printing story in ZiYa. The XML/SWF chart lib files have been updated as well as the ZiYa html helper. You may need to clear your browser cache to force the lib update and also make sure you are running flash > 9. We have added a printing sample application to the repository : - 0.013 – Bug Fixes – Fixed typo in base chart file – Thanks Lori ! – Fixed issue with series getting the wrong chart_value_text labels - 0.014 – Bug Fix – Fixed issue with the link component not picking up the correct area component. - 0.015 – Bug Fix – Fixed ambiguity issue with :series_explode and :series_color not interpreting the values correctly. To decipher the short hand notation ie 100, 200, 300 vs the array yaml notation ie -100 -200 -300. - 0.016 – Bug Fix – Fixed issue with background color on flash movie not rendering correctly on IE6. Also added logic to default to wmode => ‘opaque’ if a bgcolor is specified. - 0.017 – Bug Fix – Fixed issue series_color being set with a single color. - 0.018 – Reved up XML/SWF framework to latest version 4.6. NOTE: Make sure you clear out your browser cache ! – Added flag on ziya_chart helper :use_stage => true/false. The default is false. This flag provides for setting up stage_width and height. There has been instances where the page layout causes the chart to be offset or not display correctly on both IE 6 and 7. We’ve found that upgrading to the latest version and setting :use_stage => true helped prevent the layout flaws on IE.

svn co svn://rubyforge.org/var/svn/liquidrail/samples/printing

You must have a valid XML/SWF charts to enable this feature.
The printing story behind XML/SWF charts is less than ideal. We are pushing on the authors to obtain corrections and patches. If you are a registered user, we encourage you to do the same.
Here is a matrix of printing scenarios we have compiled. 
We will need your help validating and completing this data going forward so please pipe in if you see different results.

Browser versions : Firefox 2.0.0.4, Safari 3.0

Printing was surfaced via a browser page print (P) or print button (PB)

Platform      Firefox(PB) Firefox(P) Safari(PB) Safari(P) IE6(BP) IE6(P) IE7(BP) IE7(P)
Windows XP    Yes         Yes        X           X        Yes     Yes    Yes     Yes
Mac OSX       Yes         No         Yes         Yes      X       X      X       X

Printing and hidden legends: One more issue on printing. The standard trick for hidden
legends was to move the legend off the screen by setting the x,y coordinated to negative
values. Unfortunately this won't work for printing. You will need to set the width, height
and font-size to zero in order to hide the legend on screen and on print medias.

- IE6 Timeout
  The infamous timeout issue with IE6 in a deployed environment. 
  Most of you have noticed that ZiYa is working great on IE6 localy, but are getting a 
  timeout once you've deployed to your server. We have added a :cache option to the 
  ziya_html helper which forces the browser to refresh the url. By default this option
  is set to false. The other issue with caching an IE6 is that you will need to setup
  your request header in your controller as follows :

def load_chart
   chart = Ziya::Charts::Bar.new
   ....
   response.headers["Cache-Control"] = "no-cache" 
   render :xml => chart.to_xml
end

=== Features

1. Allows you to style your charts just like you would an html page using css styles philosophy. Each chart can be associated with a YAML file that allows you to specify preferences based on SWF Charts properties. Chart style sheet reside under public/charts/themes. By default all styling resides under the ‘default’ directory. Each chart type may have an associated YAML file. You can either inherit the default styles or define your own by specifying an id when you create your graph. The styles will cascade thru your graph class hierarchy and override default preferences as you would in a style sheet.

NOTE: XML/SWF charts are free of charge unless you need to use special features such
as embedded links and printing. 
The package cost $45 per domain and is well worth the investment.

2. We are leveraging ERB within the YAML file to provide access to the chart state. State can be passed in via the options hash when the graph is generated. You can also define your own methods in helpers/ZiyaHelpers. You can access these helper methods in your style file just like you would in a rails template.

3. Theme support. You can change the appearance and behavior of any charts by introducing new themes under the public/charts/themes directory.

=== Steps

1. Download and install the plugin. In you rails application issue the following command

ruby script/plugin install svn://rubyforge.org/var/svn/liquidrail/plugins/ziya/trunk

2. In your controller

require 'ziya' # <- ziya class in bleecontroller pull>< ApplicationController
  include Ziya # <-- license ziya graph="Ziya::Charts::Bar.new(" def include refresh_my_graph charts> graph.to_xml  
    end
end

The code above will create a bar chart and generate the necessary xml to pass to the client
for rendering. The chart constructor can take the xml/swf charts license, a chart
name and a chart id used to lookup the chart YAML style-sheet. If no chart_id is specified
the YAML file named after the chart class name will be used. So in this case YAML styles 
will be loaded as follows:

base_chart.yml
  bar_chart.yml    
      chart_id.yml

Preferences will be overridden by the outermost YAML file.

Sorry no idiot proof validation as of yet, so pay attention to these...

The add call can have the following options:

:axis_category_text Specifies an array of value that will be displayed on the 
x or y axis depending on the type of chart.

Example: chart.add( :axis_category_text, ['Dog', 'Cat'] )

:series Specifies an array representing the data points to draw the chart from.
The next argument is the series name to will be displayed in the chart legends. Next
is an array of data points. Optionally you can override the default chart labels by 
specifying an array of label values. You can add multiple :series tags for a given chart.

Example: chart.add( :series, "Series A", [10, 60, 90], ['Temp lo', 'Temp Avg', 'Temp Hi'] )

:axis_value_text This option allows you to override the x/y axis ticks depending on the chart
type. This should be an array of strings that will label one of the chart axis.

:user_data You can pass user defined params to the chart stylesheet using this argument.
You will be able to access these values from the chart style sheets via @options hash
which allows you to provide more dynamic styling based on some given state.

Example: graph.add( :user_data, :fred, "Fred" )

Then in you chart style sheet YAML file you can access :fred

<%=comp series_color %>
  <% if @options[:fred] == "Fred" %>
     colors: ffffff,000000
  <% else %>
     colors: ff00ff,aabbcc
  <% end %>

This gives you access to infinite possibilities to change the look and feel of any
charts based on certain state.

Additionally you can define methods in a file called helpers/ziya_helper.rb as follows:

module ZiyaHelpers
  def red
    "ff0000" 
  end
end

Then in you style file you can access the helper method as follows:

<%=comp series_color %>
  colors: <=red>,000000

3. For convenience we have defined a Ziya::Helper that you can use in the view layer the define your chart element.

In your view template you would specify the following:

<%= ziya_chart( url_for( :controller => 'blee', :action => 'refresh_my_graph' ), 
                :id => 'my_chart', :bgcolor => "transparent", :width => 400, :height => 250 ) %>

4. The chart styles sheet YAML file follows the various properties that can be set on a particular chart. Please refer to the XML/SWF charts documentation.

For example, say you have a bar chart and want to override the default bar colors.
You will need to perform the following steps:

a. Specify an chart_id in the chart ctor:
    my_bar_chart = Ziya::Charts::Bar.new( license, nil, "my_bar" )

b. Create a my_bar.yml in the themes directory as follows:

<%=chart :bar_chart %> 
   <%=comp :series_color %>
     colors: ff0000,00ff00

Save and refresh your browser and you should now see your new colors...

5. Alternatively you can also specify various themes that will define your charts look and feel.

You can create a new themes directory under your public/chart/themes directory. Add the various
YAML chart styles into that directory. To access your new theme you will need to add the following
line to your controller:

class BleeController < ApplicationController
  ziya_theme 'my_theme'
  ...
end

6. That’s yet. Happy Charting !! For feature requests or questions please post on the google group forum…

NOTE: This description has been extracted from the Plugin README and so the formatting may need updating to make browser friendly