Updates to the POV Call for Entries Admin Tool

Jim Tarvid, tarvid@ls.net

Summary

This project addresses most of the issues in the file SUB-tarvid-2008.doc amended by email correspondence with David Nanasi. Parachuting into a large code base requires fitting code in a manner consistent and compatible with that code base in order to solve problems and implement desired functional enhancements cost-effectively.

The code base is called SSPS by its author Mark Vose, author of the initial application. A deliberate attempt was made to reuse the code base and retain the look and feel.

The work plan consisted of:

1. backing up the existing web code and database
2. reconstructing the website on a workstation
3. exploring the existing code base and devising methods of introducing the changes
4. revising the code
5. posting of the revised version to an Internet accessible "sandbox"
6. review by POV staff
7. revising the "sandbox" version
8. posting the results to the live site

Steps 1 through 7 have been completed. Step 8 requires an FTP upload of the changes.

Backup

This was accomplished in two steps:

1. download the existing web tree with the Linux command "wget -m ftp://username:password@cfe.pov.org"
2. export the database using PHPMyAdmin through the control panel at the web host

Workstation Setup

The workstation is an AMD 64 bit system with Ubuntu Linux 2.6.22-14 installed with the server components Apache 2.2.4, MySQL 5.0.45 and PHP 5.2.3. The editor used was gedit 2.20.3.

A stanza was added to /etc/apache2/sites-available pointing to the "httpdocs" in the downloaded code base and an entry made in /etc/hosts so the web pages could be rendered directly on the workstation.

The database was imported into MySQL and permissions granted to the user name and password found in the code base. No changes were made to the structure of the database to maintain compatibility with archived data bases.

Code base exploration

We started by reading the sections of code to be modified and the  "SSPS" "class" structure, in particular "SSdata".  This permits abstracting snippets of code which appear useful in meeting the desired functionality. Principally, these included data base access and validation.

In the process, careful attention was paid to CSS (Cascading Style Sheets) to maintain a consistent look and feel.

Revising the code

Revisions were tackled in increasing order by ease and functionality. Putting a modest menu system in place eased navigation during coding. That was followed by changing attribution in the CFEQuickAdd module from admin to user.

Extending the film entry in the submitters report was next since display of admin user contact info provided no useful contact information.

Relaxing the data validation in SubmitterQuickAdd came last.

Functionality was checked frequently because it is relatively easy to "break" existing logic. Having a running web and data base server on the workstation system made it easy to flip back and forth between the code and the application.

Posting the code

A sandbox was created as a subdomain - cfe.ls.net by adding a stanza to /etc/apache2/sites-available, a DNS domain and importing the data base and setting up the required permissions.

This is the inverse of the original backup.

POV Staff Review

After a few working days, David forwarded comments from POV staff and we agreed the most important issue was to constrain the submitter drop down select on the CFEFormQuickAdd screen.

Revising CFEFormQuickAdd

The underlying data base retrieval class facilitates constructing a "WHERE" clause and a sub form was added to restrict entries to those containing a partial first and/or last name.

The sub-form does require sending the query arguments to the server and refreshing the form in the browser.  All that required was avoiding executing the code executed when the final submission form is submitted.

Uploading the revised version

One step remains - upload the revised PHP scripts to the cfe.pov.org web host. This entails writing and executing a simple "bash" script to FTP the modified files.

Narrative description of code changes

This section describes the changes in non-procedural language. The actual changes are documented in the file cfeadmin.diff. Additional some inline documentation is included.

admin_menu.html

A simple menu to provide navigation between forms. In many cases it replaces an inline "Switch to:" Added to:

• cfeform_change_status.php
• cfeform_quick_add.php
• cfesubmittor_quick_add.php
• main_viewall_cfeforms.php
• main_viewall_cfesubmittors.php
• receive_assign.php
• receive.php
• receive_results.php
• summary2.php
• summary.php
• summary_viewreport_eval.php

cfeform_quick_add.php

The goal of the changes to this routine is to replace the "admin" "user_id" with the "real" submitter. This is accomplished by adding a "Submittor" select field to the form. Since the "submitter" list may get quite long a "Filter" sub-form is included to reduce the list to those which contain a partial first name and/or last name.

This script, like many others in the application, was entered more than once: to enter data and also to "Save Changes". The changes introduced add a third, to filter the submitter list. Thus the first change is to distinguish between "Save Changes" and "Filter".

The bulk of the code introduced adds a "Submitter" section to the "form". This section is patterned after the other sections to maintain a consistent "look and feel".

structure of the author's invention. Relatively sophisticated as To construct the "submitter" "select" list, the "submitter" "table" is retrieved from the data base. This code is patterned after simlar code in "main_viewall_cfesubmittors.php" following the "when in Rome" maxim. The original code was built around a PHP "class" structure - "SSPS". As PHP code goes, it is sophisticated but obscure. Discovery is aided by the PHP function "print_r" which dumps a PHP array structure where it is invoked, in this case the middle of the form. Although a temporary measure this documents the syntax required to extract the data values from the structure produced by the "class" "SSdata". A similar technique was used to dig the arguments from the "Filter" subform via "print_r ("$_POST)".

The filtering is done in the "Where" clause added to the "$submitters" instance of the "SSdata" class.  This notion is inscrutable to the "non-Object PHP" programmer but this example is a fairly good introduction. The magic is in the SQL "like" operator. "%" is a wild card, so when we say  like "\"%$filter_nf%\"", we are saying any value that contains "$filter_nf". SQL string arguments are not case sensitive. Two or three characters in either the first or last name is sufficient to reduce the list to a manageable size.

cfesubmittor_quick_add.php

The goal here is to relax the fields required when the submitter is not from the United States or Canada. To do that, we simply test for "Country" and use the original field requirements for the "US" aned "CA" and a subset without "State" and "Zip" for the rest.

Additionally, "admin_menu.html" replaces the original "Switch to:" and "(no PO Boxes, please)" redacted from "Street Address:".

main_viewall_cfesubmittors.php

The goal here is to supply the director name and email address to mitigate the problem that films added with the admin "user id" didn't provide useful contact information.

The task is complicated by the fact that "submitter" is the row entity and films must be "joined" to the submitter to be displayed. A "film" view instead of a "submitter" view would facilitate a "normalized" rendering but that would require rewrite of the entire script. That would require a level of effort beyond the budget.

The compromise is to add the first director name and email address to the film list which is simple if not elegant.

The required data is already present in the query data set so all that is required to to concatenate the director name and email address to the film title.

Recommendations

Migrate the cfe.pov.org site to Drupal. Working in a well known code base would provide numerous maintenance advantages. Having one application in a CMS (content management system) would make future projects easier. The process involves a bit of ditch digging but is conceptually straight-forward.

Roles

• administrator
• submitter
• evaluator

Permissions can be finely tuned and still facilitate communication between members of different roles.

Profiles

Custom fields for demographics and contact info can be added for user profiles fullfilling the need for a data base table for admins, evaluators and submitters. User activities are logged and tracked to one can follow the path of a submission.

Data base tables

Data base tables like films, evaluations, directors can be established with CCK (Content Construction Kit) along with an extensive widget set for the user interface. Each entry can be searched, edited, commented upon. Custom views can render summary tables.

Modules

Implementation can be fairly rapid. Much of the functionality can be found in the core modules and a somewhat overwhelming number of third party modules is available. Custom modules are possible but come with a maintenance cost which is not insignificant.

Themes

Migration of the current site presents no significant theming issues. That's good because although hundreds of themes are available some sites defy fitting into one without substantial modification.

Considerations

Users of the system will have to abandon the comfort of familiarity. Drupal has its own modes of operation and changing those is expensive. Coming to terms with Drupal is neither difficult nor time consuming but one should expect some missionary organizational effort.

Level of effort to prototype is about a man week. This should pay back in the mid term.

Community support is fantastic. There is an amazing array of IRC, forum, third party support, documentation and published books.