|
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.
- Everything is handled "client-side", so there's no need to mess with PHP / Server headers and complicated client server POST / GETinteractions.
Examples
|
Open Text Field Button Target Div
Save Text Field Button Target Div
MP3 download place holder
|
Save Image place holder
Save Script placeholder
Download OpenSave placeholder
|
Opensave provides two "kinds" of button behaviors:
Save
Provides facilities to save either:
1. Text-based (ascii/utf8) data from an HTML element on the page.
2. Text-based (ascii/utf8) data from a javascript handler.
3. Binary or text files from **your** server using a provided URL.
(**your** - loading files from a different domain or sub.domain may not work depending on how the server and/or client system/html/javascript/firewall is configured.)
Open
Provides facilities to open a text-based file from the user's local machine.
Installation Steps
1. Define the SWF path.
Set the SWF file location to a "from the root" URL (starts with a slash).
Example:
opensave.swf = "/path/to/opensave.swf";
NOTE: You may also use a full URL such as:
opensave.swf = "http://www.yoursite.com/path/to/opensave.swf";
.. However, there may be problems with using a full URL. See "Proper URLs" below for more info.
2. Reference the Opensave Javascript
In your HTML page, include a reference to this Javascript script file.
Example:
<script src="http://www.yoursite.com/path/to/opensave.js"></script>
3. Include a button in your page
A "save" button:
<div id="saveData">Data to save comes from here.</div>
<div id="saveButton">Replaced By Button</div>
<script>
opensave.make({width: 100, height: 30, dataID: "saveData", buttonDiv: "saveButton"});
</script>
An "open" button:
<div id="openData">Data to open goes in here</div>
<div id="openButton">Replaced By Button</div>
<script>
opensave.make({kind:"open", width: 100, height: 30, dataID: "openData", buttonDiv: "openButton"});
</script>
See the EXAMPLES.html file for, well, examples of how to include a button into the HTML of your pages.
Button Options (quick reference)
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";
For downloading files (remote files):
var returnedObject = new Object();
// the default filename to use in the pop-up dialog.
returnedObject.filename = "whatever.foo";
returnedObject.url = "/path/to/file.foo";
// or
returnedObject.url = "http://www.yoursite.com/path/to/file.foo";
Example: function myOpenSaveHandler(buttonID){
var bi = opensave.getButtonInfo(buttonID);
var retObj = new Object();
if (bi.custom == "abc"){
retObj.filename = "abc.foo";
retObj.data = "The contents of ABC file.";
} else if (bi.custom == "download_file_xyz"){
retObj.filename = "xyz.jpg";
retObj.url = "http://path/to/xyz.jpg";
}
return retObj;
}
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.id
The 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).
objectData.data64
Base64 encoded file data. Use "opensave.Base64_decode" to decode the data if required.
|
buttonDiv |
The DIV that will be replaced by the button. 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.
opensave.getData(theButtonID)
Returns an object that contains two fields.
For local data, the returned object takes the shape of:
returnedObject.filename = "foo.bar"
returnedObject.data = "The HTML element's text data"
For remote files, the returned object takes the shape of:
returnedObject.filename = "foo.bar"
returnedObject.url = "http://ww.yoursite.com/path/to/file.foo" // as defined during button setup.
opensave.Base64_decode(encodedString)
Decodes the encoded string to original form.
opensave.make(configObject)
Creates a new button within the page.
The configObject may be JSON or a standard javascript object. See the "Button Options" section for required and optional fields.
We recommend reviewing the source code the the EXAMPLE.html file to see how to impliment. Here are a few extra examples:
JSON:
var jsonCof = {width: 100, height: 30, dataID: "HTMLelementID"};
opensave.make(jsonCof);
opensave.make({width: 100, height: 30, url: "http://www/path.to/file.jpg"});
Standard Javascript Object:
var jsObj = new Object();
jsObj.width = 100;
jsObj.height = 30;
jsObj.dataID = "HTMLelementID";
opensave.make(jsObj);
var jsObj = new Object();
jsObj.width = 100;
jsObj.height = 30;
jsObj.url = "http://www/path.to/file.jpg";
opensave.make(jsObj);
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").
|
OpenSave
OpenSave.zip