ziya 2.0.7 → 2.1.6

data/README.txt

@@ -1,6 +1,5 @@
-ziya
+=== ZiYa
     by Fernand Galiana
-    ziya.rubyforge.org
     git://github.com/derailed/ziya.git
 
 == RELEASES
@@ -17,164 +16,260 @@ ziya
           - added draw button support
           - added chart_note to annotate a chart
           - added tooltip chart support
-  
+  2.0.8 - Patches to xml/swf/5.0.7 - scroller handle fixe + Stoppped_Scolling js callback 
+          - added support for flash_to_javascript callbacks
+          - added support ids in composite charts
+          - various bug fixes 
+  2.1.0 - Refactor some of the underlying ziya code
+          - Beef up test suite
+          - changed component tree
+        - Added geographical maps support
+        - Changed the default ziyafy to install charts only by default
+          Run ziyafy --help for the various options
+        - Changed add( :composites, ... ) call to take in a hash of hash instead of id/url pair.
+          So the correct call is now of the form chart.add( :composites, :id => { :url => ... } )
+          You can now add extra attributes that will be passed to the generated image component.
+  2.1.4 - Added support for xm/swf 5.0.8
+        - Removed dependency on logging gem version
+  2.1.5 - Added ability to enhance draw and link components in subsequent stylesheets. The old
+          behavior was to simply override the whole component. Now you can keep enhancing these components
+          in higher level stylesheets.
+          
 == DESCRIPTION:
 
-ZiYa allows you to easily display graphs in your ruby based applications by leveraging
-SWF Charts (http://www.maani.us/xml_charts/index.php) and SWF gauges (http://www.maani.us/gauge/index.php). 
-This gem bundles version 5.03 and 1.6 of these flash libraries. Incorporating flash graphs or gauge in your app 
-relieves the server by allowing for delegating graph rendering to the client side. Using this gem, you will
-be able to easily create great looking charts for your application. You will also be able
-to use the charts or gauges has a navigation scheme by embedding various link in the graphical 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 ( Out of date but you'll get the basics... )
-	Documentation    : http://ziya.liquidrail.com/docs
-	Forum            : http://groups.google.com/group/ziya-plugin
-	Repositories     : http://rubyforge.org/projects/ziya 
-	                   git://github.com/derailed/ziya.git
+ZiYa allows you to easily create interactive charts, gauges and maps for your web applications. ZiYa leverages
+flash which offload heavy server side processing to the client. At the root ZiYa allows you to easily generate an
+XML files that will be downloaded to the client for rendering. Using this gem, you will be able to easily create great
+looking charts for your application. You will also be able to use the charts, gauges and maps has a navigation scheme 
+by embedding various link in the graphical components thus bringing to the table an ideal scheme for reporting and dashboard
+like applications. Your manager will love you for it !!
 
+	Blog Site     : http://ziya.liquidrail.com
+	Documentation : http://ziya.liquidrail.com/docs
+	Forum         : http://groups.google.com/group/ziya-plugin
+	Repositories  : git://github.com/derailed/ziya.git
 
 == FEATURES:
 
-*  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. A similar fee applies
-   to the gauge framework.
-
-*  We are leveraging ERB within the YAML file to provide access to the chart/gauge state. State
-   can be passed in via the options hash when the graph/gauge is generated.
-   You can also define your own methods in helpers/ziya/xxx_helper. Where xxYou can access these
-   helper methods in your style file just like you would in a rails template.
-
-*  Theme support. You can change the appearance and behavior of any charts by introducing
-   new themes under the public/charts/themes directory.
+*  Supports a wide variety of chart/gauge types, sure to fit your needs.
+*  Geographical maps. Maps can be drillable and refreshable
+*  Relieves your server load by generating the actual chart on the client side.
+*  Provides for cascading like css-styles for your charts using YAML files.
+*  Themes support. You can change the appearance and behavior of any charts by introducing new themes
 
 == REQUIREMENTS:
 
-  ZiYa depends on the logging gem version > 0.9.0  
-
-== INSTALL:
+  ZiYa depends on the following gems
   
-  On rubyforge
+  * logging
+  * color
+  
+  ZiYa comes pre-bundled with the following packages:
+  * XML/SWF charts Version 5.07 (http://www.maani.us/xml_charts/index.php)
+  * XML/SWF gauges Version 1.6  (http://www.maani.us/gauge/index.php)
+  * DIY Maps                    (http://backspace.com/mapapp/)
+  
+  XML/SWF
+    * 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, including localhost and is well worth the investment. 
+      A similar fee applies to the gauge framework.
+  
+  DIY Map
+    * This package is free for use in non-commercial applications. For commercial applications,
+    there is a $20.00 license per domain. I have chosen this package over others, as it supports
+    the interaction and configuration I was looking for, it seems stable and packs lots of features
+    for a reasonable price.
+  
+== INSTALL:
   
-  sudo gem install ziya
+  NOTE: You will need to add github as a gem source and thus will need gem version 1.3 or later
   
-  or github
+  > gem sources -a http://gems.github.com
   
-  sudo gem install derailed-ziya
+  > sudo gem install derailed-ziya
   
   cd to your application directory and issue the following command
   
-  > ziyafy
+  > ziyafy --charts
   
-  This will copy the necessary themes and flash files to run ziya in your application 
-  public/charts directory.
-      
+  This will copy the necessary themes and flash files to run ZiYa in your application 
+  public/charts directory. You can install maps and gauges components as well. Type in
+  
+  > ziyafy --help 
+    
+  To see all available options.
+              
 == SYNOPSIS:
   
-  IMPORTANT: This new gem version requires a client update to flash 9.0 and possibly you will
-  need to get a new license from XML/SWF ( $45.0 for your domain ), if you want to use
-  advanced features like links and live updates.
-  Also some api's have changed. I will try to push a new sample application and more docs in the
-  next few weeks. So make sure you try this out first in a non production environment and report
-  bugs or side effects. I'll do my best to keep up with the demand. If anyone would like to give
-  me a hand with a tutorial app or improving the docs, I am all hears...
+  This gem version requires a client update to flash 9.0 and possibly you will
+  need to get a new license from XML/SWF >= 5.0, if you want to use
+  advanced features suck as links and live updates.
   
+== Creating a ZiYa chart in a Rails 2.3 application
   
+  1 - Create a ziya.rb file under config/initializers
 
-  When using within a rails application you will need to create a ziya.rb file in your
-  config/initializers directory ( Rails 2.0 )
-  
-  ziya.rb:
-  
-    # Pull in the ZiYa gem framework
-    gem "ziya", "~> 2.0.0"
-    require 'ziya'
+      ziya.rb:
+
+        # Pull in the ZiYa gem framework
+        gem 'derailed-ziya', '= 2.1.0'
+        require 'ziya'
 
-    # Initializes the ZiYa Framework
-    Ziya.initialize( :logger      => RAILS_DEFAULT_LOGGER,
-                     :helpers_dir => File.join( File.dirname(__FILE__), %w[.. .. app helpers ziya] ),
-                     :themes_dir  => File.join( File.dirname(__FILE__), %w[.. .. public charts themes]) )  
+        # Initializes the ZiYa Framework
+        Ziya.initialize( 
+          :logger     => RAILS_DEFAULT_LOGGER,
+          :themes_dir => File.join( File.dirname(__FILE__), %w[.. .. public charts themes]) 
+        )
+
+       This will initialize the gem. You can log the output to stdout using the ZiYa bundled logger
+       or specify a file ie File.join( File.dirname(__FILE__), %w[.. log ziya.log]. If you choose to use the 
+       ZiYa logger, you can specify the :log_level option to either :warn :info :debug or :error.
+       You will need to specify your themes directory typically located under public/charts/themes or any location
+       you'll like to choose.
+      
+   3 - Create a chart controller
+   
+      blee_controller.rb:
+   
+       class BleeController < ApplicationController
+        # Load ZiYa necessary helpers
+        helper Ziya::HtmlHelpers::Charts
+        helper Ziya::YamlHelpers::Charts
+       
+        # Callback from the flash movie to get the chart's data
+        def load_chart
+          # Create a bar chart with 2 series composed of 3 data points each.
+          # Chart will be rendered using the default look and feel
+          chart = Ziya::Charts::Bar.new
+          chart.add( :axis_category_text, %w[2006 2007 2008] )
+          chart.add( :series, "Dogs", [10,20,30] )
+          chart.add( :series, "Cats", [5,15,25] )
+          respond_to do |fmt|
+            fmt.xml { render :xml => chart.to_xml }
+          end
+       end
   
-   This will initialize the gem. You can log the output to stdout as well using the ZiYa bundled logger
-   or specify a file ie File.join( File.dirname(__FILE__), %w[.. log ziya.log]. If you choose to use the 
-   ZiYa logger, you can specify the :log_level option to either :warn :info :debug or :error.
-   You will need to indicate your themes directory typically located under public/charts/themes or any location
-   you'll choose. Otherwise ZiYa will used the default themes from <<the gem ie default or commando.
-   Lastly you can specify a custom helper directory :helpers_dir, so you can use helper methods within your 
-   ZiYa stylesheets.
+   4 - Create a view
    
-   NOTE: You must create the app/helpers/ziya and public/chart/themes directory in your application
+      blee/index.html.erb:
    
-*  Creating a chart
+        # Defines the necessary tag to embed a flash movie in your html page.
+        # This will callback to your controller to fetch the necessary xml.
+        <%= ziya_chart load_chart_url -%>
    
-   blee_controller.rb
+   5 - Create a named route
    
-     class BleeController < ApplicationController
-       helper Ziya::Helper
+      config/routes.rb:
+      
+       map.load_chart '/blee/load_chart', :controller => 'blee', :action => 'load_chart'
+   
+== Styling a chart
+
+=== Basic Theme
+   
+   1 - Create a directory fred in public/charts/themes
+   2 - Create a file called column_chart.yml under the fred directory
+   2 - Edit column_chart.yml and add the following lines mind the yaml 2 space indentation!
+   
+   <%= chart :column %>
+     <%=comp :axis_category %>
+       color: ff0000
        
-       # Callback from the flash movie to get the chart's data
-       def load_chart
-         chart = Ziya::Charts::Bar.new
-         chart.add( :axis_category_text, %w[2006 2007 2008] )
-         chart.add( :series, "Dogs", [10,20,30] )
-         chart.add( :series, "Cats", [5,15,25] )
-         respond_to do |fmt|
-          fmt.xml => { render :xml => chart.to_xml }
-       end
+   3 - In fred_controller add the following directive to the chart to associate your new theme with the chart
+   
+   chart.add( :theme, 'fred' )
+   
+   4 - reload the page and you should now see the red x axis label
+   
+=== Cascading themes
+   
+   To override the default column chart theme, you may now create an instance theme. 
+   
+   1 - Create fred.yml in public/chart/themes/fred
+   
+   2 - Edit fred.yml as follows
+
+   <%= chart :column %>
+     <%=comp :axis_category %>
+       color: 00ff00
+   
+   3 - Edit your controller to indicate the instance theme name
+   
+   chart = Ziya::Charts.Column.new( nil, 'fred' )
+   
+   4 - Reload the page - The x axis category labels should now be green.
+   
+   NOTE: There are lots of setup example for themes in the ziya-galeria app at 
+   git://github.com/derailed/ziya-galeria.git. 
+   The themes component follows the xml/swf xml settings for configuration which 
+   are documented here http://www.maani.us/xml_charts/index.php?menu=Reference
+   
+=== Using theme helpers
+
+   Just like rails view template helpers, ZiYa support helpers for theme stylesheets.
+   In order to use a helper for your chart you will need to use the following steps:
+   
+   1 - Create a ziya directory under app/helpers
+   2 - Create a file called fred_helper.rb
+   3 - Edit fred_helper.rb and add the following lines
+   
+   module Ziya::FredHelper
+     def random_color
+       %w[ffaa00 aaff00 aabbff][rand(3)]
      end
-     
-   blee/index.html.erb
+   end
    
-   <%= ziya_chart load_chart_url, :size => "300x200" -%>
+   4 - Edit you theme stylesheet to call the helper method
    
-   config/routes.rb
+   In fred.yml
    
-   # Creates a named route for the chart.
-   map.load_chart '/blee/load_chart', :controller => 'blee', :action => 'load_chart'
+   <%= chart :column %>
+     <%=comp :axis_category %>
+       color: <%= random_color %>
+          
+   5 - Edit you config/initializer/ziya.rb and add the following line
+   
+      # Initializes the ZiYa Framework
+      Ziya.initialize( :logger => RAILS_DEFAULT_LOGGER,
+        :helpers_dir    => File.join( File.dirname(__FILE__), %w[.. .. app helpers ziya] ), # <-- New line !!
+        :themes_dir     => File.join( File.dirname(__FILE__), %w[.. .. public charts themes]) 
+      )
+   
+   6 - Restart your app server
+   7 - Reload the page serveral time and watch the x axis label color change
    
-* Creating a gauge
+== Creating a gauge for a rails application
 
   You will need to modify the ziya initializer and add the following directive
   
-    Ziya.initialize( :logger      => RAILS_DEFAULT_LOGGER,
-                   :helpers_dir => File.join( File.dirname(__FILE__), %w[.. .. app helpers ziya] ),
-                   :designs_dir => File.join( File.dirname(__FILE__), %w[.. .. public gauges designs] ), # => Add this !!
-                   :themes_dir  => File.join( File.dirname(__FILE__), %w[.. .. public charts themes]) )  
+    Ziya.initialize( 
+      :logger      => RAILS_DEFAULT_LOGGER,
+      :designs_dir => File.join( File.dirname(__FILE__), %w[.. .. public gauges designs] ), # => Add this !!
+      :themes_dir  => File.join( File.dirname(__FILE__), %w[.. .. public charts themes]) )  
                  
-  fred_controller.rb
+  * fred_controller.rb
   
     class FredController < ApplicationController
       def load_gauge
-        gauge = Ziya::Gauges::Base.new( @license_key, 'my_gauge' )
+        gauge = Ziya::Gauges::Base.new( LICENCE_KEY, 'my_gauge' )
          respond_to do |fmt|
           fmt.xml => { render :xml => gauge.to_xml }
          end
       end        
     end
     
-   fred/index.html.erb
+   * fred/index.html.erb
    
-   <%= ziya_gauge load_gauge_url, :size => "300x200" -%>
+   <%= ziya_gauge load_gauge_url -%>
 
-   config/routes.rb
+   * config/routes.rb
    
    # Creates a named route for the chart.
    map.load_gauge '/fred/load_gauge', :controller => 'fred', :action => 'load_gauge'
   
-  public/gauges/designs/my_gauge.yml
+  * public/gauges/designs/my_gauge.yml
 
   In the design file you will leverage the components defined in the Ziya::Gauges::Support
   package to create your gauge desgins. You gauges can be animated using rotate, scale and 
@@ -245,4 +340,4 @@ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -17,20 +17,20 @@ PROJ.url            = 'http://ziya.rubyforge.org'
 PROJ.rubyforge_name = 'ziya'            
 PROJ.description    = "Easily add charting to your rails/merb applications"
 PROJ.spec_opts      << '--color'
-PROJ.rcov_dir       = ENV['CC_BUILD_ARTIFACTS']  ? "#{ENV['CC_BUILD_ARTIFACTS']}/test_coverage" : 'coverage'  
-PROJ.rdoc_dir       = ENV['CC_BUILD_ARTIFACTS']  ? "#{ENV['CC_BUILD_ARTIFACTS']}/api_docs" : 'docs'  
+PROJ.rcov_dir       = 'coverage'  
+PROJ.rdoc_dir       = 'docs'  
 PROJ.ruby_opts      = %w[-W0]
 PROJ.version        = ::Ziya::Version.version
 PROJ.svn            = 'ziya'
 PROJ.rcov_threshold = 90.0
 PROJ.executables    = ['ziyafy']
 
-PROJ.exclude        << %w[.DS_Store$ .swo$ .swp$]
+PROJ.exclude        << %w[.DS_Store$ .swo$ .swp$ .git$]
 PROJ.tests          = FileList['test/**/test_*.rb']   
 PROJ.annotation_tags << 'BOZO'
 
 desc "Clean up artifact directories"
-task :clean do    
+task :clean do
   rcov_artifacts = File.join( File.dirname( __FILE__ ), "coverage" )
   FileUtils.rm_rf rcov_artifacts if File.exists? rcov_artifacts
   rdoc_artifacts = File.join( File.dirname( __FILE__ ), "docs" )
@@ -39,6 +39,7 @@ task :clean do
   FileUtils.rm_rf gem_artifacts if File.exists? gem_artifacts    
 end  
 
-task 'gem:package' => 'manifest:assert'
+task 'gem:package'
 
-depend_on "logging", ">= 0.9.0"
+depend_on "logging"
+depend_on "color"  , '~> 1.4.0'

data/bin/ziyafy

@@ -1,42 +1,69 @@
 #!/usr/bin/env ruby            
 require 'optparse'
 require 'ostruct'
+require 'fileutils'
 
 require File.expand_path( File.join(File.dirname(__FILE__), '..', 'lib', 'ziya') )
     
+# TODO - Use main
 module Ziya
   class Ziyafy  
     # Copy necessary ZiYa components to a ruby web application
     def initialize( argv=ARGV ) 
       option_parser = default_option_parser 
       option_parser.parse!(argv)
-      puts "Installing ZiYa artifacts in `#{options.public_dir}"        
+      puts 'You must specify at least one off --charts, --gauges or --maps' unless options.charts or options.gauges or options.maps
       copy_artifacts
     end                  
           
     # copies ziya artifacts to public app directory
     def copy_artifacts
-      source_dir = File.expand_path( File.join( File.dirname(__FILE__), %w[.. charts]) )
-      FileUtils.cp_r( source_dir, options.public_dir )
-      source_dir = File.expand_path( File.join( File.dirname(__FILE__), %w[.. gauges]) )
-      FileUtils.cp_r( source_dir, options.public_dir )      
+      %w[charts gauges maps].each do |s|
+        if options.send( s ) 
+          dest_dir = File.join( options.public_dir )
+          src_dir  = File.expand_path( File.join( File.dirname(__FILE__), %w[.. resources], s ) )
+          puts "Installing ZiYa `#{s} artifacts in `#{dest_dir}"        
+          ::FileUtils.cp_r( src_dir, dest_dir )
+         end
+      end          
     end
     
     # access the options
     def options  #:nodoc:
-      if not @options then      
+      unless @options
         @options = OpenStruct.new 
         # Unless specified copy artifacts to the public directory
-        @options.public_dir = File.join( Dir.pwd, %w[public] )
+        @options.public_dir = ::File.join( Dir.pwd, %w[public] )
+        @options.charts     = false
+        @options.gauges     = false
+        @options.maps       = false
       end
-      return @options
+      @options
     end
 
     # sets up cmd line args
     def default_option_parser #:nodoc:
-      OptionParser.new do |op|
+      ::OptionParser.new do |op|
         op.separator ""
-        op.separator "Ziyafy options"
+        op.separator "ziyafy options:"
+
+        op.on( "-c", "--charts", "Copy ZiYa charts artifacts only" ) do |dir|
+          options.charts = true
+        end
+
+        op.on( "-g", "--gauges", "Copy ZiYa gauges artifacts only" ) do |dir|
+          options.gauges = true
+        end
+
+        op.on( "-m", "--maps", "Copy ZiYa maps artifacts only" ) do |dir|
+          options.maps = true
+        end
+
+        op.on( "-a", "--all", "Copy all ZiYa artifacts" ) do |dir|
+          options.charts = true
+          options.gauges = true
+          options.maps   = true
+        end
 
         op.on( "-p", "--public_dir FILE", "The location of the public app directory." ) do |dir|
           options.public_dir = dir
@@ -47,7 +74,4 @@ module Ziya
   end
 end  
 
-Ziya::Ziyafy.new(ARGV)
-
-
-    
+Ziya::Ziyafy.new(ARGV)