ChartDirector 6.0 (Ruby Edition)
Installation
Ruby Version Compatibility
ChartDirector for Ruby requires at least Ruby 1.8, and has been tested up to Ruby 2.2 (the latest Ruby release as of the date of this document).
Extracting ChartDirector for Ruby
ChartDirector for Ruby is released as a zip file on Windows, and as a tar.gz file on Linux, FreeBSD, Solaris and Mac OS X. To use ChartDirector for Ruby, the first step is to extract the ChartDirector for Ruby distribution to an empty directory.
Running Ruby On Rails Sample Scripts
ChartDirector for Ruby comes with numerous Ruby On Rails sample scripts. They are packaged as a Ruby On Rails application in "ChartDirector/railsdemo". and is based on Rails 3.2. To try it, you would need to have Rails 3.2 or a compatible version in your Ruby system. You may then go to the "ChartDirector/railsdemo" subdirectory, and start the application using Ruby WebBrick as follows:
rails server
After starting WebBrick, you should be able to access the ChartDirector sample scripts at port 3000.
http://127.0.0.1:3000
Important Notes for Different Rails Versions
The sample Rails application is based on Rails 3.2. Because different Rails versions are not entirely compatible, if you would like to try the sample code in a different Rails version, you may need to modify them.
The followings are some of the differences between various Rails version:
- In Rails 1, HTML view files should have extension ".rhtml". In Rails 2, the extension is changed to ".html.erb", but it also supports ".rhtml". In Rails 3, ".rhtml" is no longer supported, and ".html.erb" should be used. The view files in the ChartDirector sample code use ".html.erb" as the extension.
- In Rails 1 and 2, if a variable is inserted in a view, the content is directly included in the output. For example, the content "<map>", it will be included in the output as "<map>". In Rails 3, the default is to HTML escape the variable, so "<map>" will become "<map>" in the output.
Many ChartDirector sample scripts require including dynamic HTML tags in the view. Examples are charts that include HTML image maps for tooltips and clickable hot spots, charts with track cursors and zooming and scrolling support, and realtime charts. To ensure that the dynamic HTML tags are not HTML escaped by Rails, the sample code uses the "raw" method to tell Rails 3 not to escape them. Earlier versions of Rails may not require or support the "raw" method.
- In Rails 2 and 3, by default, session variables are stored in cookies. As a result, all session variables together (including both the variable names and contents and other overhead) cannot exceed 4 Kbytes. (Rails 1 does not have this limitation.) Some ChartDirector sample scripts require larger session variables. To address this issue, in the ChartDirector sample Rails application, the session storage is configured as "active_record_store" instead of the default "cookie_store".
- In Rails 1 and 2, the default route "map.connect ':controller/:action/:id'" is enabled for a new Rails application. In Rails 3, the default route is initially commented out and therefore disabled. For convenience, the sample application uncomment and re-enables the default route in Rails 3. (This avoids the need to configure the routes for over a hundred sample controllers.)
Running Command Line Ruby Sample Scripts
In addition to Ruby On Rails sample scripts, ChartDirector for Ruby also comes with numerous command line Ruby sample scripts in "ChartDirector/rubydemo". These scripts create charts as image files. To run them, please follow the steps below to install ChartDirector for Ruby in your system first.
Using ChartDirector in Your Own Ruby or Ruby On Rails applications
The ChartDirector for Ruby library is in "ChartDirector/railsdemo/vendor". To use ChartDirector in your own Ruby or Ruby On Rails application, you need to copy the ChartDirector for Ruby library to a directory in your Ruby module search path. You may use one of the following methods:
- Run the install.rb script in the "ChartDirector" directory. This will automatically copy the ChartDirector for Ruby library to a directory in your Ruby module search path.
ruby install.rb
You may uninstall the ChartDirector for Ruby library later by using:
ruby uninstall.rb
- If you do not want to use the automatic installation script, you may manually copy *everything* in "ChartDirector/railsdemo/vendor" (including the fonts subdirectory for Linux, FreeBSD and Solaris editions of ChartDirector) to a directory in the Ruby module search path. You may use the following command to find out the directories in your Ruby module search path:
ruby -e "puts $:"
- For Ruby On Rails applications, if you do not have write access to the Ruby module search path directories, you may copy *everything* in "ChartDirector/railsdemo/vendor" (including the fonts subdirectory for Linux, FreeBSD and Solaris editions of ChartDirector) to the "vendor" subdirectory of your Ruby On Rails application.
- For standalone Ruby scripts (such as those in the "ChartDirector/rubydemo" subdirectory), if you do not have write access to the Ruby module search path directories, you may copy *everything* in "ChartDirector/railsdemo/vendor" (including the fonts subdirectory for Linux, FreeBSD and Solaris editions of ChartDirector) to the "current working directory" (that is, "ChartDirector/rubydemo" for running the sample scripts).
Installing the ChartDirector License
If you have purchased a license to use ChartDirector, you should have a license key delivered to your via email and postal mail.
If your license key is for upgrading from a previous version of ChartDirector, you need to append the upgrade license key to the previous version license key, and use the combined license key.
There are two alternative methods to install the license key.
- Create a one-line ASCII file using Notepad or other text editor, and put the license key in that line. The whole file should contain only the license key. Name that file "chartdir.lic" and put the file in the same directory as the active "libchartdir.so" (for Linux, FreeBSD, Mac OS X and Solaris) or "chartdir.dll" (for Windows), which should be in the "vendor" subdirectory (for Ruby On Rails applications), or in the directory where the ChartDirector for Ruby module is installed or copied to (eg. "/usr/local/lib/ruby/site_lib/1.8").
If the license file appears to have no effect (does not disable the yellow banner line), and you are using ChartDirector with Ruby On Rails, please make sure the web server "anonymous user" has read access to the "chartdir.lic" file. You may copy the view file "cdinfo.rhtml" (in "ChartDirector/app/views/cddemo") to the views directory of any controller, then access that view to display a diagnostic page. The page will explain why the license cannot be loaded.
Make sure your license file is called "chartdir.lic". In particular, Notepad may automatically append ".txt" to the file name when creating a new file. So even if the file is saved as "chartdir.lic", it may end up as "chartdir.lic.txt". If this is the case, please rename the file back to "chartdir.lic".
- An alternative method is to hard code the license key into the source code by using the ChartDirector.setLicenseCode API. This method is recommended if your are redistributing ChartDirector, because your customer will then be unable to see the license key (unless your software is open source).
© 2017 Advanced Software Engineering Limited. All rights reserved.