Ruby an Introduction

Ruby is the interpreted scripting language for quick and easy object-oriented programming. It has many features to process text files and to do system management tasks (as in Perl). It is simple, straight-forward, extensible, and portable.

Oh, I need to mention, it’s totally free, which means not only free of charge, but also freedom to use, copy, modify, and distribute it.

Features of Ruby

• Ruby has simple syntax, partially inspired by Eiffel and Ada.
• Ruby has exception handling features, like Java or Python, to make it easy to handle errors.
• Ruby’s operators are syntax sugar for the methods. You can redefine them easily.
• Ruby is a complete, full, pure object oriented language: OOL. This means all data in Ruby is an object, in the sense of Smalltalk: no exceptions. Example: In Ruby, the number 1 is an instance of class Fixnum.
• Ruby’s OO is carefully designed to be both complete and open for improvements. Example: Ruby has the ability to add methods to a class, or even to an instance during runtime. So, if needed, an instance of one class *can* behave differently from other instances of the same class.
• Ruby features single inheritance only, *on purpose*. But Ruby knows the concept of modules (called Categories in Objective-C). Modules are collections of methods. Every class can import a module and so gets all its methods for free. Some of us think that this is a much clearer way than multiple inheritance, which is complex, and not used very often compared with single inheritance (don’t count C++ here, as it has often no other choice due to strong type checking!).
• Ruby features true closures. Not just unnamed function, but with present variable bindings.
• Ruby features blocks in its syntax (code surrounded by ‘{‘ … ‘}’ or ‘do’ … ‘end’). These blocks can be passed to methods, or converted into closures.
• Ruby features a true mark-and-sweep garbage collector. It works with all Ruby objects. You don’t have to care about maintaining reference counts in extension libraries. This is better for your health. ;-)
• Writing C extensions in Ruby is easier than in Perl or Python, due partly to the garbage collector, and partly to the fine extension API. SWIG interface is also available.
• Integers in Ruby can (and should) be used without counting their internal representation. There *are* small integers (instances of class Fixnum) and large integers (Bignum), but you need not worry over which one is used currently. If a value is small enough, an integer is a Fixnum, otherwise it is a Bignum. Conversion occurs automatically.
• Ruby needs no variable declarations. It uses simple naming conventions to denote the scope of variables. Examples: simple ‘var’ = local variable, ‘@var’ = instance variable, ‘$var’ = global variable. So it is also not necessary to use a tiresome ‘self.’ prepended to every instance member.
• Ruby can load extension libraries dynamically if an OS allows.
• Ruby features OS independent threading. Thus, for all platforms on which Ruby runs, you also have multithreading, regardless of if the OS supports it or not, even on MS-DOS! ;-)
• Ruby is highly portable: it is developed mostly on Linux, but works on many types of UNIX, DOS, Windows 95/98/Me/NT/2000/XP, MacOS, BeOS, OS/2, etc.

Ruby Download

How to get Ruby

• The stable release ruby-1.8.5.
• The CVS branch for the development version is available. See CVS Repository Guide

Downloadable Items

• Ruby version 1.8.5 source (stable release) and its rubyforge mirror
• Stable snapshot (Thu Aug 09 04:00:52 JST 2007) is available. This is tar’ed and gzip’ed file of the latest stable CVS. It should be better than the last stable release.
• Nightly snapshot (Thu Aug 09 04:00:29 JST 2007) is available. This is tar’ed and gzip’ed file of the latest CVS. It may contain unfixed problems. (as usual ;-)
• 1.6 snapshot (Fri Dec 29 04:00:54 JST 2006) is available. This is tar’ed and gzip’ed file of the latest 1.6 CVS. If you cannot shift to 1.8 for some reasons and you want better version than last 1.6 release, use this snapshot.
• You can get Ruby-mswin32 .
• Install Ruby under Windows … A single download that contains everything you need to run Ruby under various Windows operating systems.
• Ruby on Windows (cygwin setup, djgpp, mingw)

_uacct = “UA-2597032-1″;
urchinTracker();

A picture might be worth a thousand words, but how many lines of code does it take to upload one to your Rails application? Sounds like a fun feature to tackle on a Friday. Let’s upload some mug shots. You know, to identify the goofballs around the office.

1. Install an Image Processor

We’ll need to resize the mugshots during the upload process, and we’ll also want to generate thumbnails of the mugshots to use around the site.

Image processing of this kind is best handled by native code. This means you end up either building a library for your operating system or downloading a pre-built library specific to your operating system. Then you install a Ruby library (gem) that wraps the image processing library with a Ruby API. Either way, it’s the least fun step of the entire process, so let’s get it out of the way early.

Choose from one of the following libraries:

• ImageScience: A light inline-Ruby library that only resizes images. (Wraps the FreeImage library.)
• RMagick: The grand-daddy, both in terms of advanced image processing features and memory usage. (Wraps the ImageMagick library.)
• minimagick: It’s much easier on memory than RMagick because it runs the ImageMagick command in a shell.

OK, so which library should you use? Well, given that we just need to resize images (and thumbnailing is just resizing), ImageScience is a perfect fit. If you have one of the others installed, go with it. Otherwise, spend a few minutes with the short and sweet instructions for installing ImageScience and FreeImage.

2. Download the attachment_fu Plugin

To make light work of the rest of this task, we’re going to use Rick Olson’s attachment_fu plugin. It’s a significant rewrite of his original acts_as_attachment plugin. That’s right, this isn’t Rick’s first rodeo, and it’s probably not his second. Seriously, I don’t know of a more experienced person then Rick when it comes to uploading files into Rails applications. (And he’s the king of good plugins!)

If you’re using acts_as_attachment, you might be wondering if it’s time to upgrade. It’s probably not one of those high-priority chores, but it’s definitely something you want to consider doing soon. Rick’s been working on attachment_fu for almost a year now, and polishing it smooth in production settings. It comes with a comprehensive set of tests, as well. And as you’ll see, it’s more flexible than its worthy predecessor. To top it off, the public API hasn’t changed. I converted an app this morning simply by renaming one declaration in a model from acts_as_attachment to has_attachment. Well worth the price of admission. One caveat: attachment_fu requires Rails 1.2+.

Here’s how to get it:

script/plugin install http://svn.techno-weenie.net/projects/plugins/attachment_fu/

3. Write an Upload Form

Having installed all the supporting software, it’s time to write our app. Let’s start with the upload form in the new.rhtml file:

Pretty standard form stuff, with a couple important bits. First, I’m using RESTful named routes (mugshots_paths), but it works just as well with traditional routes. Second, the form uses the file_field helper. That helper generates a Choose File button on the form. It’s important that we call the attribute :uploaded_data, as its the attribute name that attachment_fu looks for when storing the image. Third, to allow the form to accept files as POST data, the form is generated with :multipart => true. Forget either of those finer points and you’re in for a long afternoon.

4. Write a Controller

The controller is oblivious to the fact that we’re uploading images, so it’s your typical overpaid middleman. The new action displays the upload form and the create action accepts the POST data.

def new @mugshot = Mugshot.newend

def create @mugshot = Mugshot.new(params[:mugshot]) if @mugshot.save   flash[:notice] = 'Mugshot was successfully created.'   redirect_to mugshot_url(@mugshot)     else   render :action => :new endend

5. Write a Migration and Model

Next we need a MugShot model (and a corresponding database table) to store the uploaded file information. Let’s start with the migration file for the mugshots database table.

class CreateMugshots

 How did we come up with those column names?  Well, we didn't.  By convention, attachment_fu will automatically store the uploaded file information (the meta-data, if you will) in these columns. That begs the question: Where does the actual file data get stored? To answer that we need to write the MugShot model.
class Mugshot  :image,           :storage => :file_system,           :max_size => 500.kilobytes,           :resize_to => '320x200>',           :thumbnails => { :thumb => '100x100>' }

validates_as_attachment

end
Here's where the attachment_fu plugin makes you pump your fists in victory. Basically, at this point we'd rather not grovel around at the API level of whatever Ruby image library you have installed. We'd also like to program at a fairly high level and not worry about how the file information and data is stored. (We call those things implementation details when our boss is listening.)
In the has_attachment method we tell attachment_fu what to do with the uploaded image.  The options are as follows:

     :content_type - The content types that are allowed, which     defaults to all content types.  Using :image allows all     standard image types.
     :min_size - The minimum size allowed, which defaults     to 1 byte
     :max_size - The maximum size allowed, which defaults     to 1 megabyte
     :size - A range of allowed sizes, which overrides     the :min_size and :max_size options
     :resize_to - An array of width/height values, or a      geometry string for resizing the image
     :thumbnails - A set of thumbnails to generate, specified     by a hash of filename suffixes and resizing options.  This option     can be omitted if you don't need thumbnails, and you can generate more     than one thumbnail simply by adding names and sizes to the hash.
     :thumbnail_class - Sets what class (model) to use for     thumbnails, which defaults to the current class (MugShot, in this example).     You could, for example, use a different model class with a different set of     validations.
     :storage - Sets where the actual image data is stored.     Options include :file_system, :db_file, and     :s3.
     :processor - Sets what image processor to use.        Options include ImageScience, Rmagick, and     MiniMagick.  By default, it will use whatever you have installed.
     :path_prefix - Path to store the uploaded files, which     defaults to public/#{table_name} by default for the filesystem.     If you're using the S3 backend, it defaults to just #{table_name}.

We don't really want folks uploading life-sized mugshots, so calling  validates_as_attachment prevents image sizes out of range from being saved. (They're still uploaded in memory, mind you.) As well, because we set an image content type, WinZip files won't be welcome, for example.
6. The Most Wanted List
OK, so now we're off to the races: select a mugshot file using the Choose File button on the form, the mugshot image is uploaded to the server, the file metadata is stored in the mugshots database table, and the actual file data is stored in the public/mugshots directory on the server.
Now we can show a line-up of thumbnails, with each thumbnail linked to the full-size image.

The public_filename method gives us the public path to the full-size file or the thumbnail if passed the name of the thumbnail suffix (:thumb, in our case).  Given that we're using the filesystem as storage, this code ends up generating paths such as /mugshots/34/bad_man.png and /mugshots/34/bad_man_thumb.png.  Those paths are relative to the $RAILS_ROOT/public directory on our server, by default.

• The message producer can “fire and forget”, sending the message and then moving on to more important work.
• The mechanisms required for reliability are relatively simple in the producer and consumer, and the more difficult tasks (such as persistence) can be handled in the message broker.
• It is easy to add redundancy into the messaging infrastructure

For further reference, a good book on the topic is Gregor Hohpe’s Enterprise Integration Patterns

On a number of occasions I’ve started out with synchronous messaging, only to say to myself “I really want this to be reliable”. So I fire off an http request and wait for a 200. If I don’t receive a 200 after a certain amount of time, then I try again. I’ll repeat this for a few times, then I’ll give up, and log the failure somewhere.

Then I say to myself “It would be really nice to have this re-trying out-of-process”. So I add another process that receives a request for a message to be sent, sends the message, and performs any re-trying that is required. And all of a sudden, I have asynchronous messaging. Now, there’s nothing about REST that prevents asynchronous messaging, but I rarely see anyone from the Rails community talking about anything but synchronous messaging. So I thought I’d talk about how we’ve solved the problem on our project. We’ve used the ActiveMessaging plugin, originally written by some people from Thoughtworks. I’ll demonstrate ActiveMessaging here, and then over the next week or two I’ll contrast it with a JMS JRuby solution I’ve been playing around with.

Let’s say we have two Rails applications – a Customer Management application and an Order Management application. The Customer application is responsible for managing all things to do with Customers – their personal details, any communications between our business and the customers, and the customer’s user preferences. The Customer Management app has a rich view of a customer with fields such as:

• Name
• Address
• Telephone Number, etc.

The Order Management application needs to associate Orders with Customers, so that even when the Customer application is down for scheduled maintenance, orders can still be taken. The Orders app has a simple view of a Customer, with just a name and an id.

We will make the Customer application responsible for creating, updating and deleting Customers. Whenever any of these actions are performed, the Customer application notifies the Orders application with a message. The message indicates the type of action performed (create, update, or delete), and the id of the customer, so that the two ‘views’ of the Customer object (in the two different applications) can be kept in sync. The Orders application then creates, updates, or deletes its view of the customer according to the type of message that is sent.

First, we will need to setup an ActiveMQ Server. I’ve set it up locally on my machine using these instructions (I used the Linux instructions for my Macbook Pro):

http://activemq.apache.org/getting-started.html

In both of our Rails applications we will need to install the ActiveMessaging plugin:

script/plugin install http://activemessaging.googlecode.com/svn/trunk/plugins/activemessaging

ActiveMessaging provides the ability to send and receive messages. Our Customer application will send messages, and our Orders application will receive them.

For the purposes of this discussion, I will only show the ‘create’ messages, though the process would be very similar for ‘update’ and ‘delete’.

Customer application

Our Customer application has a Customer object that inherits from ActiveRecord::Base:

class Customer < ActiveRecord::Baseend

It has the following fields:

:name, :string:address, :string:telephone_number, :string:created_at, :date_time:updated_at, :date_time

Our message will be a YAML serialized message of the following simple data object:

class CustomerPayload attr_accessor :id, :name

 def initialize(params)   @id = params[:id]   @name = params[:name] endend

We use a rails observer to observe the ‘create’ event of the Customer object, construct a CustomerPayload object, serialize it, and send it via ActiveMessaging:

require ‘activemessaging/processor‘class CustomerObserver < ActiveRecord::Observer include ActiveMessaging::MessageSender observe Customer

 publishes_to :customer_queue

 def after_create(customer)   payload = YAML.dump(CustomerPayload.new(:id => customer.id, :name => customer.name))   publish :customer_queue, payload endend

To configure connection to the ActiveMQ server, I’ll need the following configuration files in both of my rails applications:

#config/broker.ymldevelopment:   adapter: stomp   login: ""   passcode: ""   host: localhost   port: 61613   reliable: false

#config/messaging.rbActiveMessaging::Gateway.define do |s|  s.queue :customer_queue, '/queue/Customer'end

And to get the observer to work, I’ll need this line in environment.rb

# Activate observers that should always be runningconfig.active_record.observers = :customer_observer

Orders application

For consuming messages, ActiveMessaging provides a directory under app called ‘processors’. In this directory of my Orders application I place my CustomerMessageProcessor:

#customer_message_processor.rbrequire 'processors/application'class CustomerMessageProcessor < ApplicationProcessor

 subscribes_to :customer_queue

 def on_message(serialized_message)   customer_payload = YAML.load(serialized_message)   customer = Customer.new(:name => customer_payload.name)   customer.id = customer_payload.id   customer.save! end

end

This class will need access to the same CustomerPayload object as the Customers application for deserialization.

In ActiveMessaging, a poller is used to poll the queue and trigger the on_message method shown above. We’ll need to start the poller in the Orders application using the following command:

script/poller run

And that’s it. If both the Orders and Customer applications are running, and have access to the ActiveMQ server, then when we create a Customer in the Customer application, it should show up in the Orders application a few moments later.

Installing is pretty straightfoward, just like the majority of Rails plugins:

script/plugin install http://opensvn.csie.org/rails_file_column/plugins/file_column/trunk

The first thing we need is to tell our model which column to use:

class Blog 

Now, if we want to include a upload mechanism in our form, we need to include some code like this:

On our views, we can use the following to show our image:

We can extend things further, like for instance, I may want to upload only “jpg” and “gif” images and I want them to have a certain size:

class Blog 

 validates_file_format_of :image, :in => ["gif", "jpg"]validates_filesize_of :image, :in => 1.kilobytes..5000.kilobytesend

Now let’s use RMagick (see previous post) to do some image manipulations, like creating two aditional images with different sizes based on the image we uploaded, one which we shall name “peq” with a 86×71 pixel dimensions and another named “med” with a 289×258 pixel dimensions, I found out from the wiki that the crop parameter conveniently preserves the center of an image, removing space from the edges to reach the target width/height ratio:

class Blog 

:store_dir => "public/images/my_stupid_place_to_keep_images_uploaded",:magick => {:versions => {       :thumb => {:crop => "1:1",  :size => "86x87!", :name => "peq"},       :normal => {:crop => "1:1", :size => "289x258!", :name=>"med"}       }     }end

So, by default file_column will save images with the following scheme:

myApp/public/[Model name]/[file_column field name]/[record id]/[image filename]

but as I showed you, it’s possible to define a different storage directory in your model.

Now let’s access the smaller images we saved with RMagick, on our views:

or

Other interesting information, you can access your image information in several ways:

>> p.image
=> “public/images/my_stupid_place_to_keep_images_uploaded/267/MyPicture.jpg”

>> p.image(”peq”)
=> “public/images/my_stupid_place_to_keep_images_uploaded/267/peq/MyPicture.jpg”

>> p.image_relative_path
=> “267/MyPicture.jpg”

>> p.image_relative_path(”peq”)
=> “267/peq/MyPicture.jpg”

>> File.basename(p.image)
=> “MyPicture.jpg”

More information on the subject:

• File_column wiki
• Uploading with File_column

There’s other alternatives for uploading images and files but I felt file_column is a good and easy solution for most cases.

A Rails plugin is either an extension or a modification of the core framework. Plugins provide:

• a way for developers to share bleeding-edge ideas without hurting the stable code base
• a segmented architecture so that units of code can be fixed or updated on their own release schedule
• an outlet for the core developers so that they don’t have to include every cool new feature under the sun

Examples of plugin usage include an ‘acts_as_taggable’ mixin for ActiveRecord objects (makes tagging trivial), ‘file_column’ for ActiveRecord (makes file uploading and image resizing easy), and ‘globalize’ (adds multilingual and internationalization support to Rails).

Further Reading

• PluginsDiscussion
• SomeImportantPluginNotes – Check your rails version before you start
• PluginsForDummies http://www.usome.com? shows the essential Ruby idea behind plugins.
• Now there are some wiki tutorials on writing plugins HowTosPlugins
• If you wrote some code or found it somewhere and you don’t know how to put it into Plugins – PluginRequests

Plugin Documentation

To find out how to use a newly installed plugin navigate to your project directory and issue the following command:

rdoc --op doc/rdoc .

this will generate complete documentation for your project, including the installed plugins it uses. You can then view the html version of this documentation by pointing your browser at yourApp/doc/rdoc.

Plugin Directory

A searchable plugin database
and RailsLodge plugin directory is also available.

Plugin Repositories

svn://rubyforge.org/var/svn/expressica/plugins/

http://soen.ca/svn/projects/rails/plugins/

http://technoweenie.stikipad.com/plugins/

http://svn.techno-weenie.net/projects/plugins/

http://svn.recentrambles.com/plugins/

http://opensvn.csie.org/rails_file_column/plugins/

http://svn.protocool.com/public/plugins/

http://tools.assembla.com/svn/breakout/breakout/vendor/plugins/

http://svn.pragprog.com/Public/plugins/

http://source.collectiveidea.com/public/rails/plugins/

https://secure.near-time.com/svn/plugins/

http://svn.inlet-media.de/svn/rails_extensions/plugins/

http://svn.viney.net.nz/things/rails/plugins/

http://svn.hasmanythrough.com/public/plugins/

http://svn.shiftnetwork.com/plugins/

svn://caboo.se/plugins/

http://svn.6brand.com/projects/plugins/

http://shanesbrain.net/svn/rails/plugins/

svn://errtheblog.com/svn/plugins/

http://svn.nkryptic.com/plugins/

http://svn.thoughtbot.com/plugins/

http://svn.webwideconsulting.com/plugins/

http://invisible.ch/svn/projects/plugins/

svn://rubyforge.org/var/svn/enum-column/plugins/

http://streamlinedframework.org:8079/streamlined/plugins/

svn://dvisionfactory.com/rails/plugins/

http://hivelogic.com/plugins/

http://mattmccray.com/svn/rails/plugins/

svn://rubyforge.org/var/svn/cartographer/plugins/

http://www.svn.recentrambles.com/plugins/

http://tanjero.com/svn/plugins/

http://filetofsole.org/svn/public/projects/rails/plugins/

http://topfunky.net/svn/plugins/

http://svn.joshpeek.com/projects/plugins/

svn://rubyforge.org/var/svn/agtools/plugins/

http://svn.aviditybytes.com/rails/plugins/

http://beautifulpixel.textdriven.com/svn/plugins/

http://mabs29.googlecode.com/svn/trunk/plugins/

http://www.codyfauser.com/svn/projects/plugins/

http://craz8.com/svn/trunk/plugins/

http://sean.treadway.info/svn/plugins/

http://svn.thebootstrapnation.com/public/plugins/

http://www.mattmccray.com/svn/rails/plugins/

svn://rubyforge.org//var/svn/validaterequest/plugins/

http://sprocket.slackworks.com/svn/rails/plugins/

http://svn.simpltry.com/plugins/

http://svn.elctech.com/svn/public/plugins/

http://xmlblog.stikipad.com/plugins/

http://www.xml-blog.com/svn/plugins/

http://svn.toolbocks.com/plugins/

http://thar.be/svn/projects/plugins/

http://code.teytek.com/rails/plugins/

http://www.infused.org/svn/plugins/

svn://rubyforge.org/var/svn/apptrain/trunk/vendor/plugins/

http://s3cachestore.googlecode.com/svn/trunk/plugins/

http://sbecker.net/shared/plugins/

http://opensvn.csie.org/macaque/plugins/

http://svn.designbyfront.com/rails/plugins/

svn://rails.bleedingtrends.com/

http://svn.rails-engines.org/plugins/

http://dev.fiatdev.com/svn/plugins/

http://john.guen.in/svn/plugins/

http://www.redhillonrails.org/svn/trunk/vendor/plugins/

svn://rubyforge.org/var/svn/actsdisjoint/plugins/

http://ajaxmessaging.googlecode.com/svn/trunk/plugins/

http://mod-i18n.googlecode.com/svn/trunk/plugins/

svn://majakari.net/public/rails/plugins/

http://svn.lightyearsoftware.com/svn/plugins

http://svn.devjavu.com/malaysia-rb/plugins/

SimpleCaptcha is a plugin for rubyonrails applications to provide the captcha functionality.
Its implementation is really simple, it requires a single line of code in view and a single line of code in controller/model. The plugin is inspired from the Tore Darell’s capthca plugin validates_captcha (Thanks for the plugin Tore!). The SimpleCaptcha has been coded from scratch where the idea of implementation and keeping it in the simplest form(writing just a single line of code), a variety of image styles, option to select the distortion level of images shows the re-invention of wheel.

Features

• Provides eight different style of images
• Can be implemented as controller based or model based
• Automated removal of old(validated and non-validated both) images.
• Now, we can add customized CSS to the image, lable and the text field
• Simple Captcha will bypass the functional/unit/integration tests, so that there will not be any mess in our test cases.
• Provides three levels of distortion of images as low, medium or high… so now, we have three levels for complexities of images.

update_attribute is now working which was a bug in the previous version, so please update your plugin by checking it out again from the SVN repository svn://rubyforge.org/var/svn/expressica/plugins/simple_captcha

Pre-requisites

1.) RMagick
RMagick is the image handling library in ruby and is required to implement the SimpleCaptcha.
RMagick is available on RubyForge

Installation

• (recommended… to sync with the latest revision.)
  SVN checkput the plugin as
  1. >>svn co svn://rubyforge.org/var/svn/expressica/plugins/simple_captcha simple_captcha

  >>svn co svn://rubyforge.org/var/svn/expressica/plugins/simple_captcha simple_captcha

Why Need for Oracle ?

Every database has its own functionalities and unique speciality to handle data. Its depend upon the developer and the specifications were the main reason for shifting databases. The aim of this article is not to analyse those things and only to expose the knolwedge how to develop an application using oracle in ruby on rails. Let’s go !

Getting started

Its assumed that your system has Oracle already. Now , we need to install the driver for oracle get connected with the rails. Its also a open source driver which can be downloaded from the site.

Click the following link to get the driver oci
http://rubyforge.org/projects/ruby-oci8/

Make sure that whether you are getting the latest driver from there. Because lots of error might be araised due to the version problems. Download the file to your system. For eg: Assume the downloaded driver file is in C: drive. The ruby command to make run the driver is

c:\> ruby ruby-oci8-1.0.0-rc3-mswin32.rb

The ruby-oci8-1.0.0-rc3-mswin32 is the downloaded file name. so make sure the file name is correct.

Configuring oracle in rails :

Different databases require different connection properties. Rails is set up to work with MySQL by default, but you want to re-configure this project to use Oracle. Change the development properties as follows. (You could change the test and production properties also, but the scope of this article doesn’t include testing or production releases.)

development:adapter: ociusername: rubypassword: rubyhost: localhost

Open the file database.yml. As a rails programmer u must known that this file is responsible for connecting database in development , testing and in the production too. Now, in the development block make changes as per above. The username and password are the fields that you have to enter corresponding to your database.

Simple Application :

I’m going to show u a sample application running rails with oracle. Application name is product. Its a very simple application likes a product catalog. User of the application can add a product, edit a product and view the list of the product using scaffold. It is assume that the reader of this article were known the scaffold concept already.

To create an application

$ rails product
$ cd product

Now the product application is created. Now the database.yml file should be configured relative to our oracle database. Edit that file as shown in below the username and password field should to varied to your system.

development:
adapter: oci
username: admin
password: admin
host: localhost

Migration :

Migration is a concept that a rails developer should come across before move ahead. Create a migration file products by

$ ruby script/generate migration products

It will create a migration file 001_product.rb in the db\migrate path of the application.
open the file and edit it as shown below

class Product
def self.up
create_table :products do |t|
t.column :name, :string, :limit => 30
t.column :description, :string
t.column :price, :integer, :null => false, :default => 0
end
end

def self.down
end
end

Type the following command to make use od the migration.

$ rake db:migrate

Now the data base is connected to rails and a tabel products is also created for our application.

Scaffolding :

The scaffolding is the basic simple concept to create a application easily. Execute the following command to create a scaffold

$ ruby script/generate scaffold product

It will create codes automatically for the add, edit and list of the products. To run the application start the server as

$ ruby script/server

That’s all. Type the following URl in the browser to view the list of products in our products table which is in our oracle database.

http://localhost:3000/products/list

Initially the table is empty and it likes to be

Products adding through the application is advisible than directly add it to the database. Once some products are added it might be shown as

The products shown here are all fake

In this tutorial, we will try to use Ajax with Rails in order to display a table of items with several functionalities :

• pagination (split the table on several pages)
• sorting (table ordering by one of its column)
• searching (selecting items to be displayed with a query)

A live demonstration of this application is available at :

http://dev.nozav.org/ajaxtable/

This is a very common task in web application development. The interest to use Ajax for this is to provide a dynamic interface which doesn’t need to reload the entire page when the table changes. The interest of using Rails is… well, if you are reading this you should already know, but Ajax is really nicely integrated with Rails, and using it is very easier with this great framework. Nevertheless, the code in this tutorial should work the traditional way (by reloading the entire page) if javascript is not available on client side. This is very important for accessibility.

The code which follows is highly inspired from several Rails wiki pages, in particular How to make a real-time search box with the Ajax helpers, and How to paginate with Ajax. I just put things together and sometimes slightly adapted the code.

Now, the warnings. I am not a Rails guru, and far from being an Ajax expert. I am a beginner in both areas. So take this document as a beginner introduction to beginners : code could be cleaner, explanations more accurate, and some things could probably have been designed more efficiently an elegantly. Moreover, as english is not my native language, you will find many faults and inaccuracies through this text. Please excuse me in advance.

Application installation and configuration

The first thing we have to do is to install and setup the application. If you already had done this before, you could probably skip this section.

Requirements

In this tutorial you are supposed to have a recent Rails version installed (at least version 1.0) and a functional database system. Here we will use sqlite, but you can replace it by the one you prefer without any problem.

Files

First, we have to create the “skeleton” of our application in the directory of our choice¹ :

$ rails ajaxtable$ cd ajaxtable

As it is a very basic application, we will use only one model, which will represent table items, and one controller for these items. We will generate the corresponding files with the Rails scripts :

$ ruby script/generate model Item$ ruby script/generate controller Item

Database

Once we have the files, we have to setup a data source. For simplicity here we will use Mysql in conjunction with Rails schema. This means that we will describe our database inside Rails and let it manage database creation.

First, we have to update the development data source in config/database.yml. Enter ur database password in password :

development: adapter: mysql database: ajaxtable_development username: root password:

Next, we will create the database by using Rails migration tools.

$ ruby script/generate migration database_creation

This should have created a db/migrate/001_database_creation.rb file in which we will define our database schema the following way :

This just defines one table named items with three columns² : a string field called name, and two integer columns called quantity and price (nothing really original, yes…).

Then, we just have to do a :

$ rake db:migrate

U can also use the following command but it shows some negotiable depreciation warnings.

$ rake migrate

And you should now have a development.db file in your db directory which is your sqlite database created by Rails with the items table inside.

Creating the model

As you probably know, a Rails application is divided into three main types of components : models, views and controllers. We will create them one by one.

The model of our application will be very simple here. In fact, as we don’t have any complex query to send to the database, it will stay the same as generated by Rails in our application installation, ie empty. So we will not touch the app/models/item.rb file.

Well, I hope this step has not been too difficult !

Creating the view

The view of our application will be split into two components : a layout, a view and a partial.

Layout

The layout is a page template which will be used to render several views. It contains some non-varying elements such as HTML header and footer, menus, design elements, etc. The utility of a layout is very limited in our example, as we will have only one page. But it is a tutorial, after all…

Here, the layout will be located in app/views/layouts/item.rhtml, and will contain something like :

An important thing here is the javascript_include_tag tag which will be replaced by the javascript libraries used by Rails to provide Ajax features.

Also note the @content_for_layout instruction, which will be replaced by the generated content when needed.

View

The view component will be used to render a particular action of our controller, which we will describe immediately after this. As it is a list action of our item controller, the view will be located in app/views/item/list.rhtml.

The content of the file will be the following :

There is nothing really complicated in the beginning. A stupid introduction text and a search form which will be used to filter items on their names.

Then, we have an image element whose id is spinner and which is hidden by default. This image will be shown briefly during Ajax operations on the page, and then hidden again when everything is finished. You can get some public domain images here :

http://mentalized.net/activity-indicators/

You have to put the chosen image file in the public/images directory of your application.

The following observe_field instruction is a bit more unusual. What this instruction does here is to add a new Ajax observer on the query field. This observer will periodically (here, every 2 seconds, look at the frequency parameter) check the content of this field and will react if this content has changed.

The action to be taken is described by the remaining parameters :

• update gives the id of the page element which will be updated. Here it is the table which encloses our partial call just a bit further in the code.
• url gives the action that will render the new HTML content to be inserted. Here the list action of our controller will handle every request.
• with indicates the way the field content will be passed to the url action. Here we will add a query parameter to our Ajax request with value equals to the content of the observed field.
• before indicates an action to be performed during the time the Ajax request is treated.
• success indicates an action to be performed when the Ajax request has been succesfully treated.

The concrete effect of all this stuff is quite simple. When the user type something in the query field, the observer will detect the new content of the field, and then generate an Ajax request sent to the server with the url and with parameters. As soon as the request is sent, the before action toggles the visibility of the spinner XHTML element, and the user can see the image. When the request answer his received, the table XHTML element is updated, and the success action hides the spinner image again.

Just for information, here is what the observe_field function returns with the given parameters :

//<![CDATA[new Form.Element.Observer('query', 2, function(element, value) {Element.show('spinner'); new Ajax.Updater('table', '/item/list', {asynchronous:true, evalScripts:true, onSuccess:function(request){Element.hide('spinner')}, parameters:'query=' + value})})//]]>

We spent some time here to detail the different options because we will meet them again in nearly all the other Ajax methods in this tutorial.

And, to finish this view description, we have a call to a partial element called items_list. We will describe this concept and its content in detail after setting up our controller.

Creating the controller

The controller will handle different kinds of requests in order to update the view by calling the model depending on the request type and its parameters.

Our Item controller will be very simple here, and will only include one action called list. We will not implement any other CRUD (Create, read, update, delete) action in this tutorial.

So here is the content of app/controllers/item_controller.rb :

Let’s explain this a bit.

Our controller only defines one action, called list. This action will have to handle every request sent to our application.

First, we define a variable called items_per_page which will represent the number of lines our table will show on each page.

Next, we define another variable called sort, depending on the request parameter of the same name. The case can be used to mask the real fields name in our database, which can be more suitable for security reasons. The reverse string in the sort parameter indicates that sorting should be made in descending order.

Then, a conditions variable is constructed if a query request parameter is present. It is an SQL-like instruction which will be used to filter our database query results based on the content of the name field.

After that, we assign the total number of items in our database matching the conditions to the @total variable.

And eventually, we find a call to the Rails paginate instruction. We give to this instruction the model it should be associated to (:items), a sort field, conditions to be applied to the query, and the number of items we want on each page. And it automagically returns us a paginator object called @items_pages and the items for the current page number (this page number is passed as a page request parameter, which is transparent here). The paginator object will be used later to display pagination links.

All we have seen for the controller until now applied to every request passed to the application, whatever its type. The most used kinds of HTTP requests are the traditional GET and POST, but Rails and Ajax can make an important use of a third type, whose name is XmlHttpRequest⁴.

This kind of request is launched by javascript, which will send it in the background via HTTP to the server. One use of the kind of request is to get a fragment of XHTML page used to update a part of the browser display, without reloading the entire page. This can give the user the impression of a fastest and more responsive interface.

That is what the final part of our controller deals with : it tests if the request it has received is of type xml_http_request⁵. In this case, it will not render the entire list view, but only a fragment of it, the now famous partial whose name is items_list.

So, as we can see, this xml_http_request test is the only “really Ajax” thing we met in the controller. That is because Ajax things are linked to the interface of our application, ie the view, and more specifically the part of it which will be managed with Ajax, ie the partial.

So, could you guess what we are going to do now ?

Creating the partial

A partial view component is used to render only a part of a page. It is very useful to separate some repeated view constructions in order to reuse them and to follow the Don’t Repeat Yourself (DRY) Rails principle. But it is also really useful with Ajax.

Indeed, the effect of our Ajax actions in this tutorial will always be to redisplay the table of items, whereas it is to change the page, the order or the search. So we will have to refresh the table, but not the entire page, otherwise an Ajax call is of very limited utility. That’s why we will separate all the elements which will have to be updated in a partial file⁶.

Partial filenames always begin with an underscore, so here our partial will be in app/views/item/_items_list.rhtml.

Its content will be the following :

Some explanations may be needed here. The partial contains the table pagination and sorting management. We will see both in a more detailed way.

Pagination helpers

In the beginning, we have a test to see if the total number of items found is greater than zero. In this case, we display this total number and then a paragraph which will be empty if there is only one page in our items pagination.

If we have more than one page of results, we clearly have to display pagination links. Rails already have methods to help dealing with them, but we will have to customize them a little. For this, we will create a helper.

A helper is a Ruby function which is used to help generating the view. The aim is to separate the code in these functions from the view itself, and to make this code reusable.

Our helpers will all be located in app/helpers/item_helper.rb. Each method in this file will be accessible from our view. If we wanted them to be usable by every view of our application, we could have put them in application_helper.rb.

Well, enough blabla, here is the code of our pagination_links_remote helper :

This method takes a paginator object as argument. This is a Rails object which keeps information about the current pagination state (number of pages, current page, etc.).

We then define a page_options hash which contains only one item called window_size. This is a parameter which tells Rails how many pages it has to show around the current one. For example, if window_size equals one, we will have something like :

1 … 5 6 7 … 13

If window_size equals 2 :

1 … 4 5 6 7 8 … 13

We could then make a call to the pagination_links function, which would generate the correct XHTML code for our links. But the problem is that it will generate “classic” XHTML links, but not the Ajax one. So we will have to redefine the links ourselves. This is done with the pagination_links_each method.

This method iterates over the pages to be displayed and then applies the block passed as its argument. Our block first defines two kinds of options :

• options are defined for the Ajax link generation. These are very similar to those defined in the observe_field element. The only new thing is the call to @params.merge, which will add the current request parameters to the link by replacing an existing page param by the page number in the block.
• html_options are just defined to generate the “classic” XHTML link, in order to let pagination work if javascript is not available.

Then, there is just a call to the link_to_remote function, which will generate the complete XHTML for our link, including the javascript and the classic XHTML href part.

Sorting helpers

Back to our partial. After the pagination links we start to define the table by itself. The definition of the table header is a bit complicated, because that is where we define the links to sort our data by a column or another. Each header cell makes use of two helpers.

The first helper is nothing but necessary. It is called sort_td_class_helper, and his only goal is to add a class="sortup" if the column is currently the one used to sort the table, or a class="sortdown" if it is used to sort in reverse order. The only utility is to allow, with CSS, to indicates to the user which column is currently used as a sorting field.

The code is nothing interesting which is already shown in the figure pagination_links_remote helper

Then, we have a second helper, called sort_link_helper which is also in that.

This helper is in fact very similar to the pagination_links_remote one, seen above. It takes two arguments :

• text, which is just the text to be displayed as the column header and sort link
• param, which is the name of the request parameter associated with the column.

The first two lines define a new variable, called key, which gets the value of the param argument, ie the sort key. The string _reverse is concatenated to it if param is already the sorting key. This is used to implement sorting in both ascending and descending order. If the user select a sort link, it will sort by ascending order ; if it selects the same link again, it will sort by descending order, and so on. You can look at the controller if you don’t find these explanations clear enough.

The rest of the helper is to define the options for the final call to the link_to_remote function. They are very similar to those of pagination_links_remote :

• the options hash, used for the javascript Ajax link, contains the url to be called to generate the new HTML, the id of the element to update, and two before and success actions to show/hide the spinner image.
• the html_options hash, used for the HTML link. It generates the content of the href attribute with the url_for Rails function.

Table body

The end of the partial just displayed our table body, with one item on each line. The only thing which may be noted here is the use of the cycle Rails function, which will automatically and alternatively add a “odd” or “even” style class to our table rows, which can be very useful to display it in a more visible way.

That’s all folks !

We have now seen every pieces of our application more or less in detail. In theory you could see the result by starting the WebRick server and point your browser to :

http://localhost:3000/item/list