The most recent version of this document can be found online at http://www.360works.com/supercontainer/documentation.html

Purchase a license or learn more about SuperContainer on the 360Works site

SuperContainer Documentation

SuperContainer eliminates the hassle of dealing with container fields in FileMaker. It runs as a web-based java application which allows you to upload, view, and download scaled images and files from an embedded web viewer in FileMaker (introduced in FileMaker 8.5).

It is an effective replacement for container fields in solutions which require users to read and store files associated with records in FileMaker container fields, and offers numerous advantages over container fields.

SuperContainer is designed to be used from within a Web Viewer layout element in FileMaker, by pointing the Web Viewer to a URL that uniquely identifies a file resource you wish to store. This URL can contain any number of arbitrary path components.

In addition, SuperContainer ships with a Companion Plugin that allows you to automate access to SuperContainer resources. Consult the documentation in the SuperContainer Companion Plugin directory for more details and examples.

Advantages of SuperContainer over container fields

• Solves all problems with cross-platform pathnames.
• Solves the problem of all users needing to have the correct file server volume mounted.
• Users can insert files from their own computer, without copying them to the mounted server before inserting them into FileMaker
• When files are deleted in SuperContainer, they are truly deleted, instead of just losing the reference to them.

• Files are stored in neatly organized folders which you control.
• FileMaker just stores a reference to the files, which means that your database file sizes don't grow out of control.
• The referenced files can be backed up separately, so incremental backups won't become overloaded with a single huge FileMaker file every night.

• Dynamic thumbnail generation feature means much faster viewing and network efficiency for large files.
• Multithreaded viewing means your users can work while images load in the background.
• Because SuperContainer stores references to documents as standard http:// links, it is very easy and efficient to display them on FileMaker-powered web sites.
• Files are stored in neatly organized folders which you control
• Since SuperContainer is also compatible with Instant Web Publishing, this gives FileMaker users, for the first time ever, an easy and integrated way to do browser-based file uploads into FileMaker Pro.

System Requirements

• Clients:
  • Must be running FileMaker 8.5 or later to view the items stored in SuperContainer.
  • To use the optional SuperContainer companion plugin, Windows clients must have Java 1.4 or later installed.

• Server:
  • Macintosh OS X: Mac OS X 10.2 or later
  • Windows: Microsoft Windows XP with Service Pack 2, Windows XP Professional, Windows 2000 Server, Windows 2000 Professional, or Windows Server 2003; Java 1.4 or later
  • Linux/Solaris: Java 1.4 or later

If your computer does not have Java installed, you may download it at http://java.sun.com/javase/downloads/index.jsp

Installation: Deployment Options

You can run SuperContainer as a standalone application, or by bundling into FileMaker Server Advanced, or in your own copy of Tomcat. If you are upgrading from a version older than 1.3, be aware that the URL formats have changed in SuperContainer.

Option 1: Using SuperContainer as a standalone server application

This approach is excellent for simple deployment, as well as for testing and development. There's no installation required, you just start the server and immediately begin using it. You will need to start the SuperContainerServer every time the machine it is running on is rebooted.

Note: the standalone application must be in the same directory as the SuperContainer application folder.

Option 2: Installing SuperContainer with FileMaker Server Advanced

This approach is recommended for advanced users if you are running SuperContainer on a dedicated server which is also running FileMaker Server Advanced 8 or FileMaker Server 9 or FileMaker Server Advanced 9.

Installing SuperContainer on Macintosh

1. If desired, customize the settings found in the SuperContainer/WEB-INF/web.xml configuration file. If you are upgrading from a previous version, copy any custom settings from your old web.xml file to the new version's web.xml file. You can customize the path where files are stored, as well as set a username and password to protect your SuperContainer files.
2. FileMaker Server 8: replace the /Library/FileMaker Server/Web Publishing/jakarta-tomcat/conf/server.xml with the server.xml file in the Support files/FMS 8 directory. FileMaker Server 9: replace the /Library/FileMaker Server/Web Publishing/publishing-engine/cwpe-tomcat/conf/server.xml with the server.xml file in the Support files/FMS 9 directory. This replacement file uncomments a single configuration line that allows FileMaker Server Advanced to host any application, not just the ones that come with it.
3. FileMaker Server 8: copy the SuperContainer folder into the /Library/FileMaker Server/Web Publishing/jakarta-tomcat/webapps folder. FileMaker Server 9: copy the SuperContainer folder into the /Library/FileMaker Server/Web Publishing/publishing-engine/cwpe-tomcat/bin folder.
4. Restart the FileMaker Web Publishing computer.
5. Go to http://serverAddress:8080/SuperContainer to make sure that SuperContainer is running correctly. Note that the default port with Tomcat is 8080, instead of 8020 for standalone mode.

Installing SuperContainer on Windows

1. If desired, customize the settings found in the SuperContainer/WEB-INF/web.xml configuration file. If you are upgrading from a previous version, copy any custom settings from your old web.xml file to the new version's web.xml file. You can customize the path where files are stored, as well as set a username and password to protect your SuperContainer files.
2. FileMaker Server 8: replace the C:\Program Files\FileMaker\FileMaker Server\Web Publishing\jakarta-tomcat\conf\server.xml with the server.xml file in the Support files\FMS 8 directory. FileMaker Server 9: replace the C:\Program Files\FileMaker\FileMaker Server\Web Publishing\publishing-engine\cwpe-tomcat\conf\server.xml with the server.xml file in the Support files\FMS 9 directory. This replacement file uncomments a single configuration line that allows FileMaker Server Advanced to host any application, not just the ones that come with it.
3. FileMaker Server 8: copy the SuperContainer folder into the C:\Program Files\FileMaker\FileMaker Server\Web Publishing\jakarta-tomcat\webapps folder. FileMaker Server 9: copy the SuperContainer folder into the C:\Program Files\FileMaker\FileMaker Server\Web Publishing\publishing-engine\cwpe-tomcat\bin folder.
4. Restart the FileMaker Web Publishing computer.
5. Go to http://serverAddress:8080/SuperContainer to make sure that SuperContainer is running correctly. Note that the default port with Tomcat is 8080, instead of 8020 for standalone mode.

Option 3: Installing SuperContainer with Tomcat

This approach is recommended for advanced users if you are running Linux, Solaris, or any other computer not running FileMaker Server Advanced.

You must have a copy of Tomcat (downloadable from http://tomcat.apache.org) installed and running.

1. If desired, customize the settings found in the SuperContainer/WEB-INF/web.xml configuration file. You can customize the path where files are stored, as well as set a username and password to protect your SuperContainer files.
2. Copy the SuperContainer folder into the Tomcat webapps folder.
3. Restart Tomcat.
4. Go to http://serverAddress:8080/SuperContainer to make sure that SuperContainer is running correctly. Note that the default port with Tomcat is 8080, instead of 8020 for standalone mode.

Using SuperContainer in your solution

Let's walk through setting up SuperContainer for a sample FileMaker solution. We will assume for these examples that your server is called 'yourServer.com', and that you have a table occurrence called 'Asset' with a field called 'ID'. This ID field is how you want to reference your files on the server. Substitute the actual values for your situation.

Registration

You must activate the software at http://yourServer.com:8020/SuperContainer/Registration before using it in your solution. You may use the demonstration license code that came with your download e-mail to run SuperContainer for 2 hours per server restart. While SuperContainer is running in DEMO mode, a small "DEMO" flag will be displayed on all pages.

SuperContainer URLs

You will need to start by creating a WebViewer in your FileMaker 8.5 layout, and assign a SuperContainer URL to the WebViewer. The first part of the URL is always:

http://yourServer.com:portNumber/SuperContainer/Files

After that, you specify where on the server you want the uploaded file to be stored. You can include slashes in the URL to store the files subfolders, like this:

/path/to/file

Typically, you would include the name of the table and the ID of the record into the URL, so if SuperContainer is running on the default port of 8020 for our example 'Asset' table, your URL for record number 4321 would look like this:

http://yourServer.com:8020/SuperContainer/Files/Asset/4321

The FileMaker calculation to do this would look like this:

"http://yourServer.com:8020/SuperContainer/Files/" & Get ( LayoutTableName ) & "/" & ID

Specifying image dimensions

If you are storing images in SuperContainer, you should also specify a maximum width, maximum height, or both. This is done by appending additional parameters to your URL. If you don't specify a width or height, images are displayed at their original size. Here are some examples of URLs with width and/or height parameters:

If you always want your SuperContainer thumbnail to match the size of the web viewer it is displayed in, you can use the new GetLayoutObjectAttribute FileMaker function to dynamically calculate your height and width parameters. If you named your WebViewer layout object 'Thumbnail', you could use a URL calculation like this (split across three lines for readability):

"http://yourServer.com:8020/SuperContainer/Files/" & Get ( LayoutTableName ) & "/" & ID & "?"
& "height=" & GetLayoutObjectAttribute ( "Thumbnail" ; "height" )
& "&width=" & GetLayoutObjectAttribute ( "Thumbnail" ; "width" )

If you go into layout mode and change the size of the web viewer, the URL will adjust itself automatically! If you have a border around the web viewer, you'll need to subtract twice the border thickness from the width and height to match the size correctly. Here is what the URL would look like with a 1 pixel border:

"http://yourServer.com:8020/SuperContainer/Files/" & Get ( LayoutTableName ) & "/" & ID & "?"
& "height=" & GetLayoutObjectAttribute ( "Thumbnail" ; "height" ) - 2
& "&width=" & GetLayoutObjectAttribute ( "Thumbnail" ; "width" ) - 2

Embedding authentication username and password in the URL

If you have password-protected your SuperContainer installation and don't want users to be prompted for a username and password, you can embed this information directly into your URL. For a username of "bob" and password "secret", you can do the following:

http://bob:secret@yourServer.com:8020/SuperContainer/Files/etc...

Specifying a custom resolution

If you need to print images from SuperContainer, you can specify an optional resolution parameter, telling SuperContainer to display images as hi-res. The default resolution is 72. If you specify a different resolution, SuperContainer will return a large image, and will alter the HTML img tag to have the correct width and height.

Here is an example URL with a resolution parameter set:

http://yourServer.com:8020/SuperContainer/Files/xyz?width=64&height=64&resolution=300

If the original image is large enough, this results in an on-screen image no larger than 64x64 pixels, with a resolution of 300 DPI. If the image is not large enough, the DPI will be scaled down to no less than 72 DPI.

Supported Image Formats

SuperContainer currently supports thumbnail generation for the following image formats: bmp, jpg, gif, png, jpeg2000, raw, pnm, and tiff. Some TIFF images use a compression format that SuperContainer cannot resize. These will always be displayed as full-size images.

Customizing SuperContainer Appearance

The appearance of a SuperContainer page can be customized by setting custom style and background-color parameters in your SuperContainer URL. Some styles affect which controls are visible or hidden, others affect the layout arrangement, and others modify the font of the resource title.

"style" URL parameter

Specify a "style" url parameter to change the way a resource is displayed by SuperContainer. You can group multiple style names together with the "+" symbol. For example:

Here is a quick summary of the different styles that are available by default:

Layout Styles

(empty)

the default style looks like a container field, except there is an upload input if the resource is empty, and a delete button if it is non-empty.

listview

intended for use in list layouts, displays a small thumbnail or icon, with the filename to the right of it. All editing controls and other info are hidden. You should set width=64 and height=64 parameters in the URL when using this style, e.g. "/Asset/4321?style=listview&width=64&height=64"

image_only

hides everything except the image or file icon.

nodelete

always hides the delete button.

upload

always show the upload button (even if the resource is non-empty).

readonly

hides the delete and upload buttons.

nopreview

hides the image or icon.

info

displays a table containing the filename, filesize, and date uploaded. This causes the title to be hidden, since that is included in the table.

title

always display the title, for both images and icons (by default, the title is hidden for images)

notitle

always hide the title

nolink

disable the hyperlink for the document. Clicking on a thumbnail or document will not do anything.

Alignment Styles

left

aligns image, title, and controls to the left

right

aligns image, title, and controls to the right. There is no horizontal style to align to the center because that is the default.

center

aligns content in the center of the web viewer.

bottom

aligns content at the bottom of the web viewer. There is no 'top' style because that is the default.

Title Font Styles

small, x-small, xx-small, large, x-large, xx-large

sets the title size

bold

bolds the title

italic

italicizes the title

smallcaps

displays the title in smallcaps

See the SuperContainer Example file for a demonstration of how setting different style parameters can affect the appearance of SuperContainer.

"background-color" URL parameter

Specify a "background-color" url parameter to set the background color of the BODY. This can be handy if you're using SuperContainer on a colored background, and want unused space to blend in. Note: this is not a style parameter, but its own separate URL parameter. So you might have a URL that looks like this (with a background color of rgb(10,20,30)):

The background-color value can be a color name (green), rgb value (rgb(10,10,255)), or hex value (#336699). Note that for hex values, you'll need to escape the "#" symbol with a %23 in the URL.

Customizing SuperContainer Behavior

To disable opening a SuperContainer file in a new browser window, uncheck the Allow interaction with web viewer content checkbox in FileMaker for the Web Viewer component. You can then assign a button action to the web viewer to trigger a script when the web viewer is clicked.

SuperContainer Companion plugin

Everything outlined in this document can be done without any plugins or software to install on your user's computers. However, there are some advanced features and workflow automation that can be accomplished using the SuperContainer companion plugin, which is included with SuperContainer. See the 'documentation.html' file in the SuperContainer Companion Plugin folder for more information.

Advanced tips

Creating custom styles

Advanced users can also define custom styles by editing the custom.css file in the SuperContainer application directory. You can also contact us for support if you'd like help with customized styles.

Revision Tracking

You can control your own version tracking by appending a revision number to your SuperContainer URLs, like this:

Since SuperContainer treats each slash in your URL as a folder, this will cause it to reference the 'revision2' subfolder inside folder '4321'. By removing the delete option, you can use this to make sure that a history all files is kept.

• Always use the nodelete in your URL to prevent users from deleting any resources
• Initially, a supercontainer resource is empty, and shows an upload form
• When a user submits a resource, the upload form disappears. The nodelete style hides the delete button.
• If a user wishes to replace the resource, she clicks a button in the FileMaker layout, which you would script to increment the revision number for the current record.
• The change in the revision number changes the SuperContainer URL, so the upload form appears again.
• The file has not actually been deleted, but appears to have been. Now the users uploads a new file.
• To see historical documents which were "deleted", just decrement the version number.

See the SuperContainer Example file for a demonstration of this technique.

View Types

In the example URLs above, notice the "/Files/" portion after the application base URL. This specifies the view type to use. 99% of the time you will be using the Files view type for your URLs. If you want to return the raw data for a resource, you can use RawData instead. This can be handy if you are referencing a SuperContainer resource from another URL, or using some tool to get the contents of a supercontainer resource file. The companion plugin uses the RawData view type to pull data from SuperContainer.

Leveraging the Plugin

For fine-grained control over your workflow, you can set all your web layouts to use the readonly style, and use the plugin for all editing purposes. This allows you to build custom actions into scripts that occur whenever an item is uploaded. This makes implementing revision tracking much easier (see above). You could also utilize something like the 360works Textractor plugin to store the text of any uploaded documents in FileMaker.

Here are some example scripts you can integrate with your solutions. These illustrate error-checking best practices, and helpful ways to utilize the plugin functions.

Checking for plugin installation

If the user does not have the SuperContainer plugin installed, you may choose to exit the script, or take her to a different layout which uses a web viewer to upload/download files instead of the plugin. To check whether the plugin is installed, use the following method:

# Exit if plugin is not installed
If[SCVersion = "?"]
 Show Custom Dialog ["SuperCOntainer Plugin is not installed."]
 Halt Script
End If

Setting the base URL

You must always set the supercontainer base URL before calling other plugin methods. A good time to do this is in your startup script.

Set Variable[$result; Value:SCSetBaseURL("http://yourServer.com:8020/SuperContainer/Files")]
If [$result = "ERROR"]
 Show Custom Dialog ["Could not connect to SuperContainer Server!"; SCLastError]
End If

Example upload dialog

Use the following script to upload a file to SuperContainer using the plugin. This shows a file chooser dialog. When a file is selected, it is uploaded to SuperContainer, and the web viewer is refreshed to show the new file. This demonstrates usage of the plugin functions SCChooseFile, SCSetContainer and SCLastError. Note that you need to give your web viewer a name ("webviewer" in this example) for the Set Web Viewer script step to work correctly.

# Do the upload
Set Variable [$result; Value:SCSetContainer(Get ( LayoutTableName ) & "/" & ID ; SCChooseFile)]
# Check for error during upload
If [$result = "ERROR"]
 Show Custom Dialog ["Could not upload file"; SCLastError]
End If
# Refresh the web viewer to show the new file
Set Web Viewer [Object Name: "webviewer"; Action: Reset]

Example download dialog

If you wish to open a SuperContainer file locally instead of opening it in the user's browser, you can use the plugin to look for the file on a mounted volume, or download it to the user's local hard drive. You might make the web viewer a button which triggers the following script to download the file. The following script demonstrates uages of the plugin functions SCGetFileURL and SCDownload.

Set Variable[$folderPath; Value: Get ( LayoutTableName ) & "/" & ID]
If [IsEmpty ( SCGetInfo($folderPath) ) ]
 # There is no file to open
 Exit Script
End If
Show Custom Dialog ["Do you want to open the file in your web browser, or download it to your local drive?"]
If [Get(LastMessageChoice) = 1]
 # Open in web browser. Note we reference "RawData" instead of "Files"
 Set Variable [$url; Value: "http://myServer.com:8020/SuperContainer/RawData/" & $folderPath]
Else If [Get(LastMessageChoice) = 2]
 # Download a local copy of the file and open that. This will be a "file://" url.
 Set Variable [$url; Value: SCDownload( $folderPath )]
 If [$url = "Error"]
 Show Custom Dialog ["An Error occurred while download the file" ; SCLastError]
 Exit Script
 End If
Else
 # User clicked 'cancel'
 Exit Script
End If
Open URL [$url]

Portals

Web Views cannot be embedded in portal rows. If you want to display SuperContainer files in a portal, create an unstored calculation in the portal table whose type is "container". Set the calculation to LeftValues ( SCGetInfo("path/to/my/record" ) ; 1 ). This calculation will use the plugin to display the name of the resource in the portal. <p> If you're sure that only images will be used in a container and you want to display thumbnail views of the images, you can use the following calculation instead: SCGetContainer("path/to/my/record" ; 64 ; 64). Adjust the path, width, and height for your needs. The drawback with this is, if the container contains non-image data, the entire file will be downloaded each time the portal is displayed!

Tying into FileMaker account privileges

By default all FileMaker users have equal access to SuperContainer. Even if a user has read-only access in FileMaker, SuperContainer has no way of knowing that, unless you specify additional parameters in the URL.

To disable uploading and deletion for FileMaker users with read-only access, you can use a calculation like this to generate your SuperContainer URL:

"http://yourServer.com:8020/SuperContainer/Files/" & Get ( LayoutTableName ) & "/" & ID & "?style=" &
If (Get(PrivilegeSetName) = "[Read-Only Access]" ; "readonly" ; "")

The above appends a "readonly" style name if the FileMaker user is in the Read-Only Access privilege set. You can also use this technique to allow all users to upload, but only admins to delete (by using the nodelete style).

Integrating with or migrating from other FileMaker databases

Importing legacy container data into SuperContainer

If you are migrating an existing FileMaker solution to use SuperContainer, you need a way to move your existing container fields over to SuperContainer. You can accomplish this by using the SuperContainer Companion Plugin. Simple write a script that loops through your records and call SCSetContainer("Asset/" & Asset::ID ; Asset::OldContainerField) for each record you wish to move over. See the Companion Plugin documentation for more details, or watch a video demonstrating how to do this at http://www.360works.com/supercontainer/demos/set_container/

Importing SuperContainer resources from the file system

If you have a directory full of files you wish to add to SuperContainer, you can either copy them to the directory where SuperContainer stores its files, or use the companion plugin function SCScanDirectory to return a list of files in a directory. You can optionally set a flag to scan for files recursively. See the Companion Plugin documentation for more details.

Support

You can contact 360Works at (770) 234-9293, or on our website at http://www.360works.com. We include one hour of support with all products that we sell, with the exception of Developer licenses. After that time, our standard hourly rate ($135 at the time of this writing) applies to all support.