Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Fall 2014/oss E1453 syy

2014-10-30T02:55:45Z

Shjoshi2: /* Concise Report on Refactoring */

'''E1453. Refactoring AssignmentsController'''

This page provides a description of the Expertiza based OSS project. This project aimed at refactoring the AssignmentsController as well as adding some missing functionality related to topics within an assignment.

'''Introduction to Expertiza''' 

[http://expertiza.ncsu.edu/ Expertiza] is a project developed using Ruby on Rails platform. It provides features like peer review, team assignments and submission of projects. This can be achieved by submitting code base, URL of hosted code on remote server and Wiki submissions. It is an open source application and the code can be cloned from [https://github.com/expertiza/expertiza github]. This application provides an efficient way to manage assignments, grades and reviews. This makes the process easier and faster when the class strength is large.

Expertiza is supported by National Science Foundation under Grant No. 0536558. Additional funding from the NCSU Learning in a Technology-Rich Environment (LITRE) program, the NCSU Faculty Center for Teaching and Learning, the NCSU STEM Initiative, and the Center for Advanced Computing and Communication.

'''Classes involved:'''
assignment_controller.rb
sign_up_sheet_controller.rb
assignment.rb
sign_up_sheet.rb

'''What they do:'''
The assignment model and controller are used to create and edit assignments. It provides tabs for rubrics, review strategy, due dates, and topics. The sign_up_sheet model and controller handle operations on the topics associated with each assignment.

'''What needs to be done:'''
The Topics tab in the Assignments --> Edit view is not usable right now. The functionality that displays topics also needs to be usable by the student view, since students also have to view the list of topics (when they sign up for a topic). Instructor and student functionality is a little different: instructors can add topics and change the number of slots, but they can’t sign up for topics. The Topics tab needs to be fixed, edit/delete topic functionality is to be added for instructors and common/duplicate code needs to be refactored.

= Problem Statement =
Currently the topics tab is not usable to the instructor when he is editing a current assignment or creating a new one. This functionality is necessary as it enables the instructor to create/delete/edit/view topics present under the selected assignment. Currently, the instructor achieves this using the pop-up menu that appears adjacent every assignment on the page that lists all the assignments. We were required to implement the topics tab.

The functionality to display the topics under an assignment is duplicated between the AssignmentController views and the SignupSheetController views. Both the instructor and the student can view the topics by selecting an assignment and we were required to remove this duplication in the views.

=Changes Made=

==Controller==

{| class="wikitable"
|-
! style="width:5%;"|Sr. No.
! style="width:13%;"|Method Name
! style="width:33%;"|Changes Made
! style="width:43%;"|Reason For Change
|- style="vertical-align:top;"
| 1
| create
| Fixed redirection after topic creation to Topics tab
| On successful creation of a topic, the action was merely redirecting to the assignments/edit view
|-
| 2
| update
| Fixed redirection after topic updation to Topics tab
| Once a topic was successfully edited, the view rendered was just a list of topics
|-
| 2
| edit
| Initialized @assignment_id variable
| The variable is used in the edit view
|-
| 2
| rowspan="3" valign="middle" |
destroy
| Renamed the 'delete' method to 'destroy'
| This was done for better Rails 4 routing compatibility
|-
| 2
| Initialized the assignment_id parameter
| This is used further on and is not passed from the link URL
|-
| 2
| Fixed redirection after topic deletion to Topics tab
| Once a topic was successfully deleted, the view rendered was just a list of topics
|}

==Views==

{| class="wikitable"
|-
! style="width:18%;"|View Name
! style="width:33%;"|Changes Made
! style="width:43%;"|Reason For Change
|- style="vertical-align:top;"
| rowspan="5" valign="middle" |
_add_signup_topcis
| Fixed title
| The page title displayed for an instructor was "Sign-up sheet for ... "
|-
| Commented out View/Manage bookmark links
| These links were broken, and according to existing code were not meant for the instructor view.
|-
| Added variable initialization for @sign_up_topics
| The variable was referenced further on in the view, which was causing an 'nil value' error
|-
| Fixed flash message rendering for new topic creation
| The flash message was rendering incorrectly with HTML tags visible on the web page
|-
| Added full path names to partial names
| The shared partials were also being used by views in the Assignments controller, so full paths were needed
|-
| _add_topics
| Added separation between the Import Topics and Manage Bookmarks links
| The two links were clumped together and it was difficult to distinguish between them
|-
| _actions
| Replaced rendering of the reserve_topic partial with the _all_actions partial
| The reserve_topic partial is no longer being used and is replaced by the newly created _all_actions partial
|-
| _all_actions
| Created this new partial
| We created the _all_actions partial to conditionally render the "Actions" table field for both instructors and students. This now also includes working links through which instructors or administrators can edit or delete topics.
|-
| _table_line
| Gave edit/delete rights to Super Admin
| The Super-Administrator user wasn't included in the list of users with these permissions
|-
| edit
| Modified title and included @assignment_id variable to be passed as a parameter variable to the update action
| The view was initially trying to access the params[:assignment_id] variable which was not getting initialized
|}

= Re-factored Code Cases =

== Case 1 : Refactoring the AssignmentsController and SignupSheetController ==

===Removing duplicate _add_signup_topics partials===
The AssignmentsController displayed topics to the instructor while he was editing an assignment. It used _add_signup_topics.html.erb partial to render topics under the topics tab. The SignupSheetController displayed topics to a student who wanted to view signup topics under an assignment. It was found that it had its own copy namely _add_signup_topcis.html.erb to display topics to the student. We wanted to have these two controllers use the same views to render the same thing which was list of topics under an assignment. We made the AssignmentsController reuse the _add_signup_topcis.html.erb partial under the SignupSheetController.

view:assignments/edit.html.erb 
This view contains all the tabs to display like general,rubrics,review_strategy, topics which are related to the selected assignment. tabs-5 is the topics tab which we are interested in.
<pre>
<div id="tabs-3">
<%= render 'assignments/edit/review_strategy' %>
</div>
<div id="tabs-4">
<%= render 'assignments/edit/due_dates' %>
</div>
<div id="tabs-5">
<%= render 'assignments/edit/add_signup_topics' %>
</div>
</pre>

===After Changes===
We have redundant code in two methods so we merged add_signup_topics_staggered and add_signup_topics into add_signup_topics. The action calls single method for both type of assignments and renders views based on condition of staggered or non-staggered assignment.

<pre>
<div id="tabs-3">
<%= render 'assignments/edit/review_strategy' %>
</div>
<div id="tabs-4">
<%= render 'assignments/edit/due_dates' %>
</div>
<div id="tabs-5">
<%= render '/sign_up_sheet/add_signup_topcis.html' %>
</div>
</pre>

=== Refactoring view code into relevant views ===
There were no edit/delete links to edit/delete a topic in the instructor view. These had to be conditionally added based on the role of the currently logged in user. This was to prevent students from editing/deleting topics and to keep instructors from signing up for a topic. This was implemented as follows.

===Adding Edit/Delete functionality to topics tab===

The current expertiza project had two views to display the Actions column in the topics table. These were _reserve_topics.html.erb and _actions.html. The first one was displaying the signup button for the student and the latter was displaying the bookmarks and rendering the _reserve_topics.html.erb after the bookmarks. On top of this we had to add the edit/delete links for the instructor. A refactor was called for. We decided to create a _all_actions.html.erb partial which had the responsibility to display the relevant actions depending upon the role of the currently logged in user. This helped us remove the separate partial to render actions pertaining to a student, namely _reserve_topics.html.erb . Also the _actions.html.erb only took care of displaying the bookmark links rather than dealing with both bookmarks and actions.

partial_view:_all_actions,html.erb
<pre>
<% if ['Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator'].include? current_user_role?.name %>
<td align="center">
<%= link_to image_tag('edit_icon.png', :border => 0, :title => 'Edit Topic', :align => 'middle'), :controller=>'sign_up_sheet', :action=> 'edit', :id => topic.id %>
<%= link_to image_tag('delete_icon.png', :border => 0, :title => 'Delete Topic', :align => 'middle'), sign_up_sheet_path(topic.id), method: :delete, data: {confirm: 'Are you sure?'} %>
<%elsif @show_actions %>
...
#Render signup button for student here. The @show_actions will be true if this partial is navigated from the SignupSheetController which is accessible only to students.
</pre>

== Case 2 : Cleaning up unused code ==
The Refactors mentioned above enable us to delete unused partials namely:

*assignments controller partials :
**_add_signup_topics.html.erb
**_reserve_topic.html.erb

*signup_sheet_controller partials :
**_reserve_topic.html.erb
 

=Steps to verify changes=

===Instructor Role===
Log into the application with the user having instructor's role (user3, password). [http://152.46.18.5:3000/ VCL application link]

1. Go to Manage -> Assignments and expand the assignments section.

2. Hover over the options symbol adjacent to the assignment and select the edit icon from the popup.

3. We have pre-created an assignment with multiple topics with id. 253, so you can click this link to edit it - http://152.46.18.5:3000/assignments/253/edit

4. Click on topics tab.

[[File:Topics tab.png]]

 
5. You can edit or delete any topic here as you are in instructor role.

[[File:Edit-topic.png]]

6. Also you can undo, redo any changes you have made.

[[File:Undo.png]]

===Student Role===
1. Log into the application with a user with Student role (user10, password).

2. We have added this student from the instructor view into assignment id. 253 that we used above. So this is accessible to the student. The name of the assignment appears in the
student view as Copy of assignment 1.

[[File:Student-view.png]]

3. Click on the Copy of assignment 1 -> SignupSheet and the student can see the edited topics for the assignment with a signup icon and no edit/delete options which are instructor specific.

[[File:Signupsheet.png]]

=See Also=
#[https://github.com/expertiza/expertiza Expertiza on GitHub]
#[https://github.com/itsmylifesoham/expertiza GitHub Project Repository Fork]
#[http://expertiza.ncsu.edu/ The live Expertiza website]
#[http://152.46.18.5:3000/ VCL link] - This might not be available after Nov. 2014
#[http://wikis.lib.ncsu.edu/index.php/Expertiza Expertiza project documentation wiki]
#[https://docs.google.com/document/d/1FZCL9KWSdVNsX9BowuZ3gxbCOJoiWX-GVLctSZei3No The OSS project requirements doc (Fall 2014 - Expertiza)]

= References=
[http://expertiza.ncsu.edu/ Expertiza] 
[http://en.wikipedia.org/wiki/Code_refactoring Code Refactoring] 
[http://en.wikipedia.org/wiki/Code_smell Code smell]

CSC/ECE 517 Fall 2014/oss E1453 syy

2014-10-30T02:01:42Z

Shjoshi2: /* Additional Learning and Future Work */

CSC/ECE 517 Fall 2014/oss E1453 syy

2014-10-30T02:01:18Z

Shjoshi2: /* References */

CSC/ECE 517 Fall 2014/oss E1453 syy

2014-10-30T02:00:31Z

Shjoshi2: /* Steps to verify changes */

File:Signupsheet.png

2014-10-30T02:00:12Z

Shjoshi2:

File:Student-view.png

2014-10-30T01:57:38Z

Shjoshi2:

File:Undo.png

2014-10-30T01:54:10Z

Shjoshi2:

CSC/ECE 517 Fall 2014/oss E1453 syy

2014-10-30T01:51:35Z

Shjoshi2: /* Steps to verify changes */

File:Edit-topic.png

2014-10-30T01:51:14Z

Shjoshi2:

CSC/ECE 517 Fall 2014/oss E1453 syy

2014-10-30T01:49:27Z

Shjoshi2: /* Steps to verify changes */

File:Topics tab.png

2014-10-30T01:49:00Z

Shjoshi2:

CSC/ECE 517 Fall 2014/oss E1453 syy

2014-10-30T01:48:32Z

Shjoshi2: /* Steps to verify changes */

CSC/ECE 517 Fall 2014/oss E1453 syy

2014-10-30T01:41:10Z

Shjoshi2: /* Steps to verify changes */

CSC/ECE 517 Fall 2014/oss E1453 syy

2014-10-30T01:39:15Z

Shjoshi2: /* Case 2 : Cleaning up unused code */

CSC/ECE 517 Fall 2014/oss E1453 syy

2014-10-30T01:38:45Z

Shjoshi2: /* After Changes */

CSC/ECE 517 Fall 2014/oss E1453 syy

2014-10-30T01:38:21Z

Shjoshi2: /* After Changes */

CSC/ECE 517 Fall 2014/oss E1453 syy

2014-10-30T01:34:30Z

Shjoshi2:

CSC/ECE 517 Fall 2014/oss E1453 syy

2014-10-30T01:31:42Z

Shjoshi2:

'''E1453. Refactoring AssignmentsController'''

This page provides a description of the Expertiza based OSS project. This project aimed at refactoring the AssignmentsController as well as adding some missing functionality related to topics within an assignment.

'''Introduction to Expertiza''' 

[http://expertiza.ncsu.edu/ Expertiza] is a project developed using Ruby on Rails platform. It provides features like peer review, team assignments and submission of projects. This can be achieved by submitting code base, URL of hosted code on remote server and Wiki submissions. It is an open source application and the code can be cloned from [https://github.com/expertiza/expertiza github]. This application provides an efficient way to manage assignments, grades and reviews. This makes the process easier and faster when the class strength is large.

Expertiza is supported by National Science Foundation under Grant No. 0536558. Additional funding from the NCSU Learning in a Technology-Rich Environment (LITRE) program, the NCSU Faculty Center for Teaching and Learning, the NCSU STEM Initiative, and the Center for Advanced Computing and Communication.

'''Classes involved:'''
assignment_controller.rb
sign_up_sheet_controller.rb
assignment.rb
sign_up_sheet.rb

'''What they do:'''
The assignment model and controller are used to create and edit assignments. It provides tabs for rubrics, review strategy, due dates, and topics. The sign_up_sheet model and controller handle operations on the topics associated with each assignment.

'''What needs to be done:'''
The Topics tab in the Assignments --> Edit view is not usable right now. The functionality that displays topics also needs to be usable by the student view, since students also have to view the list of topics (when they sign up for a topic). Instructor and student functionality is a little different: instructors can add topics and change the number of slots, but they can’t sign up for topics. The Topics tab needs to be fixed, edit/delete topic functionality is to be added for instructors and common/duplicate code needs to be refactored.

= Problem Statement =
Currently the topics tab is not usable to the instructor when he is editing a current assignment or creating a new one. This functionality is necessary as it enables the instructor to create/delete/edit/view topics present under the selected assignment. Currently, the instructor achieves this using the pop-up menu that appears adjacent every assignment on the page that lists all the assignments. We were required to implement the topics tab.

The functionality to display the topics under an assignment is duplicated between the AssignmentController views and the SignupSheetController views. Both the instructor and the student can view the topics by selecting an assignment and we were required to remove this duplication in the views.

= Re-factored Code Cases =

== Case 1 : Refactoring the AssignmentsController and SignupSheetController ==

===Removing duplicate _add_signup_topics partials===
The AssignmentsController displayed topics to the instructor while he was editing an assignment. It used _add_signup_topics.html.erb partial to render topics under the topics tab. The SignupSheetController displayed topics to a student who wanted to view signup topics under an assignment. It was found that it had its own copy namely _add_signup_topcis.html.erb to display topics to the student. We wanted to have these two controllers use the same views to render the same thing which was list of topics under an assignment. We made the AssignmentsController reuse the _add_signup_topcis.html.erb partial under the SignupSheetController.

view:assignments/edit.html.erb 
This view contains all the tabs to display like general,rubrics,review_strategy, topics which are related to the selected assignment. tabs-5 is the topics tab which we are interested in.
<pre>
<div id="tabs-3">
<%= render 'assignments/edit/review_strategy' %>
</div>
<div id="tabs-4">
<%= render 'assignments/edit/due_dates' %>
</div>
<div id="tabs-5">
<%= render 'assignments/edit/add_signup_topics' %>
</div>
</pre>

===After Changes===
We have redundant code in two methods so we merged add_signup_topics_staggered and add_signup_topics into add_signup_topics. The action calls single method for both type of assignments and renders views based on condition of staggered or non-staggered assignment.

<pre>
<div id="tabs-3">
<%= render 'assignments/edit/review_strategy' %>
</div>
<div id="tabs-4">
<%= render 'assignments/edit/due_dates' %>
</div>
<div id="tabs-5">
<%= render '/sign_up_sheet/add_signup_topcis.html' %>
</div>
</pre>

Refactoring view code into relevant views 
There were no edit/delete links to edit/delete a topic in the instructor view. These had to be conditionally added based on the role of the currently logged in user. This was to prevent students from editing/deleting topics and to keep instructors from signing up for a topic. This was implemented as follows.

===Adding Edit/Delete functionality to topics tab===

The current expertiza project had two views to display the Actions column in the topics table. These were _reserve_topics.html.erb and _actions.html. The first one was displaying the signup button for the student and the latter was displaying the bookmarks and rendering the _reserve_topics.html.erb after the bookmarks. On top of this we had to add the edit/delete links for the instructor. A refactor was called for. We decided to create a _all_actions.html.erb partial which had the responsibility to display the relevant actions depending upon the role of the currently logged in user. This helped us remove the separate partial to render actions pertaining to a student, namely _reserve_topics.html.erb . Also the _actions.html.erb only took care of displaying the bookmark links rather than dealing with both bookmarks and actions.

partial_view:_all_actions,html.erb
<pre>
<% if ['Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator'].include? current_user_role?.name %>
<td align="center">
<%= link_to image_tag('edit_icon.png', :border => 0, :title => 'Edit Topic', :align => 'middle'), :controller=>'sign_up_sheet', :action=> 'edit', :id => topic.id %>
<%= link_to image_tag('delete_icon.png', :border => 0, :title => 'Delete Topic', :align => 'middle'), sign_up_sheet_path(topic.id), method: :delete, data: {confirm: 'Are you sure?'} %>
<%elsif @show_actions %>
...
#Render signup button for student here. The @show_actions will be true if this partial is navigated from the SignupSheetController which is accessible only to students.
</pre>

== Case 2 : Cleaning up unused code ==
The Refactors mentioned above enable us to delete unused partials namely:

*assignments controller partials :
**_add_signup_topics.html.erb
**_reserve_topic.html.erb

*signup_sheet_controller partials :
**_reserve_topic.html.erb

Similarly the method call is re-factored in various views.
For instance, for view _assignments_actions.html.erb

Before Changes 
<% if @assignment.staggered_deadline == true %>
<%= link_to image_tag('/images/tree_view/edit-signup-sheet-24.png', :title => 'Edit signup sheet'),
{:controller => 'sign_up_sheet', :action => 'add_signup_topics_staggered', :id => node.node_object_id},
{:title => 'Edit signup sheet'} %>
<% else %>
<%= link_to image_tag('/images/tree_view/edit-signup-sheet-24.png', :title => 'Edit signup sheet'),
{:controller => 'sign_up_sheet', :action => 'add_signup_topics', :id => node.node_object_id},
{:title => 'Edit signup sheet'} %>
<% end %>

After Changes 
<%= link_to image_tag('/images/tree_view/edit-signup-sheet-24.png', :title => 'Edit signup sheet'),
{:controller => 'sign_up_sheet', :action => 'add_signup_topics', :id => node.node_object_id},
{:title => 'Edit signup sheet'} %>

== Case 2 : Method Extraction ==

Improved readability by [http://sourcemaking.com/refactoring/extract-method extracting] two separate functionalities from the same method into separate methods with appropriate naming convention and responsibilities.

===Current Scenario===

The add_signup_topics calculated due dates for separate topics for a Staggered assignment with individual Topic deadlines.

def add_signup_topics
load_add_signup_topics(params[:id])
if @assignment.staggered_deadline ==true
@review_rounds = Assignment.find(params[:id]).get_review_rounds
@topics = SignUpTopic.find_all_by_assignment_id(params[:id])

#below functionality finds allows to set due dates for topics of assignment
@duedates = SignUpTopic.find_by_sql("SELECT s.id as topic_id FROM sign_up_topics s WHERE s.assignment_id = " + params[:id].to_s)
if !@topics.nil?
i=0
@topics.each { |topic|
......
i = i + 1
end

#Render a view different for staggered deadlines assignment from the add_sign_up.html.erb
render "add_signup_topics_staggered"
end
end

===After Changes===

The logic to calculate due_dates was moved to a separate method called assignment_due_date , as this is only valid for staggered assignments
and hence it should be placed in a different method instead of merging it the add_signup_topics

def add_signup_topics
load_add_signup_topics(params[:id])
if @assignment.staggered_deadline ==true
@review_rounds = Assignment.find(params[:id]).get_review_rounds
@topics = SignUpTopic.find_all_by_assignment_id(params[:id])

#Function call to set up due dates
assignment_due_date

#Render a view different from the add_sign_up.html.erb , so rendering a view for staggered deadlines.
render "add_signup_topics_staggered"
end
end

def assignment_due_date
#below functionality finds allows to set due dates for topics of assignment
@duedates = SignUpTopic.find_by_sql("SELECT s.id as topic_id FROM sign_up_topics s WHERE s.assignment_id = " + params[:id].to_s)
if !@topics.nil?
i=0
@topics.each { |topic|
......
i = i + 1
end
end

==Case 3 : Modularize Code in application.rb==
===Current Scenario===
In the assignment.rb model, there exists one method(check_condition) which checks whether review, meta-review, etc are allowed or not. This method makes database calls to TopicDeadline table, DueDate and DeadlineType tables. Following is the code which was existing before the changes were made. It has the logic to find the nearest due date that hasn't passed.

assignment.rb

drop_topic_deadline_id = DeadlineType.find_by_name('drop_topic').id
if self.staggered_deadline?

if topic_id

next_due_date = TopicDeadline.find(:first, :conditions => ['topic_id = ? and due_at >= ? and deadline_type_id <> ?',
topic_id, Time.now, drop_topic_deadline_id], :order => 'due_at')
else

next_due_date = TopicDeadline.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
self.id, Time.now, drop_topic_deadline_id], :joins => {:topic => :assignment}, :order => 'due_at')
end
else
next_due_date = DueDate.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
self.id, Time.now, drop_topic_deadline_id], :order => 'due_at')
end

===After changes===
The database queries have been moved to their respective models. The queries to TopicDeadline table, DueDate table and DeadlineType table have been moved to their models. Below is the new code in assignments.rb model which calls TopicDeadline.rb, DueDate.rb and DeadlineType.rb respectively for the queries in their tables:

assignment.rb model

if self.staggered_deadline?
next_due_date = TopicDeadline.find_next_due_date(topic_id,self.id)
else
next_due_date = DueDate.find_next_due_date(self.id)
end

New find_next_due_date defined in topic_deadline.rb
def self.find_next_due_date(topic_id,assignment_id)
drop_topic_deadline_id = DeadlineType.find_drop_topic_deadline_id()
if topic_id
TopicDeadline.find(:first, :conditions => ['topic_id = ? and due_at >= ? and deadline_type_id <> ?',
topic_id, Time.now, drop_topic_deadline_id], :order => 'due_at')
else
TopicDeadline.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
assignment_id, Time.now, drop_topic_deadline_id], :joins => {:topic => :assignment}, :order => 'due_at')
end
end

New find_next_due_date method defined in due_date.rb

def self.find_next_due_date(assignment_id
drop_topic_deadline_id = DeadlineType.find_drop_topic_deadline_id()
DueDate.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
assignment_id, Time.now, drop_topic_deadline_id], :order => 'due_at')
end

New find_drop_topic_deadline_id method defined in deadline_type.rb

def self.find_drop_topic_deadline_id()
DeadlineType.find_by_name('drop_topic').id
end

== Case 4 : DeadCode Elimination in sign_up_sheet_controller.rb ==

The local variables topic_set and topic under the staggered deadline check statement were never used in the entire scope of the project , it introduced code smells. So it was checked if there was any reference to this code, and upon discovering it was not used anywhere, we decided to eliminate this [http://en.wikipedia.org/wiki/Dead_code_elimination deadcode].

===Current Scenario===

def create_default_for_microtask
.....

if @assignment.staggered_deadline?
topic_set = Array.new
topic = @sign_up_topic.id
end

.....
end

===After Changes===

def create_default_for_microtask
.....

.....
end

=Steps to verify changes=
Log into the application with the user having instructor's role or super user's role.

1. Go to Manage -> Assignments and hover over the assignment “StaggeredDeadlines_Refactoring”.

2. Click on “New Topic”.

3. Enter the details of the topic you want to create. Create at least 2 topics for better analysis of the project.

[[File:AddTopic.png]]

4. Now once you have created two new topics , then Click on “Show start/due date”.

5. You should be able to view the new start and due dates of your topics confirming these are the staggered deadlines for “StaggeredDeadlines_Refactoring” which has many topics with different deadlines.

[[File:ShowdueDate.png]]

6. Now to view the difference between the Stagerred and Non-Staggered Deadlines, follow steps.

7. Go to Manage -> Assignments and hover over “SALT Demo” and click on “Edit Signup sheet”.

8. Click on “New Topic” and fill in the details for a new topic.

[[File:NonstaggeredAddTopic.png]]

9. Now you will be able to see that there is no option for “Show Start/Due Date” which is because of the reason that this is not a staggered assignment.

[[File:NodueDate.png]]

10. Hence there is only one due date and has no dependencies on others.

= Concise Report on Refactoring =

The project had redundant code, multiple functionalities in a method and extra conditional statements in controller, model and view files. We analyzed each occurrence of these issues, thus creating a list which needed to be refactored. Controllers like sign_up_sheet_controler, assignment.rb, due_date.rb,deadline_types.rb along with other files were modified. It's very difficult to explain the sequential and detailed procedure, but it has been explained in the sections above within the capacity of the Wiki.

= Additional Learning and Future Work=

In current implementation, our database has two tables for staggered and non-staggered deadlines. For any future improvements, we can make use of [http://blog.thirst.co/post/14885390861/rails-single-table-inheritance STI (Single Table Inheritance)] and analyze if applying STI would really impact query performance when application runs and extracts data from database.

=See Also=
#[https://github.com/expertiza/expertiza Expertiza on GitHub]
#[https://github.com/itsmylifesoham/expertiza GitHub Project Repository Fork]
#[http://expertiza.ncsu.edu/ The live Expertiza website]
#[http://152.46.18.5:3000/ VCL link] - This might not be available after Nov. 2014
#[http://wikis.lib.ncsu.edu/index.php/Expertiza Expertiza project documentation wiki]
#[https://docs.google.com/document/d/1FZCL9KWSdVNsX9BowuZ3gxbCOJoiWX-GVLctSZei3No The OSS project requirements doc (Fall 2014 - Expertiza)]

= References=
[http://expertiza.ncsu.edu/ Expertiza] 
[http://eewang.github.io/blog/2013/03/12/how-and-when-to-use-single-table-inheritance-in-rails/ Single Table Inheritance] 
[http://en.wikipedia.org/wiki/Code_refactoring Code Refactoring] 
[http://en.wikipedia.org/wiki/Code_smell Code smell]

CSC/ECE 517 Fall 2014/oss E1453 syy

2014-10-29T20:21:59Z

Shjoshi2:

'''E1453. Refactoring AssignmentsController'''

This page provides a description of the Expertiza based OSS project. This project aimed at refactoring the AssignmentsController as well as adding some missing functionality related to topics within an assignment.

'''Introduction to Expertiza''' 

[http://expertiza.ncsu.edu/ Expertiza] is a project developed using Ruby on Rails platform. It provides features like peer review, team assignments and submission of projects. This can be achieved by submitting code base, URL of hosted code on remote server and Wiki submissions. It is an open source application and the code can be cloned from [https://github.com/expertiza/expertiza github]. This application provides an efficient way to manage assignments, grades and reviews. This makes the process easier and faster when the class strength is large.

Expertiza is supported by National Science Foundation under Grant No. 0536558. Additional funding from the NCSU Learning in a Technology-Rich Environment (LITRE) program, the NCSU Faculty Center for Teaching and Learning, the NCSU STEM Initiative, and the Center for Advanced Computing and Communication.

= Project Resources =

[https://github.com/itsmylifesoham/expertiza GitHub Project Repository]

[http://152.46.18.5:3000/ VCL IP Address]

[http://wikis.lib.ncsu.edu/index.php/Expertiza Expertiza Wiki]

= Problem Statement =
Currently the topics tab is not usable to the instructor when he is editing a current assignment or creating a new one. This functionality is necessary as it enables the instructor to create/delete/edit/view topics present under the selected assignment. Currently, the instructor achieves this using the pop-up menu that appears adjacent every assignment on the page that lists all the assignments. We were required to implement the topics tab.

The functionality to display the topics under an assignment is duplicated between the AssignmentController views and the SignupSheetController views. Both the instructor and the student can view the topics by selecting an assignment and we were required to remove this duplication in the views.

= Re-factored Code Cases =

== Case 1 : Refactoring the AssignmentsController and SignupSheetController ==

===Removing duplicate _add_signup_topics partials===
The AssignmentsController displayed topics to the instructor while he was editing an assignment. It used _add_signup_topics.html.erb partial to render topics under the topics tab. The SignupSheetController displayed topics to a student who wanted to view signup topics under an assignment. It was found that it had its own copy namely _add_signup_topcis.html.erb to display topics to the student. We wanted to have these two controllers use the same views to render the same thing which was list of topics under an assignment. We made the AssignmentsController reuse the _add_signup_topcis.html.erb partial under the SignupSheetController.

view:assignments/edit.html.erb 
This view contains all the tabs to display like general,rubrics,review_strategy, topics which are related to the selected assignment. tabs-5 is the topics tab which we are interested in.
<pre>
<div id="tabs-3">
<%= render 'assignments/edit/review_strategy' %>
</div>
<div id="tabs-4">
<%= render 'assignments/edit/due_dates' %>
</div>
<div id="tabs-5">
<%= render 'assignments/edit/add_signup_topics' %>
</div>
</pre>

===After Changes===
We have redundant code in two methods so we merged add_signup_topics_staggered and add_signup_topics into add_signup_topics. The action calls single method for both type of assignments and renders views based on condition of staggered or non-staggered assignment.

<pre>
<div id="tabs-3">
<%= render 'assignments/edit/review_strategy' %>
</div>
<div id="tabs-4">
<%= render 'assignments/edit/due_dates' %>
</div>
<div id="tabs-5">
<%= render '/sign_up_sheet/add_signup_topcis.html' %>
</div>
</pre>

Refactoring view code into relevant views 
There were no edit/delete links to edit/delete a topic in the instructor view. These had to be conditionally added based on the role of the currently logged in user. This was to prevent students from editing/deleting topics and to keep instructors from signing up for a topic. This was implemented as follows.

===Adding Edit/Delete functionality to topics tab===

The current expertiza project had two views to display the Actions column in the topics table. These were _reserve_topics.html.erb and _actions.html. The first one was displaying the signup button for the student and the latter was displaying the bookmarks and rendering the _reserve_topics.html.erb after the bookmarks. On top of this we had to add the edit/delete links for the instructor. A refactor was called for. We decided to create a _all_actions.html.erb partial which had the responsibility to display the relevant actions depending upon the role of the currently logged in user. This helped us remove the separate partial to render actions pertaining to a student, namely _reserve_topics.html.erb . Also the _actions.html.erb only took care of displaying the bookmark links rather than dealing with both bookmarks and actions.

partial_view:_all_actions,html.erb
<pre>
<% if ['Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator'].include? current_user_role?.name %>
<td align="center">
<%= link_to image_tag('edit_icon.png', :border => 0, :title => 'Edit Topic', :align => 'middle'), :controller=>'sign_up_sheet', :action=> 'edit', :id => topic.id %>
<%= link_to image_tag('delete_icon.png', :border => 0, :title => 'Delete Topic', :align => 'middle'), sign_up_sheet_path(topic.id), method: :delete, data: {confirm: 'Are you sure?'} %>
<%elsif @show_actions %>
...
#Render signup button for student here. The @show_actions will be true if this partial is navigated from the SignupSheetController which is accessible only to students.
</pre>

== Case 2 : Cleaning up unused code ==
The Refactors mentioned above enable us to delete unused partials namely:

assignments controller partials :
1. _add_signup_topics.html.erb
2. _reserve_topic.html.erb

signup_sheet_controller partials :
1. _reserve_topic.html.erb

Similarly the method call is re-factored in various views.
For instance, for view _assignments_actions.html.erb

Before Changes 
<% if @assignment.staggered_deadline == true %>
<%= link_to image_tag('/images/tree_view/edit-signup-sheet-24.png', :title => 'Edit signup sheet'),
{:controller => 'sign_up_sheet', :action => 'add_signup_topics_staggered', :id => node.node_object_id},
{:title => 'Edit signup sheet'} %>
<% else %>
<%= link_to image_tag('/images/tree_view/edit-signup-sheet-24.png', :title => 'Edit signup sheet'),
{:controller => 'sign_up_sheet', :action => 'add_signup_topics', :id => node.node_object_id},
{:title => 'Edit signup sheet'} %>
<% end %>

After Changes 
<%= link_to image_tag('/images/tree_view/edit-signup-sheet-24.png', :title => 'Edit signup sheet'),
{:controller => 'sign_up_sheet', :action => 'add_signup_topics', :id => node.node_object_id},
{:title => 'Edit signup sheet'} %>

== Case 2 : Method Extraction ==

Improved readability by [http://sourcemaking.com/refactoring/extract-method extracting] two separate functionalities from the same method into separate methods with appropriate naming convention and responsibilities.

===Current Scenario===

The add_signup_topics calculated due dates for separate topics for a Staggered assignment with individual Topic deadlines.

def add_signup_topics
load_add_signup_topics(params[:id])
if @assignment.staggered_deadline ==true
@review_rounds = Assignment.find(params[:id]).get_review_rounds
@topics = SignUpTopic.find_all_by_assignment_id(params[:id])

#below functionality finds allows to set due dates for topics of assignment
@duedates = SignUpTopic.find_by_sql("SELECT s.id as topic_id FROM sign_up_topics s WHERE s.assignment_id = " + params[:id].to_s)
if !@topics.nil?
i=0
@topics.each { |topic|
......
i = i + 1
end

#Render a view different for staggered deadlines assignment from the add_sign_up.html.erb
render "add_signup_topics_staggered"
end
end

===After Changes===

The logic to calculate due_dates was moved to a separate method called assignment_due_date , as this is only valid for staggered assignments
and hence it should be placed in a different method instead of merging it the add_signup_topics

def add_signup_topics
load_add_signup_topics(params[:id])
if @assignment.staggered_deadline ==true
@review_rounds = Assignment.find(params[:id]).get_review_rounds
@topics = SignUpTopic.find_all_by_assignment_id(params[:id])

#Function call to set up due dates
assignment_due_date

#Render a view different from the add_sign_up.html.erb , so rendering a view for staggered deadlines.
render "add_signup_topics_staggered"
end
end

def assignment_due_date
#below functionality finds allows to set due dates for topics of assignment
@duedates = SignUpTopic.find_by_sql("SELECT s.id as topic_id FROM sign_up_topics s WHERE s.assignment_id = " + params[:id].to_s)
if !@topics.nil?
i=0
@topics.each { |topic|
......
i = i + 1
end
end

==Case 3 : Modularize Code in application.rb==
===Current Scenario===
In the assignment.rb model, there exists one method(check_condition) which checks whether review, meta-review, etc are allowed or not. This method makes database calls to TopicDeadline table, DueDate and DeadlineType tables. Following is the code which was existing before the changes were made. It has the logic to find the nearest due date that hasn't passed.

assignment.rb

drop_topic_deadline_id = DeadlineType.find_by_name('drop_topic').id
if self.staggered_deadline?

if topic_id

next_due_date = TopicDeadline.find(:first, :conditions => ['topic_id = ? and due_at >= ? and deadline_type_id <> ?',
topic_id, Time.now, drop_topic_deadline_id], :order => 'due_at')
else

next_due_date = TopicDeadline.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
self.id, Time.now, drop_topic_deadline_id], :joins => {:topic => :assignment}, :order => 'due_at')
end
else
next_due_date = DueDate.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
self.id, Time.now, drop_topic_deadline_id], :order => 'due_at')
end

===After changes===
The database queries have been moved to their respective models. The queries to TopicDeadline table, DueDate table and DeadlineType table have been moved to their models. Below is the new code in assignments.rb model which calls TopicDeadline.rb, DueDate.rb and DeadlineType.rb respectively for the queries in their tables:

assignment.rb model

if self.staggered_deadline?
next_due_date = TopicDeadline.find_next_due_date(topic_id,self.id)
else
next_due_date = DueDate.find_next_due_date(self.id)
end

New find_next_due_date defined in topic_deadline.rb
def self.find_next_due_date(topic_id,assignment_id)
drop_topic_deadline_id = DeadlineType.find_drop_topic_deadline_id()
if topic_id
TopicDeadline.find(:first, :conditions => ['topic_id = ? and due_at >= ? and deadline_type_id <> ?',
topic_id, Time.now, drop_topic_deadline_id], :order => 'due_at')
else
TopicDeadline.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
assignment_id, Time.now, drop_topic_deadline_id], :joins => {:topic => :assignment}, :order => 'due_at')
end
end

New find_next_due_date method defined in due_date.rb

def self.find_next_due_date(assignment_id
drop_topic_deadline_id = DeadlineType.find_drop_topic_deadline_id()
DueDate.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
assignment_id, Time.now, drop_topic_deadline_id], :order => 'due_at')
end

New find_drop_topic_deadline_id method defined in deadline_type.rb

def self.find_drop_topic_deadline_id()
DeadlineType.find_by_name('drop_topic').id
end

== Case 4 : DeadCode Elimination in sign_up_sheet_controller.rb ==

The local variables topic_set and topic under the staggered deadline check statement were never used in the entire scope of the project , it introduced code smells. So it was checked if there was any reference to this code, and upon discovering it was not used anywhere, we decided to eliminate this [http://en.wikipedia.org/wiki/Dead_code_elimination deadcode].

===Current Scenario===

def create_default_for_microtask
.....

if @assignment.staggered_deadline?
topic_set = Array.new
topic = @sign_up_topic.id
end

.....
end

===After Changes===

def create_default_for_microtask
.....

.....
end

=Steps to verify changes=
Log into the application with the user having instructor's role or super user's role.

1. Go to Manage -> Assignments and hover over the assignment “StaggeredDeadlines_Refactoring”.

2. Click on “New Topic”.

3. Enter the details of the topic you want to create. Create at least 2 topics for better analysis of the project.

[[File:AddTopic.png]]

4. Now once you have created two new topics , then Click on “Show start/due date”.

5. You should be able to view the new start and due dates of your topics confirming these are the staggered deadlines for “StaggeredDeadlines_Refactoring” which has many topics with different deadlines.

[[File:ShowdueDate.png]]

6. Now to view the difference between the Stagerred and Non-Staggered Deadlines, follow steps.

7. Go to Manage -> Assignments and hover over “SALT Demo” and click on “Edit Signup sheet”.

8. Click on “New Topic” and fill in the details for a new topic.

[[File:NonstaggeredAddTopic.png]]

9. Now you will be able to see that there is no option for “Show Start/Due Date” which is because of the reason that this is not a staggered assignment.

[[File:NodueDate.png]]

10. Hence there is only one due date and has no dependencies on others.

= Concise Report on Refactoring =

The project had redundant code, multiple functionalities in a method and extra conditional statements in controller, model and view files. We analyzed each occurrence of these issues, thus creating a list which needed to be refactored. Controllers like sign_up_sheet_controler, assignment.rb, due_date.rb,deadline_types.rb along with other files were modified. It's very difficult to explain the sequential and detailed procedure, but it has been explained in the sections above within the capacity of the Wiki.

= Additional Learning and Future Work=

In current implementation, our database has two tables for staggered and non-staggered deadlines. For any future improvements, we can make use of [http://blog.thirst.co/post/14885390861/rails-single-table-inheritance STI (Single Table Inheritance)] and analyze if applying STI would really impact query performance when application runs and extracts data from database.

= References=
[http://expertiza.ncsu.edu/ Expertiza] 
[http://eewang.github.io/blog/2013/03/12/how-and-when-to-use-single-table-inheritance-in-rails/ Single Table Inheritance] 
[http://en.wikipedia.org/wiki/Code_refactoring Code Refactoring] 
[http://en.wikipedia.org/wiki/Code_smell Code smell]

CSC/ECE 517 Fall 2014/oss E1453 syy

2014-10-29T20:08:30Z

Shjoshi2: /* Adding Edit/Delete functionality to topics tab */

'''E1453. Refactoring AssignmentsController'''

This page provides a description of the Expertiza based OSS project. This project aimed at refactoring the AssignmentsController as well as adding some missing functionality related to topics within an assignment.

'''Introduction to Expertiza''' 

[http://expertiza.ncsu.edu/ Expertiza] is a project developed using Ruby on Rails platform. It provides features like peer review, team assignments and submission of projects. This can be achieved by submitting code base, URL of hosted code on remote server and Wiki submissions. It is an open source application and the code can be cloned from [https://github.com/expertiza/expertiza github]. This application provides an efficient way to manage assignments, grades and reviews. This makes the process easier and faster when the class strength is large.

Expertiza is supported by National Science Foundation under Grant No. 0536558. Additional funding from the NCSU Learning in a Technology-Rich Environment (LITRE) program, the NCSU Faculty Center for Teaching and Learning, the NCSU STEM Initiative, and the Center for Advanced Computing and Communication.

= Project Resources =

[https://github.com/itsmylifesoham/expertiza GitHub Project Repository]

[http://152.46.18.5:3000/ VCL IP Address]

[http://wikis.lib.ncsu.edu/index.php/Expertiza Expertiza Wiki]

= Problem Statement =
Currently the topics tab is not usable to the instructor when he is editing a current assignment or creating a new one. This functionality is necessary as it enables the instructor to create/delete/edit/view topics present under the selected assignment. Currently, the instructor achieves this using the pop-up menu that appears adjacent every assignment on the page that lists all the assignments. We were required to implement the topics tab.

The functionality to display the topics under an assignment is duplicated between the AssignmentController views and the SignupSheetController views. Both the instructor and the student can view the topics by selecting an assignment and we were required to remove this duplication in the views.

= Re-factored Code Cases =

== Case 1 : Refactoring the AssignmentsController and SignupSheetController ==

===Removing duplicate _add_signup_topics partials===
The AssignmentsController displayed topics to the instructor while he was editing an assignment. It used _add_signup_topics.html.erb partial to render topics under the topics tab. The SignupSheetController displayed topics to a student who wanted to view signup topics under an assignment. It was found that it had its own copy namely _add_signup_topcis.html.erb to display topics to the student. We wanted to have these two controllers use the same views to render the same thing which was list of topics under an assignment. We made the AssignmentsController reuse the _add_signup_topcis.html.erb partial under the SignupSheetController.

view:assignments/edit.html.erb 
This view contains all the tabs to display like general,rubrics,review_strategy, topics which are related to the selected assignment. tabs-5 is the topics tab which we are interested in.
<pre>
<div id="tabs-3">
<%= render 'assignments/edit/review_strategy' %>
</div>
<div id="tabs-4">
<%= render 'assignments/edit/due_dates' %>
</div>
<div id="tabs-5">
<%= render 'assignments/edit/add_signup_topics' %>
</div>
</pre>

===After Changes===
We have redundant code in two methods so we merged add_signup_topics_staggered and add_signup_topics into add_signup_topics. The action calls single method for both type of assignments and renders views based on condition of staggered or non-staggered assignment.

<pre>
<div id="tabs-3">
<%= render 'assignments/edit/review_strategy' %>
</div>
<div id="tabs-4">
<%= render 'assignments/edit/due_dates' %>
</div>
<div id="tabs-5">
<%= render '/sign_up_sheet/add_signup_topcis.html' %>
</div>
</pre>

Refactoring view code into relevant views 
There were no edit/delete links to edit/delete a topic in the instructor view. These had to be conditionally added based on the role of the currently logged in user. This was to prevent students from editing/deleting topics and to keep instructors from signing up for a topic. This was implemented as follows.

===Adding Edit/Delete functionality to topics tab===

The current expertiza project had two views to display the Actions column in the topics table. These were _reserve_topics.html.erb and _actions.html. The first one was displaying the signup button for the student and the latter was displaying the bookmarks and rendering the _reserve_topics.html.erb after the bookmarks. On top of this we had to add the edit/delete links for the instructor. A refactor was called for. We decided to create a _all_actions.html.erb partial which had the responsibility to display the relevant actions depending upon the role of the currently logged in user. This helped us remove the separate partial to render actions pertaining to a student, namely _reserve_topics.html.erb . Also the _actions.html.erb only took care of displaying the bookmark links rather than dealing with both bookmarks and actions.

partial_view:_all_actions,html.erb
<pre>
<% if ['Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator'].include? current_user_role?.name %>
<td align="center">
<%= link_to image_tag('edit_icon.png', :border => 0, :title => 'Edit Topic', :align => 'middle'), :controller=>'sign_up_sheet', :action=> 'edit', :id => topic.id %>
<%= link_to image_tag('delete_icon.png', :border => 0, :title => 'Delete Topic', :align => 'middle'), sign_up_sheet_path(topic.id), method: :delete, data: {confirm: 'Are you sure?'} %>
<%elsif @show_actions %>
...
#Render signup button for student here. The @show_actions will be true if this partial is navigated from the SignupSheetController which is accessible only to students.
</pre>

Similarly the method call is re-factored in various views.
For instance, for view _assignments_actions.html.erb

Before Changes 
<% if @assignment.staggered_deadline == true %>
<%= link_to image_tag('/images/tree_view/edit-signup-sheet-24.png', :title => 'Edit signup sheet'),
{:controller => 'sign_up_sheet', :action => 'add_signup_topics_staggered', :id => node.node_object_id},
{:title => 'Edit signup sheet'} %>
<% else %>
<%= link_to image_tag('/images/tree_view/edit-signup-sheet-24.png', :title => 'Edit signup sheet'),
{:controller => 'sign_up_sheet', :action => 'add_signup_topics', :id => node.node_object_id},
{:title => 'Edit signup sheet'} %>
<% end %>

After Changes 
<%= link_to image_tag('/images/tree_view/edit-signup-sheet-24.png', :title => 'Edit signup sheet'),
{:controller => 'sign_up_sheet', :action => 'add_signup_topics', :id => node.node_object_id},
{:title => 'Edit signup sheet'} %>

== Case 2 : Method Extraction ==

Improved readability by [http://sourcemaking.com/refactoring/extract-method extracting] two separate functionalities from the same method into separate methods with appropriate naming convention and responsibilities.

===Current Scenario===

The add_signup_topics calculated due dates for separate topics for a Staggered assignment with individual Topic deadlines.

def add_signup_topics
load_add_signup_topics(params[:id])
if @assignment.staggered_deadline ==true
@review_rounds = Assignment.find(params[:id]).get_review_rounds
@topics = SignUpTopic.find_all_by_assignment_id(params[:id])

#below functionality finds allows to set due dates for topics of assignment
@duedates = SignUpTopic.find_by_sql("SELECT s.id as topic_id FROM sign_up_topics s WHERE s.assignment_id = " + params[:id].to_s)
if !@topics.nil?
i=0
@topics.each { |topic|
......
i = i + 1
end

#Render a view different for staggered deadlines assignment from the add_sign_up.html.erb
render "add_signup_topics_staggered"
end
end

===After Changes===

The logic to calculate due_dates was moved to a separate method called assignment_due_date , as this is only valid for staggered assignments
and hence it should be placed in a different method instead of merging it the add_signup_topics

def add_signup_topics
load_add_signup_topics(params[:id])
if @assignment.staggered_deadline ==true
@review_rounds = Assignment.find(params[:id]).get_review_rounds
@topics = SignUpTopic.find_all_by_assignment_id(params[:id])

#Function call to set up due dates
assignment_due_date

#Render a view different from the add_sign_up.html.erb , so rendering a view for staggered deadlines.
render "add_signup_topics_staggered"
end
end

def assignment_due_date
#below functionality finds allows to set due dates for topics of assignment
@duedates = SignUpTopic.find_by_sql("SELECT s.id as topic_id FROM sign_up_topics s WHERE s.assignment_id = " + params[:id].to_s)
if !@topics.nil?
i=0
@topics.each { |topic|
......
i = i + 1
end
end

==Case 3 : Modularize Code in application.rb==
===Current Scenario===
In the assignment.rb model, there exists one method(check_condition) which checks whether review, meta-review, etc are allowed or not. This method makes database calls to TopicDeadline table, DueDate and DeadlineType tables. Following is the code which was existing before the changes were made. It has the logic to find the nearest due date that hasn't passed.

assignment.rb

drop_topic_deadline_id = DeadlineType.find_by_name('drop_topic').id
if self.staggered_deadline?

if topic_id

next_due_date = TopicDeadline.find(:first, :conditions => ['topic_id = ? and due_at >= ? and deadline_type_id <> ?',
topic_id, Time.now, drop_topic_deadline_id], :order => 'due_at')
else

next_due_date = TopicDeadline.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
self.id, Time.now, drop_topic_deadline_id], :joins => {:topic => :assignment}, :order => 'due_at')
end
else
next_due_date = DueDate.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
self.id, Time.now, drop_topic_deadline_id], :order => 'due_at')
end

===After changes===
The database queries have been moved to their respective models. The queries to TopicDeadline table, DueDate table and DeadlineType table have been moved to their models. Below is the new code in assignments.rb model which calls TopicDeadline.rb, DueDate.rb and DeadlineType.rb respectively for the queries in their tables:

assignment.rb model

if self.staggered_deadline?
next_due_date = TopicDeadline.find_next_due_date(topic_id,self.id)
else
next_due_date = DueDate.find_next_due_date(self.id)
end

New find_next_due_date defined in topic_deadline.rb
def self.find_next_due_date(topic_id,assignment_id)
drop_topic_deadline_id = DeadlineType.find_drop_topic_deadline_id()
if topic_id
TopicDeadline.find(:first, :conditions => ['topic_id = ? and due_at >= ? and deadline_type_id <> ?',
topic_id, Time.now, drop_topic_deadline_id], :order => 'due_at')
else
TopicDeadline.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
assignment_id, Time.now, drop_topic_deadline_id], :joins => {:topic => :assignment}, :order => 'due_at')
end
end

New find_next_due_date method defined in due_date.rb

def self.find_next_due_date(assignment_id
drop_topic_deadline_id = DeadlineType.find_drop_topic_deadline_id()
DueDate.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
assignment_id, Time.now, drop_topic_deadline_id], :order => 'due_at')
end

New find_drop_topic_deadline_id method defined in deadline_type.rb

def self.find_drop_topic_deadline_id()
DeadlineType.find_by_name('drop_topic').id
end

== Case 4 : DeadCode Elimination in sign_up_sheet_controller.rb ==

The local variables topic_set and topic under the staggered deadline check statement were never used in the entire scope of the project , it introduced code smells. So it was checked if there was any reference to this code, and upon discovering it was not used anywhere, we decided to eliminate this [http://en.wikipedia.org/wiki/Dead_code_elimination deadcode].

===Current Scenario===

def create_default_for_microtask
.....

if @assignment.staggered_deadline?
topic_set = Array.new
topic = @sign_up_topic.id
end

.....
end

===After Changes===

def create_default_for_microtask
.....

.....
end

=Steps to verify changes=
Log into the application with the user having instructor's role or super user's role.

1. Go to Manage -> Assignments and hover over the assignment “StaggeredDeadlines_Refactoring”.

2. Click on “New Topic”.

3. Enter the details of the topic you want to create. Create at least 2 topics for better analysis of the project.

[[File:AddTopic.png]]

4. Now once you have created two new topics , then Click on “Show start/due date”.

5. You should be able to view the new start and due dates of your topics confirming these are the staggered deadlines for “StaggeredDeadlines_Refactoring” which has many topics with different deadlines.

[[File:ShowdueDate.png]]

6. Now to view the difference between the Stagerred and Non-Staggered Deadlines, follow steps.

7. Go to Manage -> Assignments and hover over “SALT Demo” and click on “Edit Signup sheet”.

8. Click on “New Topic” and fill in the details for a new topic.

[[File:NonstaggeredAddTopic.png]]

9. Now you will be able to see that there is no option for “Show Start/Due Date” which is because of the reason that this is not a staggered assignment.

[[File:NodueDate.png]]

10. Hence there is only one due date and has no dependencies on others.

= Concise Report on Refactoring =

The project had redundant code, multiple functionalities in a method and extra conditional statements in controller, model and view files. We analyzed each occurrence of these issues, thus creating a list which needed to be refactored. Controllers like sign_up_sheet_controler, assignment.rb, due_date.rb,deadline_types.rb along with other files were modified. It's very difficult to explain the sequential and detailed procedure, but it has been explained in the sections above within the capacity of the Wiki.

= Additional Learning and Future Work=

In current implementation, our database has two tables for staggered and non-staggered deadlines. For any future improvements, we can make use of [http://blog.thirst.co/post/14885390861/rails-single-table-inheritance STI (Single Table Inheritance)] and analyze if applying STI would really impact query performance when application runs and extracts data from database.

= References=
[http://expertiza.ncsu.edu/ Expertiza] 
[http://eewang.github.io/blog/2013/03/12/how-and-when-to-use-single-table-inheritance-in-rails/ Single Table Inheritance] 
[http://en.wikipedia.org/wiki/Code_refactoring Code Refactoring] 
[http://en.wikipedia.org/wiki/Code_smell Code smell]

CSC/ECE 517 Fall 2014/oss E1453 syy

2014-10-29T20:07:34Z

Shjoshi2: /* Adding Edit/Delete links */

'''E1453. Refactoring AssignmentsController'''

This page provides a description of the Expertiza based OSS project. This project aimed at refactoring the AssignmentsController as well as adding some missing functionality related to topics within an assignment.

'''Introduction to Expertiza''' 

[http://expertiza.ncsu.edu/ Expertiza] is a project developed using Ruby on Rails platform. It provides features like peer review, team assignments and submission of projects. This can be achieved by submitting code base, URL of hosted code on remote server and Wiki submissions. It is an open source application and the code can be cloned from [https://github.com/expertiza/expertiza github]. This application provides an efficient way to manage assignments, grades and reviews. This makes the process easier and faster when the class strength is large.

Expertiza is supported by National Science Foundation under Grant No. 0536558. Additional funding from the NCSU Learning in a Technology-Rich Environment (LITRE) program, the NCSU Faculty Center for Teaching and Learning, the NCSU STEM Initiative, and the Center for Advanced Computing and Communication.

= Project Resources =

[https://github.com/itsmylifesoham/expertiza GitHub Project Repository]

[http://152.46.18.5:3000/ VCL IP Address]

[http://wikis.lib.ncsu.edu/index.php/Expertiza Expertiza Wiki]

= Problem Statement =
Currently the topics tab is not usable to the instructor when he is editing a current assignment or creating a new one. This functionality is necessary as it enables the instructor to create/delete/edit/view topics present under the selected assignment. Currently, the instructor achieves this using the pop-up menu that appears adjacent every assignment on the page that lists all the assignments. We were required to implement the topics tab.

The functionality to display the topics under an assignment is duplicated between the AssignmentController views and the SignupSheetController views. Both the instructor and the student can view the topics by selecting an assignment and we were required to remove this duplication in the views.

= Re-factored Code Cases =

== Case 1 : Refactoring the AssignmentsController and SignupSheetController ==

===Removing duplicate _add_signup_topics partials===
The AssignmentsController displayed topics to the instructor while he was editing an assignment. It used _add_signup_topics.html.erb partial to render topics under the topics tab. The SignupSheetController displayed topics to a student who wanted to view signup topics under an assignment. It was found that it had its own copy namely _add_signup_topcis.html.erb to display topics to the student. We wanted to have these two controllers use the same views to render the same thing which was list of topics under an assignment. We made the AssignmentsController reuse the _add_signup_topcis.html.erb partial under the SignupSheetController.

view:assignments/edit.html.erb 
This view contains all the tabs to display like general,rubrics,review_strategy, topics which are related to the selected assignment. tabs-5 is the topics tab which we are interested in.
<pre>
<div id="tabs-3">
<%= render 'assignments/edit/review_strategy' %>
</div>
<div id="tabs-4">
<%= render 'assignments/edit/due_dates' %>
</div>
<div id="tabs-5">
<%= render 'assignments/edit/add_signup_topics' %>
</div>
</pre>

===After Changes===
We have redundant code in two methods so we merged add_signup_topics_staggered and add_signup_topics into add_signup_topics. The action calls single method for both type of assignments and renders views based on condition of staggered or non-staggered assignment.

<pre>
<div id="tabs-3">
<%= render 'assignments/edit/review_strategy' %>
</div>
<div id="tabs-4">
<%= render 'assignments/edit/due_dates' %>
</div>
<div id="tabs-5">
<%= render '/sign_up_sheet/add_signup_topcis.html' %>
</div>
</pre>

Refactoring view code into relevant views 
There were no edit/delete links to edit/delete a topic in the instructor view. These had to be conditionally added based on the role of the currently logged in user. This was to prevent students from editing/deleting topics and to keep instructors from signing up for a topic. This was implemented as follows.

===Adding Edit/Delete functionality to topics tab===

The current expertiza project had two views to display the Actions column in the topics table. These were _reserve_topics.html.erb and _actions.html. The first one was displaying the signup button for the student and the latter was displaying the bookmarks and rendering the _reserve_topics.html.erb after the bookmarks. On top of this we had to add the edit/delete links for the instructor. A refactor was called for. We decided to create a _all_actions.html.erb partial which had the responsibility to display the relevant actions depending upon the role of the currently logged in user. This helped us remove the separate partial to render actions pertaining to a student, namely _reserve_topics.html.erb . Also the _actions.html.erb only took care of displaying the bookmark links rather than dealing with both bookmarks and actions.

partial_view:_all_actions,html.erb
<pre>
<% if ['Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator'].include? current_user_role?.name %>
<td align="center">
<%= link_to image_tag('edit_icon.png', :border => 0, :title => 'Edit Topic', :align => 'middle'), :controller=>'sign_up_sheet', :action=> 'edit', :id => topic.id %>
<%= link_to image_tag('delete_icon.png', :border => 0, :title => 'Delete Topic', :align => 'middle'), sign_up_sheet_path(topic.id), method: :delete, data: {confirm: 'Are you sure?'} %>
<%elsif @show_actions %>
#Render signup button for student here. The @show_actions will be true if this partial is navigated from the SignupSheetController which is accessible only to students.
</pre>

def redirect_to_sign_up(assignment_id)
assignment = Assignment.find(assignment_id)
redirect_to :action => 'add_signup_topics', :id => assignment_id
end

Similarly the method call is re-factored in various views.
For instance, for view _assignments_actions.html.erb

Before Changes 
<% if @assignment.staggered_deadline == true %>
<%= link_to image_tag('/images/tree_view/edit-signup-sheet-24.png', :title => 'Edit signup sheet'),
{:controller => 'sign_up_sheet', :action => 'add_signup_topics_staggered', :id => node.node_object_id},
{:title => 'Edit signup sheet'} %>
<% else %>
<%= link_to image_tag('/images/tree_view/edit-signup-sheet-24.png', :title => 'Edit signup sheet'),
{:controller => 'sign_up_sheet', :action => 'add_signup_topics', :id => node.node_object_id},
{:title => 'Edit signup sheet'} %>
<% end %>

After Changes 
<%= link_to image_tag('/images/tree_view/edit-signup-sheet-24.png', :title => 'Edit signup sheet'),
{:controller => 'sign_up_sheet', :action => 'add_signup_topics', :id => node.node_object_id},
{:title => 'Edit signup sheet'} %>

== Case 2 : Method Extraction ==

Improved readability by [http://sourcemaking.com/refactoring/extract-method extracting] two separate functionalities from the same method into separate methods with appropriate naming convention and responsibilities.

===Current Scenario===

The add_signup_topics calculated due dates for separate topics for a Staggered assignment with individual Topic deadlines.

def add_signup_topics
load_add_signup_topics(params[:id])
if @assignment.staggered_deadline ==true
@review_rounds = Assignment.find(params[:id]).get_review_rounds
@topics = SignUpTopic.find_all_by_assignment_id(params[:id])

#below functionality finds allows to set due dates for topics of assignment
@duedates = SignUpTopic.find_by_sql("SELECT s.id as topic_id FROM sign_up_topics s WHERE s.assignment_id = " + params[:id].to_s)
if !@topics.nil?
i=0
@topics.each { |topic|
......
i = i + 1
end

#Render a view different for staggered deadlines assignment from the add_sign_up.html.erb
render "add_signup_topics_staggered"
end
end

===After Changes===

The logic to calculate due_dates was moved to a separate method called assignment_due_date , as this is only valid for staggered assignments
and hence it should be placed in a different method instead of merging it the add_signup_topics

def add_signup_topics
load_add_signup_topics(params[:id])
if @assignment.staggered_deadline ==true
@review_rounds = Assignment.find(params[:id]).get_review_rounds
@topics = SignUpTopic.find_all_by_assignment_id(params[:id])

#Function call to set up due dates
assignment_due_date

#Render a view different from the add_sign_up.html.erb , so rendering a view for staggered deadlines.
render "add_signup_topics_staggered"
end
end

def assignment_due_date
#below functionality finds allows to set due dates for topics of assignment
@duedates = SignUpTopic.find_by_sql("SELECT s.id as topic_id FROM sign_up_topics s WHERE s.assignment_id = " + params[:id].to_s)
if !@topics.nil?
i=0
@topics.each { |topic|
......
i = i + 1
end
end

==Case 3 : Modularize Code in application.rb==
===Current Scenario===
In the assignment.rb model, there exists one method(check_condition) which checks whether review, meta-review, etc are allowed or not. This method makes database calls to TopicDeadline table, DueDate and DeadlineType tables. Following is the code which was existing before the changes were made. It has the logic to find the nearest due date that hasn't passed.

assignment.rb

drop_topic_deadline_id = DeadlineType.find_by_name('drop_topic').id
if self.staggered_deadline?

if topic_id

next_due_date = TopicDeadline.find(:first, :conditions => ['topic_id = ? and due_at >= ? and deadline_type_id <> ?',
topic_id, Time.now, drop_topic_deadline_id], :order => 'due_at')
else

next_due_date = TopicDeadline.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
self.id, Time.now, drop_topic_deadline_id], :joins => {:topic => :assignment}, :order => 'due_at')
end
else
next_due_date = DueDate.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
self.id, Time.now, drop_topic_deadline_id], :order => 'due_at')
end

===After changes===
The database queries have been moved to their respective models. The queries to TopicDeadline table, DueDate table and DeadlineType table have been moved to their models. Below is the new code in assignments.rb model which calls TopicDeadline.rb, DueDate.rb and DeadlineType.rb respectively for the queries in their tables:

assignment.rb model

if self.staggered_deadline?
next_due_date = TopicDeadline.find_next_due_date(topic_id,self.id)
else
next_due_date = DueDate.find_next_due_date(self.id)
end

New find_next_due_date defined in topic_deadline.rb
def self.find_next_due_date(topic_id,assignment_id)
drop_topic_deadline_id = DeadlineType.find_drop_topic_deadline_id()
if topic_id
TopicDeadline.find(:first, :conditions => ['topic_id = ? and due_at >= ? and deadline_type_id <> ?',
topic_id, Time.now, drop_topic_deadline_id], :order => 'due_at')
else
TopicDeadline.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
assignment_id, Time.now, drop_topic_deadline_id], :joins => {:topic => :assignment}, :order => 'due_at')
end
end

New find_next_due_date method defined in due_date.rb

def self.find_next_due_date(assignment_id
drop_topic_deadline_id = DeadlineType.find_drop_topic_deadline_id()
DueDate.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
assignment_id, Time.now, drop_topic_deadline_id], :order => 'due_at')
end

New find_drop_topic_deadline_id method defined in deadline_type.rb

def self.find_drop_topic_deadline_id()
DeadlineType.find_by_name('drop_topic').id
end

== Case 4 : DeadCode Elimination in sign_up_sheet_controller.rb ==

The local variables topic_set and topic under the staggered deadline check statement were never used in the entire scope of the project , it introduced code smells. So it was checked if there was any reference to this code, and upon discovering it was not used anywhere, we decided to eliminate this [http://en.wikipedia.org/wiki/Dead_code_elimination deadcode].

===Current Scenario===

def create_default_for_microtask
.....

if @assignment.staggered_deadline?
topic_set = Array.new
topic = @sign_up_topic.id
end

.....
end

===After Changes===

def create_default_for_microtask
.....

.....
end

=Steps to verify changes=
Log into the application with the user having instructor's role or super user's role.

1. Go to Manage -> Assignments and hover over the assignment “StaggeredDeadlines_Refactoring”.

2. Click on “New Topic”.

3. Enter the details of the topic you want to create. Create at least 2 topics for better analysis of the project.

[[File:AddTopic.png]]

4. Now once you have created two new topics , then Click on “Show start/due date”.

5. You should be able to view the new start and due dates of your topics confirming these are the staggered deadlines for “StaggeredDeadlines_Refactoring” which has many topics with different deadlines.

[[File:ShowdueDate.png]]

6. Now to view the difference between the Stagerred and Non-Staggered Deadlines, follow steps.

7. Go to Manage -> Assignments and hover over “SALT Demo” and click on “Edit Signup sheet”.

8. Click on “New Topic” and fill in the details for a new topic.

[[File:NonstaggeredAddTopic.png]]

9. Now you will be able to see that there is no option for “Show Start/Due Date” which is because of the reason that this is not a staggered assignment.

[[File:NodueDate.png]]

10. Hence there is only one due date and has no dependencies on others.

= Concise Report on Refactoring =

The project had redundant code, multiple functionalities in a method and extra conditional statements in controller, model and view files. We analyzed each occurrence of these issues, thus creating a list which needed to be refactored. Controllers like sign_up_sheet_controler, assignment.rb, due_date.rb,deadline_types.rb along with other files were modified. It's very difficult to explain the sequential and detailed procedure, but it has been explained in the sections above within the capacity of the Wiki.

= Additional Learning and Future Work=

In current implementation, our database has two tables for staggered and non-staggered deadlines. For any future improvements, we can make use of [http://blog.thirst.co/post/14885390861/rails-single-table-inheritance STI (Single Table Inheritance)] and analyze if applying STI would really impact query performance when application runs and extracts data from database.

= References=
[http://expertiza.ncsu.edu/ Expertiza] 
[http://eewang.github.io/blog/2013/03/12/how-and-when-to-use-single-table-inheritance-in-rails/ Single Table Inheritance] 
[http://en.wikipedia.org/wiki/Code_refactoring Code Refactoring] 
[http://en.wikipedia.org/wiki/Code_smell Code smell]

CSC/ECE 517 Fall 2014/oss E1453 syy

2014-10-29T20:06:45Z

Shjoshi2: /* Current Scenario */

'''E1453. Refactoring AssignmentsController'''

This page provides a description of the Expertiza based OSS project. This project aimed at refactoring the AssignmentsController as well as adding some missing functionality related to topics within an assignment.

'''Introduction to Expertiza''' 

[http://expertiza.ncsu.edu/ Expertiza] is a project developed using Ruby on Rails platform. It provides features like peer review, team assignments and submission of projects. This can be achieved by submitting code base, URL of hosted code on remote server and Wiki submissions. It is an open source application and the code can be cloned from [https://github.com/expertiza/expertiza github]. This application provides an efficient way to manage assignments, grades and reviews. This makes the process easier and faster when the class strength is large.

Expertiza is supported by National Science Foundation under Grant No. 0536558. Additional funding from the NCSU Learning in a Technology-Rich Environment (LITRE) program, the NCSU Faculty Center for Teaching and Learning, the NCSU STEM Initiative, and the Center for Advanced Computing and Communication.

= Project Resources =

[https://github.com/itsmylifesoham/expertiza GitHub Project Repository]

[http://152.46.18.5:3000/ VCL IP Address]

[http://wikis.lib.ncsu.edu/index.php/Expertiza Expertiza Wiki]

= Problem Statement =
Currently the topics tab is not usable to the instructor when he is editing a current assignment or creating a new one. This functionality is necessary as it enables the instructor to create/delete/edit/view topics present under the selected assignment. Currently, the instructor achieves this using the pop-up menu that appears adjacent every assignment on the page that lists all the assignments. We were required to implement the topics tab.

The functionality to display the topics under an assignment is duplicated between the AssignmentController views and the SignupSheetController views. Both the instructor and the student can view the topics by selecting an assignment and we were required to remove this duplication in the views.

= Re-factored Code Cases =

== Case 1 : Refactoring the AssignmentsController and SignupSheetController ==

===Removing duplicate _add_signup_topics partials===
The AssignmentsController displayed topics to the instructor while he was editing an assignment. It used _add_signup_topics.html.erb partial to render topics under the topics tab. The SignupSheetController displayed topics to a student who wanted to view signup topics under an assignment. It was found that it had its own copy namely _add_signup_topcis.html.erb to display topics to the student. We wanted to have these two controllers use the same views to render the same thing which was list of topics under an assignment. We made the AssignmentsController reuse the _add_signup_topcis.html.erb partial under the SignupSheetController.

view:assignments/edit.html.erb 
This view contains all the tabs to display like general,rubrics,review_strategy, topics which are related to the selected assignment. tabs-5 is the topics tab which we are interested in.
<pre>
<div id="tabs-3">
<%= render 'assignments/edit/review_strategy' %>
</div>
<div id="tabs-4">
<%= render 'assignments/edit/due_dates' %>
</div>
<div id="tabs-5">
<%= render 'assignments/edit/add_signup_topics' %>
</div>
</pre>

===After Changes===
We have redundant code in two methods so we merged add_signup_topics_staggered and add_signup_topics into add_signup_topics. The action calls single method for both type of assignments and renders views based on condition of staggered or non-staggered assignment.

<pre>
<div id="tabs-3">
<%= render 'assignments/edit/review_strategy' %>
</div>
<div id="tabs-4">
<%= render 'assignments/edit/due_dates' %>
</div>
<div id="tabs-5">
<%= render '/sign_up_sheet/add_signup_topcis.html' %>
</div>
</pre>

Refactoring view code into relevant views 
There were no edit/delete links to edit/delete a topic in the instructor view. These had to be conditionally added based on the role of the currently logged in user. This was to prevent students from editing/deleting topics and to keep instructors from signing up for a topic. This was implemented as follows.

===Adding Edit/Delete links===

The current expertiza project had two views to display the Actions column in the topics table. These were _reserve_topics.html.erb and _actions.html. The first one was displaying the signup button for the student and the latter was displaying the bookmarks and rendering the _reserve_topics.html.erb after the bookmarks. On top of this we had to add the edit/delete links for the instructor. A refactor was called for. We decided to create a _all_actions.html.erb partial which had the responsibility to display the relevant actions depending upon the role of the currently logged in user. This helped us remove the separate partial to render actions pertaining to a student, namely _reserve_topics.html.erb . Also the _actions.html.erb only took care of displaying the bookmark links rather than dealing with both bookmarks and actions.

partial_view:_all_actions,html.erb
<pre>
<% if ['Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator'].include? current_user_role?.name %>
<td align="center">
<%= link_to image_tag('edit_icon.png', :border => 0, :title => 'Edit Topic', :align => 'middle'), :controller=>'sign_up_sheet', :action=> 'edit', :id => topic.id %>
<%= link_to image_tag('delete_icon.png', :border => 0, :title => 'Delete Topic', :align => 'middle'), sign_up_sheet_path(topic.id), method: :delete, data: {confirm: 'Are you sure?'} %>
<%elsif @show_actions %>
#Render signup button for student here. The @show_actions will be true if this partial is navigated from the SignupSheetController which is accessible only to students.
</pre>

def redirect_to_sign_up(assignment_id)
assignment = Assignment.find(assignment_id)
redirect_to :action => 'add_signup_topics', :id => assignment_id
end

Similarly the method call is re-factored in various views.
For instance, for view _assignments_actions.html.erb

Before Changes 
<% if @assignment.staggered_deadline == true %>
<%= link_to image_tag('/images/tree_view/edit-signup-sheet-24.png', :title => 'Edit signup sheet'),
{:controller => 'sign_up_sheet', :action => 'add_signup_topics_staggered', :id => node.node_object_id},
{:title => 'Edit signup sheet'} %>
<% else %>
<%= link_to image_tag('/images/tree_view/edit-signup-sheet-24.png', :title => 'Edit signup sheet'),
{:controller => 'sign_up_sheet', :action => 'add_signup_topics', :id => node.node_object_id},
{:title => 'Edit signup sheet'} %>
<% end %>

After Changes 
<%= link_to image_tag('/images/tree_view/edit-signup-sheet-24.png', :title => 'Edit signup sheet'),
{:controller => 'sign_up_sheet', :action => 'add_signup_topics', :id => node.node_object_id},
{:title => 'Edit signup sheet'} %>

== Case 2 : Method Extraction ==

Improved readability by [http://sourcemaking.com/refactoring/extract-method extracting] two separate functionalities from the same method into separate methods with appropriate naming convention and responsibilities.

===Current Scenario===

The add_signup_topics calculated due dates for separate topics for a Staggered assignment with individual Topic deadlines.

def add_signup_topics
load_add_signup_topics(params[:id])
if @assignment.staggered_deadline ==true
@review_rounds = Assignment.find(params[:id]).get_review_rounds
@topics = SignUpTopic.find_all_by_assignment_id(params[:id])

#below functionality finds allows to set due dates for topics of assignment
@duedates = SignUpTopic.find_by_sql("SELECT s.id as topic_id FROM sign_up_topics s WHERE s.assignment_id = " + params[:id].to_s)
if !@topics.nil?
i=0
@topics.each { |topic|
......
i = i + 1
end

#Render a view different for staggered deadlines assignment from the add_sign_up.html.erb
render "add_signup_topics_staggered"
end
end

===After Changes===

The logic to calculate due_dates was moved to a separate method called assignment_due_date , as this is only valid for staggered assignments
and hence it should be placed in a different method instead of merging it the add_signup_topics

def add_signup_topics
load_add_signup_topics(params[:id])
if @assignment.staggered_deadline ==true
@review_rounds = Assignment.find(params[:id]).get_review_rounds
@topics = SignUpTopic.find_all_by_assignment_id(params[:id])

#Function call to set up due dates
assignment_due_date

#Render a view different from the add_sign_up.html.erb , so rendering a view for staggered deadlines.
render "add_signup_topics_staggered"
end
end

def assignment_due_date
#below functionality finds allows to set due dates for topics of assignment
@duedates = SignUpTopic.find_by_sql("SELECT s.id as topic_id FROM sign_up_topics s WHERE s.assignment_id = " + params[:id].to_s)
if !@topics.nil?
i=0
@topics.each { |topic|
......
i = i + 1
end
end

==Case 3 : Modularize Code in application.rb==
===Current Scenario===
In the assignment.rb model, there exists one method(check_condition) which checks whether review, meta-review, etc are allowed or not. This method makes database calls to TopicDeadline table, DueDate and DeadlineType tables. Following is the code which was existing before the changes were made. It has the logic to find the nearest due date that hasn't passed.

assignment.rb

drop_topic_deadline_id = DeadlineType.find_by_name('drop_topic').id
if self.staggered_deadline?

if topic_id

next_due_date = TopicDeadline.find(:first, :conditions => ['topic_id = ? and due_at >= ? and deadline_type_id <> ?',
topic_id, Time.now, drop_topic_deadline_id], :order => 'due_at')
else

next_due_date = TopicDeadline.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
self.id, Time.now, drop_topic_deadline_id], :joins => {:topic => :assignment}, :order => 'due_at')
end
else
next_due_date = DueDate.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
self.id, Time.now, drop_topic_deadline_id], :order => 'due_at')
end

===After changes===
The database queries have been moved to their respective models. The queries to TopicDeadline table, DueDate table and DeadlineType table have been moved to their models. Below is the new code in assignments.rb model which calls TopicDeadline.rb, DueDate.rb and DeadlineType.rb respectively for the queries in their tables:

assignment.rb model

if self.staggered_deadline?
next_due_date = TopicDeadline.find_next_due_date(topic_id,self.id)
else
next_due_date = DueDate.find_next_due_date(self.id)
end

New find_next_due_date defined in topic_deadline.rb
def self.find_next_due_date(topic_id,assignment_id)
drop_topic_deadline_id = DeadlineType.find_drop_topic_deadline_id()
if topic_id
TopicDeadline.find(:first, :conditions => ['topic_id = ? and due_at >= ? and deadline_type_id <> ?',
topic_id, Time.now, drop_topic_deadline_id], :order => 'due_at')
else
TopicDeadline.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
assignment_id, Time.now, drop_topic_deadline_id], :joins => {:topic => :assignment}, :order => 'due_at')
end
end

New find_next_due_date method defined in due_date.rb

def self.find_next_due_date(assignment_id
drop_topic_deadline_id = DeadlineType.find_drop_topic_deadline_id()
DueDate.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
assignment_id, Time.now, drop_topic_deadline_id], :order => 'due_at')
end

New find_drop_topic_deadline_id method defined in deadline_type.rb

def self.find_drop_topic_deadline_id()
DeadlineType.find_by_name('drop_topic').id
end

== Case 4 : DeadCode Elimination in sign_up_sheet_controller.rb ==

The local variables topic_set and topic under the staggered deadline check statement were never used in the entire scope of the project , it introduced code smells. So it was checked if there was any reference to this code, and upon discovering it was not used anywhere, we decided to eliminate this [http://en.wikipedia.org/wiki/Dead_code_elimination deadcode].

===Current Scenario===

def create_default_for_microtask
.....

if @assignment.staggered_deadline?
topic_set = Array.new
topic = @sign_up_topic.id
end

.....
end

===After Changes===

def create_default_for_microtask
.....

.....
end

=Steps to verify changes=
Log into the application with the user having instructor's role or super user's role.

1. Go to Manage -> Assignments and hover over the assignment “StaggeredDeadlines_Refactoring”.

2. Click on “New Topic”.

3. Enter the details of the topic you want to create. Create at least 2 topics for better analysis of the project.

[[File:AddTopic.png]]

4. Now once you have created two new topics , then Click on “Show start/due date”.

5. You should be able to view the new start and due dates of your topics confirming these are the staggered deadlines for “StaggeredDeadlines_Refactoring” which has many topics with different deadlines.

[[File:ShowdueDate.png]]

6. Now to view the difference between the Stagerred and Non-Staggered Deadlines, follow steps.

7. Go to Manage -> Assignments and hover over “SALT Demo” and click on “Edit Signup sheet”.

8. Click on “New Topic” and fill in the details for a new topic.

[[File:NonstaggeredAddTopic.png]]

9. Now you will be able to see that there is no option for “Show Start/Due Date” which is because of the reason that this is not a staggered assignment.

[[File:NodueDate.png]]

10. Hence there is only one due date and has no dependencies on others.

= Concise Report on Refactoring =

The project had redundant code, multiple functionalities in a method and extra conditional statements in controller, model and view files. We analyzed each occurrence of these issues, thus creating a list which needed to be refactored. Controllers like sign_up_sheet_controler, assignment.rb, due_date.rb,deadline_types.rb along with other files were modified. It's very difficult to explain the sequential and detailed procedure, but it has been explained in the sections above within the capacity of the Wiki.

= Additional Learning and Future Work=

In current implementation, our database has two tables for staggered and non-staggered deadlines. For any future improvements, we can make use of [http://blog.thirst.co/post/14885390861/rails-single-table-inheritance STI (Single Table Inheritance)] and analyze if applying STI would really impact query performance when application runs and extracts data from database.

= References=
[http://expertiza.ncsu.edu/ Expertiza] 
[http://eewang.github.io/blog/2013/03/12/how-and-when-to-use-single-table-inheritance-in-rails/ Single Table Inheritance] 
[http://en.wikipedia.org/wiki/Code_refactoring Code Refactoring] 
[http://en.wikipedia.org/wiki/Code_smell Code smell]

CSC/ECE 517 Fall 2014/oss E1453 syy

2014-10-29T20:05:59Z

Shjoshi2:

'''E1453. Refactoring AssignmentsController'''

This page provides a description of the Expertiza based OSS project. This project aimed at refactoring the AssignmentsController as well as adding some missing functionality related to topics within an assignment.

'''Introduction to Expertiza''' 

[http://expertiza.ncsu.edu/ Expertiza] is a project developed using Ruby on Rails platform. It provides features like peer review, team assignments and submission of projects. This can be achieved by submitting code base, URL of hosted code on remote server and Wiki submissions. It is an open source application and the code can be cloned from [https://github.com/expertiza/expertiza github]. This application provides an efficient way to manage assignments, grades and reviews. This makes the process easier and faster when the class strength is large.

Expertiza is supported by National Science Foundation under Grant No. 0536558. Additional funding from the NCSU Learning in a Technology-Rich Environment (LITRE) program, the NCSU Faculty Center for Teaching and Learning, the NCSU STEM Initiative, and the Center for Advanced Computing and Communication.

= Project Resources =

[https://github.com/itsmylifesoham/expertiza GitHub Project Repository]

[http://152.46.18.5:3000/ VCL IP Address]

[http://wikis.lib.ncsu.edu/index.php/Expertiza Expertiza Wiki]

= Problem Statement =
Currently the topics tab is not usable to the instructor when he is editing a current assignment or creating a new one. This functionality is necessary as it enables the instructor to create/delete/edit/view topics present under the selected assignment. Currently, the instructor achieves this using the pop-up menu that appears adjacent every assignment on the page that lists all the assignments. We were required to implement the topics tab.

The functionality to display the topics under an assignment is duplicated between the AssignmentController views and the SignupSheetController views. Both the instructor and the student can view the topics by selecting an assignment and we were required to remove this duplication in the views.

= Re-factored Code Cases =

== Case 1 : Refactoring the AssignmentsController and SignupSheetController ==

===Current Scenario===
The AssignmentsController displayed topics to the instructor while he was editing an assignment. It used _add_signup_topics.html.erb partial to render topics under the topics tab. The SignupSheetController displayed topics to a student who wanted to view signup topics under an assignment. It was found that it had its own copy namely _add_signup_topcis.html.erb to display topics to the student. We wanted to have these two controllers use the same views to render the same thing which was list of topics under an assignment. We made the AssignmentsController reuse the _add_signup_topcis.html.erb partial under the SignupSheetController.

view:assignments/edit.html.erb 
This view contains all the tabs to display like general,rubrics,review_strategy, topics which are related to the selected assignment. tabs-5 is the topics tab which we are interested in.
<pre>
<div id="tabs-3">
<%= render 'assignments/edit/review_strategy' %>
</div>
<div id="tabs-4">
<%= render 'assignments/edit/due_dates' %>
</div>
<div id="tabs-5">
<%= render 'assignments/edit/add_signup_topics' %>
</div>
</pre>

===After Changes===
We have redundant code in two methods so we merged add_signup_topics_staggered and add_signup_topics into add_signup_topics. The action calls single method for both type of assignments and renders views based on condition of staggered or non-staggered assignment.

<pre>
<div id="tabs-3">
<%= render 'assignments/edit/review_strategy' %>
</div>
<div id="tabs-4">
<%= render 'assignments/edit/due_dates' %>
</div>
<div id="tabs-5">
<%= render '/sign_up_sheet/add_signup_topcis.html' %>
</div>
</pre>

Refactoring view code into relevant views 
There were no edit/delete links to edit/delete a topic in the instructor view. These had to be conditionally added based on the role of the currently logged in user. This was to prevent students from editing/deleting topics and to keep instructors from signing up for a topic. This was implemented as follows.

===Adding Edit/Delete links===

The current expertiza project had two views to display the Actions column in the topics table. These were _reserve_topics.html.erb and _actions.html. The first one was displaying the signup button for the student and the latter was displaying the bookmarks and rendering the _reserve_topics.html.erb after the bookmarks. On top of this we had to add the edit/delete links for the instructor. A refactor was called for. We decided to create a _all_actions.html.erb partial which had the responsibility to display the relevant actions depending upon the role of the currently logged in user. This helped us remove the separate partial to render actions pertaining to a student, namely _reserve_topics.html.erb . Also the _actions.html.erb only took care of displaying the bookmark links rather than dealing with both bookmarks and actions.

partial_view:_all_actions,html.erb
<pre>
<% if ['Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator'].include? current_user_role?.name %>
<td align="center">
<%= link_to image_tag('edit_icon.png', :border => 0, :title => 'Edit Topic', :align => 'middle'), :controller=>'sign_up_sheet', :action=> 'edit', :id => topic.id %>
<%= link_to image_tag('delete_icon.png', :border => 0, :title => 'Delete Topic', :align => 'middle'), sign_up_sheet_path(topic.id), method: :delete, data: {confirm: 'Are you sure?'} %>
<%elsif @show_actions %>
#Render signup button for student here. The @show_actions will be true if this partial is navigated from the SignupSheetController which is accessible only to students.
</pre>

def redirect_to_sign_up(assignment_id)
assignment = Assignment.find(assignment_id)
redirect_to :action => 'add_signup_topics', :id => assignment_id
end

Similarly the method call is re-factored in various views.
For instance, for view _assignments_actions.html.erb

Before Changes 
<% if @assignment.staggered_deadline == true %>
<%= link_to image_tag('/images/tree_view/edit-signup-sheet-24.png', :title => 'Edit signup sheet'),
{:controller => 'sign_up_sheet', :action => 'add_signup_topics_staggered', :id => node.node_object_id},
{:title => 'Edit signup sheet'} %>
<% else %>
<%= link_to image_tag('/images/tree_view/edit-signup-sheet-24.png', :title => 'Edit signup sheet'),
{:controller => 'sign_up_sheet', :action => 'add_signup_topics', :id => node.node_object_id},
{:title => 'Edit signup sheet'} %>
<% end %>

After Changes 
<%= link_to image_tag('/images/tree_view/edit-signup-sheet-24.png', :title => 'Edit signup sheet'),
{:controller => 'sign_up_sheet', :action => 'add_signup_topics', :id => node.node_object_id},
{:title => 'Edit signup sheet'} %>

== Case 2 : Method Extraction ==

Improved readability by [http://sourcemaking.com/refactoring/extract-method extracting] two separate functionalities from the same method into separate methods with appropriate naming convention and responsibilities.

===Current Scenario===

The add_signup_topics calculated due dates for separate topics for a Staggered assignment with individual Topic deadlines.

def add_signup_topics
load_add_signup_topics(params[:id])
if @assignment.staggered_deadline ==true
@review_rounds = Assignment.find(params[:id]).get_review_rounds
@topics = SignUpTopic.find_all_by_assignment_id(params[:id])

#below functionality finds allows to set due dates for topics of assignment
@duedates = SignUpTopic.find_by_sql("SELECT s.id as topic_id FROM sign_up_topics s WHERE s.assignment_id = " + params[:id].to_s)
if !@topics.nil?
i=0
@topics.each { |topic|
......
i = i + 1
end

#Render a view different for staggered deadlines assignment from the add_sign_up.html.erb
render "add_signup_topics_staggered"
end
end

===After Changes===

The logic to calculate due_dates was moved to a separate method called assignment_due_date , as this is only valid for staggered assignments
and hence it should be placed in a different method instead of merging it the add_signup_topics

def add_signup_topics
load_add_signup_topics(params[:id])
if @assignment.staggered_deadline ==true
@review_rounds = Assignment.find(params[:id]).get_review_rounds
@topics = SignUpTopic.find_all_by_assignment_id(params[:id])

#Function call to set up due dates
assignment_due_date

#Render a view different from the add_sign_up.html.erb , so rendering a view for staggered deadlines.
render "add_signup_topics_staggered"
end
end

def assignment_due_date
#below functionality finds allows to set due dates for topics of assignment
@duedates = SignUpTopic.find_by_sql("SELECT s.id as topic_id FROM sign_up_topics s WHERE s.assignment_id = " + params[:id].to_s)
if !@topics.nil?
i=0
@topics.each { |topic|
......
i = i + 1
end
end

==Case 3 : Modularize Code in application.rb==
===Current Scenario===
In the assignment.rb model, there exists one method(check_condition) which checks whether review, meta-review, etc are allowed or not. This method makes database calls to TopicDeadline table, DueDate and DeadlineType tables. Following is the code which was existing before the changes were made. It has the logic to find the nearest due date that hasn't passed.

assignment.rb

drop_topic_deadline_id = DeadlineType.find_by_name('drop_topic').id
if self.staggered_deadline?

if topic_id

next_due_date = TopicDeadline.find(:first, :conditions => ['topic_id = ? and due_at >= ? and deadline_type_id <> ?',
topic_id, Time.now, drop_topic_deadline_id], :order => 'due_at')
else

next_due_date = TopicDeadline.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
self.id, Time.now, drop_topic_deadline_id], :joins => {:topic => :assignment}, :order => 'due_at')
end
else
next_due_date = DueDate.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
self.id, Time.now, drop_topic_deadline_id], :order => 'due_at')
end

===After changes===
The database queries have been moved to their respective models. The queries to TopicDeadline table, DueDate table and DeadlineType table have been moved to their models. Below is the new code in assignments.rb model which calls TopicDeadline.rb, DueDate.rb and DeadlineType.rb respectively for the queries in their tables:

assignment.rb model

if self.staggered_deadline?
next_due_date = TopicDeadline.find_next_due_date(topic_id,self.id)
else
next_due_date = DueDate.find_next_due_date(self.id)
end

New find_next_due_date defined in topic_deadline.rb
def self.find_next_due_date(topic_id,assignment_id)
drop_topic_deadline_id = DeadlineType.find_drop_topic_deadline_id()
if topic_id
TopicDeadline.find(:first, :conditions => ['topic_id = ? and due_at >= ? and deadline_type_id <> ?',
topic_id, Time.now, drop_topic_deadline_id], :order => 'due_at')
else
TopicDeadline.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
assignment_id, Time.now, drop_topic_deadline_id], :joins => {:topic => :assignment}, :order => 'due_at')
end
end

New find_next_due_date method defined in due_date.rb

def self.find_next_due_date(assignment_id
drop_topic_deadline_id = DeadlineType.find_drop_topic_deadline_id()
DueDate.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
assignment_id, Time.now, drop_topic_deadline_id], :order => 'due_at')
end

New find_drop_topic_deadline_id method defined in deadline_type.rb

def self.find_drop_topic_deadline_id()
DeadlineType.find_by_name('drop_topic').id
end

== Case 4 : DeadCode Elimination in sign_up_sheet_controller.rb ==

The local variables topic_set and topic under the staggered deadline check statement were never used in the entire scope of the project , it introduced code smells. So it was checked if there was any reference to this code, and upon discovering it was not used anywhere, we decided to eliminate this [http://en.wikipedia.org/wiki/Dead_code_elimination deadcode].

===Current Scenario===

def create_default_for_microtask
.....

if @assignment.staggered_deadline?
topic_set = Array.new
topic = @sign_up_topic.id
end

.....
end

===After Changes===

def create_default_for_microtask
.....

.....
end

=Steps to verify changes=
Log into the application with the user having instructor's role or super user's role.

1. Go to Manage -> Assignments and hover over the assignment “StaggeredDeadlines_Refactoring”.

2. Click on “New Topic”.

3. Enter the details of the topic you want to create. Create at least 2 topics for better analysis of the project.

[[File:AddTopic.png]]

4. Now once you have created two new topics , then Click on “Show start/due date”.

5. You should be able to view the new start and due dates of your topics confirming these are the staggered deadlines for “StaggeredDeadlines_Refactoring” which has many topics with different deadlines.

[[File:ShowdueDate.png]]

6. Now to view the difference between the Stagerred and Non-Staggered Deadlines, follow steps.

7. Go to Manage -> Assignments and hover over “SALT Demo” and click on “Edit Signup sheet”.

8. Click on “New Topic” and fill in the details for a new topic.

[[File:NonstaggeredAddTopic.png]]

9. Now you will be able to see that there is no option for “Show Start/Due Date” which is because of the reason that this is not a staggered assignment.

[[File:NodueDate.png]]

10. Hence there is only one due date and has no dependencies on others.

= Concise Report on Refactoring =

The project had redundant code, multiple functionalities in a method and extra conditional statements in controller, model and view files. We analyzed each occurrence of these issues, thus creating a list which needed to be refactored. Controllers like sign_up_sheet_controler, assignment.rb, due_date.rb,deadline_types.rb along with other files were modified. It's very difficult to explain the sequential and detailed procedure, but it has been explained in the sections above within the capacity of the Wiki.

= Additional Learning and Future Work=

In current implementation, our database has two tables for staggered and non-staggered deadlines. For any future improvements, we can make use of [http://blog.thirst.co/post/14885390861/rails-single-table-inheritance STI (Single Table Inheritance)] and analyze if applying STI would really impact query performance when application runs and extracts data from database.

= References=
[http://expertiza.ncsu.edu/ Expertiza] 
[http://eewang.github.io/blog/2013/03/12/how-and-when-to-use-single-table-inheritance-in-rails/ Single Table Inheritance] 
[http://en.wikipedia.org/wiki/Code_refactoring Code Refactoring] 
[http://en.wikipedia.org/wiki/Code_smell Code smell]

CSC/ECE 517 Fall 2014/oss E1453 syy

2014-10-29T19:48:53Z

Shjoshi2:

'''E1453. Refactoring AssignmentsController'''

This page provides a description of the Expertiza based OSS project. This project aimed at refactoring the AssignmentsController as well as adding some missing functionality related to topics within an assignment.

'''Introduction to Expertiza''' 

[http://expertiza.ncsu.edu/ Expertiza] is a project developed using Ruby on Rails platform. It provides features like peer review, team assignments and submission of projects. This can be achieved by submitting code base, URL of hosted code on remote server and Wiki submissions. It is an open source application and the code can be cloned from [https://github.com/expertiza/expertiza github]. This application provides an efficient way to manage assignments, grades and reviews. This makes the process easier and faster when the class strength is large.

Expertiza is supported by National Science Foundation under Grant No. 0536558. Additional funding from the NCSU Learning in a Technology-Rich Environment (LITRE) program, the NCSU Faculty Center for Teaching and Learning, the NCSU STEM Initiative, and the Center for Advanced Computing and Communication.

= Project Resources =

[https://github.com/itsmylifesoham/expertiza GitHub Project Repository]

[http://152.46.18.5:3000/ VCL IP Address]

[http://wikis.lib.ncsu.edu/index.php/Expertiza Expertiza Wiki]

= Problem Statement =
Currently the topics tab is not usable to the instructor when he is editing a current assignment or creating a new one. This functionality is necessary as it enables the instructor to create/delete/edit/view topics present under the selected assignment. Currently, the instructor achieves this using the pop-up menu that appears adjacent every assignment on the page that lists all the assignments. We were required to implement the topics tab.

The functionality to display the topics under an assignment is duplicated between the AssignmentController views and the SignupSheetController views. Both the instructor and the student can view the topics by selecting an assignment and we were required to remove this duplication in the views.

= Re-factored Code Cases =

== Case 1 : Refactoring the AssignmentsController and SignupSheetController to use same views ==

===Current Scenario===
The AssignmentsController displayed topics to the instructor while he was editing an assignment. It used _add_signup_topics.html.erb partial to render topics under the topics tab. The SignupSheetController displayed topics to a student who wanted to view signup topics under an assignment. It was found that it had its own copy namely _add_signup_topcis.html.erb to display topics to the student. We wanted to have these two controllers use the same views to render the same thing which was list of topics under an assignment. We made the AssignmentsController reuse the _add_signup_topcis.html.erb partial under the SignupSheetController.

view:assignments/edit.html.erb 
This view contains all the tabs to display like general,rubrics,review_strategy, topics which are related to the selected assignment. tabs-5 is the topics tab which we are interested in.
<pre>
<div id="tabs-3">
<%= render 'assignments/edit/review_strategy' %>
</div>
<div id="tabs-4">
<%= render 'assignments/edit/due_dates' %>
</div>
<div id="tabs-5">
<%= render 'assignments/edit/add_signup_topics' %>
</div>
</pre>

===After Changes===
We have redundant code in two methods so we merged add_signup_topics_staggered and add_signup_topics into add_signup_topics. The action calls single method for both type of assignments and renders views based on condition of staggered or non-staggered assignment.

<pre>
<div id="tabs-3">
<%= render 'assignments/edit/review_strategy' %>
</div>
<div id="tabs-4">
<%= render 'assignments/edit/due_dates' %>
</div>
<div id="tabs-5">
<%= render '/sign_up_sheet/add_signup_topcis.html' %>
</div>
</pre>

Single method call 
At several places in the project, there was separate method call based on staggered and non-staggered assignments. We have made a single method call and condition check in various files ,for type of assignment, has been removed as part of re-factoring.

def redirect_to_sign_up(assignment_id)
assignment = Assignment.find(assignment_id)
redirect_to :action => 'add_signup_topics', :id => assignment_id
end

Similarly the method call is re-factored in various views.
For instance, for view _assignments_actions.html.erb

Before Changes 
<% if @assignment.staggered_deadline == true %>
<%= link_to image_tag('/images/tree_view/edit-signup-sheet-24.png', :title => 'Edit signup sheet'),
{:controller => 'sign_up_sheet', :action => 'add_signup_topics_staggered', :id => node.node_object_id},
{:title => 'Edit signup sheet'} %>
<% else %>
<%= link_to image_tag('/images/tree_view/edit-signup-sheet-24.png', :title => 'Edit signup sheet'),
{:controller => 'sign_up_sheet', :action => 'add_signup_topics', :id => node.node_object_id},
{:title => 'Edit signup sheet'} %>
<% end %>

After Changes 
<%= link_to image_tag('/images/tree_view/edit-signup-sheet-24.png', :title => 'Edit signup sheet'),
{:controller => 'sign_up_sheet', :action => 'add_signup_topics', :id => node.node_object_id},
{:title => 'Edit signup sheet'} %>

== Case 2 : Method Extraction ==

Improved readability by [http://sourcemaking.com/refactoring/extract-method extracting] two separate functionalities from the same method into separate methods with appropriate naming convention and responsibilities.

===Current Scenario===

The add_signup_topics calculated due dates for separate topics for a Staggered assignment with individual Topic deadlines.

def add_signup_topics
load_add_signup_topics(params[:id])
if @assignment.staggered_deadline ==true
@review_rounds = Assignment.find(params[:id]).get_review_rounds
@topics = SignUpTopic.find_all_by_assignment_id(params[:id])

#below functionality finds allows to set due dates for topics of assignment
@duedates = SignUpTopic.find_by_sql("SELECT s.id as topic_id FROM sign_up_topics s WHERE s.assignment_id = " + params[:id].to_s)
if !@topics.nil?
i=0
@topics.each { |topic|
......
i = i + 1
end

#Render a view different for staggered deadlines assignment from the add_sign_up.html.erb
render "add_signup_topics_staggered"
end
end

===After Changes===

The logic to calculate due_dates was moved to a separate method called assignment_due_date , as this is only valid for staggered assignments
and hence it should be placed in a different method instead of merging it the add_signup_topics

def add_signup_topics
load_add_signup_topics(params[:id])
if @assignment.staggered_deadline ==true
@review_rounds = Assignment.find(params[:id]).get_review_rounds
@topics = SignUpTopic.find_all_by_assignment_id(params[:id])

#Function call to set up due dates
assignment_due_date

#Render a view different from the add_sign_up.html.erb , so rendering a view for staggered deadlines.
render "add_signup_topics_staggered"
end
end

def assignment_due_date
#below functionality finds allows to set due dates for topics of assignment
@duedates = SignUpTopic.find_by_sql("SELECT s.id as topic_id FROM sign_up_topics s WHERE s.assignment_id = " + params[:id].to_s)
if !@topics.nil?
i=0
@topics.each { |topic|
......
i = i + 1
end
end

==Case 3 : Modularize Code in application.rb==
===Current Scenario===
In the assignment.rb model, there exists one method(check_condition) which checks whether review, meta-review, etc are allowed or not. This method makes database calls to TopicDeadline table, DueDate and DeadlineType tables. Following is the code which was existing before the changes were made. It has the logic to find the nearest due date that hasn't passed.

assignment.rb

drop_topic_deadline_id = DeadlineType.find_by_name('drop_topic').id
if self.staggered_deadline?

if topic_id

next_due_date = TopicDeadline.find(:first, :conditions => ['topic_id = ? and due_at >= ? and deadline_type_id <> ?',
topic_id, Time.now, drop_topic_deadline_id], :order => 'due_at')
else

next_due_date = TopicDeadline.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
self.id, Time.now, drop_topic_deadline_id], :joins => {:topic => :assignment}, :order => 'due_at')
end
else
next_due_date = DueDate.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
self.id, Time.now, drop_topic_deadline_id], :order => 'due_at')
end

===After changes===
The database queries have been moved to their respective models. The queries to TopicDeadline table, DueDate table and DeadlineType table have been moved to their models. Below is the new code in assignments.rb model which calls TopicDeadline.rb, DueDate.rb and DeadlineType.rb respectively for the queries in their tables:

assignment.rb model

if self.staggered_deadline?
next_due_date = TopicDeadline.find_next_due_date(topic_id,self.id)
else
next_due_date = DueDate.find_next_due_date(self.id)
end

New find_next_due_date defined in topic_deadline.rb
def self.find_next_due_date(topic_id,assignment_id)
drop_topic_deadline_id = DeadlineType.find_drop_topic_deadline_id()
if topic_id
TopicDeadline.find(:first, :conditions => ['topic_id = ? and due_at >= ? and deadline_type_id <> ?',
topic_id, Time.now, drop_topic_deadline_id], :order => 'due_at')
else
TopicDeadline.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
assignment_id, Time.now, drop_topic_deadline_id], :joins => {:topic => :assignment}, :order => 'due_at')
end
end

New find_next_due_date method defined in due_date.rb

def self.find_next_due_date(assignment_id
drop_topic_deadline_id = DeadlineType.find_drop_topic_deadline_id()
DueDate.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
assignment_id, Time.now, drop_topic_deadline_id], :order => 'due_at')
end

New find_drop_topic_deadline_id method defined in deadline_type.rb

def self.find_drop_topic_deadline_id()
DeadlineType.find_by_name('drop_topic').id
end

== Case 4 : DeadCode Elimination in sign_up_sheet_controller.rb ==

The local variables topic_set and topic under the staggered deadline check statement were never used in the entire scope of the project , it introduced code smells. So it was checked if there was any reference to this code, and upon discovering it was not used anywhere, we decided to eliminate this [http://en.wikipedia.org/wiki/Dead_code_elimination deadcode].

===Current Scenario===

def create_default_for_microtask
.....

if @assignment.staggered_deadline?
topic_set = Array.new
topic = @sign_up_topic.id
end

.....
end

===After Changes===

def create_default_for_microtask
.....

.....
end

=Steps to verify changes=
Log into the application with the user having instructor's role or super user's role.

1. Go to Manage -> Assignments and hover over the assignment “StaggeredDeadlines_Refactoring”.

2. Click on “New Topic”.

3. Enter the details of the topic you want to create. Create at least 2 topics for better analysis of the project.

[[File:AddTopic.png]]

4. Now once you have created two new topics , then Click on “Show start/due date”.

5. You should be able to view the new start and due dates of your topics confirming these are the staggered deadlines for “StaggeredDeadlines_Refactoring” which has many topics with different deadlines.

[[File:ShowdueDate.png]]

6. Now to view the difference between the Stagerred and Non-Staggered Deadlines, follow steps.

7. Go to Manage -> Assignments and hover over “SALT Demo” and click on “Edit Signup sheet”.

8. Click on “New Topic” and fill in the details for a new topic.

[[File:NonstaggeredAddTopic.png]]

9. Now you will be able to see that there is no option for “Show Start/Due Date” which is because of the reason that this is not a staggered assignment.

[[File:NodueDate.png]]

10. Hence there is only one due date and has no dependencies on others.

= Concise Report on Refactoring =

The project had redundant code, multiple functionalities in a method and extra conditional statements in controller, model and view files. We analyzed each occurrence of these issues, thus creating a list which needed to be refactored. Controllers like sign_up_sheet_controler, assignment.rb, due_date.rb,deadline_types.rb along with other files were modified. It's very difficult to explain the sequential and detailed procedure, but it has been explained in the sections above within the capacity of the Wiki.

= Additional Learning and Future Work=

In current implementation, our database has two tables for staggered and non-staggered deadlines. For any future improvements, we can make use of [http://blog.thirst.co/post/14885390861/rails-single-table-inheritance STI (Single Table Inheritance)] and analyze if applying STI would really impact query performance when application runs and extracts data from database.

= References=
[http://expertiza.ncsu.edu/ Expertiza] 
[http://eewang.github.io/blog/2013/03/12/how-and-when-to-use-single-table-inheritance-in-rails/ Single Table Inheritance] 
[http://en.wikipedia.org/wiki/Code_refactoring Code Refactoring] 
[http://en.wikipedia.org/wiki/Code_smell Code smell]

CSC/ECE 517 Fall 2014/oss E1453 syy

2014-10-29T19:47:31Z

Shjoshi2:

'''E1453. Refactoring AssignmentsController'''

This page provides a description of the Expertiza based OSS project. This project aimed at refactoring the AssignmentsController as well as adding some missing functionality related to topics within an assignment.

'''Introduction to Expertiza''' 

[http://expertiza.ncsu.edu/ Expertiza] is a project developed using Ruby on Rails platform. It provides features like peer review, team assignments and submission of projects. This can be achieved by submitting code base, URL of hosted code on remote server and Wiki submissions. It is an open source application and the code can be cloned from [https://github.com/expertiza/expertiza github]. This application provides an efficient way to manage assignments, grades and reviews. This makes the process easier and faster when the class strength is large.

Expertiza is supported by National Science Foundation under Grant No. 0536558. Additional funding from the NCSU Learning in a Technology-Rich Environment (LITRE) program, the NCSU Faculty Center for Teaching and Learning, the NCSU STEM Initiative, and the Center for Advanced Computing and Communication.

= Project Resources =

[https://github.com/itsmylifesoham/expertiza GitHub Project Repository]

[http://152.46.18.5:3000/ VCL IP Address]

[http://wikis.lib.ncsu.edu/index.php/Expertiza Expertiza Wiki]

= Problem Statement =
Currently the topics tab is not usable to the instructor when he is editing a current assignment or creating a new one. This functionality is necessary as it enables the instructor to create/delete/edit/view topics present under the selected assignment. Currently, the instructor achieves this using the pop-up menu that appears adjacent every assignment on the page that lists all the assignments. We were required to implement the topics tab.

The functionality to display the topics under an assignment is duplicated between the AssignmentController views and the SignupSheetController views. Both the instructor and the student can view the topics by selecting an assignment and we were required to remove this duplication in the views.

= Re-factored Code Cases =

== Case 1 : Refactoring the AssignmentsController and SignupSheetController to use same views ==

===Current Scenario===
The AssignmentsController displayed topics to the instructor while he was editing an assignment. It used _add_signup_topics.html.erb partial to render topics under the topics tab. The SignupSheetController displayed topics to a student who wanted to view signup topics under an assignment. It was found that it had its own copy namely _add_signup_topcis.html.erb to display topics to the student. We wanted to have these two controllers use the same views to render the same thing which was list of topics under an assignment. We made the AssignmentsController reuse the _add_signup_topcis.html.erb partial under the SignupSheetController.

view:assignments/edit.html.erb 
This view contains all the tabs to display like general,rubrics,review_strategy, topics which are related to the selected assignment. tabs-5 is the topics tab which we are interested in.
<pre>
<div id="tabs-3">
<%= render 'assignments/edit/review_strategy' %>
</div>
<div id="tabs-4">
<%= render 'assignments/edit/due_dates' %>
</div>
<div id="tabs-5">
<%= render 'assignments/edit/add_signup_topics' %>
</div>
</pre>

<pre>
<div id="tabs-3">
<%= render 'assignments/edit/review_strategy' %>
</div>
<div id="tabs-4">
<%= render 'assignments/edit/due_dates' %>
</div>
<div id="tabs-5">
<%= render '/sign_up_sheet/add_signup_topcis.html' %>
</div>
</pre>

method:add_signup_topics 
It is similar to the above function except that all the topics and review/submission rounds have the similar deadlines.
def add_signup_topics
load_add_signup_topics(params[:id])
end

Conditional call 
We had to make conditional check every time the function is called for the assignment type. For instance, below method redirects to the /add_signup_topics or the /add_signup_topics_staggered page depending on assignment type
def redirect_to_sign_up(assignment_id)
assignment = Assignment.find(assignment_id)
if assignment.staggered_deadline == true
redirect_to :action => 'add_signup_topics_staggered', :id => assignment_id
else
redirect_to :action => 'add_signup_topics', :id => assignment_id
end
end

===After Changes===
We have redundant code in two methods so we merged add_signup_topics_staggered and add_signup_topics into add_signup_topics. The action calls single method for both type of assignments and renders views based on condition of staggered or non-staggered assignment.

def add_signup_topics
load_add_signup_topics(params[:id])
if @assignment.staggered_deadline ==true
....

#below functionality finds allows to set due dates for topics of assignment
@duedates = SignUpTopic.find_by_sql("SELECT s.id as topic_id FROM sign_up_topics s WHERE s.assignment_id = " + params[:id].to_s)
....

#Render a view different for staggered deadlines assignment from the add_sign_up.html.erb
render "add_signup_topics_staggered"
end
end

Single method call 
At several places in the project, there was separate method call based on staggered and non-staggered assignments. We have made a single method call and condition check in various files ,for type of assignment, has been removed as part of re-factoring.

def redirect_to_sign_up(assignment_id)
assignment = Assignment.find(assignment_id)
redirect_to :action => 'add_signup_topics', :id => assignment_id
end

Similarly the method call is re-factored in various views.
For instance, for view _assignments_actions.html.erb

Before Changes 
<% if @assignment.staggered_deadline == true %>
<%= link_to image_tag('/images/tree_view/edit-signup-sheet-24.png', :title => 'Edit signup sheet'),
{:controller => 'sign_up_sheet', :action => 'add_signup_topics_staggered', :id => node.node_object_id},
{:title => 'Edit signup sheet'} %>
<% else %>
<%= link_to image_tag('/images/tree_view/edit-signup-sheet-24.png', :title => 'Edit signup sheet'),
{:controller => 'sign_up_sheet', :action => 'add_signup_topics', :id => node.node_object_id},
{:title => 'Edit signup sheet'} %>
<% end %>

After Changes 
<%= link_to image_tag('/images/tree_view/edit-signup-sheet-24.png', :title => 'Edit signup sheet'),
{:controller => 'sign_up_sheet', :action => 'add_signup_topics', :id => node.node_object_id},
{:title => 'Edit signup sheet'} %>

== Case 2 : Method Extraction ==

Improved readability by [http://sourcemaking.com/refactoring/extract-method extracting] two separate functionalities from the same method into separate methods with appropriate naming convention and responsibilities.

===Current Scenario===

The add_signup_topics calculated due dates for separate topics for a Staggered assignment with individual Topic deadlines.

def add_signup_topics
load_add_signup_topics(params[:id])
if @assignment.staggered_deadline ==true
@review_rounds = Assignment.find(params[:id]).get_review_rounds
@topics = SignUpTopic.find_all_by_assignment_id(params[:id])

#below functionality finds allows to set due dates for topics of assignment
@duedates = SignUpTopic.find_by_sql("SELECT s.id as topic_id FROM sign_up_topics s WHERE s.assignment_id = " + params[:id].to_s)
if !@topics.nil?
i=0
@topics.each { |topic|
......
i = i + 1
end

#Render a view different for staggered deadlines assignment from the add_sign_up.html.erb
render "add_signup_topics_staggered"
end
end

===After Changes===

The logic to calculate due_dates was moved to a separate method called assignment_due_date , as this is only valid for staggered assignments
and hence it should be placed in a different method instead of merging it the add_signup_topics

def add_signup_topics
load_add_signup_topics(params[:id])
if @assignment.staggered_deadline ==true
@review_rounds = Assignment.find(params[:id]).get_review_rounds
@topics = SignUpTopic.find_all_by_assignment_id(params[:id])

#Function call to set up due dates
assignment_due_date

#Render a view different from the add_sign_up.html.erb , so rendering a view for staggered deadlines.
render "add_signup_topics_staggered"
end
end

def assignment_due_date
#below functionality finds allows to set due dates for topics of assignment
@duedates = SignUpTopic.find_by_sql("SELECT s.id as topic_id FROM sign_up_topics s WHERE s.assignment_id = " + params[:id].to_s)
if !@topics.nil?
i=0
@topics.each { |topic|
......
i = i + 1
end
end

==Case 3 : Modularize Code in application.rb==
===Current Scenario===
In the assignment.rb model, there exists one method(check_condition) which checks whether review, meta-review, etc are allowed or not. This method makes database calls to TopicDeadline table, DueDate and DeadlineType tables. Following is the code which was existing before the changes were made. It has the logic to find the nearest due date that hasn't passed.

assignment.rb

drop_topic_deadline_id = DeadlineType.find_by_name('drop_topic').id
if self.staggered_deadline?

if topic_id

next_due_date = TopicDeadline.find(:first, :conditions => ['topic_id = ? and due_at >= ? and deadline_type_id <> ?',
topic_id, Time.now, drop_topic_deadline_id], :order => 'due_at')
else

next_due_date = TopicDeadline.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
self.id, Time.now, drop_topic_deadline_id], :joins => {:topic => :assignment}, :order => 'due_at')
end
else
next_due_date = DueDate.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
self.id, Time.now, drop_topic_deadline_id], :order => 'due_at')
end

===After changes===
The database queries have been moved to their respective models. The queries to TopicDeadline table, DueDate table and DeadlineType table have been moved to their models. Below is the new code in assignments.rb model which calls TopicDeadline.rb, DueDate.rb and DeadlineType.rb respectively for the queries in their tables:

assignment.rb model

if self.staggered_deadline?
next_due_date = TopicDeadline.find_next_due_date(topic_id,self.id)
else
next_due_date = DueDate.find_next_due_date(self.id)
end

New find_next_due_date defined in topic_deadline.rb
def self.find_next_due_date(topic_id,assignment_id)
drop_topic_deadline_id = DeadlineType.find_drop_topic_deadline_id()
if topic_id
TopicDeadline.find(:first, :conditions => ['topic_id = ? and due_at >= ? and deadline_type_id <> ?',
topic_id, Time.now, drop_topic_deadline_id], :order => 'due_at')
else
TopicDeadline.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
assignment_id, Time.now, drop_topic_deadline_id], :joins => {:topic => :assignment}, :order => 'due_at')
end
end

New find_next_due_date method defined in due_date.rb

def self.find_next_due_date(assignment_id
drop_topic_deadline_id = DeadlineType.find_drop_topic_deadline_id()
DueDate.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
assignment_id, Time.now, drop_topic_deadline_id], :order => 'due_at')
end

New find_drop_topic_deadline_id method defined in deadline_type.rb

def self.find_drop_topic_deadline_id()
DeadlineType.find_by_name('drop_topic').id
end

== Case 4 : DeadCode Elimination in sign_up_sheet_controller.rb ==

The local variables topic_set and topic under the staggered deadline check statement were never used in the entire scope of the project , it introduced code smells. So it was checked if there was any reference to this code, and upon discovering it was not used anywhere, we decided to eliminate this [http://en.wikipedia.org/wiki/Dead_code_elimination deadcode].

===Current Scenario===

def create_default_for_microtask
.....

if @assignment.staggered_deadline?
topic_set = Array.new
topic = @sign_up_topic.id
end

.....
end

===After Changes===

def create_default_for_microtask
.....

.....
end

=Steps to verify changes=
Log into the application with the user having instructor's role or super user's role.

1. Go to Manage -> Assignments and hover over the assignment “StaggeredDeadlines_Refactoring”.

2. Click on “New Topic”.

3. Enter the details of the topic you want to create. Create at least 2 topics for better analysis of the project.

[[File:AddTopic.png]]

4. Now once you have created two new topics , then Click on “Show start/due date”.

5. You should be able to view the new start and due dates of your topics confirming these are the staggered deadlines for “StaggeredDeadlines_Refactoring” which has many topics with different deadlines.

[[File:ShowdueDate.png]]

6. Now to view the difference between the Stagerred and Non-Staggered Deadlines, follow steps.

7. Go to Manage -> Assignments and hover over “SALT Demo” and click on “Edit Signup sheet”.

8. Click on “New Topic” and fill in the details for a new topic.

[[File:NonstaggeredAddTopic.png]]

9. Now you will be able to see that there is no option for “Show Start/Due Date” which is because of the reason that this is not a staggered assignment.

[[File:NodueDate.png]]

10. Hence there is only one due date and has no dependencies on others.

= Concise Report on Refactoring =

The project had redundant code, multiple functionalities in a method and extra conditional statements in controller, model and view files. We analyzed each occurrence of these issues, thus creating a list which needed to be refactored. Controllers like sign_up_sheet_controler, assignment.rb, due_date.rb,deadline_types.rb along with other files were modified. It's very difficult to explain the sequential and detailed procedure, but it has been explained in the sections above within the capacity of the Wiki.

= Additional Learning and Future Work=

In current implementation, our database has two tables for staggered and non-staggered deadlines. For any future improvements, we can make use of [http://blog.thirst.co/post/14885390861/rails-single-table-inheritance STI (Single Table Inheritance)] and analyze if applying STI would really impact query performance when application runs and extracts data from database.

= References=
[http://expertiza.ncsu.edu/ Expertiza] 
[http://eewang.github.io/blog/2013/03/12/how-and-when-to-use-single-table-inheritance-in-rails/ Single Table Inheritance] 
[http://en.wikipedia.org/wiki/Code_refactoring Code Refactoring] 
[http://en.wikipedia.org/wiki/Code_smell Code smell]

CSC/ECE 517 Fall 2014/oss E1453 syy

2014-10-29T19:32:42Z

Shjoshi2: Created page with "'''E1453. Refactoring AssignmentsController''' This page provides a description of the Expertiza based OSS project. This project aimed at refactoring the AssignmentsController a..."

'''E1453. Refactoring AssignmentsController'''

This page provides a description of the Expertiza based OSS project. This project aimed at refactoring the AssignmentsController as well as adding some missing functionality related to topics within an assignment.

'''Introduction to Expertiza''' 

[http://expertiza.ncsu.edu/ Expertiza] is a project developed using Ruby on Rails platform. It provides features like peer review, team assignments and submission of projects. This can be achieved by submitting code base, URL of hosted code on remote server and Wiki submissions. It is an open source application and the code can be cloned from [https://github.com/expertiza/expertiza github]. This application provides an efficient way to manage assignments, grades and reviews. This makes the process easier and faster when the class strength is large.

Expertiza is supported by National Science Foundation under Grant No. 0536558. Additional funding from the NCSU Learning in a Technology-Rich Environment (LITRE) program, the NCSU Faculty Center for Teaching and Learning, the NCSU STEM Initiative, and the Center for Advanced Computing and Communication.

= Project Resources =

[https://github.com/itsmylifesoham/expertiza GitHub Project Repository]

[http://152.46.18.5:3000/ VCL IP Address]

[http://wikis.lib.ncsu.edu/index.php/Expertiza Expertiza Wiki]

= Problem Statement =
Currently the topics tab is not usable to the instructor when he is editing a current assignment or creating a new one. This functionality is necessary as it enables the instructor to create/delete/edit/view topics present under the selected assignment. Currently, the instructor achieves this using the pop-up menu that appears adjacent every assignment on the page that lists all the assignments. We were required to implement the topics tab.

The functionality to display the topics under an assignment is duplicated between the AssignmentController views and the SignupSheetController views. Both the instructor and the student can view the topics by selecting an assignment and we were required to remove this duplication in the views.

= Re-factored Code Cases =

== Case 1 : Refactoring in sign_up_sheet_controller.rb ==

===Current Scenario===
Different method definitions for setting up staggered and non-staggered assignment sign up sheet.

method:add_signup_topics_staggered 
This method lists all the available topics for an assignment and allows admin to set due dates for assignment.Staggered means that different topics can have different deadlines.
def add_signup_topics_staggered
load_add_signup_topics(params[:id])
....

#below functionality finds allows to set due dates for topics of assignment
@duedates = SignUpTopic.find_by_sql("SELECT s.id as topic_id FROM sign_up_topics s WHERE s.assignment_id = " + params[:id].to_s)
....
end

method:add_signup_topics 
It is similar to the above function except that all the topics and review/submission rounds have the similar deadlines.
def add_signup_topics
load_add_signup_topics(params[:id])
end

Conditional call 
We had to make conditional check every time the function is called for the assignment type. For instance, below method redirects to the /add_signup_topics or the /add_signup_topics_staggered page depending on assignment type
def redirect_to_sign_up(assignment_id)
assignment = Assignment.find(assignment_id)
if assignment.staggered_deadline == true
redirect_to :action => 'add_signup_topics_staggered', :id => assignment_id
else
redirect_to :action => 'add_signup_topics', :id => assignment_id
end
end

===After Changes===
We have redundant code in two methods so we merged add_signup_topics_staggered and add_signup_topics into add_signup_topics. The action calls single method for both type of assignments and renders views based on condition of staggered or non-staggered assignment.

def add_signup_topics
load_add_signup_topics(params[:id])
if @assignment.staggered_deadline ==true
....

#below functionality finds allows to set due dates for topics of assignment
@duedates = SignUpTopic.find_by_sql("SELECT s.id as topic_id FROM sign_up_topics s WHERE s.assignment_id = " + params[:id].to_s)
....

#Render a view different for staggered deadlines assignment from the add_sign_up.html.erb
render "add_signup_topics_staggered"
end
end

Single method call 
At several places in the project, there was separate method call based on staggered and non-staggered assignments. We have made a single method call and condition check in various files ,for type of assignment, has been removed as part of re-factoring.

def redirect_to_sign_up(assignment_id)
assignment = Assignment.find(assignment_id)
redirect_to :action => 'add_signup_topics', :id => assignment_id
end

Similarly the method call is re-factored in various views.
For instance, for view _assignments_actions.html.erb

Before Changes 
<% if @assignment.staggered_deadline == true %>
<%= link_to image_tag('/images/tree_view/edit-signup-sheet-24.png', :title => 'Edit signup sheet'),
{:controller => 'sign_up_sheet', :action => 'add_signup_topics_staggered', :id => node.node_object_id},
{:title => 'Edit signup sheet'} %>
<% else %>
<%= link_to image_tag('/images/tree_view/edit-signup-sheet-24.png', :title => 'Edit signup sheet'),
{:controller => 'sign_up_sheet', :action => 'add_signup_topics', :id => node.node_object_id},
{:title => 'Edit signup sheet'} %>
<% end %>

After Changes 
<%= link_to image_tag('/images/tree_view/edit-signup-sheet-24.png', :title => 'Edit signup sheet'),
{:controller => 'sign_up_sheet', :action => 'add_signup_topics', :id => node.node_object_id},
{:title => 'Edit signup sheet'} %>

== Case 2 : Method Extraction ==

Improved readability by [http://sourcemaking.com/refactoring/extract-method extracting] two separate functionalities from the same method into separate methods with appropriate naming convention and responsibilities.

===Current Scenario===

The add_signup_topics calculated due dates for separate topics for a Staggered assignment with individual Topic deadlines.

def add_signup_topics
load_add_signup_topics(params[:id])
if @assignment.staggered_deadline ==true
@review_rounds = Assignment.find(params[:id]).get_review_rounds
@topics = SignUpTopic.find_all_by_assignment_id(params[:id])

#below functionality finds allows to set due dates for topics of assignment
@duedates = SignUpTopic.find_by_sql("SELECT s.id as topic_id FROM sign_up_topics s WHERE s.assignment_id = " + params[:id].to_s)
if !@topics.nil?
i=0
@topics.each { |topic|
......
i = i + 1
end

#Render a view different for staggered deadlines assignment from the add_sign_up.html.erb
render "add_signup_topics_staggered"
end
end

===After Changes===

The logic to calculate due_dates was moved to a separate method called assignment_due_date , as this is only valid for staggered assignments
and hence it should be placed in a different method instead of merging it the add_signup_topics

def add_signup_topics
load_add_signup_topics(params[:id])
if @assignment.staggered_deadline ==true
@review_rounds = Assignment.find(params[:id]).get_review_rounds
@topics = SignUpTopic.find_all_by_assignment_id(params[:id])

#Function call to set up due dates
assignment_due_date

#Render a view different from the add_sign_up.html.erb , so rendering a view for staggered deadlines.
render "add_signup_topics_staggered"
end
end

def assignment_due_date
#below functionality finds allows to set due dates for topics of assignment
@duedates = SignUpTopic.find_by_sql("SELECT s.id as topic_id FROM sign_up_topics s WHERE s.assignment_id = " + params[:id].to_s)
if !@topics.nil?
i=0
@topics.each { |topic|
......
i = i + 1
end
end

==Case 3 : Modularize Code in application.rb==
===Current Scenario===
In the assignment.rb model, there exists one method(check_condition) which checks whether review, meta-review, etc are allowed or not. This method makes database calls to TopicDeadline table, DueDate and DeadlineType tables. Following is the code which was existing before the changes were made. It has the logic to find the nearest due date that hasn't passed.

assignment.rb

drop_topic_deadline_id = DeadlineType.find_by_name('drop_topic').id
if self.staggered_deadline?

if topic_id

next_due_date = TopicDeadline.find(:first, :conditions => ['topic_id = ? and due_at >= ? and deadline_type_id <> ?',
topic_id, Time.now, drop_topic_deadline_id], :order => 'due_at')
else

next_due_date = TopicDeadline.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
self.id, Time.now, drop_topic_deadline_id], :joins => {:topic => :assignment}, :order => 'due_at')
end
else
next_due_date = DueDate.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
self.id, Time.now, drop_topic_deadline_id], :order => 'due_at')
end

===After changes===
The database queries have been moved to their respective models. The queries to TopicDeadline table, DueDate table and DeadlineType table have been moved to their models. Below is the new code in assignments.rb model which calls TopicDeadline.rb, DueDate.rb and DeadlineType.rb respectively for the queries in their tables:

assignment.rb model

if self.staggered_deadline?
next_due_date = TopicDeadline.find_next_due_date(topic_id,self.id)
else
next_due_date = DueDate.find_next_due_date(self.id)
end

New find_next_due_date defined in topic_deadline.rb
def self.find_next_due_date(topic_id,assignment_id)
drop_topic_deadline_id = DeadlineType.find_drop_topic_deadline_id()
if topic_id
TopicDeadline.find(:first, :conditions => ['topic_id = ? and due_at >= ? and deadline_type_id <> ?',
topic_id, Time.now, drop_topic_deadline_id], :order => 'due_at')
else
TopicDeadline.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
assignment_id, Time.now, drop_topic_deadline_id], :joins => {:topic => :assignment}, :order => 'due_at')
end
end

New find_next_due_date method defined in due_date.rb

def self.find_next_due_date(assignment_id
drop_topic_deadline_id = DeadlineType.find_drop_topic_deadline_id()
DueDate.find(:first, :conditions => ['assignment_id = ? and due_at >= ? and deadline_type_id <> ?',
assignment_id, Time.now, drop_topic_deadline_id], :order => 'due_at')
end

New find_drop_topic_deadline_id method defined in deadline_type.rb

def self.find_drop_topic_deadline_id()
DeadlineType.find_by_name('drop_topic').id
end

== Case 4 : DeadCode Elimination in sign_up_sheet_controller.rb ==

The local variables topic_set and topic under the staggered deadline check statement were never used in the entire scope of the project , it introduced code smells. So it was checked if there was any reference to this code, and upon discovering it was not used anywhere, we decided to eliminate this [http://en.wikipedia.org/wiki/Dead_code_elimination deadcode].

===Current Scenario===

def create_default_for_microtask
.....

if @assignment.staggered_deadline?
topic_set = Array.new
topic = @sign_up_topic.id
end

.....
end

===After Changes===

def create_default_for_microtask
.....

.....
end

=Steps to verify changes=
Log into the application with the user having instructor's role or super user's role.

1. Go to Manage -> Assignments and hover over the assignment “StaggeredDeadlines_Refactoring”.

2. Click on “New Topic”.

3. Enter the details of the topic you want to create. Create at least 2 topics for better analysis of the project.

[[File:AddTopic.png]]

4. Now once you have created two new topics , then Click on “Show start/due date”.

5. You should be able to view the new start and due dates of your topics confirming these are the staggered deadlines for “StaggeredDeadlines_Refactoring” which has many topics with different deadlines.

[[File:ShowdueDate.png]]

6. Now to view the difference between the Stagerred and Non-Staggered Deadlines, follow steps.

7. Go to Manage -> Assignments and hover over “SALT Demo” and click on “Edit Signup sheet”.

8. Click on “New Topic” and fill in the details for a new topic.

[[File:NonstaggeredAddTopic.png]]

9. Now you will be able to see that there is no option for “Show Start/Due Date” which is because of the reason that this is not a staggered assignment.

[[File:NodueDate.png]]

10. Hence there is only one due date and has no dependencies on others.

= Concise Report on Refactoring =

The project had redundant code, multiple functionalities in a method and extra conditional statements in controller, model and view files. We analyzed each occurrence of these issues, thus creating a list which needed to be refactored. Controllers like sign_up_sheet_controler, assignment.rb, due_date.rb,deadline_types.rb along with other files were modified. It's very difficult to explain the sequential and detailed procedure, but it has been explained in the sections above within the capacity of the Wiki.

= Additional Learning and Future Work=

In current implementation, our database has two tables for staggered and non-staggered deadlines. For any future improvements, we can make use of [http://blog.thirst.co/post/14885390861/rails-single-table-inheritance STI (Single Table Inheritance)] and analyze if applying STI would really impact query performance when application runs and extracts data from database.

= References=
[http://expertiza.ncsu.edu/ Expertiza] 
[http://eewang.github.io/blog/2013/03/12/how-and-when-to-use-single-table-inheritance-in-rails/ Single Table Inheritance] 
[http://en.wikipedia.org/wiki/Code_refactoring Code Refactoring] 
[http://en.wikipedia.org/wiki/Code_smell Code smell]

CSC/ECE 517 Fall 2014

2014-10-29T19:15:10Z

Shjoshi2:

*[[CSC/ECE_517_Fall_2014/sample_page]]
*[[CSC/ECE_517_Fall_2014/ch1a 22 as]]
*[[CSC/ECE 517 Fall 2014/ch1a 19 mx]]
*[[CSC/ECE 517 Fall 2014/ch1a 3 zq]]
*[[CSC/ECE 517 Fall 2014/ch1a 4 lf]]
*[[CSC/ECE 517 Fall 2014/ch1a 4 wl]]
*[[CSC/ECE 517 Fall 2014/ch1a a7 ch]]
*[[CSC/ECE 517 Fall 2014/ch1a 25 rs]]
*[[CSC/ECE 517 Fall 2014/ch1a 25 jf]]
*[[CSC/ECE 517 Fall 2014/ch1a 8 os]]
*[[CSC/ECE 517 Fall 2014/ch1a 8 sn]]
*[[CSC/ECE 517 Fall 2014/ch1a 15 gs]]
*[[CSC/ECE 517 Fall 2014/ch1a 10 hu]]
*[[CSC/ECE 517 Fall 2014/ch1a 20 kv]]
*[[CSC/ECE 517 Fall 2014/ch1a 21 as]]
*[[CSC/ECE 517 Fall 2014/ch1a 24 sa]]
*[[CSC/ECE 517 Fall 2014/ch1a 26 sn]]
*[[CSC/ECE 517 Fall 2014/ch1a 6 rl]]
*[[CSC/ECE 517 Fall 2014/ch1a 2 ss]]
*[[CSC/ECE 517 Fall 2014/ch1a 16 av]]
*[[CSC/ECE 517 Fall 2014/ch1a 1 rm]]
*[[CSC/ECE 517 Fall 2014/ch1a 1 sj]]
*[[CSC/ECE 517 Fall 2014/ch1a 23 ss]]
*[[CSC/ECE 517 Fall 2014/ch1a 20 rn]]
*[[CSC/ECE 517 Fall 2014/ch1a 22 sp]]
*[[CSC/ECE 517 Fall 2014/oss M1454 rss]]

*[[CSC/ECE 517 Fall 2014/ch1a 26 gn]]

*[[CSC/ECE 517 Fall 2014/ch1a 13 va]]
*[[CSC/ECE 517 Fall 2014/ch1a 9 aa]]
*[[CSC/ECE 517 Fall 2014/ch1a 9 kn]]
*[[CSC/ECE 517 Fall 2014/ch1a 11 ap]]
*[[CSC/ECE 517 Fall 2014/ch1a 25 ks]]
*[[CSC/ECE 517 Fall 2014/ch1a 7 kz]]
*[[CSC/ECE_517_Fall_2014/ch1a_6_bn]]
*[[CSC/ECE_517_Fall_2014/ch1a 10 zz]]
*[[CSC/ECE_517_Fall_2014/ch1a 16 va]]
*[[CSC/ECE_517_Fall_2014/ch1a F1415 rv]]
*[[CSC/ECE_517_Fall_2014/ch1a_3_cp]]
*[[CSC/ECE 517 Fall 2014/ch1b 26 sa]]
*[[CSC/ECE_517_Fall_2014/ch1b_28_cg]]
*[[CSC/ECE_517_Fall_2014/ch1b 29 ry]]
*[[CSC/ECE_517_Fall_2014/ch1b 30 cs]]
*[[CSC/ECE_517_Fall_2014/ch1b_33_jy]]
*[[CSC/ECE_517_Fall_2014/ch1b_27_js]]
*[[CSC/ECE 517 Fall 2014/oss E1453 syy]]
*[[CSC/ECE 517 Fall 2014/oss E1463 vpd]]
*[[CSC/ECE 517 Fall 2014/oss E1465 oak]]
*[[CSC/ECE 517 Fall 2014/oss_M1456_kdv]]
*[[CSC/ECE 517 Fall 2014/oss_M1453_sst]]
*[[CSC/ECE 517 Fall 2014/oss_E1456_akk]]
*[[CSC/ECE_517_Fall_2014/oss_M1455_asa]]
*[[CSC/ECE_517_Fall_2014/oss_E1458_sst]]
*[[CSC/ECE_517_Fall_2014/oss_E1457_ags]]
*[[CSC/ECE_517_Fall_2014/OSS_E1466_gjf]]
*[[CSC/ECE_517_Fall_2014/oss_M1452_jns]]
*[[CSC/ECE_517_Fall_2014/oss_E1462_nms]]
*[[CSC/ECE_517_Fall_2014/OSS_S1455_ajp]]
*[[CSC/ECE_517_Fall_2014/OSS_S1454_ccc]]
*[[CSC/ECE_517_Fall_2014/OSS_E1450_cxm]]
*[[CSC/ECE_517_Fall_2014/OSS_E1455_skn]]
*[[CSC/ECE_517_Fall_2014/OSS_M1450_vda]]
*[[CSC/ECE_517_Fall_2014/OSS_E1467_rsv]]
*[[CSC/ECE_517_Fall_2014/OSS_E1464_vnn]]
*[[CSC/ECE 517 Fall 2014/OSS_M1451_ahs]]

CSC/ECE 517 Fall 2014/ch1a 24 sa

2014-09-26T03:44:39Z

Shjoshi2: /* Option 2 */

=Active Model Serializers=

[http://en.wikipedia.org/wiki/Ruby_on_Rails Ruby on Rails] offers strong features to write API based server applications, which expose data through a well designed API and serve data in various formats as requested. One of these features is '''[http://github.com/rails-api/active_model_serializers Active Model Serializers]''' which helps the API designers to have fine control over the response generated by the API to a data request. '''Active Model Serializers''' help programmers do this very easily and cleanly without breaking separation of concerns in a rails application. They promote [http://en.wikipedia.org/wiki/Convention_over_configuration convention over configuration], thus reducing code bloat and increasing code scalibility and readability.
 

[[File:ClientServer.png‎|right|]]

__TOC__

=Background=

The modern web has seen more and more web applications that are written as web services or web APIs. These applications do not return a web page to the client browser, but return just the bare bones data to the client in the format requested. This gives the clients the liberty to develop customized User Interfaces for the same web application. A common example is the Rotten Tomatoes API which offers movie data in JSON, XML and various other formats. The clients request the Rotten Tomatoes web server for the data in the desired format, and the web server is able to respond with the correct data in the required format.

Active Model Serializers are a way for Web API designers who use Ruby on Rails to have full control over the formatting and the content of data that is returned to clients. For eg. An employee data model returned as JSON to a data request might look like this:

<pre>
{Employee: {
name: emp_name
age: 26
salary: 35000
weight: 90kg
height: 170
}
}
</pre>

But the API designer may want to improve this formatting and exclude certain fields so that the response is just the data without clubbing it under the "Employee" root token:

<pre>
{
EmpConciseDetails: emp_name 26
}
</pre>

In a Ruby On Rails application there could be a couple of ways to achieve this.

===Option 1 : Customizing response in Controller Layer===

The first one is shown below where we can specify the JSON formatting option in the action method which handles the data request. The below method fetches the desired Employee and returns its JSON representation to the client:

<pre>
def show
@emp = Employee.find(params[:id])

respond_to do |format|
format.json { render :json => @emp, root:false}
end
end
</pre>

Specifying '''root: false''' above will remove the unwanted Employee token from the resultant JSON. However this method is not recommended as we are littering our controller layer with data formatting code. If we want to maintain the MVC separation of concerns, formatting the response data does not belong in the controller layer.

===Option 2: Customizing response in Model Layer===

Another option is to override the '''as_json''' method of the Employee data model which is typically an Active Record in a Rails application:

<pre>

class Employee < ActiveRecord

def as_json(options)
super(:only => [:name, :age])
end

end
</pre>

The above '''as_json''' method is called whenever Rails has to convert the Employee object to its JSON format to send to the client. Our custom '''as_json''' method will help us return only the name and the age as desired. However we again have a problem as we are littering our Model layer with custom formatting tasks which it is not intended to handle.

Through '''Active model serializers''' we are able to place these custom formatting tasks to a separate class namely an EmployeeSerializer which inherits from ActiveModel::Serializer class. The Rails application is able to discover this serializer when Employee data model has to be serialized without any configuration from the programmer's side. The advantages of this scheme are dual. It helps keep separation of concerns in the Rails application, and its done with a convention over configuration approach. Specifics are discussed in following sections.

= Introduction =
Knowledge of the following terms would help before getting to the usage of '''Active Model Serializers'''.

===Active Model===
'''[http://railscasts.com/episodes/219-active-model Active Model]''' is closely related to the widely used concept of '''[http://en.wikibooks.org/wiki/Ruby_on_Rails/ActiveRecord Active Record]''' in the Rails world. '''Active Record''' is an object that maps directly to the data in our database. An '''Active Record''' takes care of fetching and saving data to the database. For example, in an employee records application an Employee Active Record helps to persist a newly created/edited Employee. So how is an '''Active Model''' different?

It may not always be the case that the Employee model has to be backed by a database and the programmer may decide not to implement an Employee model as an Active Record. However the programmer might want some of the model attribute validation functionality that an Active Record provides. For eg: Imagine an employee records system that handles an create employee form by reading the POST data into an Employee object. The system does not persist this Employee model to any database though. It simply emails the admin with all the captured data present in the Employee model. However before emailing the programmer might want to validate if certain required attributes about the Employee are present.

The solution to this problem is the Active Model class. An '''Active Model''' is an Active Record devoid of all the database persistence functionality. Infact, the rails developers segregated all the non database functionality out of an '''Active Record''' into an '''Active Model'''.

===Serializer===
Serializer is a small program that takes an object residing in program memory (for example: could be a C# object in an ASP.NET application, or an ActiveModel object in a Rails application) and converts this information into format that is transferrable over the wire, for example, JSON and XML. This is required because the client may be written in Java and there is no way for it to read an Active Model Ruby Object that exists in memory on the server side.

===API Server Application===
API Server application is an application which serves data requests coming from a variety of clients (for example: mobile, desktop) in various formats such as JSON, XML. For example, An employee data web service which returns employee age and name in both JSON and XML

=Why Active Model Serializers?=

===Custom response attributes===
It is not always the case that an API application serves a request by responding with data as it is stored on the server. The API designer has a task of exposing just the right data to the clients and hence needs fine control over exactly what part of the data on the server is returned in a response. An Active Model Serializer could help return just the Employee age and name to the client as JSON and ignore all the other attributes set on an Employee Model.
 

===Separation of Concerns===
The response data could also be customized in the respond_to method of the rails controller action or for example, by implementing a custom as_json method on the model class. However this breaks the separation of concerns principle as we let something like formatting the response data venture into the controller and model layer. With Active Model Serializers we can keep this functionality segregated from the application.
 

===Maintainability===
Client needs keep changing. Let's say a Client requests some changes to the API response data, only the Active Model Serializer would get affected and there are no side effects on the Controller or the Model itself.
 

=How Active Model Serializer Works?=
[[File:Active-Model-Serializer2.png‎|right]]

Active Model Serializers work with the help of two components namely '''Serializer''' and '''Adapter'''. Let's say we wanted to write an Active Model Serializer for customizing an API that returns Employee data as json. We would have to write an '''EmployeeSerializer''' which is configured to use a '''JsonApiAdapter'''. The '''Serializer''' Component would specify which attributes and relationships of Employee to other models would be captured in the response data. For example, it might choose to return the Employee name, age and the data about the employee's family members which are different models. The '''Adapter''' component specifies how to format this selected Employee data in the correct format as required by the client. A JsonApiAdapter would format it as JSON and is the default adapter used by an Active Model Serializer. However you can always supply your own Adapter for the serializer to use.

Assume the Employee data API scenario cited above and Refer to the figure.

===Step 1 : Controller===
The Controller receives the request for json data and routes it to a specific action method

===Step 2 : Action Method===
The action method has a respond_to method that returns Employee model as JSON. When Rails encounters this line, it looks for an EmployeeSerializer in the project specifically in a file employee_serializer to get the exact data to be put into the response.

===Step 3 : Active Model Serializer===
The EmployeeSerializer is by default configured to use a JsonApiAdapter and formats the specified attributes and relationships in the JSON format. This forms the final customized response.

Instead of returning the default JSON conversion of the Employee model from the respond_to method, that Rails does automatically for us, we were able to customize our API response data through the use of Active Model Serializers in a non-intrusive way maintaining separation from the controller and the model layers.

=Using Active Model Serializer=

Time to write some code now.

===Step1 : Install gem ===
Active Model Serializer is available as a gem. Add to the gem file the following line :
<pre>
gem 'active_model_serializers'
</pre>

===Step2 : Update bundle===
Run the following command at the terminal window to install the gem.

<pre>
bundle update
</pre>

===Step3 : Generate Serializer Class===
This gem provides a serializer generator for the selected Active Model. For example, if employee was your Active Model run :
<pre>
rails g serializer employee
</pre>

This would create a file employee_serializer.rb containing the following code in the newly created app/serializers directory of your project:
<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id

end
</pre>

===Step4 : Customize Serializer===
Add your custom attributes and any other customizations to this file. For example: We are adding a url attribute to get details of this employee, although the Employee Active Model does not have any such attribute. We also add a custom attribute '''EmpConciseDetails''' that appends two attributes of an Employee. We add it because the client might be interested in it. That is the power of Active Model Serializer. It does not require us to define another property on the Employee Active Model to return its Url or EmpConciseDetails.

<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :url, :EmpConciseDetails

def url
employee_url(object)
end

def EmpConciseDetails
:name + " " + :age
end

end
</pre>

===Step5 : Get Custom object formatting===
That's it! Whenever an Employee is requested the custom EmployeeSerializer does the task of serializing the employee to json and will now include a url token to view the Employee and Employee name and age in concise form:

<pre>
{
url: /employees/1.json
EmpConciseDetails: emp_name 26
}
</pre>

=References=
#[http://railscasts.com/episodes/409-active-model-serializers Railcast on Active Model Serializers]
#[https://github.com/rails-api/active_model_serializers Active Model Serializer module on github]
#[http://asciicasts.com/episodes/409-active-model-serializers Active Model Serializer Asciicast]
#[https://www.youtube.com/watch?v=G6ipU6AiEXY Active Model Serializer Video Tutorial]
#[http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/ Active Model]
#[http://en.wikipedia.org/wiki/Serialization Serialization wiki]
#[http://en.wikipedia.org/wiki/JSON JSON wiki]
#[http://en.wikipedia.org/wiki/RubyGems RubyGems wiki]

CSC/ECE 517 Fall 2014/ch1a 24 sa

2014-09-26T03:44:26Z

Shjoshi2: /* Option 1 */

=Active Model Serializers=

[http://en.wikipedia.org/wiki/Ruby_on_Rails Ruby on Rails] offers strong features to write API based server applications, which expose data through a well designed API and serve data in various formats as requested. One of these features is '''[http://github.com/rails-api/active_model_serializers Active Model Serializers]''' which helps the API designers to have fine control over the response generated by the API to a data request. '''Active Model Serializers''' help programmers do this very easily and cleanly without breaking separation of concerns in a rails application. They promote [http://en.wikipedia.org/wiki/Convention_over_configuration convention over configuration], thus reducing code bloat and increasing code scalibility and readability.
 

[[File:ClientServer.png‎|right|]]

__TOC__

=Background=

The modern web has seen more and more web applications that are written as web services or web APIs. These applications do not return a web page to the client browser, but return just the bare bones data to the client in the format requested. This gives the clients the liberty to develop customized User Interfaces for the same web application. A common example is the Rotten Tomatoes API which offers movie data in JSON, XML and various other formats. The clients request the Rotten Tomatoes web server for the data in the desired format, and the web server is able to respond with the correct data in the required format.

Active Model Serializers are a way for Web API designers who use Ruby on Rails to have full control over the formatting and the content of data that is returned to clients. For eg. An employee data model returned as JSON to a data request might look like this:

<pre>
{Employee: {
name: emp_name
age: 26
salary: 35000
weight: 90kg
height: 170
}
}
</pre>

But the API designer may want to improve this formatting and exclude certain fields so that the response is just the data without clubbing it under the "Employee" root token:

<pre>
{
EmpConciseDetails: emp_name 26
}
</pre>

In a Ruby On Rails application there could be a couple of ways to achieve this.

===Option 1 : Customizing response in Controller Layer===

The first one is shown below where we can specify the JSON formatting option in the action method which handles the data request. The below method fetches the desired Employee and returns its JSON representation to the client:

<pre>
def show
@emp = Employee.find(params[:id])

respond_to do |format|
format.json { render :json => @emp, root:false}
end
end
</pre>

Specifying '''root: false''' above will remove the unwanted Employee token from the resultant JSON. However this method is not recommended as we are littering our controller layer with data formatting code. If we want to maintain the MVC separation of concerns, formatting the response data does not belong in the controller layer.

===Option 2===

Another option is to override the '''as_json''' method of the Employee data model which is typically an Active Record in a Rails application:

<pre>

class Employee < ActiveRecord

def as_json(options)
super(:only => [:name, :age])
end

end
</pre>

The above '''as_json''' method is called whenever Rails has to convert the Employee object to its JSON format to send to the client. Our custom '''as_json''' method will help us return only the name and the age as desired. However we again have a problem as we are littering our Model layer with custom formatting tasks which it is not intended to handle.

Through '''Active model serializers''' we are able to place these custom formatting tasks to a separate class namely an EmployeeSerializer which inherits from ActiveModel::Serializer class. The Rails application is able to discover this serializer when Employee data model has to be serialized without any configuration from the programmer's side. The advantages of this scheme are dual. It helps keep separation of concerns in the Rails application, and its done with a convention over configuration approach. Specifics are discussed in following sections.

= Introduction =
Knowledge of the following terms would help before getting to the usage of '''Active Model Serializers'''.

===Active Model===
'''[http://railscasts.com/episodes/219-active-model Active Model]''' is closely related to the widely used concept of '''[http://en.wikibooks.org/wiki/Ruby_on_Rails/ActiveRecord Active Record]''' in the Rails world. '''Active Record''' is an object that maps directly to the data in our database. An '''Active Record''' takes care of fetching and saving data to the database. For example, in an employee records application an Employee Active Record helps to persist a newly created/edited Employee. So how is an '''Active Model''' different?

It may not always be the case that the Employee model has to be backed by a database and the programmer may decide not to implement an Employee model as an Active Record. However the programmer might want some of the model attribute validation functionality that an Active Record provides. For eg: Imagine an employee records system that handles an create employee form by reading the POST data into an Employee object. The system does not persist this Employee model to any database though. It simply emails the admin with all the captured data present in the Employee model. However before emailing the programmer might want to validate if certain required attributes about the Employee are present.

The solution to this problem is the Active Model class. An '''Active Model''' is an Active Record devoid of all the database persistence functionality. Infact, the rails developers segregated all the non database functionality out of an '''Active Record''' into an '''Active Model'''.

===Serializer===
Serializer is a small program that takes an object residing in program memory (for example: could be a C# object in an ASP.NET application, or an ActiveModel object in a Rails application) and converts this information into format that is transferrable over the wire, for example, JSON and XML. This is required because the client may be written in Java and there is no way for it to read an Active Model Ruby Object that exists in memory on the server side.

===API Server Application===
API Server application is an application which serves data requests coming from a variety of clients (for example: mobile, desktop) in various formats such as JSON, XML. For example, An employee data web service which returns employee age and name in both JSON and XML

=Why Active Model Serializers?=

===Custom response attributes===
It is not always the case that an API application serves a request by responding with data as it is stored on the server. The API designer has a task of exposing just the right data to the clients and hence needs fine control over exactly what part of the data on the server is returned in a response. An Active Model Serializer could help return just the Employee age and name to the client as JSON and ignore all the other attributes set on an Employee Model.
 

===Separation of Concerns===
The response data could also be customized in the respond_to method of the rails controller action or for example, by implementing a custom as_json method on the model class. However this breaks the separation of concerns principle as we let something like formatting the response data venture into the controller and model layer. With Active Model Serializers we can keep this functionality segregated from the application.
 

===Maintainability===
Client needs keep changing. Let's say a Client requests some changes to the API response data, only the Active Model Serializer would get affected and there are no side effects on the Controller or the Model itself.
 

=How Active Model Serializer Works?=
[[File:Active-Model-Serializer2.png‎|right]]

Active Model Serializers work with the help of two components namely '''Serializer''' and '''Adapter'''. Let's say we wanted to write an Active Model Serializer for customizing an API that returns Employee data as json. We would have to write an '''EmployeeSerializer''' which is configured to use a '''JsonApiAdapter'''. The '''Serializer''' Component would specify which attributes and relationships of Employee to other models would be captured in the response data. For example, it might choose to return the Employee name, age and the data about the employee's family members which are different models. The '''Adapter''' component specifies how to format this selected Employee data in the correct format as required by the client. A JsonApiAdapter would format it as JSON and is the default adapter used by an Active Model Serializer. However you can always supply your own Adapter for the serializer to use.

Assume the Employee data API scenario cited above and Refer to the figure.

===Step 1 : Controller===
The Controller receives the request for json data and routes it to a specific action method

===Step 2 : Action Method===
The action method has a respond_to method that returns Employee model as JSON. When Rails encounters this line, it looks for an EmployeeSerializer in the project specifically in a file employee_serializer to get the exact data to be put into the response.

===Step 3 : Active Model Serializer===
The EmployeeSerializer is by default configured to use a JsonApiAdapter and formats the specified attributes and relationships in the JSON format. This forms the final customized response.

Instead of returning the default JSON conversion of the Employee model from the respond_to method, that Rails does automatically for us, we were able to customize our API response data through the use of Active Model Serializers in a non-intrusive way maintaining separation from the controller and the model layers.

=Using Active Model Serializer=

Time to write some code now.

===Step1 : Install gem ===
Active Model Serializer is available as a gem. Add to the gem file the following line :
<pre>
gem 'active_model_serializers'
</pre>

===Step2 : Update bundle===
Run the following command at the terminal window to install the gem.

<pre>
bundle update
</pre>

===Step3 : Generate Serializer Class===
This gem provides a serializer generator for the selected Active Model. For example, if employee was your Active Model run :
<pre>
rails g serializer employee
</pre>

This would create a file employee_serializer.rb containing the following code in the newly created app/serializers directory of your project:
<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id

end
</pre>

===Step4 : Customize Serializer===
Add your custom attributes and any other customizations to this file. For example: We are adding a url attribute to get details of this employee, although the Employee Active Model does not have any such attribute. We also add a custom attribute '''EmpConciseDetails''' that appends two attributes of an Employee. We add it because the client might be interested in it. That is the power of Active Model Serializer. It does not require us to define another property on the Employee Active Model to return its Url or EmpConciseDetails.

<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :url, :EmpConciseDetails

def url
employee_url(object)
end

def EmpConciseDetails
:name + " " + :age
end

end
</pre>

===Step5 : Get Custom object formatting===
That's it! Whenever an Employee is requested the custom EmployeeSerializer does the task of serializing the employee to json and will now include a url token to view the Employee and Employee name and age in concise form:

<pre>
{
url: /employees/1.json
EmpConciseDetails: emp_name 26
}
</pre>

=References=
#[http://railscasts.com/episodes/409-active-model-serializers Railcast on Active Model Serializers]
#[https://github.com/rails-api/active_model_serializers Active Model Serializer module on github]
#[http://asciicasts.com/episodes/409-active-model-serializers Active Model Serializer Asciicast]
#[https://www.youtube.com/watch?v=G6ipU6AiEXY Active Model Serializer Video Tutorial]
#[http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/ Active Model]
#[http://en.wikipedia.org/wiki/Serialization Serialization wiki]
#[http://en.wikipedia.org/wiki/JSON JSON wiki]
#[http://en.wikipedia.org/wiki/RubyGems RubyGems wiki]

CSC/ECE 517 Fall 2014/ch1a 24 sa

2014-09-26T03:43:22Z

Shjoshi2: /* Using Active Model Serializer */

=Active Model Serializers=

[http://en.wikipedia.org/wiki/Ruby_on_Rails Ruby on Rails] offers strong features to write API based server applications, which expose data through a well designed API and serve data in various formats as requested. One of these features is '''[http://github.com/rails-api/active_model_serializers Active Model Serializers]''' which helps the API designers to have fine control over the response generated by the API to a data request. '''Active Model Serializers''' help programmers do this very easily and cleanly without breaking separation of concerns in a rails application. They promote [http://en.wikipedia.org/wiki/Convention_over_configuration convention over configuration], thus reducing code bloat and increasing code scalibility and readability.
 

[[File:ClientServer.png‎|right|]]

__TOC__

=Background=

The modern web has seen more and more web applications that are written as web services or web APIs. These applications do not return a web page to the client browser, but return just the bare bones data to the client in the format requested. This gives the clients the liberty to develop customized User Interfaces for the same web application. A common example is the Rotten Tomatoes API which offers movie data in JSON, XML and various other formats. The clients request the Rotten Tomatoes web server for the data in the desired format, and the web server is able to respond with the correct data in the required format.

Active Model Serializers are a way for Web API designers who use Ruby on Rails to have full control over the formatting and the content of data that is returned to clients. For eg. An employee data model returned as JSON to a data request might look like this:

<pre>
{Employee: {
name: emp_name
age: 26
salary: 35000
weight: 90kg
height: 170
}
}
</pre>

But the API designer may want to improve this formatting and exclude certain fields so that the response is just the data without clubbing it under the "Employee" root token:

<pre>
{
EmpConciseDetails: emp_name 26
}
</pre>

In a Ruby On Rails application there could be a couple of ways to achieve this.

===Option 1===

The first one is shown below where we can specify the JSON formatting option in the action method which handles the data request. The below method fetches the desired Employee and returns its JSON representation to the client:

<pre>
def show
@emp = Employee.find(params[:id])

respond_to do |format|
format.json { render :json => @emp, root:false}
end
end
</pre>

Specifying '''root: false''' above will remove the unwanted Employee token from the resultant JSON. However this method is not recommended as we are littering our controller layer with data formatting code. If we want to maintain the MVC separation of concerns, formatting the response data does not belong in the controller layer.

===Option 2===

Another option is to override the '''as_json''' method of the Employee data model which is typically an Active Record in a Rails application:

<pre>

class Employee < ActiveRecord

def as_json(options)
super(:only => [:name, :age])
end

end
</pre>

The above '''as_json''' method is called whenever Rails has to convert the Employee object to its JSON format to send to the client. Our custom '''as_json''' method will help us return only the name and the age as desired. However we again have a problem as we are littering our Model layer with custom formatting tasks which it is not intended to handle.

Through '''Active model serializers''' we are able to place these custom formatting tasks to a separate class namely an EmployeeSerializer which inherits from ActiveModel::Serializer class. The Rails application is able to discover this serializer when Employee data model has to be serialized without any configuration from the programmer's side. The advantages of this scheme are dual. It helps keep separation of concerns in the Rails application, and its done with a convention over configuration approach. Specifics are discussed in following sections.

= Introduction =
Knowledge of the following terms would help before getting to the usage of '''Active Model Serializers'''.

===Active Model===
'''[http://railscasts.com/episodes/219-active-model Active Model]''' is closely related to the widely used concept of '''[http://en.wikibooks.org/wiki/Ruby_on_Rails/ActiveRecord Active Record]''' in the Rails world. '''Active Record''' is an object that maps directly to the data in our database. An '''Active Record''' takes care of fetching and saving data to the database. For example, in an employee records application an Employee Active Record helps to persist a newly created/edited Employee. So how is an '''Active Model''' different?

It may not always be the case that the Employee model has to be backed by a database and the programmer may decide not to implement an Employee model as an Active Record. However the programmer might want some of the model attribute validation functionality that an Active Record provides. For eg: Imagine an employee records system that handles an create employee form by reading the POST data into an Employee object. The system does not persist this Employee model to any database though. It simply emails the admin with all the captured data present in the Employee model. However before emailing the programmer might want to validate if certain required attributes about the Employee are present.

The solution to this problem is the Active Model class. An '''Active Model''' is an Active Record devoid of all the database persistence functionality. Infact, the rails developers segregated all the non database functionality out of an '''Active Record''' into an '''Active Model'''.

===Serializer===
Serializer is a small program that takes an object residing in program memory (for example: could be a C# object in an ASP.NET application, or an ActiveModel object in a Rails application) and converts this information into format that is transferrable over the wire, for example, JSON and XML. This is required because the client may be written in Java and there is no way for it to read an Active Model Ruby Object that exists in memory on the server side.

===API Server Application===
API Server application is an application which serves data requests coming from a variety of clients (for example: mobile, desktop) in various formats such as JSON, XML. For example, An employee data web service which returns employee age and name in both JSON and XML

=Why Active Model Serializers?=

===Custom response attributes===
It is not always the case that an API application serves a request by responding with data as it is stored on the server. The API designer has a task of exposing just the right data to the clients and hence needs fine control over exactly what part of the data on the server is returned in a response. An Active Model Serializer could help return just the Employee age and name to the client as JSON and ignore all the other attributes set on an Employee Model.
 

===Separation of Concerns===
The response data could also be customized in the respond_to method of the rails controller action or for example, by implementing a custom as_json method on the model class. However this breaks the separation of concerns principle as we let something like formatting the response data venture into the controller and model layer. With Active Model Serializers we can keep this functionality segregated from the application.
 

===Maintainability===
Client needs keep changing. Let's say a Client requests some changes to the API response data, only the Active Model Serializer would get affected and there are no side effects on the Controller or the Model itself.
 

=How Active Model Serializer Works?=
[[File:Active-Model-Serializer2.png‎|right]]

Active Model Serializers work with the help of two components namely '''Serializer''' and '''Adapter'''. Let's say we wanted to write an Active Model Serializer for customizing an API that returns Employee data as json. We would have to write an '''EmployeeSerializer''' which is configured to use a '''JsonApiAdapter'''. The '''Serializer''' Component would specify which attributes and relationships of Employee to other models would be captured in the response data. For example, it might choose to return the Employee name, age and the data about the employee's family members which are different models. The '''Adapter''' component specifies how to format this selected Employee data in the correct format as required by the client. A JsonApiAdapter would format it as JSON and is the default adapter used by an Active Model Serializer. However you can always supply your own Adapter for the serializer to use.

Assume the Employee data API scenario cited above and Refer to the figure.

===Step 1 : Controller===
The Controller receives the request for json data and routes it to a specific action method

===Step 2 : Action Method===
The action method has a respond_to method that returns Employee model as JSON. When Rails encounters this line, it looks for an EmployeeSerializer in the project specifically in a file employee_serializer to get the exact data to be put into the response.

===Step 3 : Active Model Serializer===
The EmployeeSerializer is by default configured to use a JsonApiAdapter and formats the specified attributes and relationships in the JSON format. This forms the final customized response.

Instead of returning the default JSON conversion of the Employee model from the respond_to method, that Rails does automatically for us, we were able to customize our API response data through the use of Active Model Serializers in a non-intrusive way maintaining separation from the controller and the model layers.

=Using Active Model Serializer=

Time to write some code now.

===Step1 : Install gem ===
Active Model Serializer is available as a gem. Add to the gem file the following line :
<pre>
gem 'active_model_serializers'
</pre>

===Step2 : Update bundle===
Run the following command at the terminal window to install the gem.

<pre>
bundle update
</pre>

===Step3 : Generate Serializer Class===
This gem provides a serializer generator for the selected Active Model. For example, if employee was your Active Model run :
<pre>
rails g serializer employee
</pre>

This would create a file employee_serializer.rb containing the following code in the newly created app/serializers directory of your project:
<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id

end
</pre>

===Step4 : Customize Serializer===
Add your custom attributes and any other customizations to this file. For example: We are adding a url attribute to get details of this employee, although the Employee Active Model does not have any such attribute. We also add a custom attribute '''EmpConciseDetails''' that appends two attributes of an Employee. We add it because the client might be interested in it. That is the power of Active Model Serializer. It does not require us to define another property on the Employee Active Model to return its Url or EmpConciseDetails.

<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :url, :EmpConciseDetails

def url
employee_url(object)
end

def EmpConciseDetails
:name + " " + :age
end

end
</pre>

===Step5 : Get Custom object formatting===
That's it! Whenever an Employee is requested the custom EmployeeSerializer does the task of serializing the employee to json and will now include a url token to view the Employee and Employee name and age in concise form:

<pre>
{
url: /employees/1.json
EmpConciseDetails: emp_name 26
}
</pre>

=References=
#[http://railscasts.com/episodes/409-active-model-serializers Railcast on Active Model Serializers]
#[https://github.com/rails-api/active_model_serializers Active Model Serializer module on github]
#[http://asciicasts.com/episodes/409-active-model-serializers Active Model Serializer Asciicast]
#[https://www.youtube.com/watch?v=G6ipU6AiEXY Active Model Serializer Video Tutorial]
#[http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/ Active Model]
#[http://en.wikipedia.org/wiki/Serialization Serialization wiki]
#[http://en.wikipedia.org/wiki/JSON JSON wiki]
#[http://en.wikipedia.org/wiki/RubyGems RubyGems wiki]

CSC/ECE 517 Fall 2014/ch1a 24 sa

2014-09-26T03:40:45Z

Shjoshi2: /* How Active Model Serializer Works? */

=Active Model Serializers=

[http://en.wikipedia.org/wiki/Ruby_on_Rails Ruby on Rails] offers strong features to write API based server applications, which expose data through a well designed API and serve data in various formats as requested. One of these features is '''[http://github.com/rails-api/active_model_serializers Active Model Serializers]''' which helps the API designers to have fine control over the response generated by the API to a data request. '''Active Model Serializers''' help programmers do this very easily and cleanly without breaking separation of concerns in a rails application. They promote [http://en.wikipedia.org/wiki/Convention_over_configuration convention over configuration], thus reducing code bloat and increasing code scalibility and readability.
 

[[File:ClientServer.png‎|right|]]

__TOC__

=Background=

The modern web has seen more and more web applications that are written as web services or web APIs. These applications do not return a web page to the client browser, but return just the bare bones data to the client in the format requested. This gives the clients the liberty to develop customized User Interfaces for the same web application. A common example is the Rotten Tomatoes API which offers movie data in JSON, XML and various other formats. The clients request the Rotten Tomatoes web server for the data in the desired format, and the web server is able to respond with the correct data in the required format.

Active Model Serializers are a way for Web API designers who use Ruby on Rails to have full control over the formatting and the content of data that is returned to clients. For eg. An employee data model returned as JSON to a data request might look like this:

<pre>
{Employee: {
name: emp_name
age: 26
salary: 35000
weight: 90kg
height: 170
}
}
</pre>

But the API designer may want to improve this formatting and exclude certain fields so that the response is just the data without clubbing it under the "Employee" root token:

<pre>
{
EmpConciseDetails: emp_name 26
}
</pre>

In a Ruby On Rails application there could be a couple of ways to achieve this.

===Option 1===

The first one is shown below where we can specify the JSON formatting option in the action method which handles the data request. The below method fetches the desired Employee and returns its JSON representation to the client:

<pre>
def show
@emp = Employee.find(params[:id])

respond_to do |format|
format.json { render :json => @emp, root:false}
end
end
</pre>

Specifying '''root: false''' above will remove the unwanted Employee token from the resultant JSON. However this method is not recommended as we are littering our controller layer with data formatting code. If we want to maintain the MVC separation of concerns, formatting the response data does not belong in the controller layer.

===Option 2===

Another option is to override the '''as_json''' method of the Employee data model which is typically an Active Record in a Rails application:

<pre>

class Employee < ActiveRecord

def as_json(options)
super(:only => [:name, :age])
end

end
</pre>

The above '''as_json''' method is called whenever Rails has to convert the Employee object to its JSON format to send to the client. Our custom '''as_json''' method will help us return only the name and the age as desired. However we again have a problem as we are littering our Model layer with custom formatting tasks which it is not intended to handle.

Through '''Active model serializers''' we are able to place these custom formatting tasks to a separate class namely an EmployeeSerializer which inherits from ActiveModel::Serializer class. The Rails application is able to discover this serializer when Employee data model has to be serialized without any configuration from the programmer's side. The advantages of this scheme are dual. It helps keep separation of concerns in the Rails application, and its done with a convention over configuration approach. Specifics are discussed in following sections.

= Introduction =
Knowledge of the following terms would help before getting to the usage of '''Active Model Serializers'''.

===Active Model===
'''[http://railscasts.com/episodes/219-active-model Active Model]''' is closely related to the widely used concept of '''[http://en.wikibooks.org/wiki/Ruby_on_Rails/ActiveRecord Active Record]''' in the Rails world. '''Active Record''' is an object that maps directly to the data in our database. An '''Active Record''' takes care of fetching and saving data to the database. For example, in an employee records application an Employee Active Record helps to persist a newly created/edited Employee. So how is an '''Active Model''' different?

It may not always be the case that the Employee model has to be backed by a database and the programmer may decide not to implement an Employee model as an Active Record. However the programmer might want some of the model attribute validation functionality that an Active Record provides. For eg: Imagine an employee records system that handles an create employee form by reading the POST data into an Employee object. The system does not persist this Employee model to any database though. It simply emails the admin with all the captured data present in the Employee model. However before emailing the programmer might want to validate if certain required attributes about the Employee are present.

The solution to this problem is the Active Model class. An '''Active Model''' is an Active Record devoid of all the database persistence functionality. Infact, the rails developers segregated all the non database functionality out of an '''Active Record''' into an '''Active Model'''.

===Serializer===
Serializer is a small program that takes an object residing in program memory (for example: could be a C# object in an ASP.NET application, or an ActiveModel object in a Rails application) and converts this information into format that is transferrable over the wire, for example, JSON and XML. This is required because the client may be written in Java and there is no way for it to read an Active Model Ruby Object that exists in memory on the server side.

===API Server Application===
API Server application is an application which serves data requests coming from a variety of clients (for example: mobile, desktop) in various formats such as JSON, XML. For example, An employee data web service which returns employee age and name in both JSON and XML

=Why Active Model Serializers?=

===Custom response attributes===
It is not always the case that an API application serves a request by responding with data as it is stored on the server. The API designer has a task of exposing just the right data to the clients and hence needs fine control over exactly what part of the data on the server is returned in a response. An Active Model Serializer could help return just the Employee age and name to the client as JSON and ignore all the other attributes set on an Employee Model.
 

===Separation of Concerns===
The response data could also be customized in the respond_to method of the rails controller action or for example, by implementing a custom as_json method on the model class. However this breaks the separation of concerns principle as we let something like formatting the response data venture into the controller and model layer. With Active Model Serializers we can keep this functionality segregated from the application.
 

===Maintainability===
Client needs keep changing. Let's say a Client requests some changes to the API response data, only the Active Model Serializer would get affected and there are no side effects on the Controller or the Model itself.
 

=How Active Model Serializer Works?=
[[File:Active-Model-Serializer2.png‎|right]]

Active Model Serializers work with the help of two components namely '''Serializer''' and '''Adapter'''. Let's say we wanted to write an Active Model Serializer for customizing an API that returns Employee data as json. We would have to write an '''EmployeeSerializer''' which is configured to use a '''JsonApiAdapter'''. The '''Serializer''' Component would specify which attributes and relationships of Employee to other models would be captured in the response data. For example, it might choose to return the Employee name, age and the data about the employee's family members which are different models. The '''Adapter''' component specifies how to format this selected Employee data in the correct format as required by the client. A JsonApiAdapter would format it as JSON and is the default adapter used by an Active Model Serializer. However you can always supply your own Adapter for the serializer to use.

Assume the Employee data API scenario cited above and Refer to the figure.

===Step 1 : Controller===
The Controller receives the request for json data and routes it to a specific action method

===Step 2 : Action Method===
The action method has a respond_to method that returns Employee model as JSON. When Rails encounters this line, it looks for an EmployeeSerializer in the project specifically in a file employee_serializer to get the exact data to be put into the response.

===Step 3 : Active Model Serializer===
The EmployeeSerializer is by default configured to use a JsonApiAdapter and formats the specified attributes and relationships in the JSON format. This forms the final customized response.

Instead of returning the default JSON conversion of the Employee model from the respond_to method, that Rails does automatically for us, we were able to customize our API response data through the use of Active Model Serializers in a non-intrusive way maintaining separation from the controller and the model layers.

=Using Active Model Serializer=

Time to write some code now.

===Step1===
Active Model Serializer is available as a gem. Add to the gem file the following line :
<pre>
gem 'active_model_serializers'
</pre>

===Step2===
Run the following command at the terminal window to install the gem.

<pre>
bundle update
</pre>

===Step3===
This gem provides a serializer generator for the selected Active Model. For example, if employee was your Active Model run :
<pre>
rails g serializer employee
</pre>

This would create a file employee_serializer.rb containing the following code in the newly created app/serializers directory of your project:
<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id

end
</pre>

===Step4===
Add your custom attributes and any other customizations to this file. For example: We are adding a url attribute to get details of this employee, although the Employee Active Model does not have any such attribute. We also add a custom attribute '''EmpConciseDetails''' that appends two attributes of an Employee. We add it because the client might be interested in it. That is the power of Active Model Serializer. It does not require us to define another property on the Employee Active Model to return its Url or EmpConciseDetails.

<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :url, :EmpConciseDetails

def url
employee_url(object)
end

def EmpConciseDetails
:name + " " + :age
end

end
</pre>

===Step5===
That's it! Whenever an Employee is requested the custom EmployeeSerializer does the task of serializing the employee to json and will now include a url token to view the Employee and Employee name and age in concise form:

<pre>
{
url: /employees/1.json
EmpConciseDetails: emp_name 26
}
</pre>

=References=
#[http://railscasts.com/episodes/409-active-model-serializers Railcast on Active Model Serializers]
#[https://github.com/rails-api/active_model_serializers Active Model Serializer module on github]
#[http://asciicasts.com/episodes/409-active-model-serializers Active Model Serializer Asciicast]
#[https://www.youtube.com/watch?v=G6ipU6AiEXY Active Model Serializer Video Tutorial]
#[http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/ Active Model]
#[http://en.wikipedia.org/wiki/Serialization Serialization wiki]
#[http://en.wikipedia.org/wiki/JSON JSON wiki]
#[http://en.wikipedia.org/wiki/RubyGems RubyGems wiki]

CSC/ECE 517 Fall 2014/ch1a 24 sa

2014-09-26T03:39:51Z

Shjoshi2: /* Why Active Model Serializers? */

=Active Model Serializers=

[http://en.wikipedia.org/wiki/Ruby_on_Rails Ruby on Rails] offers strong features to write API based server applications, which expose data through a well designed API and serve data in various formats as requested. One of these features is '''[http://github.com/rails-api/active_model_serializers Active Model Serializers]''' which helps the API designers to have fine control over the response generated by the API to a data request. '''Active Model Serializers''' help programmers do this very easily and cleanly without breaking separation of concerns in a rails application. They promote [http://en.wikipedia.org/wiki/Convention_over_configuration convention over configuration], thus reducing code bloat and increasing code scalibility and readability.
 

[[File:ClientServer.png‎|right|]]

__TOC__

=Background=

The modern web has seen more and more web applications that are written as web services or web APIs. These applications do not return a web page to the client browser, but return just the bare bones data to the client in the format requested. This gives the clients the liberty to develop customized User Interfaces for the same web application. A common example is the Rotten Tomatoes API which offers movie data in JSON, XML and various other formats. The clients request the Rotten Tomatoes web server for the data in the desired format, and the web server is able to respond with the correct data in the required format.

Active Model Serializers are a way for Web API designers who use Ruby on Rails to have full control over the formatting and the content of data that is returned to clients. For eg. An employee data model returned as JSON to a data request might look like this:

<pre>
{Employee: {
name: emp_name
age: 26
salary: 35000
weight: 90kg
height: 170
}
}
</pre>

But the API designer may want to improve this formatting and exclude certain fields so that the response is just the data without clubbing it under the "Employee" root token:

<pre>
{
EmpConciseDetails: emp_name 26
}
</pre>

In a Ruby On Rails application there could be a couple of ways to achieve this.

===Option 1===

The first one is shown below where we can specify the JSON formatting option in the action method which handles the data request. The below method fetches the desired Employee and returns its JSON representation to the client:

<pre>
def show
@emp = Employee.find(params[:id])

respond_to do |format|
format.json { render :json => @emp, root:false}
end
end
</pre>

Specifying '''root: false''' above will remove the unwanted Employee token from the resultant JSON. However this method is not recommended as we are littering our controller layer with data formatting code. If we want to maintain the MVC separation of concerns, formatting the response data does not belong in the controller layer.

===Option 2===

Another option is to override the '''as_json''' method of the Employee data model which is typically an Active Record in a Rails application:

<pre>

class Employee < ActiveRecord

def as_json(options)
super(:only => [:name, :age])
end

end
</pre>

The above '''as_json''' method is called whenever Rails has to convert the Employee object to its JSON format to send to the client. Our custom '''as_json''' method will help us return only the name and the age as desired. However we again have a problem as we are littering our Model layer with custom formatting tasks which it is not intended to handle.

Through '''Active model serializers''' we are able to place these custom formatting tasks to a separate class namely an EmployeeSerializer which inherits from ActiveModel::Serializer class. The Rails application is able to discover this serializer when Employee data model has to be serialized without any configuration from the programmer's side. The advantages of this scheme are dual. It helps keep separation of concerns in the Rails application, and its done with a convention over configuration approach. Specifics are discussed in following sections.

= Introduction =
Knowledge of the following terms would help before getting to the usage of '''Active Model Serializers'''.

===Active Model===
'''[http://railscasts.com/episodes/219-active-model Active Model]''' is closely related to the widely used concept of '''[http://en.wikibooks.org/wiki/Ruby_on_Rails/ActiveRecord Active Record]''' in the Rails world. '''Active Record''' is an object that maps directly to the data in our database. An '''Active Record''' takes care of fetching and saving data to the database. For example, in an employee records application an Employee Active Record helps to persist a newly created/edited Employee. So how is an '''Active Model''' different?

It may not always be the case that the Employee model has to be backed by a database and the programmer may decide not to implement an Employee model as an Active Record. However the programmer might want some of the model attribute validation functionality that an Active Record provides. For eg: Imagine an employee records system that handles an create employee form by reading the POST data into an Employee object. The system does not persist this Employee model to any database though. It simply emails the admin with all the captured data present in the Employee model. However before emailing the programmer might want to validate if certain required attributes about the Employee are present.

The solution to this problem is the Active Model class. An '''Active Model''' is an Active Record devoid of all the database persistence functionality. Infact, the rails developers segregated all the non database functionality out of an '''Active Record''' into an '''Active Model'''.

===Serializer===
Serializer is a small program that takes an object residing in program memory (for example: could be a C# object in an ASP.NET application, or an ActiveModel object in a Rails application) and converts this information into format that is transferrable over the wire, for example, JSON and XML. This is required because the client may be written in Java and there is no way for it to read an Active Model Ruby Object that exists in memory on the server side.

===API Server Application===
API Server application is an application which serves data requests coming from a variety of clients (for example: mobile, desktop) in various formats such as JSON, XML. For example, An employee data web service which returns employee age and name in both JSON and XML

=Why Active Model Serializers?=

===Custom response attributes===
It is not always the case that an API application serves a request by responding with data as it is stored on the server. The API designer has a task of exposing just the right data to the clients and hence needs fine control over exactly what part of the data on the server is returned in a response. An Active Model Serializer could help return just the Employee age and name to the client as JSON and ignore all the other attributes set on an Employee Model.
 

===Separation of Concerns===
The response data could also be customized in the respond_to method of the rails controller action or for example, by implementing a custom as_json method on the model class. However this breaks the separation of concerns principle as we let something like formatting the response data venture into the controller and model layer. With Active Model Serializers we can keep this functionality segregated from the application.
 

===Maintainability===
Client needs keep changing. Let's say a Client requests some changes to the API response data, only the Active Model Serializer would get affected and there are no side effects on the Controller or the Model itself.
 

=How Active Model Serializer Works?=
[[File:Active-Model-Serializer2.png‎|right]]

Active Model Serializers work with the help of two components namely '''Serializer''' and '''Adapter'''. Let's say we wanted to write an Active Model Serializer for customizing an API that returns Employee data as json. We would have to write an '''EmployeeSerializer''' which is configured to use a '''JsonApiAdapter'''. The '''Serializer''' Component would specify which attributes and relationships of Employee to other models would be captured in the response data. For example, it might choose to return the Employee name, age and the data about the employee's family members which are different models. The '''Adapter''' component specifies how to format this selected Employee data in the correct format as required by the client. A JsonApiAdapter would format it as JSON and is the default adapter used by an Active Model Serializer. However you can always supply your own Adapter for the serializer to use.

Assume the Employee data API scenario cited above and Refer to the figure.

===Step 1===
The Controller receives the request for json data and routes it to a specific action method

===Step 2===
The action method has a respond_to method that returns Employee model as JSON. When Rails encounters this line, it looks for an EmployeeSerializer in the project specifically in a file employee_serializer to get the exact data to be put into the response.

===Step 3===
The EmployeeSerializer is by default configured to use a JsonApiAdapter and formats the specified attributes and relationships in the JSON format. This forms the final customized response.

Instead of returning the default JSON conversion of the Employee model from the respond_to method, that Rails does automatically for us, we were able to customize our API response data through the use of Active Model Serializers in a non-intrusive way maintaining separation from the controller and the model layers.

=Using Active Model Serializer=

Time to write some code now.

===Step1===
Active Model Serializer is available as a gem. Add to the gem file the following line :
<pre>
gem 'active_model_serializers'
</pre>

===Step2===
Run the following command at the terminal window to install the gem.

<pre>
bundle update
</pre>

===Step3===
This gem provides a serializer generator for the selected Active Model. For example, if employee was your Active Model run :
<pre>
rails g serializer employee
</pre>

This would create a file employee_serializer.rb containing the following code in the newly created app/serializers directory of your project:
<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id

end
</pre>

===Step4===
Add your custom attributes and any other customizations to this file. For example: We are adding a url attribute to get details of this employee, although the Employee Active Model does not have any such attribute. We also add a custom attribute '''EmpConciseDetails''' that appends two attributes of an Employee. We add it because the client might be interested in it. That is the power of Active Model Serializer. It does not require us to define another property on the Employee Active Model to return its Url or EmpConciseDetails.

<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :url, :EmpConciseDetails

def url
employee_url(object)
end

def EmpConciseDetails
:name + " " + :age
end

end
</pre>

===Step5===
That's it! Whenever an Employee is requested the custom EmployeeSerializer does the task of serializing the employee to json and will now include a url token to view the Employee and Employee name and age in concise form:

<pre>
{
url: /employees/1.json
EmpConciseDetails: emp_name 26
}
</pre>

=References=
#[http://railscasts.com/episodes/409-active-model-serializers Railcast on Active Model Serializers]
#[https://github.com/rails-api/active_model_serializers Active Model Serializer module on github]
#[http://asciicasts.com/episodes/409-active-model-serializers Active Model Serializer Asciicast]
#[https://www.youtube.com/watch?v=G6ipU6AiEXY Active Model Serializer Video Tutorial]
#[http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/ Active Model]
#[http://en.wikipedia.org/wiki/Serialization Serialization wiki]
#[http://en.wikipedia.org/wiki/JSON JSON wiki]
#[http://en.wikipedia.org/wiki/RubyGems RubyGems wiki]

CSC/ECE 517 Fall 2014/ch1a 24 sa

2014-09-26T02:45:39Z

Shjoshi2: /* Using Active Model Serializer */

=Active Model Serializers=

[http://en.wikipedia.org/wiki/Ruby_on_Rails Ruby on Rails] offers strong features to write API based server applications, which expose data through a well designed API and serve data in various formats as requested. One of these features is '''[http://github.com/rails-api/active_model_serializers Active Model Serializers]''' which helps the API designers to have fine control over the response generated by the API to a data request. '''Active Model Serializers''' help programmers do this very easily and cleanly without breaking separation of concerns in a rails application. They promote [http://en.wikipedia.org/wiki/Convention_over_configuration convention over configuration], thus reducing code bloat and increasing code scalibility and readability.
 

[[File:ClientServer.png‎|right|]]

__TOC__

=Background=

The modern web has seen more and more web applications that are written as web services or web APIs. These applications do not return a web page to the client browser, but return just the bare bones data to the client in the format requested. This gives the clients the liberty to develop customized User Interfaces for the same web application. A common example is the Rotten Tomatoes API which offers movie data in JSON, XML and various other formats. The clients request the Rotten Tomatoes web server for the data in the desired format, and the web server is able to respond with the correct data in the required format.

Active Model Serializers are a way for Web API designers who use Ruby on Rails to have full control over the formatting and the content of data that is returned to clients. For eg. An employee data model returned as JSON to a data request might look like this:

<pre>
{Employee: {
name: emp_name
age: 26
salary: 35000
weight: 90kg
height: 170
}
}
</pre>

But the API designer may want to improve this formatting and exclude certain fields so that the response is just the data without clubbing it under the "Employee" root token:

<pre>
{
EmpConciseDetails: emp_name 26
}
</pre>

In a Ruby On Rails application there could be a couple of ways to achieve this.

===Option 1===

The first one is shown below where we can specify the JSON formatting option in the action method which handles the data request. The below method fetches the desired Employee and returns its JSON representation to the client:

<pre>
def show
@emp = Employee.find(params[:id])

respond_to do |format|
format.json { render :json => @emp, root:false}
end
end
</pre>

Specifying '''root: false''' above will remove the unwanted Employee token from the resultant JSON. However this method is not recommended as we are littering our controller layer with data formatting code. If we want to maintain the MVC separation of concerns, formatting the response data does not belong in the controller layer.

===Option 2===

Another option is to override the '''as_json''' method of the Employee data model which is typically an Active Record in a Rails application:

<pre>

class Employee < ActiveRecord

def as_json(options)
super(:only => [:name, :age])
end

end
</pre>

The above '''as_json''' method is called whenever Rails has to convert the Employee object to its JSON format to send to the client. Our custom '''as_json''' method will help us return only the name and the age as desired. However we again have a problem as we are littering our Model layer with custom formatting tasks which it is not intended to handle.

Through '''Active model serializers''' we are able to place these custom formatting tasks to a separate class namely an EmployeeSerializer which inherits from ActiveModel::Serializer class. The Rails application is able to discover this serializer when Employee data model has to be serialized without any configuration from the programmer's side. The advantages of this scheme are dual. It helps keep separation of concerns in the Rails application, and its done with a convention over configuration approach. Specifics are discussed in following sections.

= Introduction =
Knowledge of the following terms would help before getting to the usage of '''Active Model Serializers'''.

===Active Model===
'''[http://railscasts.com/episodes/219-active-model Active Model]''' is closely related to the widely used concept of '''[http://en.wikibooks.org/wiki/Ruby_on_Rails/ActiveRecord Active Record]''' in the Rails world. '''Active Record''' is an object that maps directly to the data in our database. An '''Active Record''' takes care of fetching and saving data to the database. For example, in an employee records application an Employee Active Record helps to persist a newly created/edited Employee. So how is an '''Active Model''' different?

It may not always be the case that the Employee model has to be backed by a database and the programmer may decide not to implement an Employee model as an Active Record. However the programmer might want some of the model attribute validation functionality that an Active Record provides. For eg: Imagine an employee records system that handles an create employee form by reading the POST data into an Employee object. The system does not persist this Employee model to any database though. It simply emails the admin with all the captured data present in the Employee model. However before emailing the programmer might want to validate if certain required attributes about the Employee are present.

The solution to this problem is the Active Model class. An '''Active Model''' is an Active Record devoid of all the database persistence functionality. Infact, the rails developers segregated all the non database functionality out of an '''Active Record''' into an '''Active Model'''.

===Serializer===
Serializer is a small program that takes an object residing in program memory (for example: could be a C# object in an ASP.NET application, or an ActiveModel object in a Rails application) and converts this information into format that is transferrable over the wire, for example, JSON and XML. This is required because the client may be written in Java and there is no way for it to read an Active Model Ruby Object that exists in memory on the server side.

===API Server Application===
API Server application is an application which serves data requests coming from a variety of clients (for example: mobile, desktop) in various formats such as JSON, XML. For example, An employee data web service which returns employee age and name in both JSON and XML

=Why Active Model Serializers?=

* '''Custom response attributes:''' It is not always the case that an API application serves a request by responding with data as it is stored on the server. The API designer has a task of exposing just the right data to the clients and hence needs fine control over exactly what part of the data on the server is returned in a response. An Active Model Serializer could help return just the Employee age and name to the client as JSON and ignore all the other attributes set on an Employee Model.
 
* '''Separation of Concerns:''' The response data could also be customized in the respond_to method of the rails controller action or for example, by implementing a custom as_json method on the model class. However this breaks the separation of concerns principle as we let something like formatting the response data venture into the controller and model layer. With Active Model Serializers we can keep this functionality segregated from the application.
 
*'''Maintainability:''' Client needs keep changing. Let's say a Client requests some changes to the API response data, only the Active Model Serializer would get affected and there are no side effects on the Controller or the Model itself.
 
=How Active Model Serializer Works?=
[[File:Active-Model-Serializer2.png‎|right]]

Active Model Serializers work with the help of two components namely '''Serializer''' and '''Adapter'''. Let's say we wanted to write an Active Model Serializer for customizing an API that returns Employee data as json. We would have to write an '''EmployeeSerializer''' which is configured to use a '''JsonApiAdapter'''. The '''Serializer''' Component would specify which attributes and relationships of Employee to other models would be captured in the response data. For example, it might choose to return the Employee name, age and the data about the employee's family members which are different models. The '''Adapter''' component specifies how to format this selected Employee data in the correct format as required by the client. A JsonApiAdapter would format it as JSON and is the default adapter used by an Active Model Serializer. However you can always supply your own Adapter for the serializer to use.

Assume the Employee data API scenario cited above and Refer to the figure.

===Step 1===
The Controller receives the request for json data and routes it to a specific action method

===Step 2===
The action method has a respond_to method that returns Employee model as JSON. When Rails encounters this line, it looks for an EmployeeSerializer in the project specifically in a file employee_serializer to get the exact data to be put into the response.

===Step 3===
The EmployeeSerializer is by default configured to use a JsonApiAdapter and formats the specified attributes and relationships in the JSON format. This forms the final customized response.

Instead of returning the default JSON conversion of the Employee model from the respond_to method, that Rails does automatically for us, we were able to customize our API response data through the use of Active Model Serializers in a non-intrusive way maintaining separation from the controller and the model layers.

=Using Active Model Serializer=

Time to write some code now.

===Step1===
Active Model Serializer is available as a gem. Add to the gem file the following line :
<pre>
gem 'active_model_serializers'
</pre>

===Step2===
Run the following command at the terminal window to install the gem.

<pre>
bundle update
</pre>

===Step3===
This gem provides a serializer generator for the selected Active Model. For example, if employee was your Active Model run :
<pre>
rails g serializer employee
</pre>

This would create a file employee_serializer.rb containing the following code in the newly created app/serializers directory of your project:
<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id

end
</pre>

===Step4===
Add your custom attributes and any other customizations to this file. For example: We are adding a url attribute to get details of this employee, although the Employee Active Model does not have any such attribute. We also add a custom attribute '''EmpConciseDetails''' that appends two attributes of an Employee. We add it because the client might be interested in it. That is the power of Active Model Serializer. It does not require us to define another property on the Employee Active Model to return its Url or EmpConciseDetails.

<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :url, :EmpConciseDetails

def url
employee_url(object)
end

def EmpConciseDetails
:name + " " + :age
end

end
</pre>

===Step5===
That's it! Whenever an Employee is requested the custom EmployeeSerializer does the task of serializing the employee to json and will now include a url token to view the Employee and Employee name and age in concise form:

<pre>
{
url: /employees/1.json
EmpConciseDetails: emp_name 26
}
</pre>

=References=
#[http://railscasts.com/episodes/409-active-model-serializers Railcast on Active Model Serializers]
#[https://github.com/rails-api/active_model_serializers Active Model Serializer module on github]
#[http://asciicasts.com/episodes/409-active-model-serializers Active Model Serializer Asciicast]
#[https://www.youtube.com/watch?v=G6ipU6AiEXY Active Model Serializer Video Tutorial]
#[http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/ Active Model]
#[http://en.wikipedia.org/wiki/Serialization Serialization wiki]
#[http://en.wikipedia.org/wiki/JSON JSON wiki]
#[http://en.wikipedia.org/wiki/RubyGems RubyGems wiki]

CSC/ECE 517 Fall 2014/ch1a 24 sa

2014-09-26T02:44:12Z

Shjoshi2: /* How Active Model Serializer Works? */

=Active Model Serializers=

[http://en.wikipedia.org/wiki/Ruby_on_Rails Ruby on Rails] offers strong features to write API based server applications, which expose data through a well designed API and serve data in various formats as requested. One of these features is '''[http://github.com/rails-api/active_model_serializers Active Model Serializers]''' which helps the API designers to have fine control over the response generated by the API to a data request. '''Active Model Serializers''' help programmers do this very easily and cleanly without breaking separation of concerns in a rails application. They promote [http://en.wikipedia.org/wiki/Convention_over_configuration convention over configuration], thus reducing code bloat and increasing code scalibility and readability.
 

[[File:ClientServer.png‎|right|]]

__TOC__

=Background=

The modern web has seen more and more web applications that are written as web services or web APIs. These applications do not return a web page to the client browser, but return just the bare bones data to the client in the format requested. This gives the clients the liberty to develop customized User Interfaces for the same web application. A common example is the Rotten Tomatoes API which offers movie data in JSON, XML and various other formats. The clients request the Rotten Tomatoes web server for the data in the desired format, and the web server is able to respond with the correct data in the required format.

Active Model Serializers are a way for Web API designers who use Ruby on Rails to have full control over the formatting and the content of data that is returned to clients. For eg. An employee data model returned as JSON to a data request might look like this:

<pre>
{Employee: {
name: emp_name
age: 26
salary: 35000
weight: 90kg
height: 170
}
}
</pre>

But the API designer may want to improve this formatting and exclude certain fields so that the response is just the data without clubbing it under the "Employee" root token:

<pre>
{
EmpConciseDetails: emp_name 26
}
</pre>

In a Ruby On Rails application there could be a couple of ways to achieve this.

===Option 1===

The first one is shown below where we can specify the JSON formatting option in the action method which handles the data request. The below method fetches the desired Employee and returns its JSON representation to the client:

<pre>
def show
@emp = Employee.find(params[:id])

respond_to do |format|
format.json { render :json => @emp, root:false}
end
end
</pre>

Specifying '''root: false''' above will remove the unwanted Employee token from the resultant JSON. However this method is not recommended as we are littering our controller layer with data formatting code. If we want to maintain the MVC separation of concerns, formatting the response data does not belong in the controller layer.

===Option 2===

Another option is to override the '''as_json''' method of the Employee data model which is typically an Active Record in a Rails application:

<pre>

class Employee < ActiveRecord

def as_json(options)
super(:only => [:name, :age])
end

end
</pre>

The above '''as_json''' method is called whenever Rails has to convert the Employee object to its JSON format to send to the client. Our custom '''as_json''' method will help us return only the name and the age as desired. However we again have a problem as we are littering our Model layer with custom formatting tasks which it is not intended to handle.

Through '''Active model serializers''' we are able to place these custom formatting tasks to a separate class namely an EmployeeSerializer which inherits from ActiveModel::Serializer class. The Rails application is able to discover this serializer when Employee data model has to be serialized without any configuration from the programmer's side. The advantages of this scheme are dual. It helps keep separation of concerns in the Rails application, and its done with a convention over configuration approach. Specifics are discussed in following sections.

= Introduction =
Knowledge of the following terms would help before getting to the usage of '''Active Model Serializers'''.

===Active Model===
'''[http://railscasts.com/episodes/219-active-model Active Model]''' is closely related to the widely used concept of '''[http://en.wikibooks.org/wiki/Ruby_on_Rails/ActiveRecord Active Record]''' in the Rails world. '''Active Record''' is an object that maps directly to the data in our database. An '''Active Record''' takes care of fetching and saving data to the database. For example, in an employee records application an Employee Active Record helps to persist a newly created/edited Employee. So how is an '''Active Model''' different?

It may not always be the case that the Employee model has to be backed by a database and the programmer may decide not to implement an Employee model as an Active Record. However the programmer might want some of the model attribute validation functionality that an Active Record provides. For eg: Imagine an employee records system that handles an create employee form by reading the POST data into an Employee object. The system does not persist this Employee model to any database though. It simply emails the admin with all the captured data present in the Employee model. However before emailing the programmer might want to validate if certain required attributes about the Employee are present.

The solution to this problem is the Active Model class. An '''Active Model''' is an Active Record devoid of all the database persistence functionality. Infact, the rails developers segregated all the non database functionality out of an '''Active Record''' into an '''Active Model'''.

===Serializer===
Serializer is a small program that takes an object residing in program memory (for example: could be a C# object in an ASP.NET application, or an ActiveModel object in a Rails application) and converts this information into format that is transferrable over the wire, for example, JSON and XML. This is required because the client may be written in Java and there is no way for it to read an Active Model Ruby Object that exists in memory on the server side.

===API Server Application===
API Server application is an application which serves data requests coming from a variety of clients (for example: mobile, desktop) in various formats such as JSON, XML. For example, An employee data web service which returns employee age and name in both JSON and XML

=Why Active Model Serializers?=

* '''Custom response attributes:''' It is not always the case that an API application serves a request by responding with data as it is stored on the server. The API designer has a task of exposing just the right data to the clients and hence needs fine control over exactly what part of the data on the server is returned in a response. An Active Model Serializer could help return just the Employee age and name to the client as JSON and ignore all the other attributes set on an Employee Model.
 
* '''Separation of Concerns:''' The response data could also be customized in the respond_to method of the rails controller action or for example, by implementing a custom as_json method on the model class. However this breaks the separation of concerns principle as we let something like formatting the response data venture into the controller and model layer. With Active Model Serializers we can keep this functionality segregated from the application.
 
*'''Maintainability:''' Client needs keep changing. Let's say a Client requests some changes to the API response data, only the Active Model Serializer would get affected and there are no side effects on the Controller or the Model itself.
 
=How Active Model Serializer Works?=
[[File:Active-Model-Serializer2.png‎|right]]

Active Model Serializers work with the help of two components namely '''Serializer''' and '''Adapter'''. Let's say we wanted to write an Active Model Serializer for customizing an API that returns Employee data as json. We would have to write an '''EmployeeSerializer''' which is configured to use a '''JsonApiAdapter'''. The '''Serializer''' Component would specify which attributes and relationships of Employee to other models would be captured in the response data. For example, it might choose to return the Employee name, age and the data about the employee's family members which are different models. The '''Adapter''' component specifies how to format this selected Employee data in the correct format as required by the client. A JsonApiAdapter would format it as JSON and is the default adapter used by an Active Model Serializer. However you can always supply your own Adapter for the serializer to use.

Assume the Employee data API scenario cited above and Refer to the figure.

===Step 1===
The Controller receives the request for json data and routes it to a specific action method

===Step 2===
The action method has a respond_to method that returns Employee model as JSON. When Rails encounters this line, it looks for an EmployeeSerializer in the project specifically in a file employee_serializer to get the exact data to be put into the response.

===Step 3===
The EmployeeSerializer is by default configured to use a JsonApiAdapter and formats the specified attributes and relationships in the JSON format. This forms the final customized response.

Instead of returning the default JSON conversion of the Employee model from the respond_to method, that Rails does automatically for us, we were able to customize our API response data through the use of Active Model Serializers in a non-intrusive way maintaining separation from the controller and the model layers.

=Using Active Model Serializer=

Time to write some code now.

'''Step 1:''' Active Model Serializer is available as a gem. Add to the gem file the following line :
<pre>
gem 'active_model_serializers'
</pre>

'''Step 2:''' Run the following command at the terminal window to install the gem.

<pre>
bundle update
</pre>

'''Step 3:''' This gem provides a serializer generator for the selected Active Model. For example, if employee was your Active Model run :
<pre>
rails g serializer employee
</pre>

This would create a file employee_serializer.rb containing the following code in the newly created app/serializers directory of your project:
<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id

end
</pre>

'''Step 4:''' Add your custom attributes and any other customizations to this file. For example: We are adding a url attribute to get details of this employee, although the Employee Active Model does not have any such attribute. We also add a custom attribute '''EmpConciseDetails''' that appends two attributes of an Employee. We add it because the client might be interested in it. That is the power of Active Model Serializer. It does not require us to define another property on the Employee Active Model to return its Url or EmpConciseDetails.

<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :url, :EmpConciseDetails

def url
employee_url(object)
end

def EmpConciseDetails
:name + " " + :age
end

end
</pre>

'''Step 5:''' That's it! Whenever an Employee is requested the custom EmployeeSerializer does the task of serializing the employee to json and will now include a url token to view the Employee and Employee name and age in concise form:

<pre>
{
url: /employees/1.json
EmpConciseDetails: emp_name 26
}
</pre>

=References=
#[http://railscasts.com/episodes/409-active-model-serializers Railcast on Active Model Serializers]
#[https://github.com/rails-api/active_model_serializers Active Model Serializer module on github]
#[http://asciicasts.com/episodes/409-active-model-serializers Active Model Serializer Asciicast]
#[https://www.youtube.com/watch?v=G6ipU6AiEXY Active Model Serializer Video Tutorial]
#[http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/ Active Model]
#[http://en.wikipedia.org/wiki/Serialization Serialization wiki]
#[http://en.wikipedia.org/wiki/JSON JSON wiki]
#[http://en.wikipedia.org/wiki/RubyGems RubyGems wiki]

CSC/ECE 517 Fall 2014/ch1a 24 sa

2014-09-26T02:43:32Z

Shjoshi2: /* How Active Model Serializer Works? */

=Active Model Serializers=

[http://en.wikipedia.org/wiki/Ruby_on_Rails Ruby on Rails] offers strong features to write API based server applications, which expose data through a well designed API and serve data in various formats as requested. One of these features is '''[http://github.com/rails-api/active_model_serializers Active Model Serializers]''' which helps the API designers to have fine control over the response generated by the API to a data request. '''Active Model Serializers''' help programmers do this very easily and cleanly without breaking separation of concerns in a rails application. They promote [http://en.wikipedia.org/wiki/Convention_over_configuration convention over configuration], thus reducing code bloat and increasing code scalibility and readability.
 

[[File:ClientServer.png‎|right|]]

__TOC__

=Background=

The modern web has seen more and more web applications that are written as web services or web APIs. These applications do not return a web page to the client browser, but return just the bare bones data to the client in the format requested. This gives the clients the liberty to develop customized User Interfaces for the same web application. A common example is the Rotten Tomatoes API which offers movie data in JSON, XML and various other formats. The clients request the Rotten Tomatoes web server for the data in the desired format, and the web server is able to respond with the correct data in the required format.

Active Model Serializers are a way for Web API designers who use Ruby on Rails to have full control over the formatting and the content of data that is returned to clients. For eg. An employee data model returned as JSON to a data request might look like this:

<pre>
{Employee: {
name: emp_name
age: 26
salary: 35000
weight: 90kg
height: 170
}
}
</pre>

But the API designer may want to improve this formatting and exclude certain fields so that the response is just the data without clubbing it under the "Employee" root token:

<pre>
{
EmpConciseDetails: emp_name 26
}
</pre>

In a Ruby On Rails application there could be a couple of ways to achieve this.

===Option 1===

The first one is shown below where we can specify the JSON formatting option in the action method which handles the data request. The below method fetches the desired Employee and returns its JSON representation to the client:

<pre>
def show
@emp = Employee.find(params[:id])

respond_to do |format|
format.json { render :json => @emp, root:false}
end
end
</pre>

Specifying '''root: false''' above will remove the unwanted Employee token from the resultant JSON. However this method is not recommended as we are littering our controller layer with data formatting code. If we want to maintain the MVC separation of concerns, formatting the response data does not belong in the controller layer.

===Option 2===

Another option is to override the '''as_json''' method of the Employee data model which is typically an Active Record in a Rails application:

<pre>

class Employee < ActiveRecord

def as_json(options)
super(:only => [:name, :age])
end

end
</pre>

The above '''as_json''' method is called whenever Rails has to convert the Employee object to its JSON format to send to the client. Our custom '''as_json''' method will help us return only the name and the age as desired. However we again have a problem as we are littering our Model layer with custom formatting tasks which it is not intended to handle.

Through '''Active model serializers''' we are able to place these custom formatting tasks to a separate class namely an EmployeeSerializer which inherits from ActiveModel::Serializer class. The Rails application is able to discover this serializer when Employee data model has to be serialized without any configuration from the programmer's side. The advantages of this scheme are dual. It helps keep separation of concerns in the Rails application, and its done with a convention over configuration approach. Specifics are discussed in following sections.

= Introduction =
Knowledge of the following terms would help before getting to the usage of '''Active Model Serializers'''.

===Active Model===
'''[http://railscasts.com/episodes/219-active-model Active Model]''' is closely related to the widely used concept of '''[http://en.wikibooks.org/wiki/Ruby_on_Rails/ActiveRecord Active Record]''' in the Rails world. '''Active Record''' is an object that maps directly to the data in our database. An '''Active Record''' takes care of fetching and saving data to the database. For example, in an employee records application an Employee Active Record helps to persist a newly created/edited Employee. So how is an '''Active Model''' different?

It may not always be the case that the Employee model has to be backed by a database and the programmer may decide not to implement an Employee model as an Active Record. However the programmer might want some of the model attribute validation functionality that an Active Record provides. For eg: Imagine an employee records system that handles an create employee form by reading the POST data into an Employee object. The system does not persist this Employee model to any database though. It simply emails the admin with all the captured data present in the Employee model. However before emailing the programmer might want to validate if certain required attributes about the Employee are present.

The solution to this problem is the Active Model class. An '''Active Model''' is an Active Record devoid of all the database persistence functionality. Infact, the rails developers segregated all the non database functionality out of an '''Active Record''' into an '''Active Model'''.

===Serializer===
Serializer is a small program that takes an object residing in program memory (for example: could be a C# object in an ASP.NET application, or an ActiveModel object in a Rails application) and converts this information into format that is transferrable over the wire, for example, JSON and XML. This is required because the client may be written in Java and there is no way for it to read an Active Model Ruby Object that exists in memory on the server side.

===API Server Application===
API Server application is an application which serves data requests coming from a variety of clients (for example: mobile, desktop) in various formats such as JSON, XML. For example, An employee data web service which returns employee age and name in both JSON and XML

=Why Active Model Serializers?=

* '''Custom response attributes:''' It is not always the case that an API application serves a request by responding with data as it is stored on the server. The API designer has a task of exposing just the right data to the clients and hence needs fine control over exactly what part of the data on the server is returned in a response. An Active Model Serializer could help return just the Employee age and name to the client as JSON and ignore all the other attributes set on an Employee Model.
 
* '''Separation of Concerns:''' The response data could also be customized in the respond_to method of the rails controller action or for example, by implementing a custom as_json method on the model class. However this breaks the separation of concerns principle as we let something like formatting the response data venture into the controller and model layer. With Active Model Serializers we can keep this functionality segregated from the application.
 
*'''Maintainability:''' Client needs keep changing. Let's say a Client requests some changes to the API response data, only the Active Model Serializer would get affected and there are no side effects on the Controller or the Model itself.
 
=How Active Model Serializer Works?=
[[File:Active-Model-Serializer2.png‎|right]]

Active Model Serializers work with the help of two components namely '''Serializer''' and '''Adapter'''. Let's say we wanted to write an Active Model Serializer for customizing an API that returns Employee data as json. We would have to write an '''EmployeeSerializer''' which is configured to use a '''JsonApiAdapter'''. The '''Serializer''' Component would specify which attributes and relationships of Employee to other models would be captured in the response data. For example, it might choose to return the Employee name, age and the data about the employee's family members which are different models. The '''Adapter''' component specifies how to format this selected Employee data in the correct format as required by the client. A JsonApiAdapter would format it as JSON and is the default adapter used by an Active Model Serializer. However you can always supply your own Adapter for the serializer to use.

Assume the Employee data API scenario cited above and Refer to the figure.

===Step 1===
The Controller receives the request for json data and routes it to a specific action method

===Step 2===
The action method has a respond_to method that returns Employee model as JSON. When Rails encounters this line, it looks for an EmployeeSerializer in the project specifically in a file employee_serializer to get the exact data to be put into the response.

===Step 3===
The EmployeeSerializer is by default configured to use a JsonApiAdapter and formats the specified attributes and relationships in the JSON format. This forms the final customized response.

As you can see, instead of returning the default JSON conversion of the Employee model from the respond_to method, that Rails does automatically for us, we were able to customize our API response data through the use of Active Model Serializers in a non-intrusive way maintaining separation from the controller and the model layers.

=Using Active Model Serializer=

Time to write some code now.

'''Step 1:''' Active Model Serializer is available as a gem. Add to the gem file the following line :
<pre>
gem 'active_model_serializers'
</pre>

'''Step 2:''' Run the following command at the terminal window to install the gem.

<pre>
bundle update
</pre>

'''Step 3:''' This gem provides a serializer generator for the selected Active Model. For example, if employee was your Active Model run :
<pre>
rails g serializer employee
</pre>

This would create a file employee_serializer.rb containing the following code in the newly created app/serializers directory of your project:
<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id

end
</pre>

'''Step 4:''' Add your custom attributes and any other customizations to this file. For example: We are adding a url attribute to get details of this employee, although the Employee Active Model does not have any such attribute. We also add a custom attribute '''EmpConciseDetails''' that appends two attributes of an Employee. We add it because the client might be interested in it. That is the power of Active Model Serializer. It does not require us to define another property on the Employee Active Model to return its Url or EmpConciseDetails.

<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :url, :EmpConciseDetails

def url
employee_url(object)
end

def EmpConciseDetails
:name + " " + :age
end

end
</pre>

'''Step 5:''' That's it! Whenever an Employee is requested the custom EmployeeSerializer does the task of serializing the employee to json and will now include a url token to view the Employee and Employee name and age in concise form:

<pre>
{
url: /employees/1.json
EmpConciseDetails: emp_name 26
}
</pre>

=References=
#[http://railscasts.com/episodes/409-active-model-serializers Railcast on Active Model Serializers]
#[https://github.com/rails-api/active_model_serializers Active Model Serializer module on github]
#[http://asciicasts.com/episodes/409-active-model-serializers Active Model Serializer Asciicast]
#[https://www.youtube.com/watch?v=G6ipU6AiEXY Active Model Serializer Video Tutorial]
#[http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/ Active Model]
#[http://en.wikipedia.org/wiki/Serialization Serialization wiki]
#[http://en.wikipedia.org/wiki/JSON JSON wiki]
#[http://en.wikipedia.org/wiki/RubyGems RubyGems wiki]

CSC/ECE 517 Fall 2014/ch1a 24 sa

2014-09-26T02:42:39Z

Shjoshi2:

=Active Model Serializers=

[http://en.wikipedia.org/wiki/Ruby_on_Rails Ruby on Rails] offers strong features to write API based server applications, which expose data through a well designed API and serve data in various formats as requested. One of these features is '''[http://github.com/rails-api/active_model_serializers Active Model Serializers]''' which helps the API designers to have fine control over the response generated by the API to a data request. '''Active Model Serializers''' help programmers do this very easily and cleanly without breaking separation of concerns in a rails application. They promote [http://en.wikipedia.org/wiki/Convention_over_configuration convention over configuration], thus reducing code bloat and increasing code scalibility and readability.
 

[[File:ClientServer.png‎|right|]]

__TOC__

=Background=

The modern web has seen more and more web applications that are written as web services or web APIs. These applications do not return a web page to the client browser, but return just the bare bones data to the client in the format requested. This gives the clients the liberty to develop customized User Interfaces for the same web application. A common example is the Rotten Tomatoes API which offers movie data in JSON, XML and various other formats. The clients request the Rotten Tomatoes web server for the data in the desired format, and the web server is able to respond with the correct data in the required format.

Active Model Serializers are a way for Web API designers who use Ruby on Rails to have full control over the formatting and the content of data that is returned to clients. For eg. An employee data model returned as JSON to a data request might look like this:

<pre>
{Employee: {
name: emp_name
age: 26
salary: 35000
weight: 90kg
height: 170
}
}
</pre>

But the API designer may want to improve this formatting and exclude certain fields so that the response is just the data without clubbing it under the "Employee" root token:

<pre>
{
EmpConciseDetails: emp_name 26
}
</pre>

In a Ruby On Rails application there could be a couple of ways to achieve this.

===Option 1===

The first one is shown below where we can specify the JSON formatting option in the action method which handles the data request. The below method fetches the desired Employee and returns its JSON representation to the client:

<pre>
def show
@emp = Employee.find(params[:id])

respond_to do |format|
format.json { render :json => @emp, root:false}
end
end
</pre>

Specifying '''root: false''' above will remove the unwanted Employee token from the resultant JSON. However this method is not recommended as we are littering our controller layer with data formatting code. If we want to maintain the MVC separation of concerns, formatting the response data does not belong in the controller layer.

===Option 2===

Another option is to override the '''as_json''' method of the Employee data model which is typically an Active Record in a Rails application:

<pre>

class Employee < ActiveRecord

def as_json(options)
super(:only => [:name, :age])
end

end
</pre>

The above '''as_json''' method is called whenever Rails has to convert the Employee object to its JSON format to send to the client. Our custom '''as_json''' method will help us return only the name and the age as desired. However we again have a problem as we are littering our Model layer with custom formatting tasks which it is not intended to handle.

Through '''Active model serializers''' we are able to place these custom formatting tasks to a separate class namely an EmployeeSerializer which inherits from ActiveModel::Serializer class. The Rails application is able to discover this serializer when Employee data model has to be serialized without any configuration from the programmer's side. The advantages of this scheme are dual. It helps keep separation of concerns in the Rails application, and its done with a convention over configuration approach. Specifics are discussed in following sections.

= Introduction =
Knowledge of the following terms would help before getting to the usage of '''Active Model Serializers'''.

===Active Model===
'''[http://railscasts.com/episodes/219-active-model Active Model]''' is closely related to the widely used concept of '''[http://en.wikibooks.org/wiki/Ruby_on_Rails/ActiveRecord Active Record]''' in the Rails world. '''Active Record''' is an object that maps directly to the data in our database. An '''Active Record''' takes care of fetching and saving data to the database. For example, in an employee records application an Employee Active Record helps to persist a newly created/edited Employee. So how is an '''Active Model''' different?

It may not always be the case that the Employee model has to be backed by a database and the programmer may decide not to implement an Employee model as an Active Record. However the programmer might want some of the model attribute validation functionality that an Active Record provides. For eg: Imagine an employee records system that handles an create employee form by reading the POST data into an Employee object. The system does not persist this Employee model to any database though. It simply emails the admin with all the captured data present in the Employee model. However before emailing the programmer might want to validate if certain required attributes about the Employee are present.

The solution to this problem is the Active Model class. An '''Active Model''' is an Active Record devoid of all the database persistence functionality. Infact, the rails developers segregated all the non database functionality out of an '''Active Record''' into an '''Active Model'''.

===Serializer===
Serializer is a small program that takes an object residing in program memory (for example: could be a C# object in an ASP.NET application, or an ActiveModel object in a Rails application) and converts this information into format that is transferrable over the wire, for example, JSON and XML. This is required because the client may be written in Java and there is no way for it to read an Active Model Ruby Object that exists in memory on the server side.

===API Server Application===
API Server application is an application which serves data requests coming from a variety of clients (for example: mobile, desktop) in various formats such as JSON, XML. For example, An employee data web service which returns employee age and name in both JSON and XML

=Why Active Model Serializers?=

* '''Custom response attributes:''' It is not always the case that an API application serves a request by responding with data as it is stored on the server. The API designer has a task of exposing just the right data to the clients and hence needs fine control over exactly what part of the data on the server is returned in a response. An Active Model Serializer could help return just the Employee age and name to the client as JSON and ignore all the other attributes set on an Employee Model.
 
* '''Separation of Concerns:''' The response data could also be customized in the respond_to method of the rails controller action or for example, by implementing a custom as_json method on the model class. However this breaks the separation of concerns principle as we let something like formatting the response data venture into the controller and model layer. With Active Model Serializers we can keep this functionality segregated from the application.
 
*'''Maintainability:''' Client needs keep changing. Let's say a Client requests some changes to the API response data, only the Active Model Serializer would get affected and there are no side effects on the Controller or the Model itself.
 
=How Active Model Serializer Works?=
[[File:Active-Model-Serializer2.png‎|right]]

Active Model Serializers work with the help of two components namely '''Serializer''' and '''Adapter'''. Let's say we wanted to write an Active Model Serializer for customizing an API that returns Employee data as json. We would have to write an '''EmployeeSerializer''' which is configured to use a '''JsonApiAdapter'''. The '''Serializer''' Component would specify which attributes and relationships of Employee to other models would be captured in the response data. For example, it might choose to return the Employee name, age and the data about the employee's family members which are different models. The '''Adapter''' component specifies how to format this selected Employee data in the correct format as required by the client. A JsonApiAdapter would format it as JSON and is the default adapter used by an Active Model Serializer. However you can always supply your own Adapter for the serializer to use.

Assume the Employee data API scenario cited above and Refer to the figure.
#The Controller receives the request for json data and routes it to a specific action method
#The action method has a respond_to method that returns Employee model as JSON. When Rails encounters this line, it looks for an EmployeeSerializer in the project specifically in a file employee_serializer to get the exact data to be put into the response.
#The EmployeeSerializer is by default configured to use a JsonApiAdapter and formats the specified attributes and relationships in the JSON format. This forms the final customized response.

As you can see, instead of returning the default JSON conversion of the Employee model from the respond_to method, that Rails does automatically for us, we were able to customize our API response data through the use of Active Model Serializers in a non-intrusive way maintaining separation from the controller and the model layers.

=Using Active Model Serializer=

Time to write some code now.

'''Step 1:''' Active Model Serializer is available as a gem. Add to the gem file the following line :
<pre>
gem 'active_model_serializers'
</pre>

'''Step 2:''' Run the following command at the terminal window to install the gem.

<pre>
bundle update
</pre>

'''Step 3:''' This gem provides a serializer generator for the selected Active Model. For example, if employee was your Active Model run :
<pre>
rails g serializer employee
</pre>

This would create a file employee_serializer.rb containing the following code in the newly created app/serializers directory of your project:
<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id

end
</pre>

'''Step 4:''' Add your custom attributes and any other customizations to this file. For example: We are adding a url attribute to get details of this employee, although the Employee Active Model does not have any such attribute. We also add a custom attribute '''EmpConciseDetails''' that appends two attributes of an Employee. We add it because the client might be interested in it. That is the power of Active Model Serializer. It does not require us to define another property on the Employee Active Model to return its Url or EmpConciseDetails.

<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :url, :EmpConciseDetails

def url
employee_url(object)
end

def EmpConciseDetails
:name + " " + :age
end

end
</pre>

'''Step 5:''' That's it! Whenever an Employee is requested the custom EmployeeSerializer does the task of serializing the employee to json and will now include a url token to view the Employee and Employee name and age in concise form:

<pre>
{
url: /employees/1.json
EmpConciseDetails: emp_name 26
}
</pre>

=References=
#[http://railscasts.com/episodes/409-active-model-serializers Railcast on Active Model Serializers]
#[https://github.com/rails-api/active_model_serializers Active Model Serializer module on github]
#[http://asciicasts.com/episodes/409-active-model-serializers Active Model Serializer Asciicast]
#[https://www.youtube.com/watch?v=G6ipU6AiEXY Active Model Serializer Video Tutorial]
#[http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/ Active Model]
#[http://en.wikipedia.org/wiki/Serialization Serialization wiki]
#[http://en.wikipedia.org/wiki/JSON JSON wiki]
#[http://en.wikipedia.org/wiki/RubyGems RubyGems wiki]

CSC/ECE 517 Fall 2014/ch1a 24 sa

2014-09-26T02:37:19Z

Shjoshi2: /* Using Active Model Serializer */

=Active Model Serializers=

[http://en.wikipedia.org/wiki/Ruby_on_Rails Ruby on Rails] offers strong features to write API based server applications, which expose data through a well designed API and serve data in various formats as requested. One of these features is '''[http://github.com/rails-api/active_model_serializers Active Model Serializers]''' which helps the API designers to have fine control over the response generated by the API to a data request. '''Active Model Serializers''' help programmers do this very easily and cleanly without breaking separation of concerns in a rails application. They promote [http://en.wikipedia.org/wiki/Convention_over_configuration convention over configuration], thus reducing code bloat and increasing code scalibility and readability.
 

[[File:ClientServer.png‎|right|]]

__TOC__

=Background=

The modern web has seen more and more web applications that are written as web services or web APIs. These applications do not return a web page to the client browser, but return just the bare bones data to the client in the format requested. This gives the clients the liberty to develop customized User Interfaces for the same web application. A common example is the Rotten Tomatoes API which offers movie data in JSON, XML and various other formats. The clients request the Rotten Tomatoes web server for the data in the desired format, and the web server is able to respond with the correct data in the required format.

Active Model Serializers are a way for Web API designers who use Ruby on Rails to have full control over the formatting and the content of data that is returned to clients. For eg. An employee data model returned as JSON to a data request might look like this:

<pre>
{Employee: {
name: emp_name
age: 26
salary: 35000
weight: 90kg
height: 170
}
}
</pre>

But the API designer may want to improve this formatting and exclude certain fields so that the response is just the data without clubbing it under the "Employee" root token:

<pre>
{
EmpConciseDetails: emp_name 26
}
</pre>

In a Ruby On Rails application there could be a couple of ways to achieve this.

===Option 1===

The first one is shown below where we can specify the JSON formatting option in the action method which handles the data request. The below method fetches the desired Employee and returns its JSON representation to the client:

<pre>
def show
@emp = Employee.find(params[:id])

respond_to do |format|
format.json { render :json => @emp, root:false}
end
end
</pre>

Specifying '''root: false''' above will remove the unwanted Employee token from the resultant JSON. However this method is not recommended as we are littering our controller layer with data formatting code. If we want to maintain the MVC separation of concerns, formatting the response data does not belong in the controller layer.

===Option 2===

Another option is to override the '''as_json''' method of the Employee data model which is typically an Active Record in a Rails application:

<pre>

class Employee < ActiveRecord

def as_json(options)
super(:only => [:name, :age])
end

end
</pre>

The above '''as_json''' method is called whenever Rails has to convert the Employee object to its JSON format to send to the client. Our custom '''as_json''' method will help us return only the name and the age as desired. However we again have a problem as we are littering our Model layer with custom formatting tasks which it is not intended to handle.

Through '''Active model serializers''' we are able to place these custom formatting tasks to a separate class namely an EmployeeSerializer which inherits from ActiveModel::Serializer class. The Rails application is able to discover this serializer when Employee data model has to be serialized without any configuration from the programmer's side. The advantages of this scheme are dual. It helps keep separation of concerns in the Rails application, and its done with a convention over configuration approach. Specifics are discussed in following sections.

= Introduction =
Knowledge of the following terms would help before getting to the usage of '''Active Model Serializers'''.

===Active Model===
'''[http://railscasts.com/episodes/219-active-model Active Model]''' is closely related to the widely used concept of '''[http://en.wikibooks.org/wiki/Ruby_on_Rails/ActiveRecord Active Record]''' in the Rails world. '''Active Record''' is an object that maps directly to the data in our database. An '''Active Record''' takes care of fetching and saving data to the database. For example, in an employee records application an Employee Active Record helps to persist a newly created/edited Employee. So how is an '''Active Model''' different?

It may not always be the case that the Employee model has to be backed by a database and the programmer may decide not to implement an Employee model as an Active Record. However the programmer might want some of the model attribute validation functionality that an Active Record provides. For eg: Imagine an employee records system that handles an create employee form by reading the POST data into an Employee object. The system does not persist this Employee model to any database though. It simply emails the admin with all the captured data present in the Employee model. However before emailing the programmer might want to validate if certain required attributes about the Employee are present.

The solution to this problem is the Active Model class. An '''Active Model''' is an Active Record devoid of all the database persistence functionality. Infact, the rails developers segregated all the non database functionality out of an '''Active Record''' into an '''Active Model'''.

===Serializer===
Serializer is a small program that takes an object residing in program memory (for example: could be a C# object in an ASP.NET application, or an ActiveModel object in a Rails application) and converts this information into format that is transferrable over the wire, for example, JSON and XML. This is required because the client may be written in Java and there is no way for it to read an Active Model Ruby Object that exists in memory on the server side.

===API Server Application===
API Server application is an application which serves data requests coming from a variety of clients (for example: mobile, desktop) in various formats such as JSON, XML. For example, An employee data web service which returns employee age and name in both JSON and XML

=Why Active Model Serializers?=

* '''Custom response attributes:''' It is not always the case that an API application serves a request by responding with data as it is stored on the server. The API designer has a task of exposing just the right data to the clients and hence needs fine control over exactly what part of the data on the server is returned in a response. An Active Model Serializer could help return just the Employee age and name to the client as JSON and ignore all the other attributes set on an Employee Model.
 
* '''Separation of Concerns:''' The response data could also be customized in the respond_to method of the rails controller action or for example, by implementing a custom as_json method on the model class. However this breaks the separation of concerns principle as we let something like formatting the response data venture into the controller and model layer. With Active Model Serializers we can keep this functionality segregated from the application.
 
*'''Maintainability:''' Client needs keep changing. Let's say a Client requests some changes to the API response data, only the Active Model Serializer would get affected and there are no side effects on the Controller or the Model itself.
 
=How Active Model Serializer Works?=
[[File:Active-Model-Serializer2.png‎|right]]

Active Model Serializers work with the help of two components namely '''Serializer''' and '''Adapter'''. Let's say we wanted to write an Active Model Serializer for customizing an API that returns Employee data as json. We would have to write an '''EmployeeSerializer''' which is configured to use a '''JsonApiAdapter'''. The '''Serializer''' Component would specify which attributes and relationships of Employee to other models would be captured in the response data. For example, it might choose to return the Employee name, age and the data about the employee's family members which are different models. The '''Adapter''' component specifies how to format this selected Employee data in the correct format as required by the client. A JsonApiAdapter would format it as JSON and is the default adapter used by an Active Model Serializer. However you can always supply your own Adapter for the serializer to use.

Assume the Employee data API scenario cited above and Refer to the figure.
#The Controller receives the request for json data and routes it to a specific action method
#The action method has a respond_to method that returns Employee model as JSON. When Rails encounters this line, it looks for an EmployeeSerializer in the project specifically in a file employee_serializer to get the exact data to be put into the response.
#The EmployeeSerializer is by default configured to use a JsonApiAdapter and formats the specified attributes and relationships in the JSON format. This forms the final customized response.

As you can see, instead of returning the default JSON conversion of the Employee model from the respond_to method, that Rails does automatically for us, we were able to customize our API response data through the use of Active Model Serializers in a non-intrusive way maintaining separation from the controller and the model layers.

=Using Active Model Serializer=

Time to write some code now.

'''Step 1:''' Active Model Serializer is available as a gem. Add to the gem file the following line :
<pre>
gem 'active_model_serializers'
</pre>

'''Step 2:''' Run the following command at the terminal window to install the gem.

<pre>
bundle update
</pre>

'''Step 3:''' This gem provides a serializer generator for the selected Active Model. For example, if employee was your Active Model run :
<pre>
rails g serializer employee
</pre>

This would create a file employee_serializer.rb containing the following code in the newly created app/serializers directory of your project:
<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id

end
</pre>

'''Step 4:''' Add your custom attributes and any other customizations to this file. For example: We are adding a url attribute to get details of this employee, although the Employee Active Model does not have any such attribute. We also add a custom attribute '''EmpConciseDetails''' that appends two attributes of an Employee. We add it because the client might be interested in it. That is the power of Active Model Serializer. It does not require us to define another property on the Employee Active Model to return its Url.

<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id, :name, :age, :url

def url
employee_url(object)
end

def EmpConciseDetails
:name + " " + :age
end

end
</pre>

'''Step 5:''' That's it! Whenever an Employee is requested the custom EmployeeSerializer does the task of serializing the employee to json and will now include a url key value pair to view the Employee.

=References=
#[http://railscasts.com/episodes/409-active-model-serializers Railcast on Active Model Serializers]
#[https://github.com/rails-api/active_model_serializers Active Model Serializer module on github]
#[http://asciicasts.com/episodes/409-active-model-serializers Active Model Serializer Asciicast]
#[https://www.youtube.com/watch?v=G6ipU6AiEXY Active Model Serializer Video Tutorial]
#[http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/ Active Model]
#[http://en.wikipedia.org/wiki/Serialization Serialization wiki]
#[http://en.wikipedia.org/wiki/JSON JSON wiki]
#[http://en.wikipedia.org/wiki/RubyGems RubyGems wiki]

CSC/ECE 517 Fall 2014/ch1a 24 sa

2014-09-26T02:33:38Z

Shjoshi2: /* Using Active Model Serializer */

=Active Model Serializers=

[http://en.wikipedia.org/wiki/Ruby_on_Rails Ruby on Rails] offers strong features to write API based server applications, which expose data through a well designed API and serve data in various formats as requested. One of these features is '''[http://github.com/rails-api/active_model_serializers Active Model Serializers]''' which helps the API designers to have fine control over the response generated by the API to a data request. '''Active Model Serializers''' help programmers do this very easily and cleanly without breaking separation of concerns in a rails application. They promote [http://en.wikipedia.org/wiki/Convention_over_configuration convention over configuration], thus reducing code bloat and increasing code scalibility and readability.
 

[[File:ClientServer.png‎|right|]]

__TOC__

=Background=

The modern web has seen more and more web applications that are written as web services or web APIs. These applications do not return a web page to the client browser, but return just the bare bones data to the client in the format requested. This gives the clients the liberty to develop customized User Interfaces for the same web application. A common example is the Rotten Tomatoes API which offers movie data in JSON, XML and various other formats. The clients request the Rotten Tomatoes web server for the data in the desired format, and the web server is able to respond with the correct data in the required format.

Active Model Serializers are a way for Web API designers who use Ruby on Rails to have full control over the formatting and the content of data that is returned to clients. For eg. An employee data model returned as JSON to a data request might look like this:

<pre>
{Employee: {
name: emp_name
age: 26
salary: 35000
weight: 90kg
height: 170
}
}
</pre>

But the API designer may want to improve this formatting and exclude certain fields so that the response is just the data without clubbing it under the "Employee" root token:

<pre>
{
EmpConciseDetails: emp_name 26
}
</pre>

In a Ruby On Rails application there could be a couple of ways to achieve this.

===Option 1===

The first one is shown below where we can specify the JSON formatting option in the action method which handles the data request. The below method fetches the desired Employee and returns its JSON representation to the client:

<pre>
def show
@emp = Employee.find(params[:id])

respond_to do |format|
format.json { render :json => @emp, root:false}
end
end
</pre>

Specifying '''root: false''' above will remove the unwanted Employee token from the resultant JSON. However this method is not recommended as we are littering our controller layer with data formatting code. If we want to maintain the MVC separation of concerns, formatting the response data does not belong in the controller layer.

===Option 2===

Another option is to override the '''as_json''' method of the Employee data model which is typically an Active Record in a Rails application:

<pre>

class Employee < ActiveRecord

def as_json(options)
super(:only => [:name, :age])
end

end
</pre>

The above '''as_json''' method is called whenever Rails has to convert the Employee object to its JSON format to send to the client. Our custom '''as_json''' method will help us return only the name and the age as desired. However we again have a problem as we are littering our Model layer with custom formatting tasks which it is not intended to handle.

Through '''Active model serializers''' we are able to place these custom formatting tasks to a separate class namely an EmployeeSerializer which inherits from ActiveModel::Serializer class. The Rails application is able to discover this serializer when Employee data model has to be serialized without any configuration from the programmer's side. The advantages of this scheme are dual. It helps keep separation of concerns in the Rails application, and its done with a convention over configuration approach. Specifics are discussed in following sections.

= Introduction =
Knowledge of the following terms would help before getting to the usage of '''Active Model Serializers'''.

===Active Model===
'''[http://railscasts.com/episodes/219-active-model Active Model]''' is closely related to the widely used concept of '''[http://en.wikibooks.org/wiki/Ruby_on_Rails/ActiveRecord Active Record]''' in the Rails world. '''Active Record''' is an object that maps directly to the data in our database. An '''Active Record''' takes care of fetching and saving data to the database. For example, in an employee records application an Employee Active Record helps to persist a newly created/edited Employee. So how is an '''Active Model''' different?

It may not always be the case that the Employee model has to be backed by a database and the programmer may decide not to implement an Employee model as an Active Record. However the programmer might want some of the model attribute validation functionality that an Active Record provides. For eg: Imagine an employee records system that handles an create employee form by reading the POST data into an Employee object. The system does not persist this Employee model to any database though. It simply emails the admin with all the captured data present in the Employee model. However before emailing the programmer might want to validate if certain required attributes about the Employee are present.

The solution to this problem is the Active Model class. An '''Active Model''' is an Active Record devoid of all the database persistence functionality. Infact, the rails developers segregated all the non database functionality out of an '''Active Record''' into an '''Active Model'''.

===Serializer===
Serializer is a small program that takes an object residing in program memory (for example: could be a C# object in an ASP.NET application, or an ActiveModel object in a Rails application) and converts this information into format that is transferrable over the wire, for example, JSON and XML. This is required because the client may be written in Java and there is no way for it to read an Active Model Ruby Object that exists in memory on the server side.

===API Server Application===
API Server application is an application which serves data requests coming from a variety of clients (for example: mobile, desktop) in various formats such as JSON, XML. For example, An employee data web service which returns employee age and name in both JSON and XML

=Why Active Model Serializers?=

* '''Custom response attributes:''' It is not always the case that an API application serves a request by responding with data as it is stored on the server. The API designer has a task of exposing just the right data to the clients and hence needs fine control over exactly what part of the data on the server is returned in a response. An Active Model Serializer could help return just the Employee age and name to the client as JSON and ignore all the other attributes set on an Employee Model.
 
* '''Separation of Concerns:''' The response data could also be customized in the respond_to method of the rails controller action or for example, by implementing a custom as_json method on the model class. However this breaks the separation of concerns principle as we let something like formatting the response data venture into the controller and model layer. With Active Model Serializers we can keep this functionality segregated from the application.
 
*'''Maintainability:''' Client needs keep changing. Let's say a Client requests some changes to the API response data, only the Active Model Serializer would get affected and there are no side effects on the Controller or the Model itself.
 
=How Active Model Serializer Works?=
[[File:Active-Model-Serializer2.png‎|right]]

Active Model Serializers work with the help of two components namely '''Serializer''' and '''Adapter'''. Let's say we wanted to write an Active Model Serializer for customizing an API that returns Employee data as json. We would have to write an '''EmployeeSerializer''' which is configured to use a '''JsonApiAdapter'''. The '''Serializer''' Component would specify which attributes and relationships of Employee to other models would be captured in the response data. For example, it might choose to return the Employee name, age and the data about the employee's family members which are different models. The '''Adapter''' component specifies how to format this selected Employee data in the correct format as required by the client. A JsonApiAdapter would format it as JSON and is the default adapter used by an Active Model Serializer. However you can always supply your own Adapter for the serializer to use.

Assume the Employee data API scenario cited above and Refer to the figure.
#The Controller receives the request for json data and routes it to a specific action method
#The action method has a respond_to method that returns Employee model as JSON. When Rails encounters this line, it looks for an EmployeeSerializer in the project specifically in a file employee_serializer to get the exact data to be put into the response.
#The EmployeeSerializer is by default configured to use a JsonApiAdapter and formats the specified attributes and relationships in the JSON format. This forms the final customized response.

As you can see, instead of returning the default JSON conversion of the Employee model from the respond_to method, that Rails does automatically for us, we were able to customize our API response data through the use of Active Model Serializers in a non-intrusive way maintaining separation from the controller and the model layers.

=Using Active Model Serializer=

Time to write some code now.

'''Step 1:''' Active Model Serializer is available as a gem. Add to the gem file the following line :
<pre>
gem 'active_model_serializers'
</pre>

'''Step 2:''' Run the following command at the terminal window to install the gem.

<pre>
bundle update
</pre>

'''Step 3:''' This gem provides a serializer generator for the selected Active Model. For example, if employee was your Active Model run :
rails g serializer employee

This would create a file employee_serializer.rb containing the following code in the newly created app/serializers directory of your project:
<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id

end
</pre>

'''Step 4:''' Add your custom attributes and any other customizations to this file. For example: We are adding a url attribute to get details of this employee although the Employee Active Model does not have any such attribute. We add it because the client might be interested in it. That is the power of Active Model Serializer. It does not require us to define another property on the Employee Active Model to return its Url.

<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id, :name, :age, :url

def url
employee_url(object)
end

end
</pre>

'''Step 5:''' That's it! Whenever an Employee is requested the custom EmployeeSerializer does the task of serializing the employee to json and will now include a url key value pair to view the Employee.

=References=
#[http://railscasts.com/episodes/409-active-model-serializers Railcast on Active Model Serializers]
#[https://github.com/rails-api/active_model_serializers Active Model Serializer module on github]
#[http://asciicasts.com/episodes/409-active-model-serializers Active Model Serializer Asciicast]
#[https://www.youtube.com/watch?v=G6ipU6AiEXY Active Model Serializer Video Tutorial]
#[http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/ Active Model]
#[http://en.wikipedia.org/wiki/Serialization Serialization wiki]
#[http://en.wikipedia.org/wiki/JSON JSON wiki]
#[http://en.wikipedia.org/wiki/RubyGems RubyGems wiki]

CSC/ECE 517 Fall 2014/ch1a 24 sa

2014-09-26T02:30:12Z

Shjoshi2: /* Active Model */

=Active Model Serializers=

[http://en.wikipedia.org/wiki/Ruby_on_Rails Ruby on Rails] offers strong features to write API based server applications, which expose data through a well designed API and serve data in various formats as requested. One of these features is '''[http://github.com/rails-api/active_model_serializers Active Model Serializers]''' which helps the API designers to have fine control over the response generated by the API to a data request. '''Active Model Serializers''' help programmers do this very easily and cleanly without breaking separation of concerns in a rails application. They promote [http://en.wikipedia.org/wiki/Convention_over_configuration convention over configuration], thus reducing code bloat and increasing code scalibility and readability.
 

[[File:ClientServer.png‎|right|]]

__TOC__

=Background=

The modern web has seen more and more web applications that are written as web services or web APIs. These applications do not return a web page to the client browser, but return just the bare bones data to the client in the format requested. This gives the clients the liberty to develop customized User Interfaces for the same web application. A common example is the Rotten Tomatoes API which offers movie data in JSON, XML and various other formats. The clients request the Rotten Tomatoes web server for the data in the desired format, and the web server is able to respond with the correct data in the required format.

Active Model Serializers are a way for Web API designers who use Ruby on Rails to have full control over the formatting and the content of data that is returned to clients. For eg. An employee data model returned as JSON to a data request might look like this:

<pre>
{Employee: {
name: emp_name
age: 26
salary: 35000
weight: 90kg
height: 170
}
}
</pre>

But the API designer may want to improve this formatting and exclude certain fields so that the response is just the data without clubbing it under the "Employee" root token:

<pre>
{
EmpConciseDetails: emp_name 26
}
</pre>

In a Ruby On Rails application there could be a couple of ways to achieve this.

===Option 1===

The first one is shown below where we can specify the JSON formatting option in the action method which handles the data request. The below method fetches the desired Employee and returns its JSON representation to the client:

<pre>
def show
@emp = Employee.find(params[:id])

respond_to do |format|
format.json { render :json => @emp, root:false}
end
end
</pre>

Specifying '''root: false''' above will remove the unwanted Employee token from the resultant JSON. However this method is not recommended as we are littering our controller layer with data formatting code. If we want to maintain the MVC separation of concerns, formatting the response data does not belong in the controller layer.

===Option 2===

Another option is to override the '''as_json''' method of the Employee data model which is typically an Active Record in a Rails application:

<pre>

class Employee < ActiveRecord

def as_json(options)
super(:only => [:name, :age])
end

end
</pre>

The above '''as_json''' method is called whenever Rails has to convert the Employee object to its JSON format to send to the client. Our custom '''as_json''' method will help us return only the name and the age as desired. However we again have a problem as we are littering our Model layer with custom formatting tasks which it is not intended to handle.

Through '''Active model serializers''' we are able to place these custom formatting tasks to a separate class namely an EmployeeSerializer which inherits from ActiveModel::Serializer class. The Rails application is able to discover this serializer when Employee data model has to be serialized without any configuration from the programmer's side. The advantages of this scheme are dual. It helps keep separation of concerns in the Rails application, and its done with a convention over configuration approach. Specifics are discussed in following sections.

= Introduction =
Knowledge of the following terms would help before getting to the usage of '''Active Model Serializers'''.

===Active Model===
'''[http://railscasts.com/episodes/219-active-model Active Model]''' is closely related to the widely used concept of '''[http://en.wikibooks.org/wiki/Ruby_on_Rails/ActiveRecord Active Record]''' in the Rails world. '''Active Record''' is an object that maps directly to the data in our database. An '''Active Record''' takes care of fetching and saving data to the database. For example, in an employee records application an Employee Active Record helps to persist a newly created/edited Employee. So how is an '''Active Model''' different?

It may not always be the case that the Employee model has to be backed by a database and the programmer may decide not to implement an Employee model as an Active Record. However the programmer might want some of the model attribute validation functionality that an Active Record provides. For eg: Imagine an employee records system that handles an create employee form by reading the POST data into an Employee object. The system does not persist this Employee model to any database though. It simply emails the admin with all the captured data present in the Employee model. However before emailing the programmer might want to validate if certain required attributes about the Employee are present.

The solution to this problem is the Active Model class. An '''Active Model''' is an Active Record devoid of all the database persistence functionality. Infact, the rails developers segregated all the non database functionality out of an '''Active Record''' into an '''Active Model'''.

===Serializer===
Serializer is a small program that takes an object residing in program memory (for example: could be a C# object in an ASP.NET application, or an ActiveModel object in a Rails application) and converts this information into format that is transferrable over the wire, for example, JSON and XML. This is required because the client may be written in Java and there is no way for it to read an Active Model Ruby Object that exists in memory on the server side.

===API Server Application===
API Server application is an application which serves data requests coming from a variety of clients (for example: mobile, desktop) in various formats such as JSON, XML. For example, An employee data web service which returns employee age and name in both JSON and XML

=Why Active Model Serializers?=

* '''Custom response attributes:''' It is not always the case that an API application serves a request by responding with data as it is stored on the server. The API designer has a task of exposing just the right data to the clients and hence needs fine control over exactly what part of the data on the server is returned in a response. An Active Model Serializer could help return just the Employee age and name to the client as JSON and ignore all the other attributes set on an Employee Model.
 
* '''Separation of Concerns:''' The response data could also be customized in the respond_to method of the rails controller action or for example, by implementing a custom as_json method on the model class. However this breaks the separation of concerns principle as we let something like formatting the response data venture into the controller and model layer. With Active Model Serializers we can keep this functionality segregated from the application.
 
*'''Maintainability:''' Client needs keep changing. Let's say a Client requests some changes to the API response data, only the Active Model Serializer would get affected and there are no side effects on the Controller or the Model itself.
 
=How Active Model Serializer Works?=
[[File:Active-Model-Serializer2.png‎|right]]

Active Model Serializers work with the help of two components namely '''Serializer''' and '''Adapter'''. Let's say we wanted to write an Active Model Serializer for customizing an API that returns Employee data as json. We would have to write an '''EmployeeSerializer''' which is configured to use a '''JsonApiAdapter'''. The '''Serializer''' Component would specify which attributes and relationships of Employee to other models would be captured in the response data. For example, it might choose to return the Employee name, age and the data about the employee's family members which are different models. The '''Adapter''' component specifies how to format this selected Employee data in the correct format as required by the client. A JsonApiAdapter would format it as JSON and is the default adapter used by an Active Model Serializer. However you can always supply your own Adapter for the serializer to use.

Assume the Employee data API scenario cited above and Refer to the figure.
#The Controller receives the request for json data and routes it to a specific action method
#The action method has a respond_to method that returns Employee model as JSON. When Rails encounters this line, it looks for an EmployeeSerializer in the project specifically in a file employee_serializer to get the exact data to be put into the response.
#The EmployeeSerializer is by default configured to use a JsonApiAdapter and formats the specified attributes and relationships in the JSON format. This forms the final customized response.

As you can see, instead of returning the default JSON conversion of the Employee model from the respond_to method, that Rails does automatically for us, we were able to customize our API response data through the use of Active Model Serializers in a non-intrusive way maintaining separation from the controller and the model layers.

=Using Active Model Serializer=

Let us see some code now.

'''Step 1:''' Active Model Serializer is available as a gem. Add to the gem file the following line :
<pre>
gem 'active_model_serializers'
</pre>

'''Step 2:''' Run the following command at the terminal window to install the gem.

<pre>
bundle update
</pre>

'''Step 3:''' This gem provides a serializer generator for the selected Active Model. For example, if employee was your Active Model run :
rails g serializer employee

This would create a file employee_serializer.rb containing the following code in the newly created app/serializers directory of your project:
<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id

end
</pre>

'''Step 4:''' Add your custom attributes and any other customizations to this file. For example: We are adding a url attribute to get details of this employee although the Employee Active Model does not have any such attribute. We add it because the client might be interested in it. That is the power of Active Model Serializer. It does not require us to define another property on the Employee Active Model to return its Url.

<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id, :name, :age, :url

def url
employee_url(object)
end

end
</pre>

'''Step 5:''' That's it! Whenever an Employee is requested the custom EmployeeSerializer does the task of serializing the employee to json and will now include a url key value pair to view the Employee.

=References=
#[http://railscasts.com/episodes/409-active-model-serializers Railcast on Active Model Serializers]
#[https://github.com/rails-api/active_model_serializers Active Model Serializer module on github]
#[http://asciicasts.com/episodes/409-active-model-serializers Active Model Serializer Asciicast]
#[https://www.youtube.com/watch?v=G6ipU6AiEXY Active Model Serializer Video Tutorial]
#[http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/ Active Model]
#[http://en.wikipedia.org/wiki/Serialization Serialization wiki]
#[http://en.wikipedia.org/wiki/JSON JSON wiki]
#[http://en.wikipedia.org/wiki/RubyGems RubyGems wiki]

CSC/ECE 517 Fall 2014/ch1a 24 sa

2014-09-26T02:28:29Z

Shjoshi2: /* Active Model */

=Active Model Serializers=

[http://en.wikipedia.org/wiki/Ruby_on_Rails Ruby on Rails] offers strong features to write API based server applications, which expose data through a well designed API and serve data in various formats as requested. One of these features is '''[http://github.com/rails-api/active_model_serializers Active Model Serializers]''' which helps the API designers to have fine control over the response generated by the API to a data request. '''Active Model Serializers''' help programmers do this very easily and cleanly without breaking separation of concerns in a rails application. They promote [http://en.wikipedia.org/wiki/Convention_over_configuration convention over configuration], thus reducing code bloat and increasing code scalibility and readability.
 

[[File:ClientServer.png‎|right|]]

__TOC__

=Background=

The modern web has seen more and more web applications that are written as web services or web APIs. These applications do not return a web page to the client browser, but return just the bare bones data to the client in the format requested. This gives the clients the liberty to develop customized User Interfaces for the same web application. A common example is the Rotten Tomatoes API which offers movie data in JSON, XML and various other formats. The clients request the Rotten Tomatoes web server for the data in the desired format, and the web server is able to respond with the correct data in the required format.

Active Model Serializers are a way for Web API designers who use Ruby on Rails to have full control over the formatting and the content of data that is returned to clients. For eg. An employee data model returned as JSON to a data request might look like this:

<pre>
{Employee: {
name: emp_name
age: 26
salary: 35000
weight: 90kg
height: 170
}
}
</pre>

But the API designer may want to improve this formatting and exclude certain fields so that the response is just the data without clubbing it under the "Employee" root token:

<pre>
{
EmpConciseDetails: emp_name 26
}
</pre>

In a Ruby On Rails application there could be a couple of ways to achieve this.

===Option 1===

The first one is shown below where we can specify the JSON formatting option in the action method which handles the data request. The below method fetches the desired Employee and returns its JSON representation to the client:

<pre>
def show
@emp = Employee.find(params[:id])

respond_to do |format|
format.json { render :json => @emp, root:false}
end
end
</pre>

Specifying '''root: false''' above will remove the unwanted Employee token from the resultant JSON. However this method is not recommended as we are littering our controller layer with data formatting code. If we want to maintain the MVC separation of concerns, formatting the response data does not belong in the controller layer.

===Option 2===

Another option is to override the '''as_json''' method of the Employee data model which is typically an Active Record in a Rails application:

<pre>

class Employee < ActiveRecord

def as_json(options)
super(:only => [:name, :age])
end

end
</pre>

The above '''as_json''' method is called whenever Rails has to convert the Employee object to its JSON format to send to the client. Our custom '''as_json''' method will help us return only the name and the age as desired. However we again have a problem as we are littering our Model layer with custom formatting tasks which it is not intended to handle.

Through '''Active model serializers''' we are able to place these custom formatting tasks to a separate class namely an EmployeeSerializer which inherits from ActiveModel::Serializer class. The Rails application is able to discover this serializer when Employee data model has to be serialized without any configuration from the programmer's side. The advantages of this scheme are dual. It helps keep separation of concerns in the Rails application, and its done with a convention over configuration approach. Specifics are discussed in following sections.

= Introduction =
Knowledge of the following terms would help before getting to the usage of '''Active Model Serializers'''.

===Active Model===
'''[http://railscasts.com/episodes/219-active-model Active Model]''' is closely related to the widely used concept of '''[http://en.wikibooks.org/wiki/Ruby_on_Rails/ActiveRecord Active Record]''' in the Rails world. '''Active Record''' is an object that maps directly to the data in our database. An '''Active Record''' takes care of fetching and saving data to the database. For example, in an employee records application an Employee Active Record helps to persist a newly created/edited Employee. So how is an '''Active Model''' different?

It may not always be the case that the Employee model has to be backed by a database. But the programmer might want some of the model attribute validation functionality that an Active Record provides. For eg: Imagine an employee records system that handles an create employee form by reading the POST data into an Employee object. The system does not persist this Employee model to any database though. It simply emails the admin with all the captured data present in the Employee model. However before emailing the programmer might want to validate if certain required attributes about the Employee are present.

The solution to this problem is the Active Model class. An '''Active Model''' is an Active Record devoid of all the database persistence functionality. Infact, the rails developers segregated all the non database functionality out of an '''Active Record''' into an '''Active Model'''.

===Serializer===
Serializer is a small program that takes an object residing in program memory (for example: could be a C# object in an ASP.NET application, or an ActiveModel object in a Rails application) and converts this information into format that is transferrable over the wire, for example, JSON and XML. This is required because the client may be written in Java and there is no way for it to read an Active Model Ruby Object that exists in memory on the server side.

===API Server Application===
API Server application is an application which serves data requests coming from a variety of clients (for example: mobile, desktop) in various formats such as JSON, XML. For example, An employee data web service which returns employee age and name in both JSON and XML

=Why Active Model Serializers?=

* '''Custom response attributes:''' It is not always the case that an API application serves a request by responding with data as it is stored on the server. The API designer has a task of exposing just the right data to the clients and hence needs fine control over exactly what part of the data on the server is returned in a response. An Active Model Serializer could help return just the Employee age and name to the client as JSON and ignore all the other attributes set on an Employee Model.
 
* '''Separation of Concerns:''' The response data could also be customized in the respond_to method of the rails controller action or for example, by implementing a custom as_json method on the model class. However this breaks the separation of concerns principle as we let something like formatting the response data venture into the controller and model layer. With Active Model Serializers we can keep this functionality segregated from the application.
 
*'''Maintainability:''' Client needs keep changing. Let's say a Client requests some changes to the API response data, only the Active Model Serializer would get affected and there are no side effects on the Controller or the Model itself.
 
=How Active Model Serializer Works?=
[[File:Active-Model-Serializer2.png‎|right]]

Active Model Serializers work with the help of two components namely '''Serializer''' and '''Adapter'''. Let's say we wanted to write an Active Model Serializer for customizing an API that returns Employee data as json. We would have to write an '''EmployeeSerializer''' which is configured to use a '''JsonApiAdapter'''. The '''Serializer''' Component would specify which attributes and relationships of Employee to other models would be captured in the response data. For example, it might choose to return the Employee name, age and the data about the employee's family members which are different models. The '''Adapter''' component specifies how to format this selected Employee data in the correct format as required by the client. A JsonApiAdapter would format it as JSON and is the default adapter used by an Active Model Serializer. However you can always supply your own Adapter for the serializer to use.

Assume the Employee data API scenario cited above and Refer to the figure.
#The Controller receives the request for json data and routes it to a specific action method
#The action method has a respond_to method that returns Employee model as JSON. When Rails encounters this line, it looks for an EmployeeSerializer in the project specifically in a file employee_serializer to get the exact data to be put into the response.
#The EmployeeSerializer is by default configured to use a JsonApiAdapter and formats the specified attributes and relationships in the JSON format. This forms the final customized response.

As you can see, instead of returning the default JSON conversion of the Employee model from the respond_to method, that Rails does automatically for us, we were able to customize our API response data through the use of Active Model Serializers in a non-intrusive way maintaining separation from the controller and the model layers.

=Using Active Model Serializer=

Let us see some code now.

'''Step 1:''' Active Model Serializer is available as a gem. Add to the gem file the following line :
<pre>
gem 'active_model_serializers'
</pre>

'''Step 2:''' Run the following command at the terminal window to install the gem.

<pre>
bundle update
</pre>

'''Step 3:''' This gem provides a serializer generator for the selected Active Model. For example, if employee was your Active Model run :
rails g serializer employee

This would create a file employee_serializer.rb containing the following code in the newly created app/serializers directory of your project:
<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id

end
</pre>

'''Step 4:''' Add your custom attributes and any other customizations to this file. For example: We are adding a url attribute to get details of this employee although the Employee Active Model does not have any such attribute. We add it because the client might be interested in it. That is the power of Active Model Serializer. It does not require us to define another property on the Employee Active Model to return its Url.

<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id, :name, :age, :url

def url
employee_url(object)
end

end
</pre>

'''Step 5:''' That's it! Whenever an Employee is requested the custom EmployeeSerializer does the task of serializing the employee to json and will now include a url key value pair to view the Employee.

=References=
#[http://railscasts.com/episodes/409-active-model-serializers Railcast on Active Model Serializers]
#[https://github.com/rails-api/active_model_serializers Active Model Serializer module on github]
#[http://asciicasts.com/episodes/409-active-model-serializers Active Model Serializer Asciicast]
#[https://www.youtube.com/watch?v=G6ipU6AiEXY Active Model Serializer Video Tutorial]
#[http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/ Active Model]
#[http://en.wikipedia.org/wiki/Serialization Serialization wiki]
#[http://en.wikipedia.org/wiki/JSON JSON wiki]
#[http://en.wikipedia.org/wiki/RubyGems RubyGems wiki]

CSC/ECE 517 Fall 2014/ch1a 24 sa

2014-09-26T02:28:11Z

Shjoshi2: /* Introduction */

=Active Model Serializers=

[http://en.wikipedia.org/wiki/Ruby_on_Rails Ruby on Rails] offers strong features to write API based server applications, which expose data through a well designed API and serve data in various formats as requested. One of these features is '''[http://github.com/rails-api/active_model_serializers Active Model Serializers]''' which helps the API designers to have fine control over the response generated by the API to a data request. '''Active Model Serializers''' help programmers do this very easily and cleanly without breaking separation of concerns in a rails application. They promote [http://en.wikipedia.org/wiki/Convention_over_configuration convention over configuration], thus reducing code bloat and increasing code scalibility and readability.
 

[[File:ClientServer.png‎|right|]]

__TOC__

=Background=

The modern web has seen more and more web applications that are written as web services or web APIs. These applications do not return a web page to the client browser, but return just the bare bones data to the client in the format requested. This gives the clients the liberty to develop customized User Interfaces for the same web application. A common example is the Rotten Tomatoes API which offers movie data in JSON, XML and various other formats. The clients request the Rotten Tomatoes web server for the data in the desired format, and the web server is able to respond with the correct data in the required format.

Active Model Serializers are a way for Web API designers who use Ruby on Rails to have full control over the formatting and the content of data that is returned to clients. For eg. An employee data model returned as JSON to a data request might look like this:

<pre>
{Employee: {
name: emp_name
age: 26
salary: 35000
weight: 90kg
height: 170
}
}
</pre>

But the API designer may want to improve this formatting and exclude certain fields so that the response is just the data without clubbing it under the "Employee" root token:

<pre>
{
EmpConciseDetails: emp_name 26
}
</pre>

In a Ruby On Rails application there could be a couple of ways to achieve this.

===Option 1===

The first one is shown below where we can specify the JSON formatting option in the action method which handles the data request. The below method fetches the desired Employee and returns its JSON representation to the client:

<pre>
def show
@emp = Employee.find(params[:id])

respond_to do |format|
format.json { render :json => @emp, root:false}
end
end
</pre>

Specifying '''root: false''' above will remove the unwanted Employee token from the resultant JSON. However this method is not recommended as we are littering our controller layer with data formatting code. If we want to maintain the MVC separation of concerns, formatting the response data does not belong in the controller layer.

===Option 2===

Another option is to override the '''as_json''' method of the Employee data model which is typically an Active Record in a Rails application:

<pre>

class Employee < ActiveRecord

def as_json(options)
super(:only => [:name, :age])
end

end
</pre>

The above '''as_json''' method is called whenever Rails has to convert the Employee object to its JSON format to send to the client. Our custom '''as_json''' method will help us return only the name and the age as desired. However we again have a problem as we are littering our Model layer with custom formatting tasks which it is not intended to handle.

Through '''Active model serializers''' we are able to place these custom formatting tasks to a separate class namely an EmployeeSerializer which inherits from ActiveModel::Serializer class. The Rails application is able to discover this serializer when Employee data model has to be serialized without any configuration from the programmer's side. The advantages of this scheme are dual. It helps keep separation of concerns in the Rails application, and its done with a convention over configuration approach. Specifics are discussed in following sections.

= Introduction =
Knowledge of the following terms would help before getting to the usage of '''Active Model Serializers'''.

===Active Model===
'''[http://railscasts.com/episodes/219-active-model Active Model]''' is closely related to the widely used concept of '''[http://en.wikibooks.org/wiki/Ruby_on_Rails/ActiveRecord Active Record]''' in the Rails world. '''Active Record''' is an object that maps directly to the data in our database. An '''Active Record''' takes care of fetching and saving data to the database. For example, in an employee records application an Employee Active Record helps to persist a newly created/edited Employee. So how is an '''Active Model''' different?

It may not always be the case that the Employee model has to be backed by a database. But the programmer might want some of the model attribute validation functionality that an Active Record provides. For eg: Imagine an employee records system that handles an create employee form by reading the POST data into an Employee object. The system does not persist this Employee model to any database though. It simply emails the admin with all the captured data present in the Employee model. However before emailing the programmer might want to validate if certain required attributes about the Employee are present.

The solution to this problem is the Active Model class. An '''Active Model''' is an Active Record devoid of all the database persistence functionality. Infact, the rails developers segregated all the non database functionality out of an '''Active Record''' into an '''Active Model'''.

===Serializer====Serializer is a small program that takes an object residing in program memory (for example: could be a C# object in an ASP.NET application, or an ActiveModel object in a Rails application) and converts this information into format that is transferrable over the wire, for example, JSON and XML. This is required because the client may be written in Java and there is no way for it to read an Active Model Ruby Object that exists in memory on the server side.

===API Server Application===
API Server application is an application which serves data requests coming from a variety of clients (for example: mobile, desktop) in various formats such as JSON, XML. For example, An employee data web service which returns employee age and name in both JSON and XML

=Why Active Model Serializers?=

* '''Custom response attributes:''' It is not always the case that an API application serves a request by responding with data as it is stored on the server. The API designer has a task of exposing just the right data to the clients and hence needs fine control over exactly what part of the data on the server is returned in a response. An Active Model Serializer could help return just the Employee age and name to the client as JSON and ignore all the other attributes set on an Employee Model.
 
* '''Separation of Concerns:''' The response data could also be customized in the respond_to method of the rails controller action or for example, by implementing a custom as_json method on the model class. However this breaks the separation of concerns principle as we let something like formatting the response data venture into the controller and model layer. With Active Model Serializers we can keep this functionality segregated from the application.
 
*'''Maintainability:''' Client needs keep changing. Let's say a Client requests some changes to the API response data, only the Active Model Serializer would get affected and there are no side effects on the Controller or the Model itself.
 
=How Active Model Serializer Works?=
[[File:Active-Model-Serializer2.png‎|right]]

Active Model Serializers work with the help of two components namely '''Serializer''' and '''Adapter'''. Let's say we wanted to write an Active Model Serializer for customizing an API that returns Employee data as json. We would have to write an '''EmployeeSerializer''' which is configured to use a '''JsonApiAdapter'''. The '''Serializer''' Component would specify which attributes and relationships of Employee to other models would be captured in the response data. For example, it might choose to return the Employee name, age and the data about the employee's family members which are different models. The '''Adapter''' component specifies how to format this selected Employee data in the correct format as required by the client. A JsonApiAdapter would format it as JSON and is the default adapter used by an Active Model Serializer. However you can always supply your own Adapter for the serializer to use.

Assume the Employee data API scenario cited above and Refer to the figure.
#The Controller receives the request for json data and routes it to a specific action method
#The action method has a respond_to method that returns Employee model as JSON. When Rails encounters this line, it looks for an EmployeeSerializer in the project specifically in a file employee_serializer to get the exact data to be put into the response.
#The EmployeeSerializer is by default configured to use a JsonApiAdapter and formats the specified attributes and relationships in the JSON format. This forms the final customized response.

As you can see, instead of returning the default JSON conversion of the Employee model from the respond_to method, that Rails does automatically for us, we were able to customize our API response data through the use of Active Model Serializers in a non-intrusive way maintaining separation from the controller and the model layers.

=Using Active Model Serializer=

Let us see some code now.

'''Step 1:''' Active Model Serializer is available as a gem. Add to the gem file the following line :
<pre>
gem 'active_model_serializers'
</pre>

'''Step 2:''' Run the following command at the terminal window to install the gem.

<pre>
bundle update
</pre>

'''Step 3:''' This gem provides a serializer generator for the selected Active Model. For example, if employee was your Active Model run :
rails g serializer employee

This would create a file employee_serializer.rb containing the following code in the newly created app/serializers directory of your project:
<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id

end
</pre>

'''Step 4:''' Add your custom attributes and any other customizations to this file. For example: We are adding a url attribute to get details of this employee although the Employee Active Model does not have any such attribute. We add it because the client might be interested in it. That is the power of Active Model Serializer. It does not require us to define another property on the Employee Active Model to return its Url.

<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id, :name, :age, :url

def url
employee_url(object)
end

end
</pre>

'''Step 5:''' That's it! Whenever an Employee is requested the custom EmployeeSerializer does the task of serializing the employee to json and will now include a url key value pair to view the Employee.

=References=
#[http://railscasts.com/episodes/409-active-model-serializers Railcast on Active Model Serializers]
#[https://github.com/rails-api/active_model_serializers Active Model Serializer module on github]
#[http://asciicasts.com/episodes/409-active-model-serializers Active Model Serializer Asciicast]
#[https://www.youtube.com/watch?v=G6ipU6AiEXY Active Model Serializer Video Tutorial]
#[http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/ Active Model]
#[http://en.wikipedia.org/wiki/Serialization Serialization wiki]
#[http://en.wikipedia.org/wiki/JSON JSON wiki]
#[http://en.wikipedia.org/wiki/RubyGems RubyGems wiki]

CSC/ECE 517 Fall 2014/ch1a 24 sa

2014-09-26T02:28:01Z

Shjoshi2: /* Introduction */

=Active Model Serializers=

[http://en.wikipedia.org/wiki/Ruby_on_Rails Ruby on Rails] offers strong features to write API based server applications, which expose data through a well designed API and serve data in various formats as requested. One of these features is '''[http://github.com/rails-api/active_model_serializers Active Model Serializers]''' which helps the API designers to have fine control over the response generated by the API to a data request. '''Active Model Serializers''' help programmers do this very easily and cleanly without breaking separation of concerns in a rails application. They promote [http://en.wikipedia.org/wiki/Convention_over_configuration convention over configuration], thus reducing code bloat and increasing code scalibility and readability.
 

[[File:ClientServer.png‎|right|]]

__TOC__

=Background=

The modern web has seen more and more web applications that are written as web services or web APIs. These applications do not return a web page to the client browser, but return just the bare bones data to the client in the format requested. This gives the clients the liberty to develop customized User Interfaces for the same web application. A common example is the Rotten Tomatoes API which offers movie data in JSON, XML and various other formats. The clients request the Rotten Tomatoes web server for the data in the desired format, and the web server is able to respond with the correct data in the required format.

Active Model Serializers are a way for Web API designers who use Ruby on Rails to have full control over the formatting and the content of data that is returned to clients. For eg. An employee data model returned as JSON to a data request might look like this:

<pre>
{Employee: {
name: emp_name
age: 26
salary: 35000
weight: 90kg
height: 170
}
}
</pre>

But the API designer may want to improve this formatting and exclude certain fields so that the response is just the data without clubbing it under the "Employee" root token:

<pre>
{
EmpConciseDetails: emp_name 26
}
</pre>

In a Ruby On Rails application there could be a couple of ways to achieve this.

===Option 1===

The first one is shown below where we can specify the JSON formatting option in the action method which handles the data request. The below method fetches the desired Employee and returns its JSON representation to the client:

<pre>
def show
@emp = Employee.find(params[:id])

respond_to do |format|
format.json { render :json => @emp, root:false}
end
end
</pre>

Specifying '''root: false''' above will remove the unwanted Employee token from the resultant JSON. However this method is not recommended as we are littering our controller layer with data formatting code. If we want to maintain the MVC separation of concerns, formatting the response data does not belong in the controller layer.

===Option 2===

Another option is to override the '''as_json''' method of the Employee data model which is typically an Active Record in a Rails application:

<pre>

class Employee < ActiveRecord

def as_json(options)
super(:only => [:name, :age])
end

end
</pre>

The above '''as_json''' method is called whenever Rails has to convert the Employee object to its JSON format to send to the client. Our custom '''as_json''' method will help us return only the name and the age as desired. However we again have a problem as we are littering our Model layer with custom formatting tasks which it is not intended to handle.

Through '''Active model serializers''' we are able to place these custom formatting tasks to a separate class namely an EmployeeSerializer which inherits from ActiveModel::Serializer class. The Rails application is able to discover this serializer when Employee data model has to be serialized without any configuration from the programmer's side. The advantages of this scheme are dual. It helps keep separation of concerns in the Rails application, and its done with a convention over configuration approach. Specifics are discussed in following sections.

= Introduction =
Knowledge of the following terms would help before getting to the usage of '''Active Model Serializers'''.

===Active Model===
'''[http://railscasts.com/episodes/219-active-model Active Model]''' is closely related to the widely used concept of '''[http://en.wikibooks.org/wiki/Ruby_on_Rails/ActiveRecord Active Record]''' in the Rails world. '''Active Record''' is an object that maps directly to the data in our database. An '''Active Record''' takes care of fetching and saving data to the database. For example, in an employee records application an Employee Active Record helps to persist a newly created/edited Employee. So how is an '''Active Model''' different?

It may not always be the case that the Employee model has to be backed by a database. But the programmer might want some of the model attribute validation functionality that an Active Record provides. For eg: Imagine an employee records system that handles an create employee form by reading the POST data into an Employee object. The system does not persist this Employee model to any database though. It simply emails the admin with all the captured data present in the Employee model. However before emailing the programmer might want to validate if certain required attributes about the Employee are present.

The solution to this problem is the Active Model class. An '''Active Model''' is an Active Record devoid of all the database persistence functionality. Infact, the rails developers segregated all the non database functionality out of an '''Active Record''' into an '''Active Model'''.

===Serializer====
Serializer is a small program that takes an object residing in program memory (for example: could be a C# object in an ASP.NET application, or an ActiveModel object in a Rails application) and converts this information into format that is transferrable over the wire, for example, JSON and XML. This is required because the client may be written in Java and there is no way for it to read an Active Model Ruby Object that exists in memory on the server side.

===API Server Application===
API Server application is an application which serves data requests coming from a variety of clients (for example: mobile, desktop) in various formats such as JSON, XML. For example, An employee data web service which returns employee age and name in both JSON and XML

=Why Active Model Serializers?=

* '''Custom response attributes:''' It is not always the case that an API application serves a request by responding with data as it is stored on the server. The API designer has a task of exposing just the right data to the clients and hence needs fine control over exactly what part of the data on the server is returned in a response. An Active Model Serializer could help return just the Employee age and name to the client as JSON and ignore all the other attributes set on an Employee Model.
 
* '''Separation of Concerns:''' The response data could also be customized in the respond_to method of the rails controller action or for example, by implementing a custom as_json method on the model class. However this breaks the separation of concerns principle as we let something like formatting the response data venture into the controller and model layer. With Active Model Serializers we can keep this functionality segregated from the application.
 
*'''Maintainability:''' Client needs keep changing. Let's say a Client requests some changes to the API response data, only the Active Model Serializer would get affected and there are no side effects on the Controller or the Model itself.
 
=How Active Model Serializer Works?=
[[File:Active-Model-Serializer2.png‎|right]]

Active Model Serializers work with the help of two components namely '''Serializer''' and '''Adapter'''. Let's say we wanted to write an Active Model Serializer for customizing an API that returns Employee data as json. We would have to write an '''EmployeeSerializer''' which is configured to use a '''JsonApiAdapter'''. The '''Serializer''' Component would specify which attributes and relationships of Employee to other models would be captured in the response data. For example, it might choose to return the Employee name, age and the data about the employee's family members which are different models. The '''Adapter''' component specifies how to format this selected Employee data in the correct format as required by the client. A JsonApiAdapter would format it as JSON and is the default adapter used by an Active Model Serializer. However you can always supply your own Adapter for the serializer to use.

Assume the Employee data API scenario cited above and Refer to the figure.
#The Controller receives the request for json data and routes it to a specific action method
#The action method has a respond_to method that returns Employee model as JSON. When Rails encounters this line, it looks for an EmployeeSerializer in the project specifically in a file employee_serializer to get the exact data to be put into the response.
#The EmployeeSerializer is by default configured to use a JsonApiAdapter and formats the specified attributes and relationships in the JSON format. This forms the final customized response.

As you can see, instead of returning the default JSON conversion of the Employee model from the respond_to method, that Rails does automatically for us, we were able to customize our API response data through the use of Active Model Serializers in a non-intrusive way maintaining separation from the controller and the model layers.

=Using Active Model Serializer=

Let us see some code now.

'''Step 1:''' Active Model Serializer is available as a gem. Add to the gem file the following line :
<pre>
gem 'active_model_serializers'
</pre>

'''Step 2:''' Run the following command at the terminal window to install the gem.

<pre>
bundle update
</pre>

'''Step 3:''' This gem provides a serializer generator for the selected Active Model. For example, if employee was your Active Model run :
rails g serializer employee

This would create a file employee_serializer.rb containing the following code in the newly created app/serializers directory of your project:
<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id

end
</pre>

'''Step 4:''' Add your custom attributes and any other customizations to this file. For example: We are adding a url attribute to get details of this employee although the Employee Active Model does not have any such attribute. We add it because the client might be interested in it. That is the power of Active Model Serializer. It does not require us to define another property on the Employee Active Model to return its Url.

<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id, :name, :age, :url

def url
employee_url(object)
end

end
</pre>

'''Step 5:''' That's it! Whenever an Employee is requested the custom EmployeeSerializer does the task of serializing the employee to json and will now include a url key value pair to view the Employee.

=References=
#[http://railscasts.com/episodes/409-active-model-serializers Railcast on Active Model Serializers]
#[https://github.com/rails-api/active_model_serializers Active Model Serializer module on github]
#[http://asciicasts.com/episodes/409-active-model-serializers Active Model Serializer Asciicast]
#[https://www.youtube.com/watch?v=G6ipU6AiEXY Active Model Serializer Video Tutorial]
#[http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/ Active Model]
#[http://en.wikipedia.org/wiki/Serialization Serialization wiki]
#[http://en.wikipedia.org/wiki/JSON JSON wiki]
#[http://en.wikipedia.org/wiki/RubyGems RubyGems wiki]

CSC/ECE 517 Fall 2014/ch1a 24 sa

2014-09-26T02:27:14Z

Shjoshi2: /* Introduction */

=Active Model Serializers=

[http://en.wikipedia.org/wiki/Ruby_on_Rails Ruby on Rails] offers strong features to write API based server applications, which expose data through a well designed API and serve data in various formats as requested. One of these features is '''[http://github.com/rails-api/active_model_serializers Active Model Serializers]''' which helps the API designers to have fine control over the response generated by the API to a data request. '''Active Model Serializers''' help programmers do this very easily and cleanly without breaking separation of concerns in a rails application. They promote [http://en.wikipedia.org/wiki/Convention_over_configuration convention over configuration], thus reducing code bloat and increasing code scalibility and readability.
 

[[File:ClientServer.png‎|right|]]

__TOC__

=Background=

The modern web has seen more and more web applications that are written as web services or web APIs. These applications do not return a web page to the client browser, but return just the bare bones data to the client in the format requested. This gives the clients the liberty to develop customized User Interfaces for the same web application. A common example is the Rotten Tomatoes API which offers movie data in JSON, XML and various other formats. The clients request the Rotten Tomatoes web server for the data in the desired format, and the web server is able to respond with the correct data in the required format.

Active Model Serializers are a way for Web API designers who use Ruby on Rails to have full control over the formatting and the content of data that is returned to clients. For eg. An employee data model returned as JSON to a data request might look like this:

<pre>
{Employee: {
name: emp_name
age: 26
salary: 35000
weight: 90kg
height: 170
}
}
</pre>

But the API designer may want to improve this formatting and exclude certain fields so that the response is just the data without clubbing it under the "Employee" root token:

<pre>
{
EmpConciseDetails: emp_name 26
}
</pre>

In a Ruby On Rails application there could be a couple of ways to achieve this.

===Option 1===

The first one is shown below where we can specify the JSON formatting option in the action method which handles the data request. The below method fetches the desired Employee and returns its JSON representation to the client:

<pre>
def show
@emp = Employee.find(params[:id])

respond_to do |format|
format.json { render :json => @emp, root:false}
end
end
</pre>

Specifying '''root: false''' above will remove the unwanted Employee token from the resultant JSON. However this method is not recommended as we are littering our controller layer with data formatting code. If we want to maintain the MVC separation of concerns, formatting the response data does not belong in the controller layer.

===Option 2===

Another option is to override the '''as_json''' method of the Employee data model which is typically an Active Record in a Rails application:

<pre>

class Employee < ActiveRecord

def as_json(options)
super(:only => [:name, :age])
end

end
</pre>

The above '''as_json''' method is called whenever Rails has to convert the Employee object to its JSON format to send to the client. Our custom '''as_json''' method will help us return only the name and the age as desired. However we again have a problem as we are littering our Model layer with custom formatting tasks which it is not intended to handle.

Through '''Active model serializers''' we are able to place these custom formatting tasks to a separate class namely an EmployeeSerializer which inherits from ActiveModel::Serializer class. The Rails application is able to discover this serializer when Employee data model has to be serialized without any configuration from the programmer's side. The advantages of this scheme are dual. It helps keep separation of concerns in the Rails application, and its done with a convention over configuration approach. Specifics are discussed in following sections.

= Introduction =
Knowledge of the following terms would help before getting to the usage of '''Active Model Serializers'''.
;Active Model
'''[http://railscasts.com/episodes/219-active-model Active Model]''' is closely related to the widely used concept of '''[http://en.wikibooks.org/wiki/Ruby_on_Rails/ActiveRecord Active Record]''' in the Rails world. '''Active Record''' is an object that maps directly to the data in our database. An '''Active Record''' takes care of fetching and saving data to the database. For example, in an employee records application an Employee Active Record helps to persist a newly created/edited Employee. So how is an '''Active Model''' different?

It may not always be the case that the Employee model has to be backed by a database. But the programmer might want some of the model attribute validation functionality that an Active Record provides. For eg: Imagine an employee records system that handles an create employee form by reading the POST data into an Employee object. The system does not persist this Employee model to any database though. It simply emails the admin with all the captured data present in the Employee model. However before emailing the programmer might want to validate if certain required attributes about the Employee are present.

The solution to this problem is the Active Model class. An '''Active Model''' is an Active Record devoid of all the database persistence functionality. Infact, the rails developers segregated all the non database functionality out of an '''Active Record''' into an '''Active Model'''.

;Serializer
:Serializer is a small program that takes an object residing in program memory (for example: could be a C# object in an ASP.NET application, or an ActiveModel object in a Rails application) and converts this information into format that is transferrable over the wire, for example, JSON and XML. This is required because the client may be written in Java and there is no way for it to read an Active Model Ruby Object that exists in memory on the server side.

;API Server Application
:API Server application is an application which serves data requests coming from a variety of clients (for example: mobile, desktop) in various formats such as JSON, XML. For example, An employee data web service which returns employee age and name in both JSON and XML

=Why Active Model Serializers?=

* '''Custom response attributes:''' It is not always the case that an API application serves a request by responding with data as it is stored on the server. The API designer has a task of exposing just the right data to the clients and hence needs fine control over exactly what part of the data on the server is returned in a response. An Active Model Serializer could help return just the Employee age and name to the client as JSON and ignore all the other attributes set on an Employee Model.
 
* '''Separation of Concerns:''' The response data could also be customized in the respond_to method of the rails controller action or for example, by implementing a custom as_json method on the model class. However this breaks the separation of concerns principle as we let something like formatting the response data venture into the controller and model layer. With Active Model Serializers we can keep this functionality segregated from the application.
 
*'''Maintainability:''' Client needs keep changing. Let's say a Client requests some changes to the API response data, only the Active Model Serializer would get affected and there are no side effects on the Controller or the Model itself.
 
=How Active Model Serializer Works?=
[[File:Active-Model-Serializer2.png‎|right]]

Active Model Serializers work with the help of two components namely '''Serializer''' and '''Adapter'''. Let's say we wanted to write an Active Model Serializer for customizing an API that returns Employee data as json. We would have to write an '''EmployeeSerializer''' which is configured to use a '''JsonApiAdapter'''. The '''Serializer''' Component would specify which attributes and relationships of Employee to other models would be captured in the response data. For example, it might choose to return the Employee name, age and the data about the employee's family members which are different models. The '''Adapter''' component specifies how to format this selected Employee data in the correct format as required by the client. A JsonApiAdapter would format it as JSON and is the default adapter used by an Active Model Serializer. However you can always supply your own Adapter for the serializer to use.

Assume the Employee data API scenario cited above and Refer to the figure.
#The Controller receives the request for json data and routes it to a specific action method
#The action method has a respond_to method that returns Employee model as JSON. When Rails encounters this line, it looks for an EmployeeSerializer in the project specifically in a file employee_serializer to get the exact data to be put into the response.
#The EmployeeSerializer is by default configured to use a JsonApiAdapter and formats the specified attributes and relationships in the JSON format. This forms the final customized response.

As you can see, instead of returning the default JSON conversion of the Employee model from the respond_to method, that Rails does automatically for us, we were able to customize our API response data through the use of Active Model Serializers in a non-intrusive way maintaining separation from the controller and the model layers.

=Using Active Model Serializer=

Let us see some code now.

'''Step 1:''' Active Model Serializer is available as a gem. Add to the gem file the following line :
<pre>
gem 'active_model_serializers'
</pre>

'''Step 2:''' Run the following command at the terminal window to install the gem.

<pre>
bundle update
</pre>

'''Step 3:''' This gem provides a serializer generator for the selected Active Model. For example, if employee was your Active Model run :
rails g serializer employee

This would create a file employee_serializer.rb containing the following code in the newly created app/serializers directory of your project:
<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id

end
</pre>

'''Step 4:''' Add your custom attributes and any other customizations to this file. For example: We are adding a url attribute to get details of this employee although the Employee Active Model does not have any such attribute. We add it because the client might be interested in it. That is the power of Active Model Serializer. It does not require us to define another property on the Employee Active Model to return its Url.

<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id, :name, :age, :url

def url
employee_url(object)
end

end
</pre>

'''Step 5:''' That's it! Whenever an Employee is requested the custom EmployeeSerializer does the task of serializing the employee to json and will now include a url key value pair to view the Employee.

=References=
#[http://railscasts.com/episodes/409-active-model-serializers Railcast on Active Model Serializers]
#[https://github.com/rails-api/active_model_serializers Active Model Serializer module on github]
#[http://asciicasts.com/episodes/409-active-model-serializers Active Model Serializer Asciicast]
#[https://www.youtube.com/watch?v=G6ipU6AiEXY Active Model Serializer Video Tutorial]
#[http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/ Active Model]
#[http://en.wikipedia.org/wiki/Serialization Serialization wiki]
#[http://en.wikipedia.org/wiki/JSON JSON wiki]
#[http://en.wikipedia.org/wiki/RubyGems RubyGems wiki]

CSC/ECE 517 Fall 2014/ch1a 24 sa

2014-09-26T02:26:52Z

Shjoshi2: /* Introduction */

=Active Model Serializers=

[http://en.wikipedia.org/wiki/Ruby_on_Rails Ruby on Rails] offers strong features to write API based server applications, which expose data through a well designed API and serve data in various formats as requested. One of these features is '''[http://github.com/rails-api/active_model_serializers Active Model Serializers]''' which helps the API designers to have fine control over the response generated by the API to a data request. '''Active Model Serializers''' help programmers do this very easily and cleanly without breaking separation of concerns in a rails application. They promote [http://en.wikipedia.org/wiki/Convention_over_configuration convention over configuration], thus reducing code bloat and increasing code scalibility and readability.
 

[[File:ClientServer.png‎|right|]]

__TOC__

=Background=

The modern web has seen more and more web applications that are written as web services or web APIs. These applications do not return a web page to the client browser, but return just the bare bones data to the client in the format requested. This gives the clients the liberty to develop customized User Interfaces for the same web application. A common example is the Rotten Tomatoes API which offers movie data in JSON, XML and various other formats. The clients request the Rotten Tomatoes web server for the data in the desired format, and the web server is able to respond with the correct data in the required format.

Active Model Serializers are a way for Web API designers who use Ruby on Rails to have full control over the formatting and the content of data that is returned to clients. For eg. An employee data model returned as JSON to a data request might look like this:

<pre>
{Employee: {
name: emp_name
age: 26
salary: 35000
weight: 90kg
height: 170
}
}
</pre>

But the API designer may want to improve this formatting and exclude certain fields so that the response is just the data without clubbing it under the "Employee" root token:

<pre>
{
EmpConciseDetails: emp_name 26
}
</pre>

In a Ruby On Rails application there could be a couple of ways to achieve this.

===Option 1===

The first one is shown below where we can specify the JSON formatting option in the action method which handles the data request. The below method fetches the desired Employee and returns its JSON representation to the client:

<pre>
def show
@emp = Employee.find(params[:id])

respond_to do |format|
format.json { render :json => @emp, root:false}
end
end
</pre>

Specifying '''root: false''' above will remove the unwanted Employee token from the resultant JSON. However this method is not recommended as we are littering our controller layer with data formatting code. If we want to maintain the MVC separation of concerns, formatting the response data does not belong in the controller layer.

===Option 2===

Another option is to override the '''as_json''' method of the Employee data model which is typically an Active Record in a Rails application:

<pre>

class Employee < ActiveRecord

def as_json(options)
super(:only => [:name, :age])
end

end
</pre>

The above '''as_json''' method is called whenever Rails has to convert the Employee object to its JSON format to send to the client. Our custom '''as_json''' method will help us return only the name and the age as desired. However we again have a problem as we are littering our Model layer with custom formatting tasks which it is not intended to handle.

Through '''Active model serializers''' we are able to place these custom formatting tasks to a separate class namely an EmployeeSerializer which inherits from ActiveModel::Serializer class. The Rails application is able to discover this serializer when Employee data model has to be serialized without any configuration from the programmer's side. The advantages of this scheme are dual. It helps keep separation of concerns in the Rails application, and its done with a convention over configuration approach. Specifics are discussed in following sections.

= Introduction =
Knowledge of the following terms would help before getting to the usage of '''Active Model Serializers'''.
;Active Model
:'''[http://railscasts.com/episodes/219-active-model Active Model]''' is closely related to the widely used concept of '''[http://en.wikibooks.org/wiki/Ruby_on_Rails/ActiveRecord Active Record]''' in the Rails world. '''Active Record''' is an object that maps directly to the data in our database. An '''Active Record''' takes care of fetching and saving data to the database. For example, in an employee records application an Employee Active Record helps to persist a newly created/edited Employee. So how is an '''Active Model''' different?

It may not always be the case that the Employee model has to be backed by a database. But the programmer might want some of the model attribute validation functionality that an Active Record provides. For eg: Imagine an employee records system that handles an create employee form by reading the POST data into an Employee object. The system does not persist this Employee model to any database though. It simply emails the admin with all the captured data present in the Employee model. However before emailing the programmer might want to validate if certain required attributes about the Employee are present.

The solution to this problem is the Active Model class. An '''Active Model''' is an Active Record devoid of all the database persistence functionality. Infact, the rails developers segregated all the non database functionality out of an '''Active Record''' into an '''Active Model'''.

;Serializer
:Serializer is a small program that takes an object residing in program memory (for example: could be a C# object in an ASP.NET application, or an ActiveModel object in a Rails application) and converts this information into format that is transferrable over the wire, for example, JSON and XML. This is required because the client may be written in Java and there is no way for it to read an Active Model Ruby Object that exists in memory on the server side.

;API Server Application
:API Server application is an application which serves data requests coming from a variety of clients (for example: mobile, desktop) in various formats such as JSON, XML. For example, An employee data web service which returns employee age and name in both JSON and XML

=Why Active Model Serializers?=

* '''Custom response attributes:''' It is not always the case that an API application serves a request by responding with data as it is stored on the server. The API designer has a task of exposing just the right data to the clients and hence needs fine control over exactly what part of the data on the server is returned in a response. An Active Model Serializer could help return just the Employee age and name to the client as JSON and ignore all the other attributes set on an Employee Model.
 
* '''Separation of Concerns:''' The response data could also be customized in the respond_to method of the rails controller action or for example, by implementing a custom as_json method on the model class. However this breaks the separation of concerns principle as we let something like formatting the response data venture into the controller and model layer. With Active Model Serializers we can keep this functionality segregated from the application.
 
*'''Maintainability:''' Client needs keep changing. Let's say a Client requests some changes to the API response data, only the Active Model Serializer would get affected and there are no side effects on the Controller or the Model itself.
 
=How Active Model Serializer Works?=
[[File:Active-Model-Serializer2.png‎|right]]

Active Model Serializers work with the help of two components namely '''Serializer''' and '''Adapter'''. Let's say we wanted to write an Active Model Serializer for customizing an API that returns Employee data as json. We would have to write an '''EmployeeSerializer''' which is configured to use a '''JsonApiAdapter'''. The '''Serializer''' Component would specify which attributes and relationships of Employee to other models would be captured in the response data. For example, it might choose to return the Employee name, age and the data about the employee's family members which are different models. The '''Adapter''' component specifies how to format this selected Employee data in the correct format as required by the client. A JsonApiAdapter would format it as JSON and is the default adapter used by an Active Model Serializer. However you can always supply your own Adapter for the serializer to use.

Assume the Employee data API scenario cited above and Refer to the figure.
#The Controller receives the request for json data and routes it to a specific action method
#The action method has a respond_to method that returns Employee model as JSON. When Rails encounters this line, it looks for an EmployeeSerializer in the project specifically in a file employee_serializer to get the exact data to be put into the response.
#The EmployeeSerializer is by default configured to use a JsonApiAdapter and formats the specified attributes and relationships in the JSON format. This forms the final customized response.

As you can see, instead of returning the default JSON conversion of the Employee model from the respond_to method, that Rails does automatically for us, we were able to customize our API response data through the use of Active Model Serializers in a non-intrusive way maintaining separation from the controller and the model layers.

=Using Active Model Serializer=

Let us see some code now.

'''Step 1:''' Active Model Serializer is available as a gem. Add to the gem file the following line :
<pre>
gem 'active_model_serializers'
</pre>

'''Step 2:''' Run the following command at the terminal window to install the gem.

<pre>
bundle update
</pre>

'''Step 3:''' This gem provides a serializer generator for the selected Active Model. For example, if employee was your Active Model run :
rails g serializer employee

This would create a file employee_serializer.rb containing the following code in the newly created app/serializers directory of your project:
<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id

end
</pre>

'''Step 4:''' Add your custom attributes and any other customizations to this file. For example: We are adding a url attribute to get details of this employee although the Employee Active Model does not have any such attribute. We add it because the client might be interested in it. That is the power of Active Model Serializer. It does not require us to define another property on the Employee Active Model to return its Url.

<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id, :name, :age, :url

def url
employee_url(object)
end

end
</pre>

'''Step 5:''' That's it! Whenever an Employee is requested the custom EmployeeSerializer does the task of serializing the employee to json and will now include a url key value pair to view the Employee.

=References=
#[http://railscasts.com/episodes/409-active-model-serializers Railcast on Active Model Serializers]
#[https://github.com/rails-api/active_model_serializers Active Model Serializer module on github]
#[http://asciicasts.com/episodes/409-active-model-serializers Active Model Serializer Asciicast]
#[https://www.youtube.com/watch?v=G6ipU6AiEXY Active Model Serializer Video Tutorial]
#[http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/ Active Model]
#[http://en.wikipedia.org/wiki/Serialization Serialization wiki]
#[http://en.wikipedia.org/wiki/JSON JSON wiki]
#[http://en.wikipedia.org/wiki/RubyGems RubyGems wiki]

CSC/ECE 517 Fall 2014/ch1a 24 sa

2014-09-26T02:18:05Z

Shjoshi2:

=Active Model Serializers=

[http://en.wikipedia.org/wiki/Ruby_on_Rails Ruby on Rails] offers strong features to write API based server applications, which expose data through a well designed API and serve data in various formats as requested. One of these features is '''[http://github.com/rails-api/active_model_serializers Active Model Serializers]''' which helps the API designers to have fine control over the response generated by the API to a data request. '''Active Model Serializers''' help programmers do this very easily and cleanly without breaking separation of concerns in a rails application. They promote [http://en.wikipedia.org/wiki/Convention_over_configuration convention over configuration], thus reducing code bloat and increasing code scalibility and readability.
 

[[File:ClientServer.png‎|right|]]

__TOC__

=Background=

The modern web has seen more and more web applications that are written as web services or web APIs. These applications do not return a web page to the client browser, but return just the bare bones data to the client in the format requested. This gives the clients the liberty to develop customized User Interfaces for the same web application. A common example is the Rotten Tomatoes API which offers movie data in JSON, XML and various other formats. The clients request the Rotten Tomatoes web server for the data in the desired format, and the web server is able to respond with the correct data in the required format.

Active Model Serializers are a way for Web API designers who use Ruby on Rails to have full control over the formatting and the content of data that is returned to clients. For eg. An employee data model returned as JSON to a data request might look like this:

<pre>
{Employee: {
name: emp_name
age: 26
salary: 35000
weight: 90kg
height: 170
}
}
</pre>

But the API designer may want to improve this formatting and exclude certain fields so that the response is just the data without clubbing it under the "Employee" root token:

<pre>
{
EmpConciseDetails: emp_name 26
}
</pre>

In a Ruby On Rails application there could be a couple of ways to achieve this.

===Option 1===

The first one is shown below where we can specify the JSON formatting option in the action method which handles the data request. The below method fetches the desired Employee and returns its JSON representation to the client:

<pre>
def show
@emp = Employee.find(params[:id])

respond_to do |format|
format.json { render :json => @emp, root:false}
end
end
</pre>

Specifying '''root: false''' above will remove the unwanted Employee token from the resultant JSON. However this method is not recommended as we are littering our controller layer with data formatting code. If we want to maintain the MVC separation of concerns, formatting the response data does not belong in the controller layer.

===Option 2===

Another option is to override the '''as_json''' method of the Employee data model which is typically an Active Record in a Rails application:

<pre>

class Employee < ActiveRecord

def as_json(options)
super(:only => [:name, :age])
end

end
</pre>

The above '''as_json''' method is called whenever Rails has to convert the Employee object to its JSON format to send to the client. Our custom '''as_json''' method will help us return only the name and the age as desired. However we again have a problem as we are littering our Model layer with custom formatting tasks which it is not intended to handle.

Through '''Active model serializers''' we are able to place these custom formatting tasks to a separate class namely an EmployeeSerializer which inherits from ActiveModel::Serializer class. The Rails application is able to discover this serializer when Employee data model has to be serialized without any configuration from the programmer's side. The advantages of this scheme are dual. It helps keep separation of concerns in the Rails application, and its done with a convention over configuration approach. Specifics are discussed in following sections.

= Introduction =
Let us familiarize ourselves with a few terms before getting to the usage of '''Active Model Serializers'''.
;Active Model
:'''[http://railscasts.com/episodes/219-active-model Active Model]''' is closely related to the widely used concept of '''[http://en.wikibooks.org/wiki/Ruby_on_Rails/ActiveRecord Active Record]''' in the Rails world. '''Active Record''' is an object that maps directly to the data in our database. An '''Active Record''' takes care of fetching and saving data to the database. For example, in an employee records application an Employee Active Record helps to persist a newly created/edited Employee. So how is an '''Active Model''' different? It may not always be the case that we want our Employee model to be backed by a database. But we might want to have all the functionality that an Active Record provides (for example, validations on the Employee model to check if name is present on the Employee Active Record before persisting it or checking if the active record got dirtied because of an attribute change etc. ). An example of this is, as and when an Employee create form is submitted, we might want to just send an email to the admin with the new employee data once we validate that data. An '''Active Model''' does just this. Infact, the rails developers segregated all the non database functionality out of an '''Active Record''' into an '''Active Model'''.

;Serializer
:Serializer is a small program that takes an object residing in program memory (for example: could be a C# object in an ASP.NET application, or an ActiveModel object in a Rails application) and converts this information into format that is transferrable over the wire, for example, JSON and XML. This is required because the client may be written in Java and there is no way for it to read an Active Model Ruby Object that exists in memory on the server side.

;API Server Application
:API Server application is an application which serves data requests coming from a variety of clients (for example: mobile, desktop) in various formats such as JSON, XML. For example, An employee data web service which returns employee age and name in both JSON and XML

=Why Active Model Serializers?=

* '''Custom response attributes:''' It is not always the case that an API application serves a request by responding with data as it is stored on the server. The API designer has a task of exposing just the right data to the clients and hence needs fine control over exactly what part of the data on the server is returned in a response. An Active Model Serializer could help return just the Employee age and name to the client as JSON and ignore all the other attributes set on an Employee Model.
 
* '''Separation of Concerns:''' The response data could also be customized in the respond_to method of the rails controller action or for example, by implementing a custom as_json method on the model class. However this breaks the separation of concerns principle as we let something like formatting the response data venture into the controller and model layer. With Active Model Serializers we can keep this functionality segregated from the application.
 
*'''Maintainability:''' Client needs keep changing. Let's say a Client requests some changes to the API response data, only the Active Model Serializer would get affected and there are no side effects on the Controller or the Model itself.
 
=How Active Model Serializer Works?=
[[File:Active-Model-Serializer2.png‎|right]]

Active Model Serializers work with the help of two components namely '''Serializer''' and '''Adapter'''. Let's say we wanted to write an Active Model Serializer for customizing an API that returns Employee data as json. We would have to write an '''EmployeeSerializer''' which is configured to use a '''JsonApiAdapter'''. The '''Serializer''' Component would specify which attributes and relationships of Employee to other models would be captured in the response data. For example, it might choose to return the Employee name, age and the data about the employee's family members which are different models. The '''Adapter''' component specifies how to format this selected Employee data in the correct format as required by the client. A JsonApiAdapter would format it as JSON and is the default adapter used by an Active Model Serializer. However you can always supply your own Adapter for the serializer to use.

Assume the Employee data API scenario cited above and Refer to the figure.
#The Controller receives the request for json data and routes it to a specific action method
#The action method has a respond_to method that returns Employee model as JSON. When Rails encounters this line, it looks for an EmployeeSerializer in the project specifically in a file employee_serializer to get the exact data to be put into the response.
#The EmployeeSerializer is by default configured to use a JsonApiAdapter and formats the specified attributes and relationships in the JSON format. This forms the final customized response.

As you can see, instead of returning the default JSON conversion of the Employee model from the respond_to method, that Rails does automatically for us, we were able to customize our API response data through the use of Active Model Serializers in a non-intrusive way maintaining separation from the controller and the model layers.

=Using Active Model Serializer=

Let us see some code now.

'''Step 1:''' Active Model Serializer is available as a gem. Add to the gem file the following line :
<pre>
gem 'active_model_serializers'
</pre>

'''Step 2:''' Run the following command at the terminal window to install the gem.

<pre>
bundle update
</pre>

'''Step 3:''' This gem provides a serializer generator for the selected Active Model. For example, if employee was your Active Model run :
rails g serializer employee

This would create a file employee_serializer.rb containing the following code in the newly created app/serializers directory of your project:
<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id

end
</pre>

'''Step 4:''' Add your custom attributes and any other customizations to this file. For example: We are adding a url attribute to get details of this employee although the Employee Active Model does not have any such attribute. We add it because the client might be interested in it. That is the power of Active Model Serializer. It does not require us to define another property on the Employee Active Model to return its Url.

<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id, :name, :age, :url

def url
employee_url(object)
end

end
</pre>

'''Step 5:''' That's it! Whenever an Employee is requested the custom EmployeeSerializer does the task of serializing the employee to json and will now include a url key value pair to view the Employee.

=References=
#[http://railscasts.com/episodes/409-active-model-serializers Railcast on Active Model Serializers]
#[https://github.com/rails-api/active_model_serializers Active Model Serializer module on github]
#[http://asciicasts.com/episodes/409-active-model-serializers Active Model Serializer Asciicast]
#[https://www.youtube.com/watch?v=G6ipU6AiEXY Active Model Serializer Video Tutorial]
#[http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/ Active Model]
#[http://en.wikipedia.org/wiki/Serialization Serialization wiki]
#[http://en.wikipedia.org/wiki/JSON JSON wiki]
#[http://en.wikipedia.org/wiki/RubyGems RubyGems wiki]

CSC/ECE 517 Fall 2014/ch1a 24 sa

2014-09-26T02:17:45Z

Shjoshi2:

=Active Model Serializers=

[http://en.wikipedia.org/wiki/Ruby_on_Rails Ruby on Rails] offers strong features to write API based server applications, which expose data through a well designed API and serve data in various formats as requested. One of these features is '''[http://github.com/rails-api/active_model_serializers Active Model Serializers]''' which helps the API designers to have fine control over the response generated by the API to a data request. '''Active Model Serializers''' help programmers do this very easily and cleanly without breaking separation of concerns in a rails application. They promote [http://en.wikipedia.org/wiki/Convention_over_configuration convention over configuration], thus reducing code bloat and increasing code scalibility and readability.
 

[[File:ClientServer.png‎|right|]]

__TOC__

==Background==

The modern web has seen more and more web applications that are written as web services or web APIs. These applications do not return a web page to the client browser, but return just the bare bones data to the client in the format requested. This gives the clients the liberty to develop customized User Interfaces for the same web application. A common example is the Rotten Tomatoes API which offers movie data in JSON, XML and various other formats. The clients request the Rotten Tomatoes web server for the data in the desired format, and the web server is able to respond with the correct data in the required format.

Active Model Serializers are a way for Web API designers who use Ruby on Rails to have full control over the formatting and the content of data that is returned to clients. For eg. An employee data model returned as JSON to a data request might look like this:

<pre>
{Employee: {
name: emp_name
age: 26
salary: 35000
weight: 90kg
height: 170
}
}
</pre>

But the API designer may want to improve this formatting and exclude certain fields so that the response is just the data without clubbing it under the "Employee" root token:

<pre>
{
EmpConciseDetails: emp_name 26
}
</pre>

In a Ruby On Rails application there could be a couple of ways to achieve this.

===Option 1===

The first one is shown below where we can specify the JSON formatting option in the action method which handles the data request. The below method fetches the desired Employee and returns its JSON representation to the client:

<pre>
def show
@emp = Employee.find(params[:id])

respond_to do |format|
format.json { render :json => @emp, root:false}
end
end
</pre>

Specifying '''root: false''' above will remove the unwanted Employee token from the resultant JSON. However this method is not recommended as we are littering our controller layer with data formatting code. If we want to maintain the MVC separation of concerns, formatting the response data does not belong in the controller layer.

===Option 2===

Another option is to override the '''as_json''' method of the Employee data model which is typically an Active Record in a Rails application:

<pre>

class Employee < ActiveRecord

def as_json(options)
super(:only => [:name, :age])
end

end
</pre>

The above '''as_json''' method is called whenever Rails has to convert the Employee object to its JSON format to send to the client. Our custom '''as_json''' method will help us return only the name and the age as desired. However we again have a problem as we are littering our Model layer with custom formatting tasks which it is not intended to handle.

Through '''Active model serializers''' we are able to place these custom formatting tasks to a separate class namely an EmployeeSerializer which inherits from ActiveModel::Serializer class. The Rails application is able to discover this serializer when Employee data model has to be serialized without any configuration from the programmer's side. The advantages of this scheme are dual. It helps keep separation of concerns in the Rails application, and its done with a convention over configuration approach. Specifics are discussed in following sections.

= Introduction =
Let us familiarize ourselves with a few terms before getting to the usage of '''Active Model Serializers'''.
;Active Model
:'''[http://railscasts.com/episodes/219-active-model Active Model]''' is closely related to the widely used concept of '''[http://en.wikibooks.org/wiki/Ruby_on_Rails/ActiveRecord Active Record]''' in the Rails world. '''Active Record''' is an object that maps directly to the data in our database. An '''Active Record''' takes care of fetching and saving data to the database. For example, in an employee records application an Employee Active Record helps to persist a newly created/edited Employee. So how is an '''Active Model''' different? It may not always be the case that we want our Employee model to be backed by a database. But we might want to have all the functionality that an Active Record provides (for example, validations on the Employee model to check if name is present on the Employee Active Record before persisting it or checking if the active record got dirtied because of an attribute change etc. ). An example of this is, as and when an Employee create form is submitted, we might want to just send an email to the admin with the new employee data once we validate that data. An '''Active Model''' does just this. Infact, the rails developers segregated all the non database functionality out of an '''Active Record''' into an '''Active Model'''.

;Serializer
:Serializer is a small program that takes an object residing in program memory (for example: could be a C# object in an ASP.NET application, or an ActiveModel object in a Rails application) and converts this information into format that is transferrable over the wire, for example, JSON and XML. This is required because the client may be written in Java and there is no way for it to read an Active Model Ruby Object that exists in memory on the server side.

;API Server Application
:API Server application is an application which serves data requests coming from a variety of clients (for example: mobile, desktop) in various formats such as JSON, XML. For example, An employee data web service which returns employee age and name in both JSON and XML

=Why Active Model Serializers?=

* '''Custom response attributes:''' It is not always the case that an API application serves a request by responding with data as it is stored on the server. The API designer has a task of exposing just the right data to the clients and hence needs fine control over exactly what part of the data on the server is returned in a response. An Active Model Serializer could help return just the Employee age and name to the client as JSON and ignore all the other attributes set on an Employee Model.
 
* '''Separation of Concerns:''' The response data could also be customized in the respond_to method of the rails controller action or for example, by implementing a custom as_json method on the model class. However this breaks the separation of concerns principle as we let something like formatting the response data venture into the controller and model layer. With Active Model Serializers we can keep this functionality segregated from the application.
 
*'''Maintainability:''' Client needs keep changing. Let's say a Client requests some changes to the API response data, only the Active Model Serializer would get affected and there are no side effects on the Controller or the Model itself.
 
=How Active Model Serializer Works?=
[[File:Active-Model-Serializer2.png‎|right]]

Active Model Serializers work with the help of two components namely '''Serializer''' and '''Adapter'''. Let's say we wanted to write an Active Model Serializer for customizing an API that returns Employee data as json. We would have to write an '''EmployeeSerializer''' which is configured to use a '''JsonApiAdapter'''. The '''Serializer''' Component would specify which attributes and relationships of Employee to other models would be captured in the response data. For example, it might choose to return the Employee name, age and the data about the employee's family members which are different models. The '''Adapter''' component specifies how to format this selected Employee data in the correct format as required by the client. A JsonApiAdapter would format it as JSON and is the default adapter used by an Active Model Serializer. However you can always supply your own Adapter for the serializer to use.

Assume the Employee data API scenario cited above and Refer to the figure.
#The Controller receives the request for json data and routes it to a specific action method
#The action method has a respond_to method that returns Employee model as JSON. When Rails encounters this line, it looks for an EmployeeSerializer in the project specifically in a file employee_serializer to get the exact data to be put into the response.
#The EmployeeSerializer is by default configured to use a JsonApiAdapter and formats the specified attributes and relationships in the JSON format. This forms the final customized response.

As you can see, instead of returning the default JSON conversion of the Employee model from the respond_to method, that Rails does automatically for us, we were able to customize our API response data through the use of Active Model Serializers in a non-intrusive way maintaining separation from the controller and the model layers.

=Using Active Model Serializer=

Let us see some code now.

'''Step 1:''' Active Model Serializer is available as a gem. Add to the gem file the following line :
<pre>
gem 'active_model_serializers'
</pre>

'''Step 2:''' Run the following command at the terminal window to install the gem.

<pre>
bundle update
</pre>

'''Step 3:''' This gem provides a serializer generator for the selected Active Model. For example, if employee was your Active Model run :
rails g serializer employee

This would create a file employee_serializer.rb containing the following code in the newly created app/serializers directory of your project:
<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id

end
</pre>

'''Step 4:''' Add your custom attributes and any other customizations to this file. For example: We are adding a url attribute to get details of this employee although the Employee Active Model does not have any such attribute. We add it because the client might be interested in it. That is the power of Active Model Serializer. It does not require us to define another property on the Employee Active Model to return its Url.

<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id, :name, :age, :url

def url
employee_url(object)
end

end
</pre>

'''Step 5:''' That's it! Whenever an Employee is requested the custom EmployeeSerializer does the task of serializing the employee to json and will now include a url key value pair to view the Employee.

=References=
#[http://railscasts.com/episodes/409-active-model-serializers Railcast on Active Model Serializers]
#[https://github.com/rails-api/active_model_serializers Active Model Serializer module on github]
#[http://asciicasts.com/episodes/409-active-model-serializers Active Model Serializer Asciicast]
#[https://www.youtube.com/watch?v=G6ipU6AiEXY Active Model Serializer Video Tutorial]
#[http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/ Active Model]
#[http://en.wikipedia.org/wiki/Serialization Serialization wiki]
#[http://en.wikipedia.org/wiki/JSON JSON wiki]
#[http://en.wikipedia.org/wiki/RubyGems RubyGems wiki]

CSC/ECE 517 Fall 2014/ch1a 24 sa

2014-09-26T02:17:07Z

Shjoshi2: /* Option 2 */

=Active Model Serializers=

[http://en.wikipedia.org/wiki/Ruby_on_Rails Ruby on Rails] offers strong features to write API based server applications, which expose data through a well designed API and serve data in various formats as requested. One of these features is '''[http://github.com/rails-api/active_model_serializers Active Model Serializers]''' which helps the API designers to have fine control over the response generated by the API to a data request. '''Active Model Serializers''' help programmers do this very easily and cleanly without breaking separation of concerns in a rails application. They promote [http://en.wikipedia.org/wiki/Convention_over_configuration convention over configuration], thus reducing code bloat and increasing code scalibility and readability.
 

[[File:ClientServer.png‎|right|]]

==Background==

The modern web has seen more and more web applications that are written as web services or web APIs. These applications do not return a web page to the client browser, but return just the bare bones data to the client in the format requested. This gives the clients the liberty to develop customized User Interfaces for the same web application. A common example is the Rotten Tomatoes API which offers movie data in JSON, XML and various other formats. The clients request the Rotten Tomatoes web server for the data in the desired format, and the web server is able to respond with the correct data in the required format.

Active Model Serializers are a way for Web API designers who use Ruby on Rails to have full control over the formatting and the content of data that is returned to clients. For eg. An employee data model returned as JSON to a data request might look like this:

<pre>
{Employee: {
name: emp_name
age: 26
salary: 35000
weight: 90kg
height: 170
}
}
</pre>

But the API designer may want to improve this formatting and exclude certain fields so that the response is just the data without clubbing it under the "Employee" root token:

<pre>
{
EmpConciseDetails: emp_name 26
}
</pre>

In a Ruby On Rails application there could be a couple of ways to achieve this.

===Option 1===

The first one is shown below where we can specify the JSON formatting option in the action method which handles the data request. The below method fetches the desired Employee and returns its JSON representation to the client:

<pre>
def show
@emp = Employee.find(params[:id])

respond_to do |format|
format.json { render :json => @emp, root:false}
end
end
</pre>

Specifying '''root: false''' above will remove the unwanted Employee token from the resultant JSON. However this method is not recommended as we are littering our controller layer with data formatting code. If we want to maintain the MVC separation of concerns, formatting the response data does not belong in the controller layer.

===Option 2===

Another option is to override the '''as_json''' method of the Employee data model which is typically an Active Record in a Rails application:

<pre>

class Employee < ActiveRecord

def as_json(options)
super(:only => [:name, :age])
end

end
</pre>

The above '''as_json''' method is called whenever Rails has to convert the Employee object to its JSON format to send to the client. Our custom '''as_json''' method will help us return only the name and the age as desired. However we again have a problem as we are littering our Model layer with custom formatting tasks which it is not intended to handle.

Through '''Active model serializers''' we are able to place these custom formatting tasks to a separate class namely an EmployeeSerializer which inherits from ActiveModel::Serializer class. The Rails application is able to discover this serializer when Employee data model has to be serialized without any configuration from the programmer's side. The advantages of this scheme are dual. It helps keep separation of concerns in the Rails application, and its done with a convention over configuration approach. Specifics are discussed in following sections.

__TOC__

= Introduction =
Let us familiarize ourselves with a few terms before getting to the usage of '''Active Model Serializers'''.
;Active Model
:'''[http://railscasts.com/episodes/219-active-model Active Model]''' is closely related to the widely used concept of '''[http://en.wikibooks.org/wiki/Ruby_on_Rails/ActiveRecord Active Record]''' in the Rails world. '''Active Record''' is an object that maps directly to the data in our database. An '''Active Record''' takes care of fetching and saving data to the database. For example, in an employee records application an Employee Active Record helps to persist a newly created/edited Employee. So how is an '''Active Model''' different? It may not always be the case that we want our Employee model to be backed by a database. But we might want to have all the functionality that an Active Record provides (for example, validations on the Employee model to check if name is present on the Employee Active Record before persisting it or checking if the active record got dirtied because of an attribute change etc. ). An example of this is, as and when an Employee create form is submitted, we might want to just send an email to the admin with the new employee data once we validate that data. An '''Active Model''' does just this. Infact, the rails developers segregated all the non database functionality out of an '''Active Record''' into an '''Active Model'''.

;Serializer
:Serializer is a small program that takes an object residing in program memory (for example: could be a C# object in an ASP.NET application, or an ActiveModel object in a Rails application) and converts this information into format that is transferrable over the wire, for example, JSON and XML. This is required because the client may be written in Java and there is no way for it to read an Active Model Ruby Object that exists in memory on the server side.

;API Server Application
:API Server application is an application which serves data requests coming from a variety of clients (for example: mobile, desktop) in various formats such as JSON, XML. For example, An employee data web service which returns employee age and name in both JSON and XML

=Why Active Model Serializers?=

* '''Custom response attributes:''' It is not always the case that an API application serves a request by responding with data as it is stored on the server. The API designer has a task of exposing just the right data to the clients and hence needs fine control over exactly what part of the data on the server is returned in a response. An Active Model Serializer could help return just the Employee age and name to the client as JSON and ignore all the other attributes set on an Employee Model.
 
* '''Separation of Concerns:''' The response data could also be customized in the respond_to method of the rails controller action or for example, by implementing a custom as_json method on the model class. However this breaks the separation of concerns principle as we let something like formatting the response data venture into the controller and model layer. With Active Model Serializers we can keep this functionality segregated from the application.
 
*'''Maintainability:''' Client needs keep changing. Let's say a Client requests some changes to the API response data, only the Active Model Serializer would get affected and there are no side effects on the Controller or the Model itself.
 
=How Active Model Serializer Works?=
[[File:Active-Model-Serializer2.png‎|right]]

Active Model Serializers work with the help of two components namely '''Serializer''' and '''Adapter'''. Let's say we wanted to write an Active Model Serializer for customizing an API that returns Employee data as json. We would have to write an '''EmployeeSerializer''' which is configured to use a '''JsonApiAdapter'''. The '''Serializer''' Component would specify which attributes and relationships of Employee to other models would be captured in the response data. For example, it might choose to return the Employee name, age and the data about the employee's family members which are different models. The '''Adapter''' component specifies how to format this selected Employee data in the correct format as required by the client. A JsonApiAdapter would format it as JSON and is the default adapter used by an Active Model Serializer. However you can always supply your own Adapter for the serializer to use.

Assume the Employee data API scenario cited above and Refer to the figure.
#The Controller receives the request for json data and routes it to a specific action method
#The action method has a respond_to method that returns Employee model as JSON. When Rails encounters this line, it looks for an EmployeeSerializer in the project specifically in a file employee_serializer to get the exact data to be put into the response.
#The EmployeeSerializer is by default configured to use a JsonApiAdapter and formats the specified attributes and relationships in the JSON format. This forms the final customized response.

As you can see, instead of returning the default JSON conversion of the Employee model from the respond_to method, that Rails does automatically for us, we were able to customize our API response data through the use of Active Model Serializers in a non-intrusive way maintaining separation from the controller and the model layers.

=Using Active Model Serializer=

Let us see some code now.

'''Step 1:''' Active Model Serializer is available as a gem. Add to the gem file the following line :
<pre>
gem 'active_model_serializers'
</pre>

'''Step 2:''' Run the following command at the terminal window to install the gem.

<pre>
bundle update
</pre>

'''Step 3:''' This gem provides a serializer generator for the selected Active Model. For example, if employee was your Active Model run :
rails g serializer employee

This would create a file employee_serializer.rb containing the following code in the newly created app/serializers directory of your project:
<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id

end
</pre>

'''Step 4:''' Add your custom attributes and any other customizations to this file. For example: We are adding a url attribute to get details of this employee although the Employee Active Model does not have any such attribute. We add it because the client might be interested in it. That is the power of Active Model Serializer. It does not require us to define another property on the Employee Active Model to return its Url.

<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id, :name, :age, :url

def url
employee_url(object)
end

end
</pre>

'''Step 5:''' That's it! Whenever an Employee is requested the custom EmployeeSerializer does the task of serializing the employee to json and will now include a url key value pair to view the Employee.

=References=
#[http://railscasts.com/episodes/409-active-model-serializers Railcast on Active Model Serializers]
#[https://github.com/rails-api/active_model_serializers Active Model Serializer module on github]
#[http://asciicasts.com/episodes/409-active-model-serializers Active Model Serializer Asciicast]
#[https://www.youtube.com/watch?v=G6ipU6AiEXY Active Model Serializer Video Tutorial]
#[http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/ Active Model]
#[http://en.wikipedia.org/wiki/Serialization Serialization wiki]
#[http://en.wikipedia.org/wiki/JSON JSON wiki]
#[http://en.wikipedia.org/wiki/RubyGems RubyGems wiki]

CSC/ECE 517 Fall 2014/ch1a 24 sa

2014-09-26T02:15:42Z

Shjoshi2: /* Background */

=Active Model Serializers=

[http://en.wikipedia.org/wiki/Ruby_on_Rails Ruby on Rails] offers strong features to write API based server applications, which expose data through a well designed API and serve data in various formats as requested. One of these features is '''[http://github.com/rails-api/active_model_serializers Active Model Serializers]''' which helps the API designers to have fine control over the response generated by the API to a data request. '''Active Model Serializers''' help programmers do this very easily and cleanly without breaking separation of concerns in a rails application. They promote [http://en.wikipedia.org/wiki/Convention_over_configuration convention over configuration], thus reducing code bloat and increasing code scalibility and readability.
 

[[File:ClientServer.png‎|right|]]

==Background==

The modern web has seen more and more web applications that are written as web services or web APIs. These applications do not return a web page to the client browser, but return just the bare bones data to the client in the format requested. This gives the clients the liberty to develop customized User Interfaces for the same web application. A common example is the Rotten Tomatoes API which offers movie data in JSON, XML and various other formats. The clients request the Rotten Tomatoes web server for the data in the desired format, and the web server is able to respond with the correct data in the required format.

Active Model Serializers are a way for Web API designers who use Ruby on Rails to have full control over the formatting and the content of data that is returned to clients. For eg. An employee data model returned as JSON to a data request might look like this:

<pre>
{Employee: {
name: emp_name
age: 26
salary: 35000
weight: 90kg
height: 170
}
}
</pre>

But the API designer may want to improve this formatting and exclude certain fields so that the response is just the data without clubbing it under the "Employee" root token:

<pre>
{
EmpConciseDetails: emp_name 26
}
</pre>

In a Ruby On Rails application there could be a couple of ways to achieve this.

===Option 1===

The first one is shown below where we can specify the JSON formatting option in the action method which handles the data request. The below method fetches the desired Employee and returns its JSON representation to the client:

<pre>
def show
@emp = Employee.find(params[:id])

respond_to do |format|
format.json { render :json => @emp, root:false}
end
end
</pre>

Specifying '''root: false''' above will remove the unwanted Employee token from the resultant JSON. However this method is not recommended as we are littering our controller layer with data formatting code. If we want to maintain the MVC separation of concerns, formatting the response data does not belong in the controller layer.

===Option 2===

Another option is to override the as_json method of the Employee data model which is typically an Active Record in a Rails application:

<pre>

class Employee < ActiveRecord

def as_json(options)
super(:only => [:name, :age])
end

end
</pre>

The above '''as_json''' method is called whenever Rails has to convert the Employee object to its JSON format to send to the client. Our custom '''as_json''' method will help us return only the name and the age as desired. However we again have a problem as we are littering our Model layer with custom formatting tasks which it is not intended to handle.

Through '''Active model serializers''' we are able to place these custom formatting tasks to a separate class namely an EmployeeSerializer which inherits from ActiveModel::Serializer class. The Rails application is able to discover this serializer when Employee data model has to be serialized without any configuration from the programmer's side. The advantages of this scheme are dual. It helps keep separation of concerns in the Rails application, and its done with a convention over configuration approach. Specifics are discussed in following sections.

__TOC__

= Introduction =
Let us familiarize ourselves with a few terms before getting to the usage of '''Active Model Serializers'''.
;Active Model
:'''[http://railscasts.com/episodes/219-active-model Active Model]''' is closely related to the widely used concept of '''[http://en.wikibooks.org/wiki/Ruby_on_Rails/ActiveRecord Active Record]''' in the Rails world. '''Active Record''' is an object that maps directly to the data in our database. An '''Active Record''' takes care of fetching and saving data to the database. For example, in an employee records application an Employee Active Record helps to persist a newly created/edited Employee. So how is an '''Active Model''' different? It may not always be the case that we want our Employee model to be backed by a database. But we might want to have all the functionality that an Active Record provides (for example, validations on the Employee model to check if name is present on the Employee Active Record before persisting it or checking if the active record got dirtied because of an attribute change etc. ). An example of this is, as and when an Employee create form is submitted, we might want to just send an email to the admin with the new employee data once we validate that data. An '''Active Model''' does just this. Infact, the rails developers segregated all the non database functionality out of an '''Active Record''' into an '''Active Model'''.

;Serializer
:Serializer is a small program that takes an object residing in program memory (for example: could be a C# object in an ASP.NET application, or an ActiveModel object in a Rails application) and converts this information into format that is transferrable over the wire, for example, JSON and XML. This is required because the client may be written in Java and there is no way for it to read an Active Model Ruby Object that exists in memory on the server side.

;API Server Application
:API Server application is an application which serves data requests coming from a variety of clients (for example: mobile, desktop) in various formats such as JSON, XML. For example, An employee data web service which returns employee age and name in both JSON and XML

=Why Active Model Serializers?=

* '''Custom response attributes:''' It is not always the case that an API application serves a request by responding with data as it is stored on the server. The API designer has a task of exposing just the right data to the clients and hence needs fine control over exactly what part of the data on the server is returned in a response. An Active Model Serializer could help return just the Employee age and name to the client as JSON and ignore all the other attributes set on an Employee Model.
 
* '''Separation of Concerns:''' The response data could also be customized in the respond_to method of the rails controller action or for example, by implementing a custom as_json method on the model class. However this breaks the separation of concerns principle as we let something like formatting the response data venture into the controller and model layer. With Active Model Serializers we can keep this functionality segregated from the application.
 
*'''Maintainability:''' Client needs keep changing. Let's say a Client requests some changes to the API response data, only the Active Model Serializer would get affected and there are no side effects on the Controller or the Model itself.
 
=How Active Model Serializer Works?=
[[File:Active-Model-Serializer2.png‎|right]]

Active Model Serializers work with the help of two components namely '''Serializer''' and '''Adapter'''. Let's say we wanted to write an Active Model Serializer for customizing an API that returns Employee data as json. We would have to write an '''EmployeeSerializer''' which is configured to use a '''JsonApiAdapter'''. The '''Serializer''' Component would specify which attributes and relationships of Employee to other models would be captured in the response data. For example, it might choose to return the Employee name, age and the data about the employee's family members which are different models. The '''Adapter''' component specifies how to format this selected Employee data in the correct format as required by the client. A JsonApiAdapter would format it as JSON and is the default adapter used by an Active Model Serializer. However you can always supply your own Adapter for the serializer to use.

Assume the Employee data API scenario cited above and Refer to the figure.
#The Controller receives the request for json data and routes it to a specific action method
#The action method has a respond_to method that returns Employee model as JSON. When Rails encounters this line, it looks for an EmployeeSerializer in the project specifically in a file employee_serializer to get the exact data to be put into the response.
#The EmployeeSerializer is by default configured to use a JsonApiAdapter and formats the specified attributes and relationships in the JSON format. This forms the final customized response.

As you can see, instead of returning the default JSON conversion of the Employee model from the respond_to method, that Rails does automatically for us, we were able to customize our API response data through the use of Active Model Serializers in a non-intrusive way maintaining separation from the controller and the model layers.

=Using Active Model Serializer=

Let us see some code now.

'''Step 1:''' Active Model Serializer is available as a gem. Add to the gem file the following line :
<pre>
gem 'active_model_serializers'
</pre>

'''Step 2:''' Run the following command at the terminal window to install the gem.

<pre>
bundle update
</pre>

'''Step 3:''' This gem provides a serializer generator for the selected Active Model. For example, if employee was your Active Model run :
rails g serializer employee

This would create a file employee_serializer.rb containing the following code in the newly created app/serializers directory of your project:
<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id

end
</pre>

'''Step 4:''' Add your custom attributes and any other customizations to this file. For example: We are adding a url attribute to get details of this employee although the Employee Active Model does not have any such attribute. We add it because the client might be interested in it. That is the power of Active Model Serializer. It does not require us to define another property on the Employee Active Model to return its Url.

<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id, :name, :age, :url

def url
employee_url(object)
end

end
</pre>

'''Step 5:''' That's it! Whenever an Employee is requested the custom EmployeeSerializer does the task of serializing the employee to json and will now include a url key value pair to view the Employee.

=References=
#[http://railscasts.com/episodes/409-active-model-serializers Railcast on Active Model Serializers]
#[https://github.com/rails-api/active_model_serializers Active Model Serializer module on github]
#[http://asciicasts.com/episodes/409-active-model-serializers Active Model Serializer Asciicast]
#[https://www.youtube.com/watch?v=G6ipU6AiEXY Active Model Serializer Video Tutorial]
#[http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/ Active Model]
#[http://en.wikipedia.org/wiki/Serialization Serialization wiki]
#[http://en.wikipedia.org/wiki/JSON JSON wiki]
#[http://en.wikipedia.org/wiki/RubyGems RubyGems wiki]

CSC/ECE 517 Fall 2014/ch1a 24 sa

2014-09-26T02:11:08Z

Shjoshi2: /* Active Model Serializers */

=Active Model Serializers=

[http://en.wikipedia.org/wiki/Ruby_on_Rails Ruby on Rails] offers strong features to write API based server applications, which expose data through a well designed API and serve data in various formats as requested. One of these features is '''[http://github.com/rails-api/active_model_serializers Active Model Serializers]''' which helps the API designers to have fine control over the response generated by the API to a data request. '''Active Model Serializers''' help programmers do this very easily and cleanly without breaking separation of concerns in a rails application. They promote [http://en.wikipedia.org/wiki/Convention_over_configuration convention over configuration], thus reducing code bloat and increasing code scalibility and readability.
 

[[File:ClientServer.png‎|right|]]

==Background==

The modern web has seen more and more web applications that are written as web services or web APIs. These applications do not return a web page to the client browser, but return just the bare bones data to the client in the format requested. This gives the clients the liberty to develop customized User Interfaces for the same web application. A common example is the Rotten Tomatoes API which offers movie data in JSON, XML and various other formats. The clients request the Rotten Tomatoes web server for the data in the desired format, and the web server is able to respond with the correct data in the required format.

Active Model Serializers are a way for Web API designers who use Ruby on Rails to have full control over the formatting and the content of data that is returned to clients. For eg. An employee data model returned as JSON to a data request might look like this:

<pre>
{Employee: {
name: emp_name
age: 26
salary: 35000
weight: 90kg
height: 170
}
}
</pre>

But the API designer may want to improve this formatting and exclude certain fields so that the response is just the data without clubbing it under the "Employee" root token:

<pre>
{
EmpConciseDetails: emp_name 26
}
</pre>

In a Ruby On Rails application there could be a couple of ways to achieve this. The first one is shown below where we can specify the JSON formatting option in the action method which handles the data request:

<pre>
def show
@emp = Employee.find(params[:id])

respond_to do |format|
format.json { render :json => @emp, root:false}
end
end
</pre>

Specifying root: false above will remove the unwanted Employee token from the resultant JSON. However this method is not recommended as we are littering our controller layer with data formatting code. If we want to maintain the MVC separation of concerns, formatting the response data does not belong in the controller layer.

Another option is to override the as_json method of the Employee data model which is typically an Active Record in a Rails application:

<pre>

class Employee < ActiveRecord

def as_json(options)
super(:only => [:name, :age])
end

end
</pre>

The above as_json method is called whenever Rails has to convert the Employee object to its JSON format to send to the client. Our custom as_json method will help us return only the name and the age as desired. However we again have a problem as we are littering our Model layer with custom formatting tasks which it is not intended to handle.

Through Active model serializers we are able to place these custom formatting tasks to a separate class namely an EmployeeSerializer which inherits from ActiveModel::Serializer class. The Rails application is able to discover this serializer when Employee data model has to be serialized without any configuration from the programmer's side. The effect of this scheme is dual. It helps keep separation of concerns in the Rails application, and its done with a convention over configuration approach which is described in later sections.

__TOC__

= Introduction =
Let us familiarize ourselves with a few terms before getting to the usage of '''Active Model Serializers'''.
;Active Model
:'''[http://railscasts.com/episodes/219-active-model Active Model]''' is closely related to the widely used concept of '''[http://en.wikibooks.org/wiki/Ruby_on_Rails/ActiveRecord Active Record]''' in the Rails world. '''Active Record''' is an object that maps directly to the data in our database. An '''Active Record''' takes care of fetching and saving data to the database. For example, in an employee records application an Employee Active Record helps to persist a newly created/edited Employee. So how is an '''Active Model''' different? It may not always be the case that we want our Employee model to be backed by a database. But we might want to have all the functionality that an Active Record provides (for example, validations on the Employee model to check if name is present on the Employee Active Record before persisting it or checking if the active record got dirtied because of an attribute change etc. ). An example of this is, as and when an Employee create form is submitted, we might want to just send an email to the admin with the new employee data once we validate that data. An '''Active Model''' does just this. Infact, the rails developers segregated all the non database functionality out of an '''Active Record''' into an '''Active Model'''.

;Serializer
:Serializer is a small program that takes an object residing in program memory (for example: could be a C# object in an ASP.NET application, or an ActiveModel object in a Rails application) and converts this information into format that is transferrable over the wire, for example, JSON and XML. This is required because the client may be written in Java and there is no way for it to read an Active Model Ruby Object that exists in memory on the server side.

;API Server Application
:API Server application is an application which serves data requests coming from a variety of clients (for example: mobile, desktop) in various formats such as JSON, XML. For example, An employee data web service which returns employee age and name in both JSON and XML

=Why Active Model Serializers?=

* '''Custom response attributes:''' It is not always the case that an API application serves a request by responding with data as it is stored on the server. The API designer has a task of exposing just the right data to the clients and hence needs fine control over exactly what part of the data on the server is returned in a response. An Active Model Serializer could help return just the Employee age and name to the client as JSON and ignore all the other attributes set on an Employee Model.
 
* '''Separation of Concerns:''' The response data could also be customized in the respond_to method of the rails controller action or for example, by implementing a custom as_json method on the model class. However this breaks the separation of concerns principle as we let something like formatting the response data venture into the controller and model layer. With Active Model Serializers we can keep this functionality segregated from the application.
 
*'''Maintainability:''' Client needs keep changing. Let's say a Client requests some changes to the API response data, only the Active Model Serializer would get affected and there are no side effects on the Controller or the Model itself.
 
=How Active Model Serializer Works?=
[[File:Active-Model-Serializer2.png‎|right]]

Active Model Serializers work with the help of two components namely '''Serializer''' and '''Adapter'''. Let's say we wanted to write an Active Model Serializer for customizing an API that returns Employee data as json. We would have to write an '''EmployeeSerializer''' which is configured to use a '''JsonApiAdapter'''. The '''Serializer''' Component would specify which attributes and relationships of Employee to other models would be captured in the response data. For example, it might choose to return the Employee name, age and the data about the employee's family members which are different models. The '''Adapter''' component specifies how to format this selected Employee data in the correct format as required by the client. A JsonApiAdapter would format it as JSON and is the default adapter used by an Active Model Serializer. However you can always supply your own Adapter for the serializer to use.

Assume the Employee data API scenario cited above and Refer to the figure.
#The Controller receives the request for json data and routes it to a specific action method
#The action method has a respond_to method that returns Employee model as JSON. When Rails encounters this line, it looks for an EmployeeSerializer in the project specifically in a file employee_serializer to get the exact data to be put into the response.
#The EmployeeSerializer is by default configured to use a JsonApiAdapter and formats the specified attributes and relationships in the JSON format. This forms the final customized response.

As you can see, instead of returning the default JSON conversion of the Employee model from the respond_to method, that Rails does automatically for us, we were able to customize our API response data through the use of Active Model Serializers in a non-intrusive way maintaining separation from the controller and the model layers.

=Using Active Model Serializer=

Let us see some code now.

'''Step 1:''' Active Model Serializer is available as a gem. Add to the gem file the following line :
<pre>
gem 'active_model_serializers'
</pre>

'''Step 2:''' Run the following command at the terminal window to install the gem.

<pre>
bundle update
</pre>

'''Step 3:''' This gem provides a serializer generator for the selected Active Model. For example, if employee was your Active Model run :
rails g serializer employee

This would create a file employee_serializer.rb containing the following code in the newly created app/serializers directory of your project:
<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id

end
</pre>

'''Step 4:''' Add your custom attributes and any other customizations to this file. For example: We are adding a url attribute to get details of this employee although the Employee Active Model does not have any such attribute. We add it because the client might be interested in it. That is the power of Active Model Serializer. It does not require us to define another property on the Employee Active Model to return its Url.

<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id, :name, :age, :url

def url
employee_url(object)
end

end
</pre>

'''Step 5:''' That's it! Whenever an Employee is requested the custom EmployeeSerializer does the task of serializing the employee to json and will now include a url key value pair to view the Employee.

=References=
#[http://railscasts.com/episodes/409-active-model-serializers Railcast on Active Model Serializers]
#[https://github.com/rails-api/active_model_serializers Active Model Serializer module on github]
#[http://asciicasts.com/episodes/409-active-model-serializers Active Model Serializer Asciicast]
#[https://www.youtube.com/watch?v=G6ipU6AiEXY Active Model Serializer Video Tutorial]
#[http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/ Active Model]
#[http://en.wikipedia.org/wiki/Serialization Serialization wiki]
#[http://en.wikipedia.org/wiki/JSON JSON wiki]
#[http://en.wikipedia.org/wiki/RubyGems RubyGems wiki]

CSC/ECE 517 Fall 2014/ch1a 24 sa

2014-09-26T02:10:15Z

Shjoshi2:

=Active Model Serializers=

[http://en.wikipedia.org/wiki/Ruby_on_Rails Ruby on Rails] offers strong features to write API based server applications, which expose data through a well designed API and serve data in various formats as requested. One of these features is '''[http://github.com/rails-api/active_model_serializers Active Model Serializers]''' which help the API designer to have fine control over the response generated by the API to a data request. '''Active Model Serializers''' help programmers do this very easily and cleanly without breaking separation of concerns in a rails application. They promote [http://en.wikipedia.org/wiki/Convention_over_configuration convention over configuration], thus reducing code bloat and increasing code scalibility and readability.
 

[[File:ClientServer.png‎|right|]]

==Background==

The modern web has seen more and more web applications that are written as web services or web APIs. These applications do not return a web page to the client browser, but return just the bare bones data to the client in the format requested. This gives the clients the liberty to develop customized User Interfaces for the same web application. A common example is the Rotten Tomatoes API which offers movie data in JSON, XML and various other formats. The clients request the Rotten Tomatoes web server for the data in the desired format, and the web server is able to respond with the correct data in the required format.

Active Model Serializers are a way for Web API designers who use Ruby on Rails to have full control over the formatting and the content of data that is returned to clients. For eg. An employee data model returned as JSON to a data request might look like this:

<pre>
{Employee: {
name: emp_name
age: 26
salary: 35000
weight: 90kg
height: 170
}
}
</pre>

But the API designer may want to improve this formatting and exclude certain fields so that the response is just the data without clubbing it under the "Employee" root token:

<pre>
{
EmpConciseDetails: emp_name 26
}
</pre>

In a Ruby On Rails application there could be a couple of ways to achieve this. The first one is shown below where we can specify the JSON formatting option in the action method which handles the data request:

<pre>
def show
@emp = Employee.find(params[:id])

respond_to do |format|
format.json { render :json => @emp, root:false}
end
end
</pre>

Specifying root: false above will remove the unwanted Employee token from the resultant JSON. However this method is not recommended as we are littering our controller layer with data formatting code. If we want to maintain the MVC separation of concerns, formatting the response data does not belong in the controller layer.

Another option is to override the as_json method of the Employee data model which is typically an Active Record in a Rails application:

<pre>

class Employee < ActiveRecord

def as_json(options)
super(:only => [:name, :age])
end

end
</pre>

The above as_json method is called whenever Rails has to convert the Employee object to its JSON format to send to the client. Our custom as_json method will help us return only the name and the age as desired. However we again have a problem as we are littering our Model layer with custom formatting tasks which it is not intended to handle.

Through Active model serializers we are able to place these custom formatting tasks to a separate class namely an EmployeeSerializer which inherits from ActiveModel::Serializer class. The Rails application is able to discover this serializer when Employee data model has to be serialized without any configuration from the programmer's side. The effect of this scheme is dual. It helps keep separation of concerns in the Rails application, and its done with a convention over configuration approach which is described in later sections.

__TOC__

= Introduction =
Let us familiarize ourselves with a few terms before getting to the usage of '''Active Model Serializers'''.
;Active Model
:'''[http://railscasts.com/episodes/219-active-model Active Model]''' is closely related to the widely used concept of '''[http://en.wikibooks.org/wiki/Ruby_on_Rails/ActiveRecord Active Record]''' in the Rails world. '''Active Record''' is an object that maps directly to the data in our database. An '''Active Record''' takes care of fetching and saving data to the database. For example, in an employee records application an Employee Active Record helps to persist a newly created/edited Employee. So how is an '''Active Model''' different? It may not always be the case that we want our Employee model to be backed by a database. But we might want to have all the functionality that an Active Record provides (for example, validations on the Employee model to check if name is present on the Employee Active Record before persisting it or checking if the active record got dirtied because of an attribute change etc. ). An example of this is, as and when an Employee create form is submitted, we might want to just send an email to the admin with the new employee data once we validate that data. An '''Active Model''' does just this. Infact, the rails developers segregated all the non database functionality out of an '''Active Record''' into an '''Active Model'''.

;Serializer
:Serializer is a small program that takes an object residing in program memory (for example: could be a C# object in an ASP.NET application, or an ActiveModel object in a Rails application) and converts this information into format that is transferrable over the wire, for example, JSON and XML. This is required because the client may be written in Java and there is no way for it to read an Active Model Ruby Object that exists in memory on the server side.

;API Server Application
:API Server application is an application which serves data requests coming from a variety of clients (for example: mobile, desktop) in various formats such as JSON, XML. For example, An employee data web service which returns employee age and name in both JSON and XML

=Why Active Model Serializers?=

* '''Custom response attributes:''' It is not always the case that an API application serves a request by responding with data as it is stored on the server. The API designer has a task of exposing just the right data to the clients and hence needs fine control over exactly what part of the data on the server is returned in a response. An Active Model Serializer could help return just the Employee age and name to the client as JSON and ignore all the other attributes set on an Employee Model.
 
* '''Separation of Concerns:''' The response data could also be customized in the respond_to method of the rails controller action or for example, by implementing a custom as_json method on the model class. However this breaks the separation of concerns principle as we let something like formatting the response data venture into the controller and model layer. With Active Model Serializers we can keep this functionality segregated from the application.
 
*'''Maintainability:''' Client needs keep changing. Let's say a Client requests some changes to the API response data, only the Active Model Serializer would get affected and there are no side effects on the Controller or the Model itself.
 
=How Active Model Serializer Works?=
[[File:Active-Model-Serializer2.png‎|right]]

Active Model Serializers work with the help of two components namely '''Serializer''' and '''Adapter'''. Let's say we wanted to write an Active Model Serializer for customizing an API that returns Employee data as json. We would have to write an '''EmployeeSerializer''' which is configured to use a '''JsonApiAdapter'''. The '''Serializer''' Component would specify which attributes and relationships of Employee to other models would be captured in the response data. For example, it might choose to return the Employee name, age and the data about the employee's family members which are different models. The '''Adapter''' component specifies how to format this selected Employee data in the correct format as required by the client. A JsonApiAdapter would format it as JSON and is the default adapter used by an Active Model Serializer. However you can always supply your own Adapter for the serializer to use.

Assume the Employee data API scenario cited above and Refer to the figure.
#The Controller receives the request for json data and routes it to a specific action method
#The action method has a respond_to method that returns Employee model as JSON. When Rails encounters this line, it looks for an EmployeeSerializer in the project specifically in a file employee_serializer to get the exact data to be put into the response.
#The EmployeeSerializer is by default configured to use a JsonApiAdapter and formats the specified attributes and relationships in the JSON format. This forms the final customized response.

As you can see, instead of returning the default JSON conversion of the Employee model from the respond_to method, that Rails does automatically for us, we were able to customize our API response data through the use of Active Model Serializers in a non-intrusive way maintaining separation from the controller and the model layers.

=Using Active Model Serializer=

Let us see some code now.

'''Step 1:''' Active Model Serializer is available as a gem. Add to the gem file the following line :
<pre>
gem 'active_model_serializers'
</pre>

'''Step 2:''' Run the following command at the terminal window to install the gem.

<pre>
bundle update
</pre>

'''Step 3:''' This gem provides a serializer generator for the selected Active Model. For example, if employee was your Active Model run :
rails g serializer employee

This would create a file employee_serializer.rb containing the following code in the newly created app/serializers directory of your project:
<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id

end
</pre>

'''Step 4:''' Add your custom attributes and any other customizations to this file. For example: We are adding a url attribute to get details of this employee although the Employee Active Model does not have any such attribute. We add it because the client might be interested in it. That is the power of Active Model Serializer. It does not require us to define another property on the Employee Active Model to return its Url.

<pre>
class EmployeeSerializer < ActiveModel::Serializer
attributes :id, :name, :age, :url

def url
employee_url(object)
end

end
</pre>

'''Step 5:''' That's it! Whenever an Employee is requested the custom EmployeeSerializer does the task of serializing the employee to json and will now include a url key value pair to view the Employee.

=References=
#[http://railscasts.com/episodes/409-active-model-serializers Railcast on Active Model Serializers]
#[https://github.com/rails-api/active_model_serializers Active Model Serializer module on github]
#[http://asciicasts.com/episodes/409-active-model-serializers Active Model Serializer Asciicast]
#[https://www.youtube.com/watch?v=G6ipU6AiEXY Active Model Serializer Video Tutorial]
#[http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/ Active Model]
#[http://en.wikipedia.org/wiki/Serialization Serialization wiki]
#[http://en.wikipedia.org/wiki/JSON JSON wiki]
#[http://en.wikipedia.org/wiki/RubyGems RubyGems wiki]