Find file
Fetching contributors…
Cannot retrieve contributors at this time
152 lines (100 sloc) 9.41 KB

Welcome to the ECSE 321 Project Management System

The Project Management System (PMS) is a suite of tools created for the ECSE 321 - Intro to Software Engineering course at McGill University in the winter of 2010.

The PMS is designed to help a business manage it's employees throughout the duration of a project, and to track the expenses employees incur. It is designed to supplement the vast majority of existing business practices instead of dramatically rewriting them and changing the fundamental operational techniques a business might employ.

The PMS is written in Ruby on Rails. Rails is a web-application framework that includes everything needed to create database-backed web applications according to the Model-View-Control pattern.

This pattern splits the view (also called the presentation) into “dumb” templates that are primarily responsible for inserting pre-built data in between HTML tags. The model contains the “smart” domain objects (such as Client, User, Project, HourReport) that holds all the business logic and knows how to persist themselves to a database. The controller handles the incoming requests (such as Save New Project, Update Client, Approve HourReport) by manipulating the model and directing data to the view.

In Rails, the model is handled by what's called an object-relational mapping layer entitled Active Record. This layer allows you to present the data from database rows as objects and embellish these data objects with business logic methods. You can read more about Active Record in files/vendor/rails/activerecord/README.html.

The controller and view are handled by the Action Pack, which handles both layers by its two parts: Action View and Action Controller. These two layers are bundled in a single package due to their heavy interdependence. This is unlike the relationship between the Active Record and Action Pack that is much more separate. Each of these packages can be used independently outside of Rails. You can read more about Action Pack in files/vendor/rails/actionpack/README.html.

Getting Started

You need to have a functional Ruby installation and the Rails gem (version 2.3.5) installed to be able to run the system. For more information on installing Ruby and Rails, visit this guide:

You also need the gems the application depends on. These can be automatically installed for you buy running 'rake gems:install' in the root directory of the project.

To install the application:

  1. Ensure you have a functional Ruby interpreter.

  2. Install the Rails gems. More info can be found here:

  3. At the command prompt, change directory into the root project directory (ecse321 if you got it from git or a tarball) so you can run 'rake', the application's command line interface.

  4. Run 'rake gems:install' to install the gems the application depends on to work.

  5. Run 'rake db:migrate' to set up the database for the application. The application uses a local SQLite3 database in development mode.

  6. (Optional) Run 'rake db:seed' to populate the database with some test data suitable for exploration.

To run the application:

  1. At the command prompt, change directory into the root project directory (ecse321 if you got it from git or a tarball), and start the web server: script/server (run with –help for options)

  2. Go to localhost:3000/ and see the system.

  3. Log in with the default user name a password, : apple123, to begin using the system. Be sure to change this

password or delete this account to prevent unauthorized access.

To view the application in production online, visit

Running Tests

To run the application's tests, you must have successfully installed the application as described above. You must also install the gems the application depends on for testing. Do this by running 'rake gems:install RAILS_ENV=test'

Once the application and testing dependencies are installed, you can navigate to the project root and run 'rake test' to run all the tests, 'rake test:units' to run all the unit tests, and 'rake test:functionals' to run the functional tests. You can also set the environment variable 'TABLES' to true or pass the –trace option to get some helpful output during the tests.

Source Code

The source code for the application is available online at

Web Servers

By default, Rails will try to use Mongrel if it's are installed when started with script/server, otherwise Rails will use WEBrick, the webserver that ships with Ruby. But you can also use Rails with a variety of other web servers.

Mongrel is a Ruby-based webserver with a C component (which requires compilation) that is suitable for development and deployment of Rails applications. If you have Ruby Gems installed, getting up and running with mongrel is as easy as: gem install mongrel. More info at:

The PMS was designed with the intention of deployment to Heroku (, a rock-solid Ruby and Rails platform hosted in the cloud. This gives the PMS supreme reliability, speed, and easy deployment. See a production version of the application at filled with demo data.


Debugger support is available through the debugger command when you start your Mongrel or Webrick server with –debugger. This means that you can break out of execution at any point in the code, investigate and change the model, AND then resume execution! You need to install ruby-debug to run the server in debugging mode. With gems, use 'gem install ruby-debug' Example:

class WeblogController < ActionController::Base
  def index
    @posts = Post.find(:all)

So the controller will accept the action, run the first line, then present you with a IRB prompt in the server window. Here you can do things like:

>> @posts.inspect
=> "[#<Post:0x14a6be8 @attributes={\"title\"=>nil, \"body\"=>nil, \"id\"=>\"1\"}>,
     #<Post:0x14a6620 @attributes={\"title\"=>\"Rails you know!\", \"body\"=>\"Only ten..\", \"id\"=>\"2\"}>]"
>> @posts.first.title = "hello from a debugger"
=> "hello from a debugger"

…and even better is that you can examine how your runtime objects actually work:

>> f = @posts.first
=> #<Post:0x13630c4 @attributes={"title"=>nil, "body"=>nil, "id"=>"1"}>
>> f.
Display all 152 possibilities? (y or n)

Finally, when you're ready to resume execution, you enter “cont”


You can interact with the domain model by starting the console through script/console. Here you'll have all parts of the application configured, just like it is when the application is running. You can inspect domain models, change values, and save to the database. Starting the script without arguments will launch it in the development environment. Passing an argument will specify a different environment, like script/console production.

To reload your controllers and models after launching the console run reload!


You can go to the command line of your database directly through script/dbconsole. You would be connected to the database with the credentials defined in database.yml. Starting the script without arguments will connect you to the development database. Passing an argument will connect you to a different database, like script/dbconsole production. Currently works for mysql, postgresql and sqlite.

Description of Contents


Holds all the code that's specific to this particular application.


Holds controllers, all named like projects_controller.rb for automated URL mapping. All controllers extend from ApplicationController which itself descends from ActionController::Base.


Holds models that should be named like project.rb. All models will extend ActiveRecord::Base.


Holds the template files for the view that are named like projects/index.html.erb for the Projects#index action. All views use eRuby (erb) syntax.


Holds the template files for layouts to be used with views. This models the common header/footer method of wrapping views. The specified layout is set by the controller using the
<tt>layout</tt> method.


Holds view helpers named like projects_helper.rb. Helpers are be used to wrap functionality for your views into methods for code reuse and clean, easy to read views.


Configuration files for the Rails environment, the routing map, the database, and other dependencies.


Contains the database schema in schema.rb.  db/migrate contains all the sequence of Migrations for the schema.


This directory is where the application documentation will be stored when generated using <tt>rake doc:app</tt>


Application specific libraries. Basically, any kind of custom code that doesn't belong under controllers, models, or helpers. This directory is in the load path.


The directory available for the web server. Contains subdirectories for images, stylesheets, and javascripts. Also contains the dispatchers and the default HTML files. This should be set as the DOCUMENT_ROOT of the web server.


Helper scripts for automation and generation.


Unit and functional tests along with fixtures.


External libraries that the application depends on. Also includes the plugins subdirectory. If the app has frozen rails, those gems also go here, under vendor/rails/. This directory is in the load path.