OpenSave

A button widget that provides file "save" and file "open" capabilities without relying on server interaction.

Integrating simple "save as" and "open file" functionality into a web page is, well, nearly impossible. Even with the new HTML 5 features, "save" and "open" are not quite "there". Plus local storage is far different from the traditional "save".

What we need are just the basics. Something that allows for classic application "save" and "open"!

OpenSave is a small AS3 Flash-based button widget that you can easily incorporate into your web page to provide basic save and open functionality.

Key Features

- Grab data from a page, then present the user with a system "Save As..." dialog window so the user can save the data to their local PC.

- Load a local file into the page using the operating system's "Open" dialog. The loaded file can be presented into the page, or handled differenlty (depending on the developer's needs) through javascript / AJAX.

See the EXAMPLES.html file for, well, examples of how to include a button into the HTML of your pages.

Button Options (quick reference)

Option

Example

width

100

REQUIRED

height

30

REQUIRED

url

"http://www/path/to/file.jpg"

url OR dataID REQUIRED

dataID

"HTMLelementID"

url OR dataID REQUIRED

buttonDiv

"HTMLelementID"

USUALLY REQUIRED

kind

"open" Defaults to "save", so you only need to use this when creating an "open" button.

OPTIONAL

swf

"http://www/path/to/opensave.swf"

OPTIONAL

handler

javascriptFunction

OPTIONAL

label

"Text to appear on button"

OPTIONAL

textColor

"#FFFFFF"

OPTIONAL

textSize

16

OPTIONAL

image_up

"http://www/path/to/button_up.png"

OPTIONAL

image_down

"http://www/path/to/button_down.png"

OPTIONAL

image_over

"http://www/path/to/button_over.png"

OPTIONAL

attach

true

OPTIONAL

custom

whatever

OPTIONAL

onComplete

javascript function

OPTIONAL

onError

javascript function

OPTIONAL

onCancel

javascript function

OPTIONAL

onProgress

javascript function

OPTIONAL

Button Option Details

kind

Establishes the kind of button you are using.

Set to "open" to make a button that loads data (from a handler) or opens a file from the user's local machine.
Set to "save" to make a button that pops up a dialog to save the data as a file on the user's local computer.

By default, buttons are set up as "save" buttons, so you'll only have to include this option if you are creating an "open" button.

width
height

Duh

url

The URL to the file the button will download to the users machine.

For use with "open" buttons only. (The "kind" option must be set to "open" in order to use this option.)

This option over-rides the "dataID" option. Meaning that if you have the "dataID" option set, AND this "url" option set, then the "url" option will be used and the "dataID" option will be ignored.

dataID

The HTML element on your page that the button will use to:

1. For "save" buttons:
Grabs the text-data out of this HTML element and saves the data to the user's computer.

2. For "open" buttons:
Loads the text-data from a file selected by the user into the HTML element.

The "dataID" refers to the HTML element's "id" attribute.

Example:
<div id="myDataContainer">Here's my data</div>

To configure a button to use the DIV above as the thing we "save from", or "load into", set "dataID" as:
dataID: "myDataContainer",

The HTML element may be any kind of HTML element including DIV, P, SELECT, INPUT etc. For FORM-based elements, Opensave set's the "value" (rather than the "innerHTML"). Whereas other elements, such as DIV or P, Opensave uses the "innerHTML" (e.g. the stuff in between the opening <tag> and closing </tag>).

handler

A user-defined javascript function that handles data IO.

Rather that relying on the HTML objects on the page to "save from" or "load into", you can employ various other javascript or AJAX methods to get or set the data.

For example, if you want to pull some txt from a remote server, or push the user's file to your server, you can leverage the "handler" option to act as a liaison between the button, and your server.

The "handler" can be used with both "save" and "open" buttons.

For "save" buttons

Opensave sends the handler the button's id:

handler(buttonID)

And your javascript must send back an object of the following shape:

For local/string data:

var returnedObject = new Object();// the default filename to use in the pop-up dialog.
returnedObject.filename = "whatever.foo";
returnedObject.data = "the text data";

The buttonID is a unique value that is automatically generated for each button, and will change each time new button is created. You can use the "custom" fields to store your own information as needed into each button. And you can use "opensave.getButtonInfo(buttonID)" to access the custom field and/or other button information.

See "opensave.getButtonInfo()" in the API section for how to gain access to each button's configuration, setup and fields. See the "custom" option description below for information on how store custom information into each button.

For "open" buttons

Opensave sends your function the contents of the file. Opensave sends an object as the argument into the function:

handler(objectData)

Where objectData contains 3 fields:

objectData.idThe button ID, which can be used in conjunction with the "opensave.getButtonInfo()" API to review the button's configuration and setup stuff.

objectData.filename The basename.ext of the loaded file (full system path is not available).

Opensave uses swfobject to render the buttons on the page. The process of rendering a button involves establishing a DIV on the page that will be used as a "placeholder", when Opensave recieves a request to make a button (opensave.make) the button replaces the "placeholder" DIV tag with the button. In other words, the DIV tag is removed from the page, and the code required to render the button replaces the DIV tag.

This situation is useful for a number of reasons:
1. Allows for designers to position the button on the page effectively (using the placeholder DIV).
2. Allows for the buttons to render after the page is loaded fully, which provides for faster perceived page rendering.
3. Ensures the button gets rendered int he proper place.
4. Ensures the DOM (and target DIV) is ready prior to rendering the button.

If you're using a text-field as your primary IO, you can use the "attach" option to render the button directly below the text-field automatically. This allows you to not have to deal with creating a separate DIV on your page manually, plus you don't have to use the buttonDiv option.

NOTE: If using the "attach" option, buttonDiv is not required, and will be ignored.

swf

Define the URL to the opensave.swf file on a 'per-button" basis. Or use this option so that you don't have to fiddle with editing the opensave.js javascript file.

kind

Since opensave can be used to both open files and save files, we need a wayto determine what kind of button we're trying to use.

By default, all buttons are set up automatically as "save" button. So this option is only required if you are making an "open" button.

label

The text to display on the button.

textColor

The color of the text label.

textSize

The size of the text label.

image_up
image_down
image_over

Custom button graphics rather than the standard, build-in button shape/design.

image_down and image_over are optional. Meaning that you can just use image_up, without including image_down or image_over.

When using this option, be sure to use proper URLs to the image files. See the "Proper URLs" section for more info.

attach

Attach a button to an HTML element.

Use the "attach" option to render a button directly below the HTML element that you are using to load/save data to/from as defined for the "dataID" option.

This option allows you to not have to deal with creating a separate "placeholder" DIV for the button on your page manually, plus you don't have to use the buttonDiv option at all.

NOTE: If using the "attach" option, buttonDiv is not required, and will be ignored.

custom

A custom field, where you can store any kind of data (string, array, object, etc) into the button for future use.

onComplete

A function that get's pinged after this event occurs. Returns one argument, which is the configuration setup for the button. See the EXAMPLE.html in the download ZIP for example usage.

onError

A function that get's pinged after this event occurs. Returns one argument, which is the configuration setup for the button. See the EXAMPLE.html in the download ZIP for example usage.

onCancel

A function that get's pinged after this event occurs. Returns one argument, which is the configuration setup for the button. See the EXAMPLE.html in the download ZIP for example usage.

onProgress

A function that get's pinged after this event occurs. Returns 3 arguments: the configuration setup for the button, total bytes, loaded bytes. See the EXAMPLE.html in the download ZIP for example usage.

API (function reference)

opensave.getButtonInfo(theButtonID);

Returns an object containing the following fields:

confObj.swf
confObj.kind
confObj.handler
confObj.id
confObj.width
confObj.height
confObj.buttonDiv
confObj.attach
confObj.dataID
confObj.url
confObj.kind
confObj.flashvars
confObj.custom
confObj.filename // Established filename, or loaded file's actual filename.
confObj.data // If the button hasn't been clicked yet, this field will be null. Otherwise, this field will contain the data from a file loaded by the user via "open". If the user has clicked the button (saved), this field will get populated with the contents of the HTML element with the id attribute in the page defined by the "dataID" option.

Proper URLs

We highly recommend using "from the root" URLs to all files associated with Opensave. Including all of the Opensave files set up in your HTML and any file URLs used within the buttons.

A "from the root" URL (root URL) is similar to using a full URL. The difference is that the domain is lopped off.

For example, a full URL looks like:

http://www.yoursite.com/path/to/file.html

Whereas a root URL looks like:

/path/to/file.html

Where the URL starts with a "/" slash character. This is a sort of short-cut type URL that instructs the browser to "start at the "root" of the website.

Using a root URL allows for Opensave to be used on any page throughout your site. Plus minimizing any crazy issues with Flash's built in security features that sometimes prohibit operations across sub.domains. For example, accessing a file or page where the "www" is not used in the URL.

For example, when a user accesses your page using the following URL:

http://yoursite.com/page.html

... and the button is configured to download a file using the "www" as:

http://www.yousite.com/file.zip

... a potential security risk is flagged by Flash, preventing the file from downloading since the request was made from "yoursite.com", while the file resides on "www.yoursite.com" (with "www").