README

VectorView
---------

CONTENTS
1. Overview
2. Rationale
3. History
4. Dependencies
5. Compatibility
6. Installation
7. Usage
8. Tips and Hints


1. Overview
VectorView is a plugin for Ruby on Rails that provides Ruby Vector Graphics (RVG) syntax in the views.


2. Rationale
 VectorView was written to keep View code in the views. It is still a view even though it is an image instead of an HTML page. Other techniques, such as creating a model that does the work of the rendering violate the basic principles of MVC and muddle your code. (Especially if you start putting that RVG code directly in the model itself!)


3. History
VectorView was orinally created by Michael Dotterer to produce image versions of the puzzlesin his puzzle site, http://selzzup.com


4. Dependencies
RMagick (and ImageMagick) are required. Installing these can be very complicated. Refer to the abundant help on the respective home pages and Google for help in installing these.


5. Compatibility
VectorView is compatible with Rails 2.3

VectorView has not been tested on Rails 3.0 and probably does not work. This work will be upcoming shortly.

VectorView was previously running in Rails 2.2, but this code is not available on github. If you need this code, feel free to contact mdotterer on GitHub and he will provide it.


6. Installation

You can install VectorView in two ways: as gem, or as a plugin. Installing as a gem is recommended because the plugin will complicate the dependencies of your application by requiring rmagick during environment load which will require RMagick to be installed before `rake gems:install` can be run.

6.1 Installing as a gem (Recommended)
 - Get the source: `git clone git://github.com/mdotterer/vectorview`
 - Build the gem: Navigate to where you downloaded the code and run: `gem build .gemspec`
 - Install the gem: `[sudo] gem install --local vectorview-0.0.1.gem`
 - Add the dependency to your environment.rb file with: config.gem 'vectorview'
 - Unpack the gem in your application: `rake gems:unpack GEM=vectorview`

NOTE: VectorView is pretty general, so it will work with most any version of RMagick. You should explicitly require which version of RMagick that you need in your environment.rb before VectorView is loaded.

6.2 Installing as a plugin
 - Check out the source into your plugins directory: `git clone git://github.com/mdotterer/vectorview.git vendor/plugins/vectorview`
 - Remove the git history: `rm -rf vendor/plugins/vectorview/.git`

The first step creates a clone of the git repository in the desired location.
Since you probably don't want or need all baggage of the version history, the second command removes this.

Unfortunately git does not have a way to do this in one step. (like svn export or bzr export)

7. Usage
Once installed, use the action as the following:

app/controllers/foos_controller.rb
FoosController < ApplicationController
  # ...
  def show
    # ...
    respond_to do |format|
      #...
      format.png { render :layout => false }
    end
  end
end

app/views/foos/show.png.rvg
size 250, 250
draw do |canvas|
  # Your RVG code goes here!
   canvas.background_fill = 'white'

  canvas.g.translate(100, 150).rotate(-30) do |body|
    body.styles(:fill=>'yellow', :stroke=>'black', :stroke_width=>2)
    body.ellipse(50, 30)
    body.rect(45, 20, -20, -10).skewX(-35)
 end

 canvas.g.translate(130, 83) do |head|
    head.styles(:stroke=>'black', :stroke_width=>2)
    head.circle(30).styles(:fill=>'yellow')
    head.circle(5, 10, -5).styles(:fill=>'black')
    head.polygon(30,0, 70,5, 30,10, 62,25, 23,20).styles(:fill=>'orange')
 end

 foot = RVG::Group.new do |_foot|
    _foot.path('m0,0 v30 l30,10 l5,-10, l-5,-10 l-30,10z').
          styles(:stroke_width=>2, :fill=>'orange', :stroke=>'black')
 end
 canvas.use(foot).translate(75, 188).rotate(15)
 canvas.use(foot).translate(100, 185).rotate(-15)

 canvas.text(125, 30) do |title|
     title.tspan("duck|").styles(:text_anchor=>'end', :font_size=>20,
                    :font_family=>'helvetica', :fill=>'black')
     title.tspan("type").styles(:font_size=>22,
            :font_family=>'times', :font_style=>'italic', :fill=>'red')
  end
  canvas.rect(249,249).styles(:stroke=>'blue', :fill=>'none')

end

The above example comes from http://www.simplesystems.org/RMagick/doc/rvgtut.html
In my usage of RVG I found that site extremely helpful. There are more examples and references of that site. You will only need the code dealing with the actual drawing, converting the image type and creating the RVG objects is done for you automatically.


8. Tips and Hints

RVG is by no means fast. You will probably want to take advantage of Rail's page caching mechanisim to reduce the number of times you generate images using your application.