DRY Up Forms with Custom Form Builders

Revisiting Our Form

Continuing with the example from my last article, I have this simple form:

<% form_for :product, :url => products_path do |f| %>

  <div class="form_item text_field">
    <label for="product[name]">Name:</label>
    <%= f.text_field :name %>

  </div>
  <div class="form_item text_field">
    <label for="product[price]">Price:</label>
    <%= f.text_field :price %>

  </div>
  <div class="form_item text_field">
    <label for="product[features]">Features (1 per line):</label>
    <%= f.text_area :features %>

  </div>
  <div class="form_item submit_button">
    <%= f.submit "Create Product" %>
  </div>

<% end %>

Note: I changed the original form’s wrapper tags from <p> to <div>. The reason is that, if you’re using the built-in Rails error message helpers, by default it will wrap erroneous fields in <div> tags. Since <div> tags can’t nest within <p> tags, this can cause serious layout-breaking problems.

There’s a lot of duplication here in terms of the wrapper code. Each field is wrapped in a <div> with a class of form_item as well as a descriptor of what kind of field it contains. I use this information for CSS styling of specific kinds of inputs. The labels are also fairly repetitive as well, and these repetitions would become more obnoxious were this a longer form.

Removing Repetition

What if we could generate this same form code while removing the repetition? It’s possible, and Rails gives us a great hook for just this scenario by allowing us to build custom Form Builders. A custom Form Builder is simply a subclass of ActionView::Helpers::FormBuilder that can alter and extend the abilities of the regular Form Builder. In our current form, the f block variable is an instance of FormBuilder, so methods like text_field and submit are all instance methods of the FormBuilder class. Let’s override these methods to not only output the field markup, but to also output the wrapper div:

# in /helpers/application_helper.rb
class WrapperFormBuilder < ActionView::Helpers::FormBuilder
  METHODS_TO_OVERRIDE = %w{text_field text_area password_field file_field date_select datetime_select submit}

  METHODS_TO_OVERRIDE.each do |method_name|
    src =<<END_SRC

      def #{method_name}_with_wrapper(field, options={})
        # allow explicit setting of label text with options[:label]
        field_label = if '#{method_name}' == 'submit'
          '' # no label for submit inputs
        elsif options[:label]
          label(field, options.delete(:label))
        else
          label(field) + ":" # Adds colon as default
        end

        # get unwrapped field
        field_markup = #{method_name}_without_wrapper(field, options)

        # return wrapped field (@template gives us access to helper methods in this class)
        @template.content_tag(:div, field_label + field_markup, :class => "form_item #{method_name}")
      end
    END_SRC

    class_eval src, __FILE__, __LINE__
    alias_method_chain method_name.to_sym, :wrapper

  end

end

For our form, we can now implement our new class like this:

<% form_for :product, :url => products_path, :builder => WrapperFormBuilder do |f| %>

Another possibility is to create a new method to replace form_for:

# in helpers/application_helper.rb
def wrapper_form_for(name, object=nil, options={}, &proc)

  form_for(name, object, options.merge(:builder => WrapperFormBuilder), &proc)

end

Using this new helper method, our form now looks like this:

<% wrapper_form_for :product, :url => products_path do |f| %>

  <%= f.text_field :name %>
  <%= f.text_field :price %>

  <%= f.text_area :features, :label => "Features (1 per line):" %>

  <%= f.submit "Create Product" %>
<% end %>

If you need to create a form field without a wrapper (perhaps to use a non-conforming wrapper), you can still access the original methods like f.text_field_without_wrapper or f.submit_without_wrapper.

I have found custom Form Builders to be powerful tools for speeding up form development, DRYing up code and keeping consistency between forms and developers. This is a fairly basic example, but the sky is the limit for what you can implement using these techniques.

Pretty Data, Pretty Code

In my last article I wrote about using data modeling to clean up form-related code and to take advantage of powerful helpers like form_for and error_messages_for. This solves the significant problem of isolating business logic into a model class, but another problem remains — how can we make our form data pretty without trashing our model’s code with view logic?

Beautifying the Data

I have a simple Product model with rows for name, price and features. Setting and displaying the price field is tricky because I need to remove currency formatting before storing it in the database as a decimal, and I want to reformat it when displaying the current price in an ‘Edit’ form. The features field is also tricky. I want the user to enter each product feature (“Slices and Dices”, “Purees Anything”, etc.) on a separate line of the textarea and for that to be split into a serialized array that I will store in the database.

My first instinct is to create virtual attributes in my model to handle the logic of deformatting/reformatting this data. Here’s how it looks:

class Product < ActiveRecord::Base
  serialize :features, Array

  validates_presence_of :name
  validates_numericality_of :price

  # need this for formatting
  def helpers

    ActionController::Base.helpers
  end

  def price_field=(p)

    # expecting p to be something like "$4,000.00", set price to 4000.00
    p.gsub!(/[^0-9.]/, '')
    self.price = p.to_f

  end

  def price_field
    helpers.number_to_currency(self.price)

  end

  def features_field=(str)
    # expecting string with features separated by newlines
    self.features = str.split("n").collect {|f| f.strip }

  end

  def features_field
    self.features.join("n")

  end
end

<%# the product form %>
<% form_for :product, url => products_path do |f| %>

  <p class="form_item text_field">
    <label for="product[name]">Name:</label>
    <%= f.text_field :name %>

  </p>
  <p class="form_item text_field">
    <label for="product[price_field]">Price:</label>
    <%= f.text_field :price_field %>

  </p>
  <p class="form_item text_field">
    <label for="product[features_field]">Features (1 per line):</label>
    <%= f.text_area :features_field %>

  </p>
  <p class="form_item submit_button">
    <%= f.submit "Create Product" %>
  </p>

<% end %>

The good news is that we have a very simple, straightforward looking view with no logic stuffed in it. Our controller is also completely vanilla, so I didn’t bother to even show it.

Our model, however, is getting cluttered. What once was a haven for business logic is now filled with both business and view logic. I’m also a little concerned about having to use the #price_field and #features_field methods, since it adds complexity to what should be a simple object API. Will this cause confusion with my fellow programmers?

Beautifying the Code

What if we extracted the view logic into its own object? By using a presenter object as an adapter between our Product model and our form we can isolate the view logic from the business logic. Here’s how it looks:

class Product < ActiveRecord::Base

  serialize :features, Array

  validates_presence_of :name
  validates_numericality_of :price

end

class ProductPresenter
  attr_reader :product

  def initialize(product)

    @product = product
  end

  # need this for formatting
  def helpers

    ActionController::Base.helpers
  end

  # for mass assignment
  def attributes=(hash)

    hash.each_pair do |key, val|
      self.send("#{key}=".to_sym, val)

    end
  end

  def price=(p)
    # expecting p to be something like "$4,000.00", set price to 4000.00

    p.gsub!(/[^0-9.]/, '')
    @product.price = p.to_f

  end

  def price
    helpers.number_to_currency(@product.price)

  end

  def features=(str)
    # expecting string with features separated by newlines
    @product.features = str.split("n").collect {|f| f.strip }

  end

  def features
    @product.features.join("n")

  end

  # proxy all other methods to @product
  def method_missing(method_name, *args, &block)

    @product.send(method_name, *args, &block)
  end

end

class ProductsController < ApplicationController
  def new
    @product = ProductPresenter.new(Product.new)

  end

  def edit
    product = Product.find(params[:id])

    @product = ProductPresenter.new(product)
  end

  def create

    @product = ProductPresenter.new(Product.new)
    @product.attributes = params[:product]

    if @product.save
      # success
    else
      render :action => 'new'

    end
  end

  def update
    p = Product.find(params[:id])

    @product = ProductPresenter.new(p)
    @product.attributes = params[:product]

    if @product.save
      # success
    else
      render :action => 'new'

    end
  end
end

<%# the product form %>
<% form_for :product, url => products_path do |f| %>

  <p class="form_item text_field">
    <label for="product[name]">Name:</label>
    <%= f.text_field :name %>

  </p>
  <p class="form_item text_field">
    <label for="product[price]">Price:</label>
    <%= f.text_field :price %>

  </p>
  <p class="form_item text_field">
    <label for="product[features]">Features (1 per line):</label>
    <%= f.text_area :features %>

  </p>
  <p class="form_item submit_button">
    <%= f.submit "Create Product" %>
  </p>

<% end %>

Our business and view logic have been effectively separated, our form code is clearer and the controller is only slightly more complicated. Because the ProductPresenter is acting as a proxy object to its Product object, we can simply treat it like a product thanks to ‘duck typing’. While this example is a little contrived, using presenter classes can make or break your code base as you create complex model objects with equally complex visual representations.

Modeling All Form Data

Forms of Every Shape and Color

As the Web continues to develop as an interactive, read/write medium, web forms are more useful and necessary than ever. Historically speaking, forms tend to be difficult for developers — validation, error handling, field population, redirection, data modeling and storage, these all play a part in even the simplest forms.

In the Rails world, our lives were made significantly easier thanks to the form_for helper. With this helper method, the Rails developer gets a lot for free thanks to its interaction with the ActiveRecord object that is being manipulated. Between ActiveRecord validation and the intelligent field population of form_for, creating forms becomes nearly trivial.

But what about the other forms, those that are not directly manipulating an ActiveRecord object? Forms like ‘Log In’ and ‘Search’ forms? If the developer is not using the form to CRUD an ActiveRecord model instance, he suddenly finds himself back to using low level helpers like text_field_tag and enforcing validation and other business logic within the controller.

But There’s a Better Way!

All data that we receive from forms should be modeled, but we don’t always have to use an ActiveRecord model class to do it. For data that needs to be modeled but not stored in the database, we can simply use a plain ol’ Ruby class. Let’s say that we want to create a login form – it will have fields for email and password, and a checkbox for “Remember Me”. We can model this data like so:

<!–

# app/models/login.rb
class Login
  attr_reader :email, :password, :remember_me
  def initialize(params = {})
    @email = params[:email]
    @password = params[:password]
    @remember_me = params[:remember_me]
  end

  def authenticate
    # tie into User model for authentication
    user = User.authenticate(self.email, self.password)
    return user
  end
end

–>

# app/models/login.rb
class Login
  attr_reader :email, :password, :remember_me

  def initialize(params = {})
    @email = params[:email]

    @password = params[:password]
    @remember_me = params[:remember_me]

  end

  def authenticate
    # tie into User model for authentication
    user = User.authenticate(self.email, self.password)

    return user
  end
end

<!–

# app/controllers/sessions_controller.rb
class SessionsController  'new' # unsuccessful login
    end
  end
end

–>

# app/controllers/sessions_controller.rb

class SessionsController < ApplicationController
  def new
    @login = Login.new

  end

  def create
    @login = Login.new(params[:login])

    if current_user = @login.authenticate
      redirect_to successful_login_path
    else

      render :action => 'new' # unsuccessful login
    end
  end

end

<!–

<%# app/views/sessions/new %>
<% form_for :login, :url => sessions_path do |f| %>
  <p class="form_item">
    <label for="login[email]">Email</label>
    <%= f.text_field :email %>
  </p>
  <p class="form_item">
    <label for="login[password]">Password</label>
    <%= f.password_field :password %>
  </p>
  <p class="form_item">
    <label for="login[remember_me]">Remember Me</label>
    <%= f.check_box :remember_me %>
  </p>
  <p class="form_item submit_button">
    <%= f.submit "Login" %>
  </p>
<% end %>

–>

<%# app/views/sessions/new %>
<% form_for :login, :url => sessions_path do |f| %>

  <p class="form_item">
    <label for="login[email]">Email</label>
    <%= f.text_field :email %>

  </p>
  <p class="form_item">
    <label for="login[password]">Password</label>
    <%= f.password_field :password %>

  </p>
  <p class="form_item">
    <label for="login[remember_me]">Remember Me</label>
    <%= f.check_box :remember_me %>

  </p>
  <p class="form_item submit_button">
    <%= f.submit "Login" %>
  </p>

<% end %>

A Dash of Validation

The good news is that we have modeled the login data and now have a place other than the controller for login-specific logic. We are still missing validation, however. If our Login class doesn’t inherit from ActiveRecord, does that mean we need to roll our own validation methods?

Thankfully Jay Fields already did the work for us by creating the Validatable Ruby gem (sudo gem install validatable). The Validatable module can be mixed into any Ruby class and provides the same validation interface that we are accustomed to using with ActiveRecord. Now we can require both the email and password to be filled out before we even try attempt a login. Here’s our updated code:

<!–

# app/models/login.rb
class Login
  include Validatable

  validates_presence_of :email, :password

  attr_reader :email, :password, :remember_me
  def initialize(params = {})
    @email = params[:email]
    @password = params[:password]
    @remember_me = params[:remember_me]
  end

  def authenticate
    # tie into User model for authentication
    unless user = User.authenticate(self.email, self.password)
      self.errors.add(:base, "No user was found with that email and password.")
    end
    return user
  end
end

–>

# app/models/login.rb
class Login
  include Validatable

  validates_presence_of :email, :password

  attr_reader :email, :password, :remember_me
  def initialize(params = {})

    @email = params[:email]
    @password = params[:password]

    @remember_me = params[:remember_me]
  end

  def authenticate

    # tie into User model for authentication
    unless user = User.authenticate(self.email, self.password)

      self.errors.add(:base, "No user was found with that email and password.")
    end
    return user

  end
end

<!–

# app/controllers/sessions_controller.rb
class SessionsController  'new' # unsuccessful login
    end
  end
end

–>

# app/controllers/sessions_controller.rb
class SessionsController < ApplicationController

  def new
    @login = Login.new
  end

  def create

    @login = Login.new(params[:login])
    if @login.valid? && current_user = @login.authenticate

      redirect_to successful_login_path
    else
      render :action => 'new' # unsuccessful login

    end
  end
end

<!–

<%# app/views/sessions/new %>
<%= error_messages_for :login %>
<% form_for :login, :url => sessions_path do |f| %>
  <p class="form_item">
    <label for="login[email]">Email</label>
    <%= f.text_field :email %>
  </p>
  <p class="form_item">
    <label for="login[password]">Password</label>
    <%= f.password_field :password %>
  </p>
  <p class="form_item">
    <label for="login[remember_me]">Remember Me</label>
    <%= f.check_box :remember_me %>
  </p>
  <p class="form_item submit_button">
    <%= f.submit "Login" %>
  </p>
<% end %>

–>

<%# app/views/sessions/new %>

<%= error_messages_for :login %>
<% form_for :login, :url => sessions_path do |f| %>

  <p class="form_item">
    <label for="login[email]">Email</label>
    <%= f.text_field :email %>

  </p>
  <p class="form_item">
    <label for="login[password]">Password</label>
    <%= f.password_field :password %>

  </p>
  <p class="form_item">
    <label for="login[remember_me]">Remember Me</label>
    <%= f.check_box :remember_me %>

  </p>
  <p class="form_item submit_button">
    <%= f.submit "Login" %>
  </p>

<% end %>

Our Login class now can use the familiar validates_* class methods, the valid? instance method and all the facilities that come with having the errors object (like using error_messages_for).

It also becomes very easy to set default values for the login form. For example, if we wanted to ‘check’ the Remember Me box by default, we could simply change our SessionsController#new action to this:

def new
  @login = Login.new(:remember_me => true)

end

Modeling our form data in this way is a win-win scenario — we’re using good coding practices by keeping business logic out of our controller, and we’re also inheriting all the facilities that Rails provides by leveraging form_for, error_messages_for and validations.

Monkey Patching 101 – Proxy Objects

I think the most significant strength of the Ruby language is its impressive power and flexibility in metaprogramming. Affectionately dubbed “Monkey Patching” by Ruby developers, metaprogramming makes it easy to ‘hack’ existing code and frameworks like Rails for infinite customization, while making it easy to keep these hacks legible, organized and maintainable.

A powerful programming concept that Ruby makes easy to implement is the use of Proxy Objects. Since Ruby implements duck typing, a proxy object can easily step in to take the place of a regular object so long as the two share a similar object interface.

The following tutorial is the extraction of a “real world” problem that was solved with the simple implementation of a few proxy objects.

The Problem

Let’s say that we are displaying information about a collection of people in our system, and we want to display min, max and averages for the attributes of the members of that collection. An immediate solution would be to clutter up my template with code to find the statistic values, but this gets messy and puts too much logic in my view. Using some kind of helper methods would help extract the logic from the view, which would be better.

That’s still not quite what I want, though. What I would really like is to have an object that acts just like a Person, but that gives me values based on a collection of Person objects rather than just one. A nice implementation would be:

@john.age #=> 22
@jim.age #=> 48

@susan.age #=> 20
avg = AveragePerson.new([@john, @jim, @susan])

avg.age #=> 30

This approach is very strong if, for example, you’re creating a table by iterating through a collection of people. Thanks to duck typing, an AveragePerson could be slipped into a collection of Person objects and the table would be none the wiser — the average data would be displayed just the same as a single person’s data.

Creating Some Models

First, let’s whip up some quick model classes. I will simply use new Ruby classes, but the following techniques can be used with ActiveRecord classes in Rails just as easily.

class Person
  attr_accessor :name, :age, :inches, :weight

  def initialize(n, a, i, w)

    @name = n
    @age = a
    @inches = i

    @weight = w
  end
end

class AveragePerson
  def initialize(col)

    @collection = col
  end
end

Writing Some Tests

Let’s write some RSpec tests to set some goals for our AveragePerson class:

require 'rubygems'
require 'spec'

describe "People Statistics" do
  before(:each) do
    @james = Person.new("James", 23, 74, 210)

    @cheryl = Person.new("Cheryl", 47, 63, 115)

    @timmy = Person.new("Timmy", 12, 55, 87)

    @people = [@james, @cheryl, @timmy]
  end

  describe "AveragePerson" do
    before(:each) do
      @average = AveragePerson.new(@people)

    end

    it "should give the average age" do
      @average.age.should eql((@james.age + @timmy.age + @cheryl.age) / 3)

    end

    it "should give the average weight" do
      @average.weight.should eql((@james.weight + @timmy.weight + @cheryl.weight) / 3)

    end

    it "should give the average inches" do
      @average.inches.should eql((@james.inches + @timmy.inches + @cheryl.inches) / 3)

    end

    it "should be named 'Average'" do
      @average.name.should eql("Average")

    end
  end
end

Now let’s get these to pass.

A Little Proxy Magic

Per our specs, we need to add #age, #weight, #inches and #name methods to AveragePerson. This would do the trick, but it’s not DRY:

class AveragePerson
  def name
    "Average"
  end  

  def age

    total = @collection.inject(0){ |sum, person| sum += person.age }

    total / @collection.length
  end

  def weight

    total = @collection.inject(0){ |sum, person| sum += person.weight }

    total / @collection.length
  end

  def inches

    total = @collection.inject(0){ |sum, person| sum += person.inches }

    total / @collection.length
  end
end

The tests should pass now, but we have some serious repetition and need to DRY this up. It’s also not extensible — any time a method is added to Person, another would need to be added to AveragePerson.

All we’re really doing here is proxying the method that AveragePerson receives to each member of the collection, so let’s use method_missing to do this more concisely and extensibly.

class AveragePerson
  def name

    "Average"
  end  

  # proxy methods to collection, return the average of results
  def method_missing(method_name, *args, &block)

    total = @collection.inject(0){ |sum, person| sum += person.send(method_name, *args, &block) }

    total / @collection.length
  end
end

Now AveragePerson will proxy any methods it doesn’t have to its collection, add up the results and return the average. The tests still pass and we have much cleaner code.

Adding in Height

It isn’t very helpful to just tell a user how many inches tall a person is, it would be much more useful to return a string like “5ft 8in”. Let’s integrate that into the Person model and write a test for AveragePerson:

class Person
  def height

    inches_to_height(self.inches)
  end

  private

  def inches_to_height(_inches)

    ft = _inches / 12
    ins = _inches % 12

    "#{ft}ft #{ins}in"
  end
end

###

describe "AveragePerson" do

  it "should give the average height" do
    @average.height.should eql("5ft 4in")

  end
end

Though our AveragePerson object is proxying the #height method to the collection, this test crashes and burns because our #method_missing assumes that each member will return a number, not a string like “6ft 0in”. To fix this, let’s “override” AveragePerson#height.

class AveragePerson
  def height
    ft = self.inches / 12

    ins = self.inches % 12
    "#{ft}ft #{ins}in"

  end
end

The tests pass, but we still have some refactoring to do. I’ve duplicated the height display logic from Person into AveragePerson, so let’s extract this out into a module and include it in both classes:

module PersonHelper

  def height
    inches_to_height(self.inches)
  end

  def inches_to_height(_inches)

    ft = _inches / 12
    ins = _inches % 12

    "#{ft}ft #{ins}in"
  end
end

class Person
  include PersonHelper

end

class AveragePerson
  include PersonHelper
end

I can also include PersonHelper into my RSpec tests so that I can make them more legible using the #inches_to_height helper method:

describe "AveragePerson" do
  include PersonHelper
  it "should give the average height" do

    # @average.height.should eql("5ft 4in")
    @average.height.should eql(inches_to_height((@james.inches + @timmy.inches + @cheryl.inches) / 3))

  end
end

Creating Max and Min Classes

Using the same proxy techniques, we can easily build out MaxPerson and MinPerson classes. First the tests:

describe "MaxPerson" do

  before(:each) do
    @max = MaxPerson.new(@people)

  end

  it "should give the max age" do
    @max.age.should eql(@cheryl.age)

  end

  it "should give the max weight" do
    @max.weight.should eql(@james.weight)

  end

  it "should give the max inches" do
    @max.inches.should eql(@james.inches)

  end

  it "should be named 'Max'" do
    @max.name.should eql("Max")

  end

  it "should give the max height" do
    @max.height.should eql(inches_to_height(@james.inches))

  end

end

describe "MinPerson" do

  before(:each) do

    @min = MinPerson.new(@people)
  end

  it "should give the min age" do

    @min.age.should eql(@timmy.age)
  end

  it "should give the min weight" do
    @min.weight.should eql(@timmy.weight)

  end

  it "should give the min inches" do
    @min.inches.should eql(@timmy.inches)

  end

  it "should be named 'Min'" do
    pending("Needs to be implemented") do

      @min.name.should eql("Min")
    end
  end

  it "should give the min height" do
    @min.height.should eql(inches_to_height(@timmy.inches))

  end
end

And here are the classes:

class MaxPerson
  include PersonHelper

  def initialize(col)
    @collection = col
  end

  def name
    "Max"
  end

  def method_missing(method_name, *args, &block)

    @collection.inject(0) do |highest, person|
      val = person.send(method_name, *args, &block)

      highest = (val > highest) ? val : highest

    end
  end
end

class MinPerson
  include PersonHelper

  def initialize(col)
    @collection = col
  end

  def name
    "Min"
  end

  def method_missing(method_name, *args, &block)

    # assumes at least one item in the collection will return a value less than 1000000
    @collection.inject(1000000) do |lowest, person|
      val = person.send(method_name, *args, &block)

      lowest = (val < lowest) ? val : lowest

    end
  end
end

More Options with Extend

Our proxy objects are working nicely, but what if we want to access our objects a different way? Maybe it would be slicker if the collection itself had methods to instantiate these objects rather than simply instantiating them explicitly. Let’s do something like this:

@people = [@john, @jim, @susan]
@people.min_person #=> MinPerson object

@people.max_person #=> MaxPerson object
@people.avg_person #=> AveragePerson object

Here is a new describe block of tests:

describe "PeopleCollection" do
  it "should return a MinPerson" do

    @people.min_person.class.should eql(MinPerson)
  end

  it "should return a MaxPerson" do
    @people.max_person.class.should eql(MaxPerson)

  end

  it "should return an AveragePerson" do
    @people.avg_person.class.should eql(AveragePerson)

  end
end

Let’s create a module that will define these collection methods:

module PeopleCollection
  def min_person

    MinPerson.new(self)
  end

  def max_person
    MaxPerson.new(self)

  end

  def avg_person
    AveragePerson.new(self)
  end

end

One way to apply this module so that our collection will have access to these methods is to open up the Array class and include the module:

class Array

  include PeopleCollection
end

# or you can use the send hack:
# Array.send :include, PeopleCollection

I’m not sure this is what I want, though. The tests passs, but I don’t really need (or want) every single array in my app to have these methods — at best it’s sloppy, at worst I could run into conflicts. I really only want my @people collection to have this functionality, so instead I will extend that instance with my module only when I need it. Here’s the updated describe test block:

describe "PeopleCollection" do
  before(:each) do
    @people.extend PeopleCollection

  end

  it "should return a MinPerson" do
    @people.min_person.class.should eql(MinPerson)

  end

  it "should return a MaxPerson" do
    @people.max_person.class.should eql(MaxPerson)

  end

  it "should return an AveragePerson" do
    @people.avg_person.class.should eql(AveragePerson)

  end
end

I have found this to be a helpful technique when you just need to add a little extra functionality to a single object and want to keep it lightweight.

Here is the final version of the script.