E1914 Refactor users controller

This is an Expertiza based OSS Project.
The project is running on VCL instance
The link to the pull request.
Each following section describes a problem that was present in the Users_controller. And the solution we implemented to solve it.
In the last section, we defend some design decisions that we took during the process.

Separate all methods related to the workflow of a RequestedUser object

Problem:
The users_controller.rb file included the standard CRUD methods for a User model along with methods for other workflows. The users_controller.rb file handled the creation and management of a RequestedUser object.
Solution:
Earlier, there was no controllers for a RequestedUser object and these were handled by the Users controller itself. We separated the RequestedUser workflow from the Users and we renamed the RequestedUser model to AccountRequest. As a part of this refactoring activity, we created a new controller called the account_requests_controller to handle the workflow of an AccountRequest. The following methods were moved from users_controller to account_requests_controller.
1) created_approved_user
2) list_pending_requested
3) request_new
4) created_requested_user_record
5) roles_for_request_sign_up
6) requested_user_params

RSpec testing for account_requests_controller

Problem:
Since we created a new controller, tests for this controller did not exist. All those tests were written in the users_controller since that was where the methods were located earlier.
Solution:
We moved the tests from the users_controller_spec.rb file to the newly created accounts_request_controller.rb file. We also had to change the tests a little to now reflect different routing expectations.
It can be seen that all 11 test cases passed for account_request_controller.

RSpec testing for users_controller

It can be seen that all 18 test cases passed for users_controller.

Writing comments to make methods more understandable

Problem:
The users_controller included a few methods which lacked documentation.
Solution:

Wrote comments for the 'foreign' method. The comments include:

1) What the method does: This method is used to find the list of roles the current user can embody.
2) Where the method is used: Used to display a drop-down selection of roles for the current user in the views.

Wrote comments for the show and show_selection methods:

1) What the method does:
show(): If the current user is a student, they should only be able to see information about themselves. All other people should be able to see information about themselves or other students. If the request to show() passes these checks, then they are shown the view 'show'. Otherwise, they are redirected to the home page.
show_selection(): If the role of a user's parent is less than the current user or if the current user is requesting to see itself or if user's parent_id does not exist then the show() method is called. All these conditions boil down to whether the current user of the system is authorized to see/edit the information about the user specified in the params. If the requested user does not exist or if the current user is not authorized to see the requested user, then the current user is redirected back to the list page.
2) Scenarios in which show_selection is called: in users/list.html.erb, a list of users is shown. On top of the list there is a functionality to search the list. When a person searches for a particular student, and selects that student, the show_selection method is called. If the person is allowed to see that student, the user is directed to the show() method. Otherwise the person stays on the list view.
3) Scenarios in which show() is called: From the edit.html.erb, if the person wants to see the information instead of editing it. From show_selection() as described above.

Renaming methods to reflect their actual behavior

Problem:
Methods in the Users_controller were not named to convey exactly what they did.
Solution:
The get_role method was named more like it would be in Java. It was renamed to 'role' because that is how it would be named in ruby. We chose to keep the method in the controller instead of moving it to the model because it does not alter the data structure and it also has selection logic.

Make GUI changes in the form displayed after "Request Account" button is clicked

Problem:
The forms that come after "Request Account" button is clicked need to be changed.
Solution: Only instructor accounts can be created, so the drop-down was removed.
All form labels were bold-faced.
The “Self Introduction” label was re-named to “Self-Introduction”.
The text-box for the self-introduction field now includes a useful hint of what is expected in the text-box. The hint is "Please include a website name".

Before it looked like this :

After it looks like this:

Paginating the list of users

Problem:
When a list of all users are shown, the list is not paginated. So the instructors see a list of all users that have enrolled for a course over all the years that they have offered the course.
Solution:
The existing project does not have the feature of pagination for the user list. So, currently, all the users are shown to the instructor.
The paginate_list method is supposed to paginate the list of users. The method was not called anywhere and also the method logic was incorrect.
With the latest implementation, the pagination is added with dropdown option - "25", "50", "100" and "ALL".
The method "paginate_list" is corrected and called at right place.
The default option is kept to "25" to reduce the web-page loading time.

Before it looked like this:

After it looks like this:

Design choices

1.Partial Views:
There are some partial views which are related to displaying forms to create/edit a user in the Users view. The same partials were earlier being used for displaying forms for requesting a new account. Now that we separated the two controllers, we had the following options regarding what to do with the partials.

Option 1) Keep accessing the partials in the users view from the newly created Accounts_request view.
This would make the code DRY but harder to understand.
Option 2) Duplicate the partials in the accounts request view.
This would make some render partial statements hard to read but would make the code DRY.
Option 3) Create partial files in the views folder.
Have Users_controller, Account_requests_controller access these partials. The code becomes DRY and also readable.

We decided to go with option 2. Even though the two forms happen to be the same right now, some time in the future, they may deviate. This option gives some flexibility to the accounts_controller to modify the form without affecting the User's form.
The partials that are now duplicated are: _email, _name, _institution, _password, and _prefs.

2.Refactoring variable names:
We refactored the variables names from requested_users to account_requests (in views, controller actions, etc.) since requested_users is a bad naming choice for our variable. As we are referring to AccountRequest model in our controllers, such renaming makes sense here.
For example:

 account_request = AccountRequest.all 

makes more sense than

 requested_users = AccountRequest.all