# 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:

- GoDropBox
- GoGoogleDrive
- GoOneDrive
- GoLocalStorage

### 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.

1. Register an account

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.

2. Create a web application

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.

3. Locate your new application's Client ID

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:

- GoGoogleDrive
- Microsoft OneDrive (Graph)
- Dropbox

### 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.

1. Saving With a Specified Path

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.

2. Saving With a Valid Current Diagram File

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`.

3. Saving With Neither

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.