Introduction ¶

An overview of the example requirements and a road map for how the tutorial will cover the development of the application.

Contents

Introduction

General Overview ¶

One of the goals of this tutorial is to give the reader a chance to walk through the process of developing a Grok application. Specific pieces of application development are handled in greater details in other how-to’s and tutorials. In this tutorial, we hope to demonstrate how the pieces can come together in a development process.

If you are a seasoned Zope3 developer or even a long-time Python developer, you probably have your own preferred development style and you may disagree with some parts of this tutorial. (If you have ideas for improvements, they are certainly welcome but this is not an exercise in determining which development style, text editor, IDE, template system, or AJAX library is the best or most efficient.)

This tutorial is targeted at those who are new to the Grok and Zope3 framework. They may have been using other web development frameworks and programming languages, or they may have been lucky enough to have found Grok first and are anxious to see what it can do for them.

We will try to not make assumptions about your knowledge of Python, Zope3, and Grok. Obviously, it is assumed that you have some software development experience and are able to learn the Python language and follow the development patterns. A great deal of high quality documentation and tutorials exists for most of the topics surrounding this tutorial. Where appropriate we will provide links to resource materials.

It is expected that you have Python version 2.5 installed on your computer. Specifically, a version of CPython in the 2.5.x series from http://www.python.org, not Jython, IronPython, or some other alternative implementation of the language. Python version 2.4 is also acceptable, however, version 2.6 is not yet supported and version 3.0 will not currently work.

Grok will work on any operating system supported by Python which includes Linux, Macintosh, and Windows. There can be some slight differences in things like directory locations depending on platform. We will try to note some of the differences, but understand that Ubuntu Linux is being used for the writing of this tutorial.

Sample Application Requirements ¶

Description ¶

In some venues, ad-hoc bands of musicians and vocalists come together to perform at scheduled events. The band leader for a given event needs to organize the people involved, develop the list of music they will perform, and distribute sheet music, chord charts, and lyrics.

A leader may be in charge of several performances involving different musicians. Likewise, musicians and vocalists may be involved in several performances lead by different people.

Currently, much of this organization is done via email. As expected, often key people are missed in the email distribution or their email address changes or their account is broken, causing them to miss important information.

Even if they receive all the information, it is still possible for them to mis- file the emails or attachments. Often updates for various performances come “out of sequence” and, if the subject is not very clear (i.e. “Friday’s Performance” instead of a distinct date), the recipient can get confused.

Having a web site that lists all the important information and allows them to download the files they need for their preparation would be a benefit to everyone involved.

Entity Outline ¶

Application Root (contains Performance objects)
- Performance
  - Date
  - Location
  - Leader
  - Start and End Times (free-form, optional)
  - Musicians (contains Musician objects)
    - Name
    - Email Address
    - Instrument
  - Set List (contains Song objects)
    - Song Title
    - Arrangement Notes
    - Display Order
    - Attachments (contains Resource references)
      - File Name
      - File URL
      - File MD5 Hash (Hidden/Optional)
  - Comments (Contains Comment objects
    - Date
    - Author Email Address
    - Comment Text

General Requirements ¶

Performances should be organized by date. Since it is possible to perform more than once in a day, an optional, “rough time” can be added to the day to differentiate them. Performances will never happen more frequently than once per hour.
Performances should be able to be found by URL’s that can be understood to refer to a certain performance. Example: http://example.com/TheBandName/2009- 03-05/
Users should be able to upload files in any format they choose (PDF, DOC, Text, etc). No special handling or MIME types are provided by the application to enhance browser interaction.

Phased Deliverables ¶

Phase 1 - Basic Functions ¶

All current and future performances are listed Sorted ascending by date.
Text-field forms

User hand-types dates, musician names, song names, and display order relying on web browser for any form completion efficiencies.
Basic file upload support

Upload file attachments to a static directory or directly into the storage database. Always upload user selected attachments and use a “name-chooser” to prevent overwriting existing files. Deleting an attachment, or the song which contains it, should remove the file from the application, but may require a management operation to reclaim the free space.
No user authentication, roles or permission support.

Rely on external security via web proxy configuration or rewrite rules.
Basic Text Comments Anyone can comment.

No email support or comment-spam protection.

Phase 2 - Improved Usability ¶

Enhanced Performance Listing

Ability to see past performances. More display of summary performance details such as simple musician and song listings.
Form Widgets

Use of date-picker, and drop down lists to speed selection of information that already exists in the application. Buttons or “Drag and Drop” to adjust display order.
Enhanced Upload

Ability to quickly select more than one attachment item. Warn user when an attachment may already exist and offer to link to the existing file rather than uploading another. (This could be done by file name matching or possibly a file content hash comparison.) Only remove underlying file content when no attachments (in any performance) reference the file.
Basic Roles for Editing

Leader role can create Performances and add songs to Set list. Assistant role can modify existing song arrangement notes and add/remove attachments.
Email Support for Comments

Basic comment-spam protection via capcha or email confirmation request. Notification email with URL of this performance sent to the addresses of all associated musicians.

Phase 3 - Style and Management ¶

Create a stylized look for the site.

Use a template system, CSS, and some images to give the site an appealing look. Should be easy to modify the colors and any logos via CSS edits.
Application Search

Ability to search or filter performances by song performed or musicians involved.
Provide Management Functions

Removal or archiving of past performances. Attachment management to free storage resources.

Development Road Map ¶

We are going to begin by getting the basic development environment in place and test that it works. We will then begin writing some tests which correspond to some of the Phase 1 requirements. From there we will begin to write model and view code to satisfy our tests.

Several iterations will be required to get through the first deliverable. From there, we will move on to the other deliverables.

It will take a significant amount of time to make it all the way through this tutorial, but we will try the keep the amount of work in each iteration manageable.

Navigation