WimpyPoint Design Documentation

I. Essentials

• User directory: /wp
• Sitewide administrator directory: none
• TCL script directory: service_name/tcl/
• Data model: service_name/www/arsdigita/doc/sql/wp.sql
• Requirements document: /arsdigita/doc/requirements/wp.html
• Design document: this file...
• Page Flow: /arsdigita/doc/page-flow/wp_interaction
• ER Diagram: /arsdigita/doc/er-diagrams/small_wp_er

II. Introduction

WimpyPoint is a web-based application for building slide presentations that replaces desktop bloatware such as Microsoft PowerPoint. You can build a slide presentation in WimpyPoint from any Web browser anywhere in the world. WimpyPoint will hold onto your presentation in a relational database management system. You can forget your laptop. You can drop your laptop. You will still be able to give your presentation anywhere in the world that you can find a Web browser.

III. Historical Considerations

WimpyPoint was born as a standalone application, started by Philip Greenspun in late December, 1997 and later enhanced by Krish Menon. WimpyPoint was rewritten by Jon Salz and reborn as an ACS application in late 1999, as a term project for MIT's 6.916: Software Engineering of Innovative Web Services class.

IV. Data Model Discussion

The primary focus of the WimpyPoint data model are the wp_presentations and wp_slides tables. For each WimpyPoint presentation there is exactly one row in wp_presentations with information such as title, page signature, copyright notice, audience, and background. Then there is at least one row in wp_slides for every slide in the presentation. The reason there is at least one row is that when a slide is modified after a version is marked, a row is actually inserted for the new version of the slide. This way, there is exactly one version of each slide in the database for each version of the presentation.

In addition to those two tables, there are a number of other tables and PL/SQL functions that comprise the WimpyPoint data model. Here is a brief overview of them:

• Tables
  • wp_styles contains information for all of the styles.
  • wp_style_images contains the background images that are associated with styles.
  • wp_checkpoints marks each user-created presentation checkpoint.
  • wp_historical_sort contains information to sort slides correctly in older checkpoints.
  • wp_attachments contains uploaded slide attachments
  • wp_user_access_ticket allows a user to "invite" someone else to work on a presentation
  
  
• PL/SQL Functions
  • wp_real_user_p is used to determine whether a user has enough slides to qualify as a real WimpyPoint user
  • wp_previous_slide returns the id of the previous slide in the given presentation and checkpoint.
  • wp_next_slide returns the id of the next slide in the given presentation and checkpoint.
  • wp_role_order maps roles into numbers so that they can be easily ordered.
  • wp_between_checkpoints_p determines whether a slide refers to a particular checkpoint.
  • wp_access returns the access rights for a presentation.
  • wp_revert_to_checkpoint updates slide information to revert a presentation to a previous checkpoint.
  • wp_set_checkpoint updates slide information to create a new checkpoint.
  • wp_migrate_slide copies a slide from one presentation to another.

V. Legal Transactions

Users may

• Add, Edit, and Delete presentations
• Add, Edit, and Delete slides
• Add, Edit, and Delete styles
• Add and Delete checkpoints
• Add, Edit, and Delete presentation permissions
• Add and Delete slide attachments

VI. API

wp_new_stuff { since_when only_from_new_users_p purpose { include_date_p 0 } { include_comments_p 1 } }

Used for sitewide listing of new content

wp_user_contributions { user_id purpose }

Used for admin listing a user's contributions

wp_help_header { title }

Returns a help header for WimpyPoint.

wp_header args

Returns a header for WimpyPoint.

wp_header_form { form args }

Returns a header for WimpyPoint.

wp_header_intl { form argv }

Return a HTML header for the page.

wp_footer {}

Returns an HTML footer for the page.

wp_access { presentation_id user_id { priv "read" } }

Returns the user's actual level, if the user can perform $priv roles on the presention.

wp_check_authorization { presentation_id user_id { priv "read" } }

{ Verifies that the user can perform $priv roles on the presentation, returning an error and bailing if not. If authorized, returns the level at which the user is actually authorized.

wp_check_style_authorization { style_id user_id }

Verifies that the user owns this style.

wp_ljoin { list values }

Appends each of values (a list) to the list.

wp_select { sql code { else "" } { elsecode "" } }

Performs a select, setting variables and executing code for each record.

wp_nextval { seq }

Returns the next value of a sequence.

wp_prepare_dml { table names values { condition "" } }

Prepares a DML statement with columns names and value values. If condition is empty, does an insert - otherwise does an update.

wp_serve_style {}

Serves the requested style to the user as a Cascading Style Sheet

wp_serve_presentation { conn edit }

Serves the requested presentation or slide.

wp_serve_attach {}

Serves the requested attachment.

wp_style_url {}

Returns the StyleURL parameter (no trailing slash).

wp_presentation_url {}

Returns the PresentationURL parameter (no trailing slash).

wp_presentation_edit_url {}

Returns the PresentationEditURL parameter (no trailing slash).

wp_attach_url {}

Returns the AttachURL parameter (no trailing slash).

wp_only_if { condition text { elsetext "" } }

If condition, returns text; otherwise returns elsetext.

wp_role_predicate { role { title "" } }

Returns a plain-English string describing an role (read/write/admin).

wp_short_role_predicate { role { title "" } }

Returns a short plain-English string describing an role (read/write/admin).

wp_slider { which current items }

Generates a slider for form variable $which with items $items, of the form { { 1 "One" } { 2 "Two" } }, where 1/2 are the query values and One/Two are the corresponding labels.

wp_numeric_sort_bulk_slides {{file_list ""}}

Sort bulk-imported slides numerically (instead of using ascii sort)

VII. Configuration/Parameters

[ns/server/service_name/acs/wp]
; Paths to use for serving styles and presentations.
StyleURL=/wp/style/
PresentationURL=/wp/display/
PresentationEditURL=/wp/display-edit/
AttachURL=/wp/attach/
; do we allow collaborators to comment on presentations
SolicitCommentsP=1
CommentApprovalPolicy=open
; Path to the unzip program to use for bulk image uploading.
PathToUnzip=/usr/bin/unzip
; Is bulk image uploading enabled?
AllowBulkUploadP=1
; Is PDF downloading enabled?
AllowPDFDownloadP=1
; Path to the htmldoc program to use for PDF downloading
PathToHtmlDoc=/usr/bin/htmldoc
; Is HTML printing (presentation in a single page) enabled?
AllowHTMLForPrintingP=1

VIII. Acceptance Tests

• Setup
  • The following tests assume that the Parameters are set to their default values.

• Testing
  • Visit /wp without being logged in. A list of public presentations created in the last two weeks should be shown.
  • View the help page.
  • View all public presentations created within the last month.
  • See a list of all WimpyPoint users with public presentations.
  • Search for a particular WimpyPoint user via their last name.
  • Log In
  • View your presentations
  • Create a new private presentation with the default style
  • Allow everyone in the Employees group (or some other user group) to view your presentation.
  • Allow one particular user to edit your presentation.
  • Create two slides.
  • Swap the order of these slides.
  • Add a third slide between the first two. Attach an image to this slide.
  • Edit the presentation to use your own style.
  • Define this style.
  • View your presentation. Make sure it uses your new style.
  • Freeze the current slide set.
  • Copy several slides from another user's presentation into yours.
  • View the presentation. Make sure the new slides are there.
  • Revert to the previously saved version.
  • View the presentation. Make sure the slides you copied over are not there.
  • Delete your presentation.
  • View everyone's presentations from the past two weeks.
  • View a random presentation. Change the display style to your own.
  • View a different presentation. Make sure it uses your style.

IX. Authors

• System creators: Philip Greenspun
• System owner: Dennis Gregorovic
• Documentation authors: Dennis Gregorovic