MWeb Documentation - MWeb Enterprise -- planning* -- online exhibits -- periods* -- administration* -- templates* -- PPS -- XML server - MWeb Universal - Glossary - Interface Admin - Messages - Support

MWeb™ Flash


Welcome to MWeb™!

This document pertains to MWeb Enterprise only.

Contents


General Guidelines

Purpose

MWeb Flash is programming code for an Adobe Flash interface to an MWeb Enterprise Database (MED). The MWeb Flash source code is free to MWeb Enterprise clients.

Our goal for MWeb Flash is to provide a framework so that web designers can use it as a starting point to create new interfaces, without having to learn how to retrieve the data. In other words, we will build the database and XML aspects, and you will add your own user interface.

MWeb Flash is written in the Adobe Flex language version 3. Flex applications can also be used as Adobe Integrated Runtime (AIR) applications, which run without a browser. The source code is fully supported like the rest of MWeb Enterprise.

To implement your own Flash interface, you will also need the MWeb XML Server (MXS). This is a RESTful Web Service that generates XML from an MWeb Enterprise Database (including PastPerfect-Online) for nearly all requests that the MWeb frontend can handle. You may need to refer to the MXS documentation while you are developing your Flash frontend. Requests not shown in that document are not currently available.

MWeb Enterprise is one of a family of MWeb products. It uses a proprietary database structure. The Database may be in one of several database systems, such as SQL Server, MySQL, Oracle, DB2, or Foxpro. An MWeb Enterprise Database is a read-only database, optimized for searching; it is rebuilt periodically by the site to add new information.

MWeb Enterprise architecture

Resources

MWeb Flash Architecture

The number of functions MWeb and MWeb Flash perform is rather small. The basic functionality provides several ways for users to search, a few ways to view the results of a search, and a few ways to view full records, images, and media. In addition, users can save and manipulate favorite records. There are also Online Exhibits (more about this below). Here's a diagram of the basic displays:

Although this diagram shows the displays in MWeb's HTML interface, the same kinds of displays will be required for MWeb Flash. However, they can look quite different. Here is one possibility:

ViewStack

MWeb Flash uses a ViewStack to implement the displays. Each display is a view:

View namePurposeStatus*
InitialView The initial view presented when MWeb Flash is loaded. Similar to MWeb's Splash Screen. Ready
New Search (includes Keyword Search) This allows the user to enter a Keyword Search, or to choose another kind of search. For Keyword Searches, only records with images are found. Ready
ASView The view to display the Advanced Search to the user Not ready
HSView The view to display a browse interface. The user may expand or collapse the hierarchy to view terms. Clicking on a term performs a Hierarchy Search (records linked to the term). Ready
CSView The view to display the Click-&-Search interface Not ready
SRView The Search Results display Ready
FRView The Full Record display Ready
IVView The Image Viewer Not ready. An alternative to the Image Viewer might be to use Zoomify or something similar.
OEView Online Exhibits selection OEs and Flash OEs may be viewed. These open in a new browser window.
FaveView The view to display the users Favorites Ready
LogonView The Logon Form Ready

* Ready means the database and XML functionality exist for you to build a user interface with. Those that are Not ready will be added when requested.

Scenarios

A typical scenario would be for a user to perform a search to find records of interest, then view these records. Such an interaction would proceed like this for a Keyword Search:

  1. Your application displays a form or list for the user to enter or select words describing the topic of interest.
  2. Your application forms the words into a Keyword Search request and sends it to MXS.
  3. MXS returns the Search Results response, which includes the number of records found and their Keys. Your application should store this list of Keys while the user pages through them. In addition, the brief records for the first 12 hits are returned. Each brief record includes the record's Key, ID, and Type (described below) attributes.
  4. Your application displays the brief records for the first 12 hits. If there are more than 12 hits, you application should display a way for the user to page through them, using "Previous" and "Next" buttons, a list of page numbers, or some similar method.
  5. If the user requests another page of hits, your application sends a request to MXS for the additional brief records.
  6. Your application displays the brief data for each record with a means for the user to view the Full Record (link or button).
  7. When the user selects a record, your application forms the Key into a Full Record request and sends it to the XML Server.
  8. MXS returns a Full Record for your application to display.

The purpose of this approach is to avoid transmission of large amounts of data from searches. For example, if there were 5,000 hits from a search, your Application probably couldn't make use of that many brief records. However the first 12 are sent in order to save a server call.

Keys and IDs

MWeb maintains two identifiers for each record in the database. Keys are MWeb's own internal keys that are unique across the database. They are 32-bit positive integers in the range 1 to 2,147,483,648. Keys have no intrinsic meaning at all.

Unfortunately, MWeb Keys are reassigned whenever the MWeb Database is rebuilt from the client's internal systems. Therefore MWeb also maintains the client's own IDs. These are alphanumeric strings that are stored exactly as received from the client; we make no claims as to their uniqueness or stability, but they tend to have both these characteristics.

In most museum collection-management systems the IDs are not unique throughout the system but only within a record-type. Thus MWeb also assigns to each record a Content Type. The combination of the ID and Content Type is the best way to be able to retrieve a record in the future. When you display a Full Record in your application, the URL should use the ID and Type in case the user wants to save the URL as a bookmark.

Please see the MWeb Glossary for help with other terms. Terms with special meanings in MWeb are shown capitalized in this document; the Glossary defines each one.

Subsets and Content Types

MWeb's most basic categorizing of records is by Content Type. However, these are not used in searching. Instead, a slightly broader concept called Subsets is the finest category of records that is retrievable.

For example, a museum might have artwork records in the Permanent Collection Content Type, and other artwork records in the Temporary Loans Content Type. Assume that both these Content Types are in the Artwork Subset. In that case, your application may request to retrieve records belonging to the Artwork Subset, but may not request to retrieve records of a specific Content Type.

To specify a Subset in a search, add the subset parameter as shown in the examples below. In addition, there are requests that will retrieve a list of all Content Types and their Subsets.


Implementation Details

Browse

Browse implements a clickable interface in which the user can see a hierarchy of terms. Terms are linked to Primary Records by the site, so when the user clicks on a term, the linked records are retrieved.

When viewing a hierarchy, the user may expand or collapse terms by clicking on arrows or other graphics next to the terms. When the user clicks on the term itself, a search is performed.

A site may have either a single hierarchy or more than one: if there is a common root term then there is only one hierarchy. If there are multiple hierarchies, the user is first shown a list of hierarchies (not expandable). When a choice is clicked, the appropriate hierarchy is retrieved.

This behavior was chosen to reduce the amount of data to retrieve, under the assumption that sites with large hierarchies would probably not have a single root term. It would not be hard to modify this behavior to allow the multiple hierarchies to be retrieved all at once and be expandable.

Search Results

MXS will return up to 10,000 records from a search. More than that is considered pointless and just burdens the server. The keys to all the returned records are stored in MWeb Flash.

However, only the first 12 of these records have brief data suitable for display. That means your interface should not plan to display more than 12 brief records unless you want to write some special code.

When the user clicks a button to see the next 12 records, a request is sent to MXS to retrieve the brief data for these. MWeb Flash includes all the functionality required for Next and Previous buttons.

Online Exhibits (OEs)

We do not plan to have MWeb Flash display MWeb Online Exhibits; since they are generated in HTML it would be impossible to get them to display correctly. However, MWeb Flash can link to OEs and have them open in a new window.

Although we do not plan to add this capability to MWeb Flash, you can retrieve the content of an OE and manipulate it if you wish to. Please see the Exhibit List Request and Exhibit Request in the MXS documentation.

MWeb and MWeb Flash both also support Flash OEs (FOEs). These are separate Flash SWF files developed by the site. They can be called from MWeb Flash and display either in the same window or a new window.

In addition, we are developing templates for FOEs similar to those in Pachyderm; these are called from MWeb Flash with parameters to specify the content of the FOE. For example, one template shows two images side-by-side for the user to compare. Text discussing the objects is shown below them. The template allows the site to specify the title, the images to be shown, and the narrative.

FOEs and FOE templates can also be called from the standard MWeb Enterprise interface, so the same content would be available to all users.


Other Information

Security and Privacy

MXS has several features that provide a high level of security for your data:

  • MXS is unable to write to, update, or delete from your MWeb Enterprise Database. Your application should not attempt this either: it both violates the license and will lead to data corruption. Tables that require updates, such as to save Favorites, are stored in a separate database. (There is more information about Favorites in next section.)
  • At present, only data and images with public-level security can be retrieved. Images and data that are restricted to users with a higher level of security are simply not retrieved. See the MWeb Security Model for details.
  • MXS does not check user IDs and passwords; this is the responsibility of the application requesting service from MXS. However, MXS incorporates encrypted handshake and timestamp information to ensure it is being called by an authorized application and is running on an authorized server (see next section).
  • The privacy on users' lists of Favorites is not high. Anyone could enter a URL and view a user's Favorites.
  • SQL injection attacks are prevented.

Caller

Another security feature of MXS is the Caller parameter. This is a 40-byte encrypted string that we will provide you to reduce the likelihood of unauthorized frontends accessing the database. You should add this string to the URL of each request; these are not shown in the examples above for clarity. Here is an example showing a sample Caller parameter:

http://www.example.org/mwebcgi/mwebxml.exe?request=keyword;keyword=tokyo;caller=A8348KLAFU894UJAF89048U34ILJKLJAFLKA8934

Favorites

Favorites is the MWeb term for a list of records that are saved by users. These are stored in separate SQLite files, one file per user. MXS can retrieve from these files using the Favorites request. Since MXS has no ability to write to data files (a design decision to ensure security), if you want to allow users to add to or update their Favorites, your application must handle this. We will provide the data model of the Favorites files on request.

Currently MWeb Flash calls the MWeb Enterprise CGI program to update Favorites.

Data-Source Names

MXS assumes the ODBC Data-Source Name (DSN) is "MWEB". If the MWeb database uses some other DSN, include it as a parameter in the Request:

http://www.example.org/mwebcgi/mwebxml.exe?dsn=mydsn;request=keyword;keyword=yyy

Displaying Images

For Search Results, the image the site designated as the first image for that record is returned. For Full Records, all images are returned. In all cases, MXS returns the full URLs for both the thumbnails and the full-size images. With full URLs, it is easy to display the thumbnail as a clickable link to the image.

Image Paths

At present, MXS assumes that images are stored using the recommended /Full/ and /Thumb/ subdirectories. There may or may not be subdirectories under /MWebimages/ for departments or other groupings. In other words, either of these structures may occur, but the second one is used only if the site has very few images.

          MWebimages                       MWebimages
           |                                |
           |- Paintings                     |- Full
           |   |                            |
           |   |- Full                      |- Thumb
           |   |
           |   |- Thumb
           |
           |- Sculpture
           |   |
           |   |- Full
           |   |
           |   |- Thumb
           |
           |- etc.
               |
               |- Full
               |
               |- Thumb

MWeb Help File

The MWeb Help file, written for the end-user, is not generally needed, except for the syntax of Advanced Search Requests. However, it also discusses Keyword Search, performance issues, and other relevant information. The text of this Help file is freely available for you to incorporate into your own Help file. You may change the text if you wish, or use it as it is.

Error Handling

If an error occurs while MXS is processing your application's Request, it returns a Response containing error information. Depending on the severity of the error, the Response may also contain some or all of the data your application requested.

Errors are of two severity levels: Critical and Warning. An example of a Critical Error would be if your application requested a Full Record but did not provide the Key or the ID and Type; obviously MXS cannot return the requested Full Record. The Critical severity means that MXS could not process the Request.

The Warning severity means that MXS tried to process the Request but some unusual condition arose.

MWeb Flash shows all errors to the user in Alerts, so that the error can be corrected or at least reported. Please include the message number in the display if you expect us to help with diagnosis.

Error numbers

Each error in the MWeb system has a unique identifier. This enables us to locate the precise cause of the error when it is reported to us. Although the text of messages may change over time, the numbers do not (although they may be removed if no longer useful). Because the numbers do not change over time, you may design your application to handle errors automatically based on the numbers.

Here is a link to the list of MWeb messages and their meanings.

Enhancements

Out goal is to provide the framework but not a complete interface; therefore we have left many features incomplete. Here are some features that you could add:

  • Sorting of SR and FR histories alphabetically.
  • Insertion of a new Favorite set alphabetically (now it is added at the end of the list)
  • Image Viewer. Not sure what to do with limited space.
  • Multiple select/drag into IV
  • Sort SR
  • Delete Faves set
  • Slideshows from Faves. Adobe's "photoviewer" application distributed with Flex could be a model.
  • Emailing and other uses of Faves
  • Preferences

Legal Matters

"MWeb", "MWeb Flash", "MWeb XML Server", and "MXS" are trademarks of Selago Design, Inc.

Use of MXS is governed by the MWeb Online Catalog System Software License Agreement. Among other matters, it specifies that each display must contain the following message and link:

This site uses the <a href="http://support.selagodesign.com/mweb/credits.asp">MWeb™ XML Server</a>.

The trademark symbol is critical. Use &trade; or &#8482; to display the trademark symbol.

The initial display must present this link so that a user with an 1024x768 monitor can see it without scrolling.

The license also specifies that the Selago Design URL (selagodesign.com) be provided when mention is made of MWeb in papers, talks, or presentations to museum audiences.


All contents of website, including HTML and JavaScript, copyright © 2010 Selago Design, Inc. MWeb, CAPS, and InFORMer are trademarks of Selago Design.
MARCView and MARConvert are trademarks of Systems Planning.

Selago Design
99 Fifth Avenue, Suite 214
Ottawa, ON K1S 5P5
Canada
(312) 239-0597
Email us

Including the name of one of our products in the subject of your message will bypass all spam filters.