= Ruby && Openlayers

* http://gitorious/gnoxys/ropenlayer
* http://openlayers.org/

== Description:

Ropenlayer is a wrapper constructor for openlayer javascript library written in ruby. It aims to provide an easy way to build maps and display it on webs.

Ropenlayer is also an ActsAs extend module for Rails. It provides acts_as_map and acts_as_localizable_on class methods to perform geolicalization maping of objects.

At the moment, Ropenlayer gem comes with the following features.

 - Create a JS Openlayer.Map object with some options from ruby methods.
 - Manage layers and controls displayed on the map.
 - Create, by default, a marker and vectors layers for render items with icons or differents features as polygons, point or lines. more will come.
 - Ropenlayer will namescope all the outpus so several maps, with differents options on same screen are allowed.
 - Set defaul latitude, longitude and zoom,
 
Working on Rails will give also this helpers

 - acts_as_map and acts_as_localizable_on methods which perform all database storage of localization data.
 - form helpers to provide an easy way to draw and store localizations on the map.

== Before use ropenlayer

Ropenlayer is still in alpha stage, so, you should have some skills with javascript and  openlayers.

Ropenlayer comes with some rails 3 generator to download latest OpenLayer js and copy images and stylesheets on Rails applications. Also, ropenLayer has big dependencies of some rails classes (ActiveRecord and ActionView), so in order to user database backend or form helpers methods, you need to develops your application on Rails. 

Ropenlayer can work alone without Rails context, but it is not the priority ATM.

== Install

On your rails application just define ropenlayer gem

  config.gem 'ropenlayer', '~>0.3.0'

In order to use acts_as_* behavior methods, generate installer and migration on your application

  $ rails generate ropenlayer:migration
  $ rake db:migrate

Will create nodes and localizations table which are managed by Ropenlayer::Node and Ropenlayer::Localization classes, based on ActiveRecord

  $ rails generate ropenlayer:install

Will create an initializer stored on <your_app/config/initializers/ropenlayer.rb with some options. Will also download latest OpenLayer Js library, and copy default css style for map 'ropenlayer.css', and some images needed on styling and map operations.

To start using Ropenlayer, include acts_as_map method on your mapper model, for example, team

  class Team < ActiveRecord::Base

     acts_as_map :default_layer => :google_streets,

  end

In your view

  <%= @team.ropenlayer_map.to_js %>


If you want to set starting latitude / longitude, zoom, default layer, you can pass it though options Hash. For example, team can have a main office.

  class Team < ActiveRecord

     has_many :offices
     has_one  :main_office, :conditions => { :main => true }

     acts_as_map :default_layer => :google_streets, :longitude => Proc.new{|t| t.main_office.longitude }, :latitude => Proc.new{|t| t.main_office.latitude }, :zoom => 5

  end

For more options see Ropenlayer::ActsAs::Mapper


Ropenlayer also can include your relations models on the map. Just give to the nodeable model the ability to be localizable

  class Office < ActiveRecord

    belongs_to :team
    
    acts_as_localizable_on :team

  end

Now, in your mapper model, you can include this relation as nodeable.


  class Team < ActiveRecord

     has_many :offices
     has_one :main_office, :conditions => { :main => true }

     acts_as_map :default_layer => :google_streets, :longitude => Proc.new{|t| t.main_office.longitude }, :latitude => Proc.new{|t| t.main_office.latitude }, :zoom => 5
                 :nodes         => [ :offices ]

  end

Ropenlayer will displayed now on team map, offices that have enough localization info. See Ropenlayer::ActsAs::Nodeable for more info


== Working with form

Ropenlayer comes with some methods built on ActionView::Helpers::FormBuilder, so on your form.

  <%= form_for @team do |f| %>
    
    <div>
        <%= f.label :name %>
        <%= f.input_field :name %>
    </div>

    <div>
      <%= f.label :localization %>
      <%= f.map_localization %>
    </div>

    <%= f.submit %>

  <% end %>

This will render a map with automatic localization callbacks to store in hidden fields the zoom, longitude and latitude of the current map state.

To use this facility, :latitude, :longitude and :zoom options must point to a valid get and set methods on the mapper Class. For example

  class Team < ActiveRecord

     has_many :offices
     has_one :main_office, :conditions => { :main => true }

     acts_as_map :default_layer => :google_streets, :longitude => :main_office_longitude, :latitude => :main_office_latitude, :zoom => :main_office_zoom
                 :nodes         => [ :offices ]

     def main_office_longitude
        main_office.longitude
     end

     def main_office_longitude=(value)
       main_office_longitude = value
     end

     def main_office_latitude
        main_office.latitude
     end

     def main_office_latitude=(value)
       main_office.latitude = value
     end

     def main_office_longitude
        main_office.longitude
     end

     def main_office_zoom=(value)
       main_office.zoom = value
     end

  end

Also, provides to a form builder method on nodeable class to draw instance position. For example

  <%= form_for [@team, @office] do |f| %>
    
    <div>
        <%= f.label :name %>
        <%= f.input_field :name %>
    </div>
    
    <div>
        <%= f.label :address %>
        <%= f.input_field :address %>
    </div>

    <div>
      <%= f.label :localization %>
      <%= f.map_nodes_editor :team %>
    </div>

    <%= f.submit %>

  <% end %>

This will render a map with automatic localization callbacks to store the position of the node in the map. At the moment, ropenlayer can draw points, lines and polygons. Circles will be next.


== DEMO

You can take a look to cartac (http://cartac.gnoxys.net) a application we develop over ropenlayer gem.

== REQUIREMENTS:

* json_pure (~>1.2.3)
* rails (~>3.0.3)

== LICENSE:

Same as Openlayers project: http://svn.openlayers.org/trunk/openlayers/license.txt

Copyright (c) 2011 Gnoxys. info@goxys.net