[Grok-dev] Idea for a new tutorial - need feedback
steveschmechel at yahoo.com
Sat Feb 28 17:06:41 EST 2009
I am going to begin working on a multi-part tutorial that will follow
the course of building a small web application using Grok. I hope that
this will bring together several aspects of working with Grok that are
covered in more detail in separate tutorials and how-to documents.
I have followed the development of Grok for quite a while (early 2007)
and tinkered with it here and there, but I do not have an opportunity to
use it as part of my job so it has never gotten to the point of feeling
"natural" to me.
As part of my volunteer work with some non-profit groups, I have used
and extended Plone to provide solutions to various problems. This has
provided me with some exposure to Zope and Python, but I am certainly
not an expert in any of those areas.
My professional work is composed of large-scale development, with layers
of requirements, tricking in through slow, bureaucratic channels. It is
really fun for me to volunteer to do some small projects, where I can
see results quickly. I see Grok as a great way to quickly try out a
solution and get user feedback. You can develop in an agile way and at
the end have something that is more than just a prototype.
I currently have an opportunity to help out a group of volunteer
musicians with organizing information about their performances within
The requirements are fairly simple and there are certainly many ways
this could be accomplished. Customizing a Plone site seems like
overkill. A small, dedicated solution would help them AND provide a
nice learning experience for myself and others.
There is no hard time frame for completing the solution, and while I
have expanded the requirement to try to cover a lot of possible
functionality in order to enhance the learning experience, the group
would be happy with even the most basic system.
What I Hope to Accomplish
I would like to create a tutorial that includes some "hard-earned
wisdom" on practical things like organizing your source code and other
artifacts within a project, using the debugger, writing and running
tests, etc. These items are often glossed over in other documentation
for the sake of simplicity, but when you want to sit down and do a
bigger project and you haven't stepped through the practical
"nuts and bolts" a few times, you can feel lost.
I want the pieces of the tutorial to follow a progression, with each
piece building on the next. Starting from a simple model and prototype
and evolving the way a real project might. For someone who makes a
living doing Zope/Grok style development, this might seem tedious and
may not match their personal work style. My target audience are those
with little or no experience in this type of development who are trying
to get into Grok to do something useful.
What I Could Use from The Grok Community
- Feedback on the requirements included below (in ReST format). I think
they cover many of the key aspects of Grok programming. (Traversal,
forms, searching, static files, security, AJAX, etc.) Can you think of
other areas that could be taught within these requirements?
- Ideas on the best approach to take when there are several
alternatives. (Templating, AJAX, etc.)
- Help when I get stuck. Everyone here is already great at helping
others. The community around Grok is one of its most attractive
assets. Thanks in advance.
- A place to put the tutorial as it is written. I currently don't have
write access to the documentation site. Let me know what I need to do
or who I need to talk to.
- Feedback on the tutorial as it evolves. As I finish significant
sections I will either prompt the list or, if there are certain
individuals who are more interested than others, I could notify them
more frequently and let others review it whenever they feel like it.
Thank you for taking the time to read all of this. I hope what I write
will be of benefit to the Grok community and make it easier for new
developers to "grok Grok".
Musical Performance Application
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
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.
- Application Root (contains Performance objects)
- Musicians (contains Musician objects)
- Email Address
- 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
- Author Email Address
- Comment Text
- 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:
- 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.
Phase 1 - Basic Functions
All current and future performances are listed
Sorted ascending by date.
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 to a static directory or BLOB resource directory.
Always upload user selected attachments and use a "name-chooser" to
prevent overwriting existing files. Deleting an attachment releases
any storage space used by the file.
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.
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.
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
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.
Ability to search or filter performances by song performed or musicians
Provide Management Functions
Removal or archiving of past performances. Attachment management to
free storage resources.
More information about the Grok-dev