The Software Simpleton

Rails - Day 2 - The Power of Consistency
Rails - Day 3 - Rails environments

Rails - Day 6 - Blueprint, Compass, SASS and HAML
Rails - Day 7 - Our first View
Rails - Day 8 - Down and Dirty with HAML and SASS
Rails - Day 9 - Rendering Content

In the last post, we covered off validation.

We have been using a mock application of an expense tracker to illustrate the key points. The expense records the expenses incurred running a small business.

In this post we want to finish the application off by completing our pseudo application by allowing updates and deletes of existing records.

Below is the index page of our expenses application that will allow a user to edit and delete existing expenses that we can create with our code thus far:

The edit action is analogous to the new action in that it just transfers control to a web page that will allow us to alter the details of an existing Expense model object.

As we mentioned in this post, the edit url takes the form of /expenses/123/edit.

Below is the haml created for each row in the above table:

This generates the following url:

At the moment, the haml that renders the screen below is all contained in the new.html.haml:

We want to abstract the Expense model rendering from the new.html.haml in order to reuse it from the edit.html.haml which is the template the rails runtime will look for by convention whenever a url similar to the one below is called:

/expenses/124/edit

The rails runtime will predictably look for a template named edit.html.haml by convention.

We extract the formbuilder haml and place it in a partial named _form.html.haml and update the new.html.haml to render from the partial:

The :locals => {:f => f} expression passes the formbuilder instance to the partial.

We can now easily create an edit.html.haml that will incorporate the partial:

Next we want to create an edit action in our ExpenseController that will retrieve the @expense instance from the database:

The @expense_types instance variable will contain a collection of all the ExpenseType objects that are mapped from records in the expense_types table.

With these sparse lines of code in place, we can now display an expense model that is ready for editing when we click on the edit link of one of the expense records that are displayed on the index page.

Rails routes several restful actions onto every resource that is generated by adding an entry similar to, map.resources :expenses to the routes.rb file.

The update action is the correct and obvious choice for updating our model.

The intricacies of setting up the relationships between the objects was done in the last post when we used accepts_nested_attributes_for to enable the complex Expense object to be created from the form fields submitted from the above page.

Below is the simple update action in our ExpenseController that will take care of the update or redirect to the edit and

In the above action, we are loading the expense object into memory and then calling the update_attributes method which updates all the attributes of a model from the passed in hash. If the object is invalid, the saving fill fail and false will be returned.

In the event of a successful call to update_attributes, the user will be redirected to the index page where a confirmation message will be displayed which has been placed in the flash provider.

Deleting a Model

This is probably the simplest action to complete. The delete link takes the form of the bin icon in the screenshot below.

This link is rendered from the following HAML:

=link_to "", {:action => "destroy", :id => e.id}, :method => :delete, :class => "icon-delete", :confirm => "Are you sure"

This will render an anchor tag that links to a controller action called destroy and passing in the id of the expense we want to delete. You can also see that the javascript confirm mechanism can be hooked up with the :confirm => "Are you sure" expression.

Below is the HTML that is rendered from the HAML:

<a href="/expenses/17" class="icon-delete" onclick="if (confirm('Are you sure')) { var f = document.createElement('form'); f.style.display = 'none'; this.parentNode.appendChild(f); f.method = 'POST'; f.action = this.href;var m = document.createElement('input'); m.setAttribute('type', 'hidden'); m.setAttribute('name', '_method'); m.setAttribute('value', 'delete'); f.appendChild(m);var s = document.createElement('input'); s.setAttribute('type', 'hidden'); s.setAttribute('name', 'authenticity_token'); s.setAttribute('value', 'rW75EzBpl9r103D8zdIzX18upwh1Vs5dyp9RWYhJ31E='); f.appendChild(s);f.submit(); };return false;"></a>

The above link generates a lot of javascript which constructs a form and posts it to the server that will in turn be routed to the destroy action of the ExpensesController.

This will call the following action in the ExpensesController:

We simply retrieve the expense instance and call the destroy method. We then place the confirmation message in the flash provider and redirect to the index page:

This ends my introduction to rails series.

You can download the code that I created writing these posts from github here.

Tuesday, 6 April 2010

Rails - Day 16 - Validation

Rails - Day 2 - The Power of Consistency
Rails - Day 3 - Rails environments

Rails - Day 6 - Blueprint, Compass, SASS and HAML
Rails - Day 7 - Our first View
Rails - Day 8 - Down and Dirty with HAML and SASS
Rails - Day 9 - Rendering Content

In the last post, we took a deeper look into working with a complex object and the Rails form builder.

We have been using a mock application example of an expense tracker to illustrate the key points. The expense tracker will record the expenses incurred running a small business.

The complex object in question is an Expense model object that is made up of the following structure:

Below is the form we have constructed to capture an expense structure that is created from the inputs submitted in this form:

One thing that has not been mentioned so far is how to validate the user supplied input that is sent from this form to the server. In this post we want to ensure that:

The External reference input has a value.
The posting Description input has a value
The user has selected an Expense Type from the dropdown
The net field has a valid monetary value added. The net field is an attribute of the Expense's child object ExpensePayment.

If we take our first requirement from the above, we can create the following unit test to ensure our assertions:

Notice that there is also a test to check that the expense object is valid. It is important to start from a good position and then assert failures.

In the above test, we are creating a valid @expense object and then setting the field we want to test (external_reference) to nil.

This test obviously fails as no validation instructions have been added on the Expense model.

Rails Model Validators

When developing a Ruby on Rails application it is a good idea to use ActiveRecord validators to ensure the state of a model before trying a persist it to the database. This type of validation is also known as first pass validation.

The most common approach is to use the declarative validates_xxxx_of class methods.

In order to make the above test pass, we use the validates_presence_of ActiveRecord class method to ensure an expense has an expense_payment attribute:

Our test now passes. The validates_presence_of method takes a list of attribute names that we want to ensure have non nil values.

Other similar attributes are:

We can validate the other attributes that we want to ensure are required like this:

validates_presence_of :external_reference, :description, :expense_date

But what about associated objects? How can we verify that the user has selected an ExpenseType from the dropdown. In our model, an Expense belongs to an ExpenseType.

In order to test this, we create the following test:

This type of relationship is very easy to validate.

The above test obviously fails but if we update the model to add the expense_type_id to the list of symbols passed as arguments to the validates_presence_of then all is good.

Our final two requirements concern the has_one ExpensePayment relationship. There are two things we need to test:

We need to ensure that there is an ExpensePayment child object contained within the Expense object.
We need to ensure that the contained child ExpensePayment object has a non nil name field.

As ever we create the following failing tests:

In order to make the first test pass which ensures that an expense_payment object is contained with in the Expense model, we just update the symbol list validates_presence_of to include the :expense_payment attribute

This will enable our first assertion to pass but the second assertion still fails.

The first step is to add a call to validates_presence_of class method in the ExpensePayment object and include the net attribute.

We then update the Expense object to include a call to the ActiveRecord validation class method validates_associated.

Above we can see the call to validates_associated :expense_payment which will instruct the framework to include the child object validations of the ExpensePayment model in the @expense.errors array.

With our validation tested, we now need to add the following to our new.html.haml view that will take care of displaying any validation errors:

And that is it, the error_messages_for :expense expression will display any error messages contained within the @expenses.errors array.

Below is how these error messages are displayed on the page. Obviously you would style the div containing the error messages but as this is post 16, I simply cannot be bothered:

Obviously, this type of validation is very simplistic. There are many hooks to get into this validation process for more complex scenarios. There are callbacks available on :before_save or :after_save or you can even override the validate_on_create or validate_on_update class methods.

In this post, we have discussed validation at a very high level.

In the next post, we will finish off the series by completing the update and delete actions.

Wednesday, 31 March 2010

Rails - Day 15 - Rails Forms Part II

Rails - Day 2 - The Power of Consistency
Rails - Day 3 - Rails environments

Rails - Day 6 - Blueprint, Compass, SASS and HAML
Rails - Day 7 - Our first View
Rails - Day 8 - Down and Dirty with HAML and SASS
Rails - Day 9 - Rendering Content

In the last post we introduced the rails form builder and showed how easy it is to render a simple form using a simple model object.

I want to go into much more detail with a pseudo real example because most of the posts about rails forms and ActiveRecord that I have come across illustrate exactly what I did in the last post and show how to use the form builder and a simple model object. Nearly all these examples show a simple model with a one to one mapping on a single table. This is not very real world.

In this post I want to show how to use a form builder with a slightly more complex model.

In the past few posts, we have been building up a simple application that will record the expenses a small business owner might incur.

Below is the view that is rendered from the new action of the ExpensesControlller where a user will add a new expense:

In the last post we were able to create an Expense object that captured the Paid by Director, Expense date, External reference and Posting Description attributes.

We covered ActiveRecord relationships in this post and defined the relationships between the expense object and its child objects.

The Expense model is a complex object with two child objects defined by the the relationships below.

We are now going to use the form builder to both set the and retrieve attributes of the child objects through an HTML form.

Our first step is to fill the Expense Type dropdown that you can see in the screenshot at the start of the post with any records that exist in the expense_types table.

The form builder contains a select method which works well for belongs_to relationships. The first argument of the select method is the foreign key of the belongs_to relationship which in our case is expense_type_id.

We could create a select method similar to the following which has the ActiveRecord call ExpenseType.all to the database defined in the view and I have seen this done quite a lot:

We could do that but this feels dirty and ugly. Such a call to the database has no place in our view and instead we add the following code to the new action of the ExpensesController:

The collect method of the array object will iterate over the array and provide a block that allows us to return a new array with different elements. I think I am right in saying that the map and collect methods are the same. A new array is created for each element in the original array that contains the id and name needed to render the option elements of the dropdown.

We then update our select method to use the instance variable @expense_types instead of the ActiveRecord call:

This makes me feel much better. The ExpenseType.all call is now in the controller which of course makes it a lot more testable and tidy than adding it directly to the form builder select method. We can also mock the call to ExpenseType.all which I prefer for testing purposes over direct database calls.

The select method will take care of the Expense belongs_to ExpenseType relationship.

There is also a has_one relationship that defines the association between Expense and ExpensePayment as we discussed in this post.

The ExpensePayment model object will take care of this part of the UI:

We also stated in this post that the VAT and Gross attributes are actually derived fields from the Net attribute.

The calculation for VAT is ((Net / 100) * 17.5)

The calculation for Gross is (Net + VAT).

So the only attribute we are concerned with recording from the user is the Net attribute. We should use JQuery and Ajax to update the derived fields Vat and Gross as the user inputs their values.

Nested Attributes

Nested attributes allow you to save attributes on associated records through the parent which is exactly the behaviour we want for our Expense has_one ExpensePayment relationship. By default nested attribute updating is turned off but you can enable it using the accepts_nested_attributes_for class method. When you enable nested attributes an attribute writer (property set in .NET speak) is defined on the model. The attribute writer is named after the association, which means that in our example, a new method will be dynamically added to the Expense model:expense_expense_payment=

Enabling nested attributes on a one to one association allows us to create both the Expense and Expense_payment in one go from a params hash that would be passed in from a rails form builder generated form.

In order to test this, we create the following failing test:

You can see from the above that the hash contains a child hash named :expense_payment_attributes that will represent the child ExpensePayment model object. To make the above test pass, we update the Expense model to the following:

The changes have incorporated the following:

To make the expense_payment attributes available through nested forms we need to add the :expense_payment_attributes convention to the attr_accessible method. We mentioned attr_accessible in the last pos tand this method restricts what methods can be accessed via a web form. This is often overlooked and is a potential security hole. Shame on you if your models do not include this.
We define the relationship as nested by using the accepts_nested_attributes_for method.
We have also updated the has_one statement to has_one :expense_payment, :dependent => :destroy which tells ActiveRecord to cascade the delete of the child object when the Expense is deleted.

Nested Model Form

In the view that will render the new action, we simply use the fields_for method to expose the fields of the nested model:

It is worth mentioning that we are using the text_field_tag method instead of the text_field method for the readonly attributes vat and gross.

This will generate the following HTML:

You can see that the p.text_field :net expression has generated an input text element with a name attribute of expense[expense_payment][net] which models the Expense has_one ExpenseType relationship and is what rails uses to build the params hash of the relationship.

If we inspect the params hash that is passed to the create action of the ExpenseController by adding the code raise params.to_yaml to the action, we get the following output:

You can see that the expense_payment_attributes hash is nested within the parent expense hash. This means that we can create an expense object from the form fields in our create action:

We are going to mention validation in the next post but if we now fill out the required fields and submit the form, the create action completes successfully.

In order to check that the ExpensePayment has made it into the database, we can spark up the rails console with the command ruby script/console and enter the expression ExpressionPayment.all.

We can see from the above that our relationship is successfully created.

I wanted to write this post because in my opinion, a lot of the posts on rails forms do not go into this level of detail for defining relationships.

I personally do not like having to add the accepts_nested_attributes_for method and would like the framework pick this up automatically. If anyone who knows rails better than me can suggest a better way than this or maybe argue that this way is a good way then please leave a comment.

In the next post, I am going to touch on how to validate your rails model.

Rails - Day 14 - Rails Forms Part I

Rails - Day 2 - The Power of Consistency
Rails - Day 3 - Rails environments

Rails - Day 6 - Blueprint, Compass, SASS and HAML
Rails - Day 7 - Our first View
Rails - Day 8 - Down and Dirty with HAML and SASS
Rails - Day 9 - Rendering Content