Welcome to MWeb™!
This document pertains to MWeb Enterprise only.
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
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:
MWeb Flash uses a ViewStack to implement the displays. Each display is a view:
* 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.
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:
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.
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.
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.
Security and Privacy
MXS has several features that provide a high level of security for your data:
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:
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.
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:
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.
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.
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.
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.
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:
"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:
The trademark symbol is critical. Use ™ or ™ 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.
copyright © 2010 Selago Design, Inc. MWeb, CAPS, and InFORMer are trademarks of Selago Design.
99 Fifth Avenue, Suite 214
Ottawa, ON K1S 5P5
Including the name of one of our products in the subject of your message will bypass all spam filters.