1
VT CS4624
Animal Rescue
Giles County Animal Rescue
Client: Christine Link-Owens
http://www.gilescountyanimalrescue.org
Neal Schneier: Neal.schneier@gmail.com, 703-483-1389.
Zachary Highman: zhighman@gmail.com. 804-938-2059.
May 2, 2012
1
2
Table of Contents
Executive Summary
3
User’s Manual
4
Developer’s Manual
7
Lesson’s Learned
18
Acknowledgements
20
References
21
2
3
Executive Summary
When we chose to work with the Giles County Animal Shelter all that we were aware of
was that they needed some work done on their website. But it was not until that we met with
Christine Link-Owens that we understood the task that we had chosen. Once we met with her
we knew what needed to be done. Create for the Giles County Animal Shelter a website that
they could use and would want to use. The current site that they were using had many issues
and was poorly designed. So this led us to rebuild the site because we thought we could do a
better job than trying to fix a poorly designed and half functioning website.
Once we decided that we were going to rebuild the site we knew that we would need to
make the site customized for her. So once we had a rough design built we communicated it
with her and took her feedback. It was from this continued process of communicating with
Christine as well as our own development that we built this site. While we were working on the
site she came across more improvements that she felt she needed and we implemented them
as they came in. At times this slowed our development because implementing new features at
the same time none of the features that she asked for took a large amount of time.
Through this process we grew a better understanding of how to work individually with a
customer and how to communicate with the customer so that they are aware of where you are
in the project and the customer would not be surprised with what was coming up. This also
required us to create a list of requirements for her saying what we would deliver results by the
required date. As discussed later we provided her a schedule at the beginning and updates as
we were working on the project. As each update was complete we would communicate that to
her so that she was aware and could begin testing as soon as features were becoming available.
Additionally, we will continue to work with her to maintain the site and fix any issues that arise
in the near future. We made a promise to her and would like to help her maintain a functioning
website that she can keep for years.
3
4
User’s Manual
The purpose of the user manual section is outline the website in a way that the user is
aware of all of the functionality on the website and can therefore navigate the website
successfully. Additionally, I will discuss the admin features so that if the user is an admin they
are aware of how to make changes to the site. I will discuss each page or page group if there
are pages that are very similar. It is important to note that you as the user will know what page
of the website you are on based on the blue line that is underneath one of the links on the dog
collar.
News
This is the home page of the new Giles County Animal Shelter website that we designed
and developed. It works based on admin submission of title, descriptions, and images. The
information presented is in chronological order and multiple images can be attached to any one
news link. When you search there is precedence order that you as a user should be aware of.
The first if the word you are searching for is in the first part of the title, then if it is in the title
and finally if it is in the description. It will then also break down the results to make sure that
there is not too much text on a single page of the results.
As an admin you can do multiple things once you are signed into your admin account.
The first is the power to edit, delete and create news articles to appear on the site. This means
that you can change the images and the wording at any point or completely remove the
content from the site in one click. In order to add a picture simply have it saved on your
computer and navigate to the file and upload it to the site. The text area has the ability to hold
large amount of text. After you hit save the news article will automatically be added to the sites
content.
4
5
Animals
The Animals’ page provides multiple purposes. It lists all of the dogs (with images when
available) that the animal shelter is currently holding. At the moment it only shows animals that
are adoptable or found but if there are more statuses used to label the dogs then there will be
more options available. These links at the top provide a quick way to sort through the dogs that
are currently at the shelter. A better way to search is again by using the search bar at the top
left. When it searches the animals it looks at the name, description and then the breed. As a
basic user you can see the status of the dog, the name, the sex, a description of the dog and the
time that it was at the shelter.
As an admin user of this page there are a couple other controls that you have over the
site itself. First of all you can edit or delete any of the dogs from the content on the site in one
click. If you edit then you are brought to a form where you can change any of the information
that is presented on the dog. Additionally, there is a green “+Add New Animal” button that
allows you to quickly add a new animal directly to the site. From this form you can fill out as
much information as you have on the dog but it is required that you provide a name, sex,
description, and status of the dog. If there is not a status that fits with the new dog then you
simply press the “+” and a text box will pop up that will allow you to type in a new status. This
will also update the Animals’ page by adding it as one of the quick sorting status at the top of
the page. Add as much information as you see necessary and click the save button and it will be
added to the site immediately.
Adoption Info, About, Volunteer, Donate, Contact
All of these pages are largely text oriented and work just to provide the user with
information on the organization. As an admin on this page there is an edit content button at the
top right which allows you to edit the content of the page you are currently viewing. Once you
click the edit content button you will be brought to a giant text field that has all of the content
from the page and buttons at the top of the text box. The buttons at the top allow you to
format the text that you want to appear on the website. Once you click the save button the
5
6
content that you just edited and formatted will be put directly onto the website. This allows
you as an admin to quickly and easily edit the page content.
Admin
The Admin page is only accessible and seeable by someone that is logged in as an
admin. Under the page you will find three sub tabs that allow you to edit the admin features.
The first list is the user’s list which allows you to see who else is an admin on the pages as well
as some other information about that user, such as a way to contact that user. If you are a
system administrator then you can also edit and remove other users from having admin rights.
The second tab allows the admin user to edit and send emails to registered users of the
newsletter. This was an important feature that there were many bugs with in the old site. There
are textboxes that allow you to edit the content of the email and then immediately send it to
the registered recipients of the newsletter.
6
7
Developer’s Manual
This section will serve to provide guidance for sustaining and extending the Giles County Animal Rescue
Website. The languages used to code this application include PHP, JavaScript(jQuery), MySQL, CSS3 and
HTML. The IDE used predominantly is NetBeans, version 7.0.1. All existing code in the application
adheres to these standards. It is the intention of this guide to provide basic knowledge to navigate the
source as well as maintain the chosen standards as new code is added. This guide will include
background information on the existing code, the file structure of the application, and the database
behind it as well as how to extend the site and add new features or pages.
Organization
Pages
Every page within the site adheres to a specific folder structure and naming convention, so as to
eliminate the need to redundant code and make modifications easier. Each group of similar pages (i.e.
create, read, edit, delete pages for an entity) is contained within a folder. The folder name should
correspond to the intended main URL for that group of pages. An example is shown below in Figure 1.1.
Figure 1.1, Animal pages folder
In Figure 1.1 there are a number of pages listed. When accessing the URL ending in ‘Animals/’ will
automatically load the file index.php. Accesses to any other pages must include the file name within the
folder (e.g. ‘/Animals/create.php’).
7
8
Shared pages used only by one folder of pages should be
stored in a folder ‘Shared’ within the page group folder. An
example is shown below in Figure 1.2.
Any pages that are shared among all pages in the site, for
example the layout file, should be stored in the folder
‘Views/Shared/’.
Content
Figure 1.2, ‘Shared’ Folder
Site content (pictures, sounds, videos) should be stored in the folder ‘Content’. Images used for site
graphics and other non-user images are stored in ‘Content/images’. Photos that are uploaded by the
user are stored in the ‘Content/photos’ folder (more on this in the section on Uploading Images in
Posts).
CSS files should be stored in the ‘Content/Themes’ folder. Usually one CSS file is used per page group.
Using the name of the page group makes the corresponding files easier to locate.
Figure 1.3 ‘Content’ Folder
JavaScript
JavaScript files belong in the ‘Scripts’ folder. For each page group, there is a folder to contain all JS files
that are associated. For JS files that are common to the entire application, store them in the root of the
‘Scripts’ folder.
8
9
Figure 1.4 ‘Scripts’ Folder
jQuery is used throughout the site, but is imported from Google’s CDN service. The include statements
are located in the layout.php file. Using Google’s version eliminates the need to store the file on the
server, as well as decreases load times.
jWYSIWYG is the script library for the rich text editor. Since its folder contains a mix of file types, it is
stored in its own folder at the root of the filesystem.
Other PHP Files
PHP files used for the purpose of exposing functions to other files should be stored in the root of the file
system, to shorten the include statements and aid in locating files.
Page Structure
This section outlines the common layout within most of the pages in the application. Most of this will
refer to the main PHP file for the page.
DocType
The doctype on each page should be the current standard for HTML 4. HTML 5 may be used, but the
newer functionality should be avoided to maintain cross browser compliance.
9
10
Figure 2.1 sample DocType
Header
There are three required items in the <head> section.
The first is the base URL. This is declared to reduce the number of places that must be changed if the
URL changes. By using a base URL, we need only change the initial declaration if the site’s domain
changes.
The second is the page title. Usually this will correspond to the current pages title followed by a pipe ‘|’
then the site title, ‘Giles County Animal Rescue’.
Last is the inclusion of the style page. Since the site layout CSS file is included in the layout page, only
the page group specific file should be loaded.
Figure 2.2 HTML Header
Body
The first entry in the body is a PHP include call to the layout.php file. This will include the site navigation
at the top of the page, as well as load common JavaScript, CSS and other common files.
10
11
Next, the active page is declared, so the corresponding tab in the navigation can be highlighted. Refer to
the layout.php file for the list of page title’s
All page specific content should be contained in a <div> with the id ‘content’. This will ensure the
content area is styled by the site.css file.
Hidden <div> elements should be placed at the bottom of of the page, outside of the ‘content’ <div>.
The last element in the page is the JavaScript inclusion. This is done at the bottom of the page to avoid
conflicts as the DOM loads.
Requests
This section will detail the HTML request procedure for obtaining data from the server or database,
using either direct navigation or AJAX calls.
URL Navigation
When the page or resources is requested when the user clicks a link or enters a URL, the code for
fetching the data and displaying it will be on the same page. The first section of code fetches the item,
the rest of the document displays it.
We begin by using a section of PHP code to initiate the database connection and fetch the appropriate
items. Before we can connect we must include the PHP file db_conn.php.
11
12
Figure 3.1 Including the Database Connection
Pages with pagination should use the URL parameter ‘s’ to signify the starting item in the pagination.
Thus value will be added to the MySQL query using a ‘LIMIT statement. The query is then run using the
mysql_query function.
Figure 3.2 Pagination and running the Query
The die function should return the user to a page, rather than showing a raw error.
The results of the query will depend on the entities being accessed. If the result is a group of entities,
the result will be iterated over and the string of HTML will be output using the PHP echo function.
AJAX Calls
Request made using AJAX will be handled by jQuery. In order to process this request a separate PHP file
for the request processing is needed. The calling JS file will access this PHP resource, which will in turn
return a JSON or HTML result. The jQuery $.ajax() function should be used to access the PHP resource.
Be sure to set the ‘cache’ property to false, to avoid new results not being loaded in certain browsers.
12
13
Figure 3.3 Sample jQuery AJAX Call
The target may simply be another page, in which case the HTML code will be returned. If accessing a
PHP controller to return a resource, the PHP file should use the ‘echo’ function to return HTML.
If JSON is returned, use the PHP function json_encode to properly format your results before returning
them.
Figure 3.4 Sample JSON PHP request handler
Files
When returning a file, the appropriate MIME type must be used. Also be sure to send in the header the
size of the file, so the browser can show a progress bar.
13
14
Figure 3.5 Returning a File to the Client
Posts
Whenever data is modified as a result of a user action, the HTML post action should be used. This can be
done in two ways: via form submission and AJAX posting.
Form Submission
Forms are used to transmit multiple items to a PHP file to use the data to modify the server or the
database. The ‘action’ attribute should be a PHP resource to handle the post. Use the ‘onSubmit’ tag to
call a validation function before the form is submitted. If there are files to be uploaded, the
“enctype=’multipart/form-data’” must be included.
Figure 4.1 Form Declaration
In the PHP file that processes this post, the form data is accessed using the $_POST function. The values
obtained are put into an insert, delete or update statement to modify the database.
14
15
Figure 4.2 Sample Post action
If the form contains a file other than a picture, the file must be read into memory using PHP. See an
example in the file upload_post.php in ‘Newsletters’ group. The file data needs to be stored in a BLOB
field in the database or saved in the filesystem.
Figure 4.3 Saving a file to the Database
Uploading Photos
To upload photos, look at the example in the create_post.php file in the ‘Home’ page group. As this page
accepts an unlimited number of files, we set the ‘name’ attribute on each file input to ‘file[]’ to tell the
PHP controller that there are multiple files. As the photo files are iterated over, a function in photo.php
is called to reduce the file size if needed. Include this file and call the reduceImage function on the
resulting image file.
15
16
Instead of storing photos in a database, we save them to the file system. The ‘image’ table in the
database stores the path to the file in the database, rather the image contents. This allows for faster
accesses to photos. To connect an image to another entity, a join table is used to connect many entities
to many photos. For example, a news_post entity is connected to the assicated photos by the
news_post_image table, which holds the ID for the news_post and image.
AJAX Posts
Data posted using AJAX will use the jQuery $.post() function. The data may be manually added to the
post in the declaration of the function, or an entire form can be used. If the entire form is to be posted,
use the serialize() function to create a JSON object to send with the post.
When the post returns, a value indicating whether or not the post was successful should be given.
Figure 4.4 Sample AJAX Post
Validation
In order to prevent user error, each form should have validation. Fields should be checked to ensure a
number of conditions to preserve the integrity of the applications. The type of input should be checked
against the database type to ensure the query will execute. Also, any fields with a maximum amount
should be checked to avoid truncation or errors.
Logical checks should also be added to prevent nonsensical data. For example, a start date should never
be after an end date.
16
17
When a field fails validation, a message should be shown at the top of the page to warn the user, and
the label should be given the class ‘errors’ to highlight it red.
Figure 5.1 Sample Validation JS Code
17
18
Lesson’s Learned
Timeline
January 31 – Meet with her and gain an understanding of the project
February 1 – Get access to GoDaddy account
February 16 – Basic website design complete
March 1 – Reorganizing GoDaddy account, begin building site
March 13 – Design approved and database designed and created
April 17 – Animals and News pages complete, testing begins
May 2 – Complete implementation including all pages and admin controls
Schedule
In order to meet our time we would meet or talk every day that there was class about
the project. This made sure that we at least kept good communication between us. Make sure
that we were keeping to the schedule that we had given her at the beginning of the semester.
We fell a little behind schedule towards the end of the semester but we were able to meet the
deadline by picking up our pace towards in the last few weeks.
18
19
Problems
When we were handed this project there were many problems with the site. As she
walked us through the site there were bugs with the forms, could not upload images and was
just overall poorly designed. In order to overcome these problems we decided that it would be
easier to rebuild the site. The question then became do you use Drupal or do we build the site
from scratch. We went with building the site from scratch because we thought it gave us more
freedom and would be easier for them to update in the future. Essentially there was one
question that we had to answer: what is the best way that we can make her site usable again?
Once we decided to build the site from scratch the next problem was how to design the
site. This first step required us to look at what she was looking for and we found direction from
something that she told us. She mentioned when we met with her that she liked this other site
design because it was simple which lead to an easy conclusion. We need to design an easy site.
So Zach created some Photoshop images that we could use. The design that Zach came up with
and I agreed was to use dog tags as the design at the top of the site. He also took the current
header design and enhanced it to work with the new site design and she loved it.
One of the big problems that we faced was making the site updateable for her as a nontechnical person. They had people in the office that had some technical skills but we wanted to
make sure that she was able to make as many changes as she needed to the site without
looking to anyone else for help. This led us to the use of jWYSIWYG which allows her to edit the
content of the site in ways that she wants. By using this feature she can format the text how
she wants and it is converted to HTML so that it is displayed in the same manner that she
formats it. We also added several other features that allowed her to change the site. For
example being able to add new status to the animals and it carrying over to the rest of the site
is a feature that she explicitly asked for. We also included an admin tab so that she could
maintain who is able to control the content on the site.
Another problem that we found as we were working on the site was the time it took to
load certain pages of the website. The obvious reason was that they were pages that contained
large amounts of images. In order to counteract this affect Zach found a PHP algorithm that
shirks images over a certain size and even takes into account the quality of the image.
19
20
Acknowledgements
We would like to thank Dr. Fox and Christine Link-Owens. Dr. Fox was our instructor that guided
us on this endeavor and provided us the opportunity to help out an organization such as Giles
County Animal Rescue.
We would also like to thank Christine Link-Owens who was always available and made clear
what she expected from us.
Edward A. Fox, http://fox.cs.vt.edu, 2160G Torgersen Hall, (540) 231-5113, fox@vt.edu
Christine Link-Owens, President, Giles County Animal Rescue, VT office 231-1532, Giles office
540-922-3958, gilescountyanimalrescue@gmail.com
The admin password that we created for this class is as follows:
username: cs4626
password: CS4624_Test
20
21
References
MySQL: The World’s Most Popular Open Source Database. Oracle. http://dev.mysql.com/.
Website.
jQuery: Write less. Do More. The jQuery Foundation. http://jquery.com/. Website.
PHP. The PHP Group. http://www.php.net/. Website.
21