SuperContainer Companion Plugin/Documentation

SuperContainer Companion Plugin User Guide

This plugin does not have to be installed to use the 360Works SuperContainer Web Viewer add-on, but it allows you to automate certain features that would normally require user interaction.</p> The plugin supports uploading container fields into SuperContainer, or downloading into a local container field from SuperContainer. In addition, there are methods for deleting a file stored in SuperContainer, download files to the local drive, and for getting details about a file stored in SuperContainer.</p> This plugin is particularly useful for migrating data from container fields in an existing solution into SuperContainer.</p> Note: Instant Web Publishing clients should not use the plugin to upload files, because for IWP the plugin is on the server, so it can only access files on the server. This is probably not what you want! Instead, IWP clients should upload file via a web viewer which is placed on a layout. Your solution might have a separate layout for IWP uploads. </p> Important: you must call SCSetBaseURL before calling any plugin functions which interact with the SuperContainer server, passing the location of the server. We've disabled IWP plugin uploads in the SuperContainer Example.fp7 file which is included in the download.</p> For example, if you are running the standalone SuperContainer server on your development machine, call this:</p>

SCSetBaseURL("http://server.mycompany.com:8020/SuperContainer/Files")

Note that you pass the complete URL, up to the "Files" component. All other plugin functions accept a relative folder path as a parameter (NOT a complete URL). This is the folder on the server where the file is stored, or where you want it to be stored. It should not include the SuperContainer host, port, or action name. For example:

SCGetContainer("staff/portraits/42")

Generally you will want to call SCSetBaseURL in your startup script. Once the plugin knows the complete URL to your server, the rest of the plugin functions only need to know the relative path on the server.

One thing to watch out for when using the plugin: Sometimes a plugin script will return before SuperContainer has finished processing the last action. So you might upload a file with the SCSetContainer plugin function, then immediately call SCGetInfo before the previous action has completed. One solution is to just put a pause script step in between the two actions.

Consult the SuperContainer documentation (Leveraging the Plugin) for several example usages of the Plugin Functions.

The companion plugin should work with container references as well as as stored container fields.

360Works Plugin Setup Guides

See Plugins_101 for Error reporting, installation, registration, and more.

Function Summary

• SCChooseFile ( { initialPath ; fileType ; title ; [ key1=value1 ; key2=value2 ; ... ] } ) — Shows a file chooser dialog where a user can browse her local hard drive.
• SCClearLocalCache ( ) — Removes any locally cached temporary files which were downloaded by the SuperContainer companion plugin.
• SCCopy ( folderPath ; destinationPath {; filename } ) — Copies a file on the SuperContainer server to a new location within the SuperContainer directory.
• SCDelete ( folderPath ) — Deletes the SuperContainer file with the given folder path.
• SCDeleteLocalFile ( localFile ) — Deletes a file from the local filesystem.
• SCDownload ( folderPath { ; destinationFolder ; width ; height; key1=value1; key2=value2; ... } ) — Download a file from the SuperContainer server to another location, unless the file already exists and is up-to-date with the version on the server.
• SCGetContainer ( folderPath {; width ; height ; resolution ; page} ) — Fetches the contents of a SuperContainer file as container data.
• SCGetFolderURL ( macPath; winPath; folderPath ) — Fetches the stored file's folder location as a URL pointing to a mounted/mapped file server.
• SCGetInfo ( folderPath { ; additionalFields } ) — Returns meta-information about a supercontainer file, such as the filename, size, height, width, dimension, and date uploaded.
• SCLastError ( ) — Whenever a plugin function fails, it will return the string "ERROR".
• SCMove ( oldFolderPath ; newFolderPath {; filename } ) — Moves a file on the SuperContainer server, without downloading it.
• SCMoveLocalFile ( sourceFile; destinationFile ) — Moves file locally from sourceFile to the destinationFile.
• SCScanDirectory ( path {; recursive } ) — Scan a local directory for files.
• SCSetBaseURL ( superContainerUrl { ; username ; password ; key1=value1 ; ... } ) — Set the location of the supercontainer server instance to be used by the plugin.
• SCSetContainer ( folderPath ; data {; filename=xyz.jpg ; showProgress=false ; ... } ) — Pushes data from a FileMaker container field to a SuperContainer file, overwriting the SuperContainer file if it exists.
• SCSetErrorCapture ( errorCapture ) — Toggles error dialogs on or off.
• SCVersion ( ) — Returns the version number of the SuperContainer companion plugin.

Function Detail

SCChooseFile ( { initialPath ; fileType ; title ; [ key1=value1 ; key2=value2 ; ... ] } )

Shows a file chooser dialog where a user can browse her local hard drive. When the user selects a file or directory and clicks "OK" on the file chooser, this function returns the path to the selected file or directory. If the user hits the cancel button, nothing is returned.

File Type

By supplying a fileType parameter, you can allow the user to just select files, just select directories, or select both files and directories. The default behavior is to only allow file selection.

When selecting files, you can combine this function with SCSetContainer to import a single file from a user's hard drive to SuperContainer. For example, the following code uploads a local file of the user's choice to the SuperContainer server:

SCSetContainer(Asset::ID ; SCChooseFile);

When selecting directories, you can combine this function with SCScanDirectory to batch-import the contents of a directory. The following example prompts the user to select a directory, then scans that directory recursively (returning a list of all files in the directory).

SCScanDirectory ( SCChooseFile("" ; "directories" ) ; true)

NOTE: specifying a fileType of "directories" or "files + directories" will cause a non-native file dialog to be used on some platforms, as the native dialogs may not support directory selection.

Parameters:

initialPath

optional path to set the initial dialog selection to. If empty, will default to the user's home directory.

fileType

whether to allow "files", "directories", or both "files + directories"

title

optional title string to display as the title of the FileChooser dialog

keyValuePairs

optional key=value pairs. Options: useNative, which you can set to false to use a Java file dialog instead of a native file dialog.

Returns: Path to the selected file, nothing if no file was selected, or "ERROR" if an error occurred.

SCClearLocalCache ( )

Removes any locally cached temporary files which were downloaded by the SuperContainer companion plugin. This will only delete files in the temporary directory. The SuperContainer companion plugin saves temporary files when SCGetContainer is called without specifying a destination path. These are saved in the tmp directory.

Returns: 1 if all temporary files were successfully deleted, or "ERROR" if one or more files could not be removed.

SCCopy ( folderPath ; destinationPath {; filename } )

Copies a file on the SuperContainer server to a new location within the SuperContainer directory. This is useful if you want to move a file somewhere without losing the reference to the original.

If there is no file at folderPath, this function will return an error.

Important: You must call SCSetBaseURL before calling this function to set the location of your SuperContainer server.

Parameters:

folderPath

The folderPath of the file to copy

destinationPath

The folderPath of where you want to copy the original file to

keyValuePairs

optional key=value pairs. Options: filename, example filename=myNewName.txt.

Returns: 1 if the file was successfully copied, or "ERROR" on failure.

SCDelete ( folderPath )

Deletes the SuperContainer file with the given folder path. If there is no file at this folderPath, nothing is changed on the server. Important: You must call SCSetBaseURL before calling this function to set the location of your SuperContainer server. To delete a file from the local filesystem, use the SCDeleteLocalFile function instead.

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

Parameters:

folderPath

the unique identifier for a supercontainer file.

Returns: 1 if the file was successfully deleted or did not exist, or "ERROR" on failure.

SCDeleteLocalFile ( localFile )

Deletes a file from the local filesystem. This may be used as part of a batch import process, to delete files after they are successfully uploaded to SuperContainer. NOTE: Be sure to check for successful upload before deleting the local files!

To delete a file from the SuperContainer server, use the SCDelete function instead.

Parameters:

localFile

path to the local file to delete

Returns: 1 if the file was successfully deleted, "" if the file did not exist, and "ERROR" if the file existed but could not be deleted.

SCDownload ( folderPath { ; destinationFolder ; width ; height; key1=value1; key2=value2; ... } )

Download a file from the SuperContainer server to another location, unless the file already exists and is up-to-date with the version on the server. If this is called multiple times for the same file, it is not downloaded again unless the file has changed on the server.

NOTE: If no destinationUrl is provided, the downloaded file will be stored in the user's temp directory, and will be deleted from the user's local drive when FileMaker exits.

Use caution when supplying a custom path, as this method will overwrite files with the same name!

Since this function returns a URL, it can be combined with the Open URL script step to open the downloaded file, for example:

Open URL [SCDownload("Photos/12345")]

Flags

The following flags are valid for this function:

• showSaveDialog: set this if you want a save dialog to pop up
• checkForFile: set this is you want to be warned if file exists. if "showSaveDialog" is set, this defaults to false because native save dialogs check for you.(only applies if showSaveDialog is false
• filename: Change the filename of the downloaded file (automatically removes any leading spaces in the filename - be sure to include your file extension, such as .txt or .pdf!).
• progress: Disable the progress bar by passing in false.
• returns: Specify what file path type you wish to be returned (fmpath, filepath)

NOTE: if specifying an additional parameter like filename, the destinationFolder, width, and height are then required, because these parameters are positional. Example:

SCDownload ( "Photos/Original/" & Photos::Photo ID ;  // Folder Path
Get( DesktopPath ) & "MyPhotos/" ; // Destination folder
0 ; 0 ; //width & height parameters
"filename=" & $fileName ; "returns=filepath" )

Important: You must call SCSetBaseURL before calling this function to set the location of your SuperContainer server.

Parameters:

folderPath

The unique SuperContainer path

userDefinedDestPath

Optional URL or FileMaker path of the folder to download the file to (ie. /Macintosh HD/Users/Shared/Images)

width

Optional integer for pictures that represents the width of the image. If a width/height is specified, non-image resources will only download a filename, not the entire file.

height

Optional integer for pictures that represents the height of the image. If a width/height is specified, non-image resources will only download a filename, not the entire file.

flags

optional key=value pairs. Options: selfSignedSSL, returns, filename; example selfSignedSSL=1.

Returns: The URL the file was downloaded to. If the file does not exist or some other error occurred, then "ERROR" will be returned.

SCGetContainer ( folderPath {; width ; height ; resolution ; page} )

Fetches the contents of a SuperContainer file as container data. This function is intended for use with exporting the contents of a SuperContainer file to a container field in FileMaker. If you want to display an image or other file within your FileMaker database, you should use a Web View layout element and reference SuperContainer directly instead of using this function. If there is no file at this folderPath, an empty result is returned. Important: You must call SCSetBaseURL before calling this function to set the location of your SuperContainer server.

Parameters:

folderPath

the unique identifier for a SuperContainer file.

width

optional width parameter. If the SuperContainer file is an image, it will be resized to this width. Pass in 0 to leave width unconstrained.

height

optional height parameter. If the SuperContainer file is an image, it will be resized to this height. Pass in 0 to leave height unconstrained.

resolution

optional resolution parameter. If the SuperContainer file is an image, the jpeg preview for it will be rendered at the specified resolution. If omitted the default resolution of 72dpi wil be used.

Returns: Container data if successful, nothing if there is no file at that path, or "ERROR" on failure.

SCGetFolderURL ( macPath; winPath; folderPath )

Fetches the stored file's folder location as a URL pointing to a mounted/mapped file server. Note that this does not download anything from the SuperContainer server; it returns a URL pointing to the folder stored directly on the SuperContainer server. This is useful to combine with the "Open URL" script step in Filemaker to allow browsing of stored resources.

Important: You must call SCSetBaseURL before calling this function to set the location of your SuperContainer server. NOTE: A mounted or mapped filesystem-accessible storage location is required to open referenced folder. Otherwise, you should download the file to the local hard drive using SCGetContainer and open it there.

Parameters:

macPath

Mac OS X path to root SuperContainer storage location

winPath

Windows to root SuperContainer storage location

folderPath

The unique identifier for a SuperContainer file folder

Returns:

SCGetInfo ( folderPath { ; additionalFields } )

Returns meta-information about a supercontainer file, such as the filename, size, height, width, dimension, and date uploaded.

The result has at least three values separated by line breaks:

• The file name
• The size (in bytes) of the file
• The date the file was uploaded to SuperContainer

You can specify additional metadata to retrieve by passing additional arguments to this function. See the 'additionalFields' documentation below for details.

MD5 Hash

Pass "md5" as an additional argument to return the MD5 hash of the file in the function result. This can serve as the fingerprint for a digital file, and can be used to help catch duplicate files, or ensure the integrity of a file. For example:

SCGetInfo("/photos/12345" ; "md5"; "width"; "height")

Might return:

Lucy.jpg
51231
4/8/08 3:02:56 PM
c7f47955c825ed83dfe2a6a2fac1a092
640
480

(the fourth line is the MD5 hash) If there is no file at this folderPath, an empty result is returned. Important: You must call SCSetBaseURL before calling this function to set the location of your SuperContainer server.

Parameters:

folderPath

the unique identifier for a supercontainer file.

additionalFields

either md5, height, width, dimension, or pagecount.

Returns: The requested data, or empty if the file does not exist, or "ERROR" on failure.

SCLastError ( )

Whenever a plugin function fails, it will return the string "ERROR". You should call this function to get a user-readable description of whatever caused the last error. Here is an example of how to use it:

If [ SCSetContainer( Asset::ID ; theContainer ) = "ERROR" ]
	Show Custom Dialog ["Could not store this file"; SCLastError]
End If

Returns: error message text

SCMove ( oldFolderPath ; newFolderPath {; filename } )

Moves a file on the SuperContainer server, without downloading it. This is useful if a folderPath changes for some reason in FileMaker, and you want to move the associated SuperContainer file.

If there is no file at oldFolderPath, this function will return an error.

Important: You must call SCSetBaseURL before calling this function to set the location of your SuperContainer server. To move a file on the local filesystem, use the SCMoveLocalFile function

#Do the move
Set Variable [$result; Value:SCMove( Get( LayoutTableName ) & "/" & ID ; Get( LayoutTableName ) & "/" & DestID; "filename=New Word Document.docx")]
#Check for error during move
If [$result = "ERROR"
		Show Custom Dialog ["Could not move file"; SCLastError]
End If
# Refresh the web viewer to show the new file
Set Web Viewer [Object Name: "webviewer"; Action: Reload]

Parameters:

oldFolderPath

The old folderPath of the file to move

newFolderPath

The folderPath to move the file to

keyValuePairs

optional key=value pairs. Options: filename, example filename=myNewName.txt.

Returns: 1 if the file was successfully moved, or "ERROR" on failure.

SCMoveLocalFile ( sourceFile; destinationFile )

Moves file locally from sourceFile to the destinationFile. This is a convenience function that doesn't communicate with the SuperContainer server at all. You might use this function to move files out of a watch directory after uploading them to SuperContainer with the SCSetContainer function.

To move a file on the local SuperContainer server, use the SCMove function.

Parameters:

sourceFile

file or directory to be moved

destinationFile

file or directory which sourceFile is to be moved to

See also: SCScanDirectory, SCMove

Returns: FMType 1 if the file is successfully moved, or "ERROR" if the files could not be moved.

SCScanDirectory ( path {; recursive } )

Scan a local directory for files. You can use this to get a list of all files in a directory, then iterate over the list in FileMaker, adding files to a SuperContainer instance with the SCSetContainer function.

Parameters:

path

path to the directory to scan

recursive

Pass in 1 to recurse into sub-directories, or pass 0 or empty to only return files in the top level directory. Does not recurse into sub-directories if this parameter is omitted.

See also: SCMoveLocalFile

Returns: a list of all files beneath the indicated directory, excluding directories, or "ERROR" on failure.

SCSetBaseURL ( superContainerUrl { ; username ; password ; key1=value1 ; ... } )

Set the location of the supercontainer server instance to be used by the plugin. You must call this function before calling any plugin functions which access the SuperContainer server! If you are running the standalone SuperContainerServer on your machine, you can use localhost as the hostname:

SCSetBaseURL("http://localhost:8020/SuperContainer/Files")

When using for live deployment, you should supply an actual hostname of IP address of the machine which will be running the shared SuperContainer instance. For example:

SCSetBaseURL("http://server.mycompany.com:8020/SuperContainer/Files")

If you supply a valid URL but there is not a running SuperContainer server at the host provided, the base URL will still be set, but an "ERROR" failure code will be returned (use SCLastError to get a detailed error message). Remember that the default port number is 8020 for the standalone SuperContainer server, and 80 when deploying with FileMaker Server.

Typically, you should call this function in a startup script in your FileMaker database. It only needs to be called once per FileMaker launch, or anytime that the base URL changes. NOTE: If specifying named parameters like selfSignedSSL, the username and password fields are required because these parameters are positional. If username/password are unused, insert empty quotes ("") instead. For example:

SCSetBaseURL("http://localhost:8020/SuperContainer/Files" ; "" ; "" ; "selfSignedSSL=1")

Parameters:

superContainerUrl

The URL of the superContainer instance to be used by the plugin, e.g. http://fmpro.example.com:8020/SuperContainer/Files.

username

optional username. If your SuperContainer server is set up with password protection, enter the username here.

password

optional password. If your SuperContainer server is set up with password protection, enter the password here.

keyValuePairs

optional key=value pairs. Options: selfSignedSSL, example selfSignedSSL=1.

Returns: 1 on success, ERROR on failure (because of an empty or invalid URL).

SCSetContainer ( folderPath ; data {; filename=xyz.jpg ; showProgress=false ; ... } )

Pushes data from a FileMaker container field to a SuperContainer file, overwriting the SuperContainer file if it exists.

NOTE: If the data parameter is empty, this will not delete the superContainer file, use the SCDelete function instead. Important: You must call SCSetBaseURL before calling this function to set the location of your SuperContainer server. If you want to update the web viewer on a layout to show the newly uploaded file, add a "Set Web Viewer [Action: Reload]" script step to the upload script. This will cause an immediate update to be triggered.

Optional Parameters

The following can be passed as additional parameters to the SCSetContainer function:

filename

use filename=desired_name to provide desired filename for the file.

showProgress

use showProgress=false to hide the progress bar during upload.

Example:

Set Variable[$result =
    SCSetContainer(
        "Documents/D23" ;
        Documents::Legacy Container ;
        "filename=newName.txt" ;
        "selfSignedSSL=1" ;
    )
]

#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: Reload]

Parameters:

folderPath

the unique identifier for a supercontainer file.

data

the data to be stored, typically a container field. Can also be a URL (ie. http://server/someFile or file:///Users/Shared/aFile) or a File path (ie. /Macintosh HD/Users/Shared/aFile or C:\Documents and Settings\aFile)

params

Additional optional parameters (filename)

Returns: 1 on success, or "ERROR" on failure.

SCSetErrorCapture ( errorCapture )

Toggles error dialogs on or off. When something unexpected happens, the plug-in will pop up a dialog displaying the error message. This makes it easy to see what went wrong. However, in some cases, you (the developer) may prefer to show your own message to the user, or possibly not show a message at all. In that case, you can call SCSetErrorCapture with a parameter of true. That will suppress the error dialog from appearing to the user.

Parameters:

errorCapture

set to true to suppress the default popups.

SCVersion ( )

Returns the version number of the SuperContainer companion plugin.

Returns: the version number, e.g. 1.32.