WebWorks File API Framework

One of the things I love about developing for BlackBerry 10 is that BlackBerry has really done well at implementing HTML5 standards (and a quick visit to http://html5test.com confirms it). While this is awesome as far as creating robust HTML5 apps is concerned, it means that developers have to learn new technologies that might not be fully implemented in your web browser. As an example, webkitGetUserMedia only recently showed up in Chrome.

The File API isn't all that new (it's been around a while now), but it's something that I couldn't find a whole lot of documentation for it. There is a very, very good article at http://www.html5rocks.com/en/tutorials/file/dndfiles/, but it's (in my opinion) a fairly involved API.

The great folks over at BlackBerry have implemented the File API, but that doesn't necessarily mean it's easy for developers to start using. And since the web is all about frameworks these days (JQuery, Sencha, etc), I figured I'd do a mini framework of BlackBerry specific File API functions to make things easy for other WebWorks Devs to implement saving and loading (including backup and restore) to their apps!

This framework is Open Source (so you can browse my typos without even downloading it), and you can check it out at My Github.

You can check out the readme in the github link to see how it works, but here's the quick how-to:

1. Include the javascript in your index.html

Example: <script type="text/javascript" src="/cssjs/bbfiles.js"></script>

2. Add the required feature IDs to your config.xml:

<feature id="blackberry.invoke.card" />
<feature id="blackberry.io" />
<feature id="blackberry.ui.toast" />

3. Create a function for whatever you want to do. Functions that are available: 

Save text to a specified file:
saveText(Text to save, save location and file name)
Example: saveText('Hello World!', '/accounts/1000/shared/misc/helloWorld.txt')

Save text to a file of the user's choice:
saveText(Text to save, location to open the file picker, 'picker')
Example: saveText('Hello World', '/accounts/1000/shared/misc/', 'picker')

Load text from a file:
loadData(location of document)
Example: loadData('/accounts/1000/shared/misc/helloWorld.txt')

Load text from a file of the user's choice:
loadData(location to open the file picker, 'picker')
Example: loadData('/accounts/1000/shared/misc/', 'picker')

Delete a specified file:
deleteFile(file location and name)
Example: deleteFile('/accounts/1000/shared/misc/helloWorld.txt')

Delete a file of the user's choice:
deleteFile(location to open the file picker, 'picker')
Example: deleteFile('/accounts/1000/shared/misc/', 'picker')

Create a folder:
createFolder(folder to create)
Example: createFolder('/accounts/1000/shared/misc/New')

Delete a folder:
deleteFolder(folder to delete)
Example: deleteFolder('/accounts/1000/shared/misc/New')

Move a file:
moveFile(location to move the file to, current file location and name)
Example: moveFile('/accounts/1000/shared/misc/downloads/', '/accounts/1000/shared/misc/helloWorld.txt')

Move a file of the user's choice:
moveFile(location to move the file to, location to open the file picker, 'picker')
Example: moveFile('/accounts/1000/shared/misc/downloads/', '/accounts/1000/shared/misc/', 'picker')

Move and Rename a file:
moveRenameFile(location to move the file to, current file location and current file name, new name)
Example: moveRenameFile('/accounts/1000/shared/misc/downloads/', '/accounts/1000/shared/misc/helloWorld.txt', 'newFile.txt')

Move and Rename a file of the user's choice:
moveRenameFile(location to move the file to, location to open the file picker, new name, 'picker')
Example: moveRenameFile('/accounts/1000/shared/misc/downloads/', '/accounts/1000/shared/misc/', 'newFile.txt', 'picker')

Copy a file:
copyFile(location to move the file to, current file location and file namee)
Example: copyFile('/accounts/1000/shared/misc/downloads/', '/accounts/1000/shared/misc/helloWorld.txt')

Copy a file of the user's choice:
copyFile(location to move the file to, location to open the file picker, 'picker')
Example: copyFile('/accounts/1000/shared/misc/downloads/', '/accounts/1000/shared/misc/', 'picker')

Copy and Rename a file:
copyRenameFile(location to copy the file to, current file location and current file name, new name)
Example: copyRenameFile('/accounts/1000/shared/misc/downloads/', '/accounts/1000/shared/misc/helloWorld.txt', 'newFile.txt')

Copy and Rename a file of the user's choice:
copyRenameFile(location to copy the file to, location to open the file picker, new name, 'picker')
Example: copyRenameFile('/accounts/1000/shared/misc/downloads/', '/accounts/1000/shared/misc/', 'newFile.txt', 'picker')

Rename a file:
renameFile(file location and current name, new name)
Example: renameFile('/accounts/1000/shared/misc/helloWorld.txt', 'yay.txt')

Rename a file of the user's choice:
renameFile(file location, new name, 'picker')
Example: renameFile('/accounts/1000/shared/misc/', 'yay.txt', 'picker')

Save Canvas to an image:
saveCanvas(canvas element, location and name you want to save canvas to)
Example: saveCanvas(document.getElementById('canvas'), '/accounts/1000/shared/misc/image.png')

Save Canvas to an image of the user's choice:
saveCanvas(canvas element, location to open the file picker, 'picker')
Example: saveCanvas(document.getElementById('canvas'), '/accounts/1000/shared/misc/', 'picker')

Load image to Canvas:
loadCanvas(canvas element, image to load', 'nopicker', width you want image to load, height you want image to load)
loadCanvas(document.getElementById('canvas'), '/accounts/1000/shared/misc/image.png', 'nopicker', 500, 300)
Note: 'nopicker' can be any text except 'picker'. It is optional, unless you specify a height and width (which are also optional).

Save image of the user's choice to Canvas:
loadCanvas(canvas element, location to open the file picker, 'picker', width you want image to load, height you want image to load)
loadCanvas(document.getElementById('canvas'), '/accounts/1000/shared/misc/', 'picker', 500, 300)

That's it! Maybe not as simple as simple can get, but a lot better than writing the function out yourself :)

Shane Cridlebaugh

Co-founder and legal nay-sayer of OSBB. Owner of SCrApps Application Development, WebWorks aficionado, Open Source contributor. SCrid2000 on most blogs. I build awesome BlackBerry apps when I'm not doing legal work or spending time with my wife and two boys.


Follow me on Twitter - @GShaneC

Check out my apps in BlackBerry World

Website: SCrApps.org

Leave your comments

Post comment as a guest

0
  • No comments found
Subscribe to the official OSBB BBM Channel!

osbbchannelQR

C00013E89

Back to top