The Sousa Page Object Sequencing tool is roughly based on the Gallery Tool developed for UC Berkeley. The Image Gallery tool is designed to sequence images using a drag and drop ordering tool developed in the Fluid Project.

See also:

• Adding New Content Elements
• Gradebook Integration
• Other Tools
• Permission Notes
• Plug-in Page Elements
• Reorderer Notes
• Sousa Page Layout

Project Level Considerations

High Level Goals

The main idea behind Sousa is to create a toolkit that allows people to experiment with content delivery in Sakai. It should be easy to add support for new kinds of content and have them drop into existing editors and viewers. It would also be nice to have a place where developers can experiment with new framework services like the JCR content repository, the Entity Broker, and UI concepts coming out of Fluid.

Additional requirements are documented in Sousa Requirements

Software Organization

Sousa currently has two application associated with it: a sequencer player/editor and a page object viewer/editor. These applications share a SequencerService and EditChainService available as a Sakai component.

Sequencer Service Design

The page object sequencer design grew out of the Gallery Tool developed for UC Berkeley. Where the Gallery Tool is organized around collections of images, Sousa is organized around a collection of content objects - either simple objects (text, images, etc.) or more complex ones (wrapped frames, page objects, etc.). Sousa is written as a Sakai tool that roughly follows Sakai tool development conventions. A SequencerService provides access to Sequences and Page objects (Layout). A second service, the EditChainService, provides access to EditChains (used to hold editing state).

Items hold a reference to a ContentResource and are ordered by a Sequence object. An EditChain is used to hold an ordered set of EditItem that allows Sousa to track changes made to a sequence. This allows the back button in a browser to work fully and even allows the user to wander off and return to an edit session in progress. The EditItem class was added to hold information about a content item while it is being edited or created.

The SequencerService is broken out into an API JAR and a Sakai component package. This should allow it to be reused across different Sousa tools. The EditChain is broken out into its own objects; sequences and edit chains are still coupled. Ideally, they should be made completely independent of each other. That would allow edit chains to be used in other applications where editing state is needed, not just in Sousa. However, it's possible that the edit chain may not be needed once the Fluid Reorderer is added.

Support is provided for marshalling a Sequence into and out of an XML description format, which is what is persisted in the ContentHostingService.

Sousa Media Engine: Extensible Media Handling

Sousa has an extensible mechanism for handling various kinds of media content elements. Handlers for support media types are registered in the ContentElementHandler. This also has methods that dispatch media management operations to the handler associated with its media type. See Adding New Content Elements for documentation on adding content elements.

Supported media operations currently include:

• Display media element
• Display media thumbnail
• Display media type icon
• Support for editing parameters

Supported media types (at this time) include:

Content Element handler objects include:

Handler operations rely on an agreement between the view template identifiers and the supported media types. These agreements are documented in the following sections.

Display Content

An rsf:id is passed to the content element handler. To this, a media type is appended, followed by an optional numbered suffix. As an example, the following rsf:id's are included in the viewpage template:

The numerical suffix distinguishes between table cells in a common row.

Display Thumbnail

An rsf:id is passed to the content element handler. To this, a media type is appended. Since only one thumbnail will ever be present, no suffix is needed. As an example, the following rsf:id's are included in the edittile template:

If no media handler is available for a given media type, a "no thumb" image is displayed. Certain types of media may have placeholder icons displayed as a thumbnail - CSV data, for example. These images are included in the tool content.

Display Icon

No agreement is necessary to show content element icons. The rsf:id passed is used as-is. Media icons from the Sakai reference library are used were available. A Sousa Grid Layout Page Object icon has been developed and is included in the tool content.

Parameter Editing

Three methods were added to the content handler system to support editing of parameters:

• isParametersEditable() - return true if this handler supports parameter editing.
• editParameters() - show form elements to capture parameters for this handler.
• saveParameters() - save data collected out to content resource.

Generally, parameters are captured as text and folded into a runtime EditItem object. This object is cached in the user's Session and allows the content item being created to be previewed, modified, etc. until it is time to save it out to content resource properties. The EditItem class is an extention of Item and is intended to hold interrim data about a content item. It is NOT intended to be included in a Sequence.

Up to four parameters can be handled by the system as it is currently defined. The following parameters are planned for media types:

Content Editing

Most Sousa content elements originate as a file. Thus, in order to edit content, users will need to upload and replace the content of an existing content resource. RSF provides support for file upload via its MultipartResolver support. See File Upload.

Three methods were added to the content handler system to support editing of content, including file upload:

• isContentEditable() - return true if the content for this item can be replaced or modified.
• editContent() - show form elements needed to edit or add content.
• saveContent() - save new content data out to a content resource.

The Sousa Page Object Viewer and Editor

Page Object Selection

The root of the resource tree for this site is shown with its top level contents (collections and resources, if any).

Display of resources should be filtered by content type. Sousa page objects are XML documents and have a content type of "sousa/grid-page".

Work Flow Design

The following is a state diagram for the Sousa Page tool. Transition to edit states will eventually be restricted by permissions (TBD).

Note: The submit link from Edit Item to Preview is the only POST operation currently used in the Sousa Page tool. All others are GET, thereby maximizing support for the browser Back button.

Layout Persistence

Page Objects (Layouts) are saved as XML documents with a simple XML syntax. It consists of a LAYOUT tag that has one or more TILE tags. Each TILE may have one or more ITEM tags in it. Each ITEM tag has only one CONTENTID tag containing the Sakai Content Hosting ID.

<layout type="single-column">
    <tile>
        <item contentId="/group/ContentTest/More Stuff/no-3.jpg"/>
        <item contentId="/group/ContentTest/More Stuff/no-2.jpg"/>
        <item contentId="/group/ContentTest/More Stuff/no-1.jpg"/>
    </tile>
</layout>

Page layouts are selected from a limited set of set of layouts including several predefined ones:

Content and Parameter Editing

In many cases, it would be very useful to have one or more parameters associated with a content element that would provide additional information to Sousa on how to display it. For example, an image might have height, width, and alignment. There are also cases where the content of the content element can be easily edited, such as plain or structured text.

A simple structure is proposed whereby up to ten parameters (currently four) can be associated with a media type. These would all be of type String (initially). Two handlers have been added to ContentElement: displayEditParameters() and saveEditParameters(). Actual parameters used are media type dependent. A predicate has been added to ContentElementHandler to check hasParameters().

Additionally, the content associated with a page item might be editable. Two handlers displayEditContent() and saveEditContent() would be added. A predicate would be added to ContentElementHandler to check isEditable().

Some content elements may have no parameters (like plain text). Some cannot be edited (like video), but may allow the file associated with the resource to be replaced.

The Sousa Page Viewer

Page objects are displayed via the Sousa Page Viewer, currently a view in the Page tool. Supported media objects may also be viewed (Sousa creates a layout wrapper for them on the fly).

This view could be reused a Resource tool action handler for Sousa page objects. Just need to make the exit link flaggable.

The Sousa Sequencer Player and Editor

The Sequence Document

Rather than relying on an order imposed by the Resource tool (like the first version of the Gallery Tool did), Sousa supports sequence editing in the tool.

Sequences could be easily kept in a database, but if they are kept as XML, they are one step closer to SCORM, OCW, and IMS-CP documents. Identifying documents that can be opened by the Content Sequencer tool may have to wait until registration with the Resource Tool can be figured out. Initially, we can filter on all xml files and let the user pick out the one to be displayed.

Sousa Sequencers should be of content type "sousa/linear-seq".

Content Repository

Like the Gallery Tool, the Content Sequencer can initially work with the Resource Tool in a site. This has the same problems that the Gallery tool has: the Resource Tool must be included in the same site as the Content Sequencer tool. It might be interesting to experiment with creating root collections in a site without the Resources tool present, since the tool does allow editing. The problem is: where does content live?

Work Flow Design

The following is a state diagram for the Sousa Sequencer tool. Transition to edit states will eventually be restricted by permissions (TBD).

This version of the flow diagram introduces page layout editing.

Sequence Editing

When the sequence is displayed for edit, each item is show with a set of control icons to move it up, down, first, and last. It contains the title of the time, and indication of its type (text, graphic, video, etc.), and a representative illustration (if available).

A set of action links is included with each item entry on the right to allow a new entry to be inserted (always after) and to delete the indicated entry.

Edit State

Ideally, the sequencer is stateless. That has major consequences for the operation of the editing application. The key question comes to either persisting on every operation, or persisting on user command.

If every operation persists the sequence (moving an item, for example), then using the Back button doesn't undo an operation.

If the Back button is to be used for undo (presumably desired), then a chain of edit commands needs to be maintained until it is time to commit them. Such an edit chain would have to be represented very efficiently in order to avoid overflowing the limits on URLs. A scheme for moving might be created that is very compact (provided that item IDs were unique only to the sequence); however, inserting new items would be expensive, in terms of URL length. Worse, the user can't edit a sequence arbitrarily long. Eventually the maximum URL length (1024) would be exceeded.

This argues for preserving the state of things in the user session. In this view, the edit chain is stored as a set of change records on a stack. Current stack location is passed in the URL. Thus if the Back button is used, the stack reference is rolled back one, even though the stack record is still included in the stack. The application would have to overwrite a previous edit entry in this event.

Editing on such a chain would continue until the user chooses one of two final operations: Save or Cancel. On Save, the edit chain is processed and applied to the sequence. On Cancel, the edit chain is discarded.

Note that on each edit view, the chain of edit events must be reapplied to the sequence in order to show the current state of editing.

The sequence being edited can be cached in the user session as well. This will save time on marshalling into and out of XML. It also allows a new sequence to be created and discarded without persisting it to a file.

Sequence Persistence

Sequences are saved as XML documents with a very simple syntax. It consists of a SEQUENCE tag that has one or more ITEM tags. Each ITEM tag has only one CONTENTID attribute containing the Sakai Content Hosting ID.

<sequence name="Aikido Opening">
    <item contentId="/group/ContentTest/Aikido/seminar.jpg"/>
    <item contentId="/group/ContentTest/Aikido/Mill City Seminar Description"/>
    <item contentId="/group/ContentTest/Aikido/aikido-opening-1.xml"/>
    <item contentId="/group/ContentTest/More Stuff/obj-test.xml"/>
</sequence>

While a simpler syntax is possible, this structure provides for future expansion, especially in ITEMS.

Sequence Selection View

A tabular view of available sequences is presented to the user. Clicking the sequence name launches the sequence.

Clicking on "Edit" brings the user to a sequence editing view.

Currently all XML files in the Sequence collection are displayed. These files should have a content type of "sakai-sousa/linear-sequence" and be filtered to remove all others.

Sequence Player

Once launched, content is sequenced page by page. Each page consists of title and page number, plus the body of the content, as specified in the sequence:

Initial support is limited to simple sequencing: linear presentation of the content objects included in a sequence specification. See Branching Sequences for an exploration of another sequence type.