|
|
| Line 1: |
Line 1: |
| '''Important: DropBox [https://blogs.dropbox.com/developers/2015/04/deprecating-the-sync-and-datastore-apis/ announced on April 23, 2015] that this API is deprecated and will be phased out by April, 2016.''' | | '''Important: DropBox [https://blogs.dropbox.com/developers/2015/04/deprecating-the-sync-and-datastore-apis/ announced on April 23, 2015] that this API is deprecated and will be phased out by April, 2016.''' |
|
| |
| It's easy to save and read record based data on Dropbox using AppStudio using Dropbox Datastores. You can then access them on all your devices and on your desktop.
| |
| * Apps must be set up in Dropbox before they will run.
| |
| * Apps need to be deployed. They cannot run locally.
| |
| * Your site will need a signing certificate so OAuth will work.
| |
| * You can only run someone else's app if you have their permission.
| |
| * Therefore you can only access someone else's files with their permission.
| |
| * If you want to access files directly, use [[Using Dropbox to save files|Dropbox Files]].
| |
| * Maximum datastore size is 10 megs.
| |
| * Maximum records per datastore is 100,000.
| |
| * Maximum record size is 100k.
| |
| * The first 5 megs do not subtract from your Dropbox allocation.
| |
|
| |
| Here's how:
| |
|
| |
| == Get a Dropbox account. ==
| |
|
| |
| Use your existing account or get a new one. They're free and easy to set up.
| |
|
| |
| == Create your app in the Dropbox App Console ==
| |
|
| |
| Go to [https://www.dropbox.com/developers/apps Dropbox App Console] and create a Dropbox API app, that does "Datastores only".
| |
|
| |
| [[File:Dropboxappconsole3.png|600px|none]]
| |
|
| |
|
| |
| === Settings ===
| |
| [[File:Dropboxappconsole1.png|601px|none]]
| |
|
| |
| Settings Fields:
| |
| * Status: Development allows up to 100 users. To apply for Production, your app will have to approved by Dropbox.
| |
| * Development users: Who is allowed to use the app?
| |
| * Permission type: Normally, read and write to its own folder.
| |
| * App key, App secret: Generated by Dropbox. Use App key in your app to identify the Dropbox app.
| |
| * OAuth redirect URIs: The complete URL to your deployed app.
| |
| * Drop-ins domains: Not needed.
| |
| * Datastores: Not needed.
| |
|
| |
| === Details ===
| |
| [[File:Dropboxappconsole2.png|500px|none]]
| |
|
| |
| Details Fields:
| |
| * App name: The name of your app. Don't use "Dropbox" in the name.
| |
| * Publisher: Your name or the name of your company.
| |
| * Description: A description of your app.
| |
| * App website: The main website for your app.
| |
| * App icons: 64x64 and 256x256 images. You need to save them to your Dropbox before uploading them.
| |
|
| |
| == Write your app ==
| |
|
| |
| === Add the Dropbox library to your project ===
| |
|
| |
| Select Global Code and Project Properties in the Project Explorer, and add the Dropbox library to the project:
| |
|
| |
| [[File:Dropboxlibrary.png|600px|none]]
| |
|
| |
| === Log into Dropbox ===
| |
|
| |
| Security is important to Dropbox apps. Before you can do anything, you need to login. Dropbox uses a security schema call [http://en.wikipedia.org/wiki/OAuth OAuth], which is fairly ease to use. OAuth requires that you use https: your site site will need a signing certificate. You can install a self signed certificate (browsers will complain) or an official one (about $59/year from a certificate authority).
| |
|
| |
| Here is what you do at the start of your app:
| |
| <pre>
| |
| Dim APP_KEY = "qx65sf9nruudj73"
| |
| Dim client = new Dropbox.Client({key: APP_KEY})
| |
| client.authenticate({interactive:False}, authenticationError)
| |
|
| |
| Function authenticationError(err)
| |
| If err Then MsgBox "Dropbox Authentication error: " & err
| |
| End Function
| |
| </pre>
| |
|
| |
| Once this is done, you can check to see if the user is authorized. If not, you need to authenticate:
| |
| <pre>
| |
| client.authenticate()
| |
| </pre>
| |
| This will load the Dropbox web page, ask the user to log in if needed and get authorization for the app.
| |
|
| |
| === Initialize your Table ===
| |
|
| |
| Once authenticated, you need open the datastore for the app.
| |
| <pre>
| |
| datastoreManager = client.getDatastoreManager()
| |
| datastoreManager.openDefaultDatastore(openDataStoreComplete)
| |
|
| |
| Function openDataStoreComplete(err, datastore)
| |
| If err Then
| |
| MsgBox "Error opening datastore: " & err
| |
| Else
| |
| studentTable=datastore.getTable("students")
| |
| End If
| |
| End Function
| |
| </pre>
| |
| * This app uses only the default datastore.
| |
| * It has one table called studentTable.
| |
| * A datastore can have multiple tables.
| |
| * getTable() returns the table.
| |
| * A table is created when records are added to it.
| |
|
| |
| === Save a record ===
| |
|
| |
| Adding records to a table is easy.
| |
| <pre>
| |
| data = {name: txtName.value, age: TxtAge.value}
| |
| ref = studentTable.insert(data)
| |
| </pre>
| |
| * The record is simply added.
| |
| * A reference to the record is returned.
| |
| * There is no duplicate checking.
| |
| * The data is formatted as an object.
| |
| * Since the operation updates a local file, there is no need for an asynchronous callback.
| |
| * Dropbox will take care of synching the updated datastore to its server later.
| |
|
| |
| === Find a record ===
| |
| The Dropbox query() function is a database style lookup.
| |
| <pre>
| |
| results = studentTable.query({name: txtFind.value})
| |
| If Len(results)>0 Then
| |
| MsgBox results[0].get("name") & " is " & results[0].get("age")
| |
| Else
| |
| MsgBox "Not found"
| |
| End If
| |
| </pre>
| |
| * The query function takes an object as a parameter.
| |
| * It can use one or more name,value pairs to match up with.
| |
| * An array is returned with all the matching records.
| |
| * Each element of the array is a reference to the record.
| |
| * Use the get() function to get fields in a record.
| |
| * Use the set() function to change fields in a record.
| |
|
| |
| === Delete a record ===
| |
| Deletes a record from a datastore.
| |
| <pre>
| |
| If Len(results)>0 Then
| |
| results[0].deleteRecord()
| |
| MsgBox "Deleted"
| |
| End If
| |
| </pre>
| |
| * You need the reference to the record to delete it.
| |
| * Operation happens immediately to the local copy of the datastore.
| |
| * Dropbox will synch to its servers later.
| |
|
| |
| === Examining a datastore on Dropbox ===
| |
| You can look at your datastore on Dropbox.com. Go to the [https://www.dropbox.com/developers/apps App Console] and choose [https://www.dropbox.com/developers/apps/datastores Browse DataStores].
| |
|
| |
| You can then choose the app you are interested in and browse its datastore:
| |
|
| |
| [[File:Dropboxappconsole4.png|600px|none]]
| |
|
| |
| === Other Dropbox Datastore functions ===
| |
| Here is the full list of calls that can be made to the Dropbox client. Docs are [https://www.dropbox.com/developers/datastore/docs/js here].
| |
|
| |
| Class Methods
| |
| * int64(x)
| |
| * isInt64(x)
| |
| * isValidID(datastoreId)
| |
|
| |
| Instance Methods
| |
| * getTable(tableId)
| |
| * ListTableIds()
| |
| * close()
| |
| * getId()
| |
| * getSyncStatus()
| |
|
| |
| Instance Properties
| |
| * recordsChanged (Dropbox.Util.EventSource<Dropbox.Datastore.RecordsChanged>)
| |
| * syncStatusChanged (Dropbox.Util.EventSource<?>)
| |
|
| |
| Datastore Manager
| |
| * close()
| |
| * openDefaultDatastore(callback)
| |
| * openDatastore(datastoreId, callback)
| |
| * createDatastore(callback)
| |
| * deleteDatastore(datastoreId, callback)
| |
| * listDatastores(callback)
| |
|
| |
| Datastore Properties
| |
| * datastoreListChanged (Dropbox.Util.EventSource<Dropbox.Datastore.DatastoreListChanged>)
| |
| * getId()
| |
| * getDatastoreInfos()
| |
|
| |
| Table Methods
| |
| * isValidId(tableId)
| |
| * getId()
| |
| * get(recordId)
| |
| * getOrInsert(recordId, defaultValues)
| |
| * insert(fieldValues)
| |
| * query(fieldValues)
| |
| * setResolutionRule(fieldName, rule)
| |
|
| |
| Record Methods
| |
| * isValidId(recordId)
| |
| * get(fieldName)
| |
| * set(fieldName, value)
| |
| * getOrCreateList(fieldName)
| |
| * getFields()
| |
| * update(a)
| |
| * deleteRecord()
| |
| * has(fieldName)
| |
| * getId()
| |
| * getTable()
| |
| * isDeleted()
| |
| * affectedRecordsByTable()
| |
| * affectedRecordsForTable(tableId)
| |
| * isLocal()
| |
|
| |
| Check [https://www.dropbox.com/developers/datastore/docs/js#Dropbox.Datastore full docs] - lots more stuff!
| |
|
| |
| === "Dropbox Cannot Authenticate" message ===
| |
|
| |
| If your app should get a message like this after working for a little while, you may need to clean the cache on your computer or device. This is more likely to happen during development than in released apps.
| |