Table of Contents
Developer Reference / AOS API Document / SNS
Storage Navigation Service (SNS)
Description:
Unlike an API, SNS is a service allowing other AO modules to pop up a browser window that the end-user can use to navigate the storage area. The purpose is to select files or folders for further processing, or select a location to place a file (save a file).
This document talks about How to use SNS, Sample SNS Usage and SNS User Interface.
How to use SNS
Unlike Storage API, No CGI script is called directly for SNS. Instead, all communication between the caller and the SNS is via JavaScript. The caller will need to first include a JavaScript chunk from snsglue.js using a HTML tag similar to the following.
<SCRIPT LANGUAGE="JavaScript" SRC="http://aoimg.com/storage/js/snsglue.js"> </SCRIPT>
snsglue.js has the necessary functions to create an “SNS object” with a set of properties and a methods. You must create an SNS object first before the SNS window can be popped-up. You create an SNS object by this javascript statement:
/ / Start by creating the sns obj that you intend to use
var mySNS = new sns('mySNS');
The object name “mySNS” can be any name you choose, but the only requirement is to use back the same name as the string argument to the sns( ) function.
Once the SNS object is created, you can then call mySNS.show( ) or mySNS.hide( ) and work on properties like mySNS.sid, mySNS.startFolder, etc. The properties in mySNS is usually intialize first before the show( ) method in invoke to bring up the SNS window.
The set of properties and methods available are:
Methods
| show() | Pop-up the SNS window. Safe to call this even if there is already an SNS window shown. |
| hide() | Dismiss the SNS window. Safe to call this even if there is no SNS window shown. |
| myfocus() | Give the SNS window focus (bring to the top) |
The SNS window only shows or hides when the corresponding methods are explicitly called. So, you typically have to add some code to show the SNS window in response to user action. And usually you also invoke hide( ) when callback events indicate that the user has finish navigating, or when your HTML page somehow unloads unexpectedly. However, you may not need to call focus( ) explicitly because a show( ) will implicitly call focus( ).
Properties
(The initial default values are shown in the assignments.)
| sid = ' ' | This is the mandatory session ID to identify whose storage area to navigate. |
| startFolder = '/' | The folder where navigation will start. The format is /AreaName[/path/to/item]. Example: /Private Homepage/images Trailing “/” is ignored because this is always a folder. |
| topFolder = '/' | The uppermost folder where navigation will be restricted to. The format is the same as that for startFolder. |
| filter = ' ' | Initial value for filename filter. If unspecified the default value is “*”, i.e. effectively not filtered. |
| maxCount = 1 | The maximum number of items the end-user may select. Value can be any positive integer. Can be zero, but probably not used that way. |
| limitSelectType = ' ' | The type of item (file, folder or both) the end-user may select. Valid values are 'file' or 'folder'. Leave it unassigned or assign a “” to allow selection of both file and folder. |
| listFolderOnly = 0 | The item listing will only show folders. Value is boolean sense, 0 or 1. |
| startItemNameValue = ' ' | The initial value in the Item Name field. This value can be overwritten by user by selection of keyboard editing, if allowed. This field is normally blank when using SNS to get to an item to open. On the other hand, it is usually assigned a starting name when using SNS to decide where to save a file (Save As…) |
| stickyItemName = 0 | The Item Name value will not be cleared when navigating from folder to folder. Value is boolean sense, 0 or 1. You usually want this behavior when doing a Save As… operation, so that filename to “save as” remain in the field while the user decides which folder to place it. |
| itemNameEditable = 0 | The Item Name can be edited using keyboard entry. Value is boolean sense, 0 or 1. |
| title = ' ' | String to appear in the SNS window title bar. |
| htmlHeader = ' ' | Embed this HTML chunk in the “header” of SNS window. See SNStest.html for sample usage. |
| htmlFooter = ' ' | Embed this HTML chunk in the “footer” of SNS window. See SNStest.html for sample usage. |
| upperFrameHeight = -1 | Height of the upper frame in pixels ( A negative number causes a default 70 to be used. ) User is always allowed to resize the frame. |
| lowerFrameHeight = -1 | Height of the lower frame in pixels ( A negative number causes a default 90 to be used. ) User is always allowed to resize the frame. |
| upperBodyAttr = ' ' | Additional HTML attribute to be embeded in the <BODY> tag for the upper frame. |
| lowerBodyAttr = ' ' | Additional HTML attribute to be embeded in the <BODY> tag for the lower frame. |
| maxSize = -1 | The maximum size (in bytes) of an item that can be selected. SNS will alert and prevent the end-user from selecting items that exceed this size. If multiple selection is allowed (maxCount > 1) then the total size of the selected item is limited by maxSize. The default value of -1 is taken to mean selection is not restricted by file size. |
topPos, leftPos, width, height: These properties will determine the initial position and size of the SNS window. However, the user is always allowed to resize the window.
topPos = '100';
leftPos = '100';
width = '400';
height = '250';
callback_script: This is an important property to understand. You must assign to it an appropraite JavaScript code, usually a function which you defined to handle the callbacks from the SNS. The code will be executed in an eval( ) statement. SNS will callback, and thus execurte the given code, for three events: Ok button is clicked, Cancel button is clicked, and the SNS Window has been Unloaded. The default 'return' string value for callback_script usually needs to be replaced.
callback_script = 'return';
Response properties (parameters). These are the properties that you will be interested in when SNS makes a callback. They indicate what the user did (event), the place where navigation left off (folder) and the selected items (itemNameValue), if any. DO NOT modify these properties.
folder = The path to the folder when user clicks Ok.
itemNameValue = Value in the Item Name field. Multiple items are comma separated.
event = '' Can be “Ok” or “Cancel” or “Unload”
While there are other properties and methods in the SNS objects, they are not intended to be modified or inspected by the caller. However, you may view the content of snsglue.js for further details.
Since SNS is manipulated in an object oriented manner, multiple SNS window can be active at the same time from the same application (or HTML page) or from different application. As long as the SNs object name is different there will be no conflict.
Sample SNS Usage
SNS User Interface
