Storage
Storing GoJS model data in cloud storage is an excellent way to be able to save and load diagrams without worrying about local system concerns. Interfacing with popular cloud storage services to achieve this goal is made easy with the GoCloudStorage library.
The GoCloudStorage class system lets developers easily store their GoJS diagram model data to popular cloud storage services. The GoCloudStorage class itself is an abstract class, never to be instantiated. Instead, its subclasses are used, each interfacing with a different cloud storage service. Currently, the GoCloudStorage system supports Dropbox, Google Drive, Microsoft OneDrive, and Local Storage. Class names are:
GoCloudStorage Subclass Construction
This section provides a description of how to create an instance of a specific GoCloudStorage subclass, GoGoogleDrive. Due to the variable nature of cloud storage service APIs, GoCloudStorage subclass constructors may vary. It is recommended you read the full documentation for any GoCloudStorage subclass you wish to use.
Before doing anything else, make sure you have a script
tag with a valid path to your gcs.js
library. By default, all GoCloudStorage
subclasses are defined in the namespace gcs
.
Here is a valid constructor call for GoGoogleDrive.
var ggd = new gcs.GoGoogleDrive( diagrams, "16225356139-n64vtg7konuetna3of3mfcaj2iffhgmg.apps.googleusercontent.com", "AIzaSydBje3lBL67MMVKw467_pvuRg7_XMVGf18", defaultModel, "../storage/goCloudStorageIcons/");
What are all these parameters? We'll step through them, one by one.
Managed Diagrams
We see the first parameter passed to the GoGoogleDrive constructor is something called diagrams
. This is the parameter known to all GoCloudStorage subclasses
as managedDiagrams
. It can be either an Array of
GoJS Diagrams or a single GoJS Diagram this instance of GoCloudStorage (in this case, an instance of GoGoogleDrive) will manage data storage for.
This parameter is required.
Client ID
The second parameter passed to the GoGoogleDrive constructor is a long string. This is the
clientId
parameter, required by all GoCloudStorage subclasses (except GoLocalStorage). This
long string ID tells the cloud storage provider (in this case, Google) and the user what application is asking to manipulate Google Drive file data.
This is usually given by the cloud storage provider's developer console or similar. You will need to create an application with the storage provider to obtain this ID.
Read more below at Obtaining Client IDs.
Google Picker API Key
This is a special, GoGoogleDrive-specific parameter. It is included here to demonstrate that some GoCloudStorage subclasses will require parameters that others will not. Again, it is recommended you read the full documentation for any GoCloudStorage subclass you wish to use.
GoGoogleDrive requires this key to allow for the familiar, Google Drive file picker interface during graphical file manipulation. Read more about this special parameter
in the full GoGoogleDrive.pickerApiKey
documentation.
Default Model
This is an optional parameter for all GoCloudStorage subclasses. It is the default model data assigned to newly created diagrams with calls to
create
. Generally, this value is obtained like so:
var defaultModel = diagram.model.toJson();If no value is supplied during construction, this defaults to a new GraphLinksModel.
Icons Relative Directory
If you plan to use a GoCloudStorage subclass instance's commands that call their custom ui
,
you will need to specify the directory in which the icons for storage services reside, relative to the directory your application page is. This is provided
by the optional iconsRelativeDirectory
parameter. The default value is
"../goCloudStorageIcons/".
Exactly what the UI looks like varies between GoCloudStorage subclasses, although it is certain all contain references to storage service icons. Without providing this parameter, it's likely the space where these images go will appear blank. Please refer to the full documentation for details on class-specific UIs.
Obtaining Client IDs
All GoCloudStorage subclasses (except GoLocalStorage) require a client ID as a parameter during construction. This lets the storage service provider and the user know the identity of the application trying to manipulate their remote filesystems. Obtaining a client ID for the storage service you wish to use, therefore, is a requirement to using the corresponding GoCloudStorage subclass.
The process for this varies from service to service, though the general steps are the same. This example uses the specific steps for obtaining a Google Drive client ID, but the general steps should be analogous with other storage services.
- Register an account
- Create a web application
- Locate your new application's Client ID
If you do not already have an account with the storage service provider, you will need to make one. In our specific case, if you did not have a Google Account, you would need to sign up for one now.
This step varies most from service to service. You must create and register an application with the storage service of your choice. For Google Drive, this can be done by following the instructions here.
Your newly registered application now has a Client ID -- a long string like the one we saw in GoCloudStorage
Subclass Construction. You will use this string as the clientId
parameter for your
instance of GoCloudStorage; in our specific case, an instance of GoGoogleDrive.
There are storage-specific pages that can help walk you through the specific process of creating / registering an application with their service. Here are their links:
Saving / Loading Data
Now that you have a working instance of a GoCloudStorage subclass, it's time to start saving and loading some GoJS Diagram model data. We will continue with our GoGoogleDrive example from GoCloudStorage Subclass Construction.
Let's say we have just opened our page. It has two GoJS Diagrams on it, both of which are managed by our instance of GoGoogleDrive. We can save their model data to Google Drive in a variety of ways.
Save vs. Save With UI
All GoCloudStorage subclasses have the functions save()
and saveWithUI()
. What's the difference?
saveWithUI()
guarantees that, when called, it will show the ui element of the invoking instance of
GoCloudStorage, allowing the user to graphically specify a file name and/or location. save()
, on the other hand, is a little more nuanced.
There are three cases. Let's return to our GoGoogleDrive example and explore them.
- Saving With a Specified Path
- Saving With a Valid Current Diagram File
- Saving With Neither
A call to save()
with a valid string path parameter will save to that specific path in Google Drive, without showing any UI.
ggd.save("1SLvlfIC14Lbrrr806gg79XZ3588ZIdCbA1fotXL7lv4");
Note: What constitutes a valid path parameter varies from service to service. See GoCloudStorage documentation for more details.
If no path is supplied, but ggd
has a valid currentDiagramFile
(a representation of the file from Google Drive ggd
has currently open, and whose contents are loaded in ggd
's managedDiagrams
),
then the diagram file content at the path in Google Drive corresponding to ggd.currentDiagramFile.path
is updated with the contents of
ggd.managedDiagrams
.
Finally, if no path is supplied and ggd.currentDiagramFile
is not valid, ggd.saveWithUI()
is called.
Loading
Loading file data is more straightforward. A call to ggd.load(<some valid path string>)
will load the file contents from the given path in Google Drive
to the ggd.managedDiagrams
. A call to ggd.loadWithUI
will display the ui and let
the user graphically choose which file to load.
Note: The file being loaded must have been saved to storage from a page with GoJS Diagrams whose DIV IDs correspond with the DIV IDs of
managedDiagrams
. Otherwise, it will not be clear to the GoCloudStorage subclass
where to load model data to, and an error will occur.
Creating / Removing Data
Creating and removing files with GoCloudStorage subclass instances is a bit more straightforward than saving and loading, but there is still some nuance. Let's take a look.
Creating Files
Continuing with our GoGoogleDrive example, what would you do if you wished to create a new file in storage to save ggd.managedDiagrams
to? You would
call the create
function.
This function does a few things. First, it sets each of ggd.managedDiagrams
to ggd.defaultModel
(which was assigned at construction, back in
GoCloudStorage Subclass Construction). Then, if the
isAutoSaving
property of ggd
is true, you will be prompted to
save your newly refreshed managedDiagrams
to Google Drive via an automatic call to saveWithUI()
.
Optionally, the create
function can accept a path parameter, just as the save()
and load()
functions described back in
Saving / Loading Data. If this parameter is supplied, once each of ggd.managedDiagrams
is reset to defaultModel
,
their model data is saved to the given path in Google Drive.
Removing Files
To remove a file from Google Drive, simply call ggd.remove(<some valid path string>)
. The file at the given path in Google Drive will be removed,
without showing any UI.
To remove a file from Google Drive with the ui element, call ggd.removeWithUI()
.
Go Cloud Storage Manager
What if you wanted to be able to save / load the diagrams on your page to / from many different cloud storage services? Say, Google Drive and Microsoft OneDrive? Or Microsoft OneDrive, Dropbox, and Google Drive? Or any combination of the currently supported GoCloudStorage subclasses? That's what the Go Cloud Storage Manager is for.
Constructing the GoCloudStorageManager
Observe a standard GoCloudStorageManager construction process:
gls = new gcs.GoLocalStorage(myDiagram, defaultModel); god = new gcs.GoOneDrive(myDiagram, 'f9b171a6-a12e-48c1-b86c-814ed40fcdd1', defaultModel); ggd = new gcs.GoGoogleDrive(myDiagram, '16225373139-n24vtg7konuetna3ofbmfcaj2infhgmg.apps.googleusercontent.com', 'AIzaSyDBj43lBLpYMMVKw4aN_pvuRg7_XMVGf18', defaultModel); gdb = new gcs.GoDropBox(myDiagram, '3sm2ko6q7u1gbix', defaultModel); storages = [gls, god, ggd, gdb]; storageManager = new gcs.GoCloudStorageManager(storages, "../storage/goCloudStorageIcons/");Despite all that code, there are only two parameters GoCloudStorageManager takes. Let's look at them.
The first parameter, storages
, is a either an Array or Set of GoCloudStorage subclasses.
This tells the GoCloudStorageManager instance, storageManager
, what storage services are being managed and how those services are managing their diagrams.
The second parameter is a string, and corresponds to the
iconsRelativeDirectory
property of GoCloudStorageManager. This
is analogous to the iconsRelativeDirectory
discussed in GoCloudStorage Subclass Construction. The only
difference is the GoCloudStorageManager applies this property to each of the GoCloudStorage subclasses' iconsRelativeDirectory
properties. This parameter
is optional, but not supplying it may mean there are blank spaces in the ui where the storage service
icons are supposed to be.
Using the GoCloudStorageManager
The first step in using the GoCloudStorageManager is to set the GoCloudStorage subclass you want to use in the moment. This is done through a UI, which is brought up with a
call to storageManager.selectStorageService()
. storageManager.currentStorageService
is set to the GoCloudStorage subclass managing the storage
service selected in the resultant UI.
Now that the GoCloudStorageManager is configured with the GoCloudStorage subclass you want to be using at the moment, managing files in storage is extremely easy. Use
of the GoCloudStorageManager assumes a desire for mainly graphical manipulation of data, so calls to save()
, load()
, create()
, and
remove()
do not take any parameters and all launch the proper ui for
storageManager.currentStorageService
.
You may want to update your page display based on the saving / loading / removal / creation of data using GoCloudStorageManager. All GoCloudStorageManager core methods
(save()
, load()
, create()
, and remove()
) return Promises that resolve with a special object, a
DiagramFile, representing the recently saved / loaded / created / removed file. With this data, you may update your
page display or perform any other action upon Promise resolution. Such as:
storageManager.load().then(function(fileData){ console.log(fileData); // the fileData DiagramFile object });Note: There are three guaranteed fields in any DiagramFile object: the name, id, and path of the represented file.