User Guide for the Retreat Registration Version Two
(RV2)Project
To help developers get up and running with working on the
Project
Author: Jan van der Breggen
Table of Contents
Introduction
This documentation is for the Rigpa Retreat Registration
Version Two PHP software project. This is not the general
project documentation which can be found at: (insert link).
The aim of this documentation is to describe the current
state of the PHP software development process that is part
of the project. The project is currently in the phase of
Prototype Development. The project is envisioned to become
an open source style team collaboration involving as many
programmers as are willing to volunteer their time and
efforts. According to research on the topic one of the
critical factors in the success of Open Source Software
Development is the availability of a working prototype of
the project. Having a critical mass of code embodied in a
working prototype sets the vision of the project in a
tangible way, and this enhances the chances of a succesful
Open Source Project (See for example
Srijith's
research paper on Open Source SD).
The of aim the working prototype is twofold:
To provide the critical mass of code and design
vision as described above;
To provide those who have to convince the wider
Rigpa world of the benefits of a world wide system
of retreat registrations with a kind of demo version
of the application.
The last point falls outside the scope of this document. The
rest of this document is made up of two sections: setting up
the RV2 Development Environment, and RV2 Software Design.
The section of Software Design will also introduce the
project's basic directory structure, so it is recommended
you go through this section after you have setup the RV2
development environment.
Setting up a Development Environment
Below you find recommendations for setting up your computer for
working on the project.
Web Server Environment
You will need to install the following on your computer:
Apache Web Server
PHP Version xxxxx
MySql Version xxxxx
Easiest is to use a package that installs and configures
all these components for you, such as Wamp Server
or Zend Community Server
You may also wish to download the of MySql Administration tools . Especially the
MySql Query Browser and MySql Administrator applications
are very useful.
Setting up the project in Eclipse PDT
The recommended IDE for developers on the Rvtwo project
is the Eclipse PDT Integrated Development Environment (
PDT Download site) .
If you are using another IDE you will need to take the
essential information supplied in this section and apply
it to your IDE's environment. After installation, upon opening
the application you will be prompted to set a work space
location. Choose your web server's document root for
this.
The source code of the Project is stored in a Subversion
repository on the project's Sourceforge site. In order
to access it throug the Eclipse PDT application you will
need to install the Subclipse plugin. This can be done
by following the steps explained on the
Tigris website .
After installing the SubClipse plugin you can download
the project Source code from the repository as follows:
From the File menu, select Import and under Other select
Checkout Projects from SVN and click Next. Select Create
a New Repository Location, click Next, and enter the
following location:
https://retreatreg.svn.sourceforge.net/svnroot/retreatreg,
and checkout the following folders:
rvtwo
ddms_server
Eclipse will ask whether to create the projects in its
workspace. Anwser 'yes' to this.
RV2 Software Design
Model-View-Controller
The basic design of the application follows the well
known Model-View-Controller (MVC) design pattern. For
indepth information about the MVC design pattern and the
reasons for using it see for example ?????? (find good
web resource to link to). Here we'll just establish the
basics needed for starting to work with the code.
Within the MVC pattern, there is a separation of
'layers':
Model - this is the layer that directly
interacts with the MySql database. Any program
code that has SQL embedded should be part of a
Model.
View - this is the layer that is responsible for
displaying the user interface. Any code that
involves HTML tags should be part of a View.
Controller - this layer is responsible for: -
providing the View with data to be displayed on
the user interface, - processing information
supplied by users through the user interface and
passing this system responses back to the View
for display, - passing data to the Model for
storage in the database. The Controller should
never go directly to the database and should not
have anything to do with formatting data into
HTML tags.
Object Oriented Approach to Application Development
The RV2 application aims as much as possible to be
Object Oriented (OO). As such the Controller and Model
functionality is all encapsulated in Classes. The
Controller classes are all stored in Controllers
directory and the Model classes are all stored in the
Models directory. Each file in these directories
contains the code for one Controller or Model class, and
the filename matches the class name. Model and
Controller Classes make use of functionality provided by
other Classes, the code of which resides in the Classes
directory. For these classes the same rule applies as
for Model and Controller Classes: one class per file and
file name and class name must match.
Smarty
Views (stored in the Views directory)are the exception
to the rule that RV2 is fully OO. Views are Smarty
Templates: a combination of HTML tags and Smarty tags
which together produce a User Interface Screen. If your
work on the RV2 project involves User Interface
development you will need to be familiar with the way
Smarty works. (Insert hyperlink to Smarty
documentation). If your work is limited to working in
the area of system Controllers you will at least need to
know how to pass data to the Smarty template. For this,
easiest is to just have a look at some existing
Controller classes and see how this is done.
