Giles County Animal Rescue

1

VT CS4624

AnimalRescue

Giles County Animal Rescue

Client:Christine Link-Owens

Neal Schneier:, 703-483-1389.

Zachary Highman:. 804-938-2059.

May 2, 2012

Table of Contents

Executive Summary / 3
User’s Manual / 4
Developer’s Manual / 7
Lesson’s Learned / 18
Acknowledgements / 20
References / 21

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.

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.

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 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.

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.

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’).

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

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.

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.

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.

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.

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.

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.

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.

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.

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.