345 lines
20 KiB
HTML
345 lines
20 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<title>GoJS Storage -- Northwoods Software</title>
|
|
<!-- Copyright 1998-2017 by Northwoods Software Corporation. -->
|
|
<script src="../release/go.js"></script>
|
|
<script src="goIntro.js"></script>
|
|
</head>
|
|
<body onload="goIntro()">
|
|
<div id="container" class="container-fluid">
|
|
<div id="content">
|
|
|
|
<h1>Storage</h1>
|
|
|
|
<p>
|
|
Storing GoJS model data in cloud storage is an excellent way to save, load, create, and delete diagram data files without worrying about local system concerns.
|
|
Interfacing with popular cloud storage services is made easy with the GoCloudStorage library.
|
|
</p>
|
|
<p>
|
|
The GoCloudStorage class system lets developers easily store their GoJS diagram model data to popular cloud storage services. The
|
|
<a href="../storage/api/symbols/GoCloudStorage.html">GoCloudStorage class</a> 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:
|
|
<ul>
|
|
<li><a href="../storage/api/symbols/GoDropBox.html">GoDropBox</a></li>
|
|
<li><a href="../storage/api/symbols/GoGoogleDrive.html">GoGoogleDrive</a></li>
|
|
<li><a href="../storage/api/symbols/GoOneDrive.html">GoOneDrive</a></li>
|
|
<li><a href="../storage/api/symbols/GoLocalStorage.html">GoLocalStorage</a></li>
|
|
</ul>
|
|
</p>
|
|
|
|
<h3 id="GoCloudStorageSubclassConstruction">GoCloudStorage Subclass Construction</h3>
|
|
|
|
<p>
|
|
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 constructor parameters and behavior vary. It is recommended you read the full
|
|
<a href="../storage/api/index.html">documentation</a> for any GoCloudStorage subclass you wish to use.
|
|
</p>
|
|
<p>
|
|
First, ensure you have a <code>script</code> tag with the path to your <code>gcs.js</code> library. All GoCloudStorage
|
|
subclasses are defined in the namespace <code>gcs</code>.
|
|
</p>
|
|
<p>
|
|
<strong>Note</strong>: To use any GoCloudStorage subclass (except for <a href="../storage/api/symbols/GoLocalStorage.html">GoLocalStorage</a>), you must
|
|
also include a <code>script</code> tag referencing the storage service provider JS library. For each subclass, these references are:
|
|
<ul>
|
|
<li><a href="../storage/api/symbols/GoDropBox.html">GoDropBox</a>: https://cdnjs.cloudflare.com/ajax/libs/dropbox.js/2.5.12/Dropbox-sdk.min.js </li>
|
|
<li><a href="../storage/api/symbols/GoGoogleDrive.html">GoGoogleDrive</a>: https://apis.google.com/js/api.js</li>
|
|
<li><a href="../storage/api/symbols/GoOneDrive.html">GoOneDrive</a>: https://js.live.net/v7.2/OneDrive.js </li>
|
|
</ul>
|
|
</p>
|
|
<p>
|
|
Here is a valid constructor call for GoGoogleDrive.
|
|
</p>
|
|
<pre data-language="javascript" id="simple">
|
|
// Create a valid GoGoogleDrive instance
|
|
var ggd = new gcs.GoGoogleDrive(
|
|
diagrams, // managedDiagrams parameter
|
|
"16225356139-n64vtg7konuetna3of3mfcaj2iffhgmg.apps.googleusercontent.com", // clientId parameter
|
|
"AIzaSydBje3lBL67MMVKw467_pvuRg7_XMVGf18", // pickerApiKey parameter
|
|
defaultModel, // defaultModel parameter
|
|
"../storage/goCloudStorageIcons/" // iconsRelativeDirectory parameter
|
|
);
|
|
</pre>
|
|
<p>
|
|
<strong>Note</strong>: All client ID's / API keys on this page are fabricated, and for example purposes only.
|
|
</p>
|
|
<p>
|
|
What are all these parameters? We'll step through them, one by one.
|
|
</p>
|
|
|
|
<h4>Managed Diagrams </h4>
|
|
<p>
|
|
The first parameter passed to the GoGoogleDrive constructor is something called <code>diagrams</code>. This is the parameter known to all GoCloudStorage subclasses
|
|
as <code><a href="../storage/api/symbols/GoCloudStorage.html#managedDiagrams">managedDiagrams</a></code>. It is either an Array of
|
|
GoJS Diagrams or a single GoJS Diagram that this instance of GoCloudStorage (in this case, GoGoogleDrive) will manage data storage for.
|
|
This parameter is required.
|
|
</p>
|
|
|
|
<h4>Client ID</h4>
|
|
<p>
|
|
The second parameter passed to the GoGoogleDrive constructor is a long string. This is the <code>
|
|
<a href="../storage/api/symbols/GoCloudStorage.html#clientId">clientId</a></code> parameter, required by all GoCloudStorage subclasses (except
|
|
<a href="../storage/api/symbols/GoLocalStorage.html">GoLocalStorage</a>). This ID tells the cloud storage provider (in this case, Google) and the user
|
|
what application is asking to manipulate stored file data (in this case, Google Drive file data).
|
|
</p>
|
|
<p>
|
|
This is usually given by the cloud storage provider's developer console or similar.
|
|
You will need to register an application with the storage provider (in this case, Google) to obtain this ID.
|
|
Read more below at <a href="#ObtainingClientIDs">Obtaining Client IDs</a>.
|
|
</p>
|
|
|
|
<h4>Google Picker API Key</h4>
|
|
<p>
|
|
This is a GoGoogleDrive-specific parameter. Some GoCloudStorage subclasses require parameters that others do not.
|
|
Again, it is recommended you read the full <a href="../storage/api/index.html">documentation</a> for any GoCloudStorage subclass you wish to use.
|
|
</p>
|
|
<p>
|
|
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 <code><a href="../storage/api/symbols/GoGoogleDrive.html#pickerApiKey">GoGoogleDrive.pickerApiKey</a></code> documentation.
|
|
</p>
|
|
|
|
<h4>Default Model </h4>
|
|
<p>
|
|
It is the default model data assigned to newly created diagrams with calls to
|
|
<code><a href="../storage/api/symbols/GoCloudStorage.html#create">create</a></code>. Generally, this value is obtained with a call to
|
|
<a href="../api/symbols/Model.html#toJson">Diagram.model.toJson()</a>.
|
|
</p>
|
|
<p>
|
|
This is an optional parameter for all GoCloudStorage subclasses.
|
|
If no value is supplied during construction, this defaults to a new <a href="../api/symbols/GraphLinksModel.html">GraphLinksModel</a>.
|
|
</p>
|
|
|
|
<h4>Icons Relative Directory</h4>
|
|
<p>
|
|
To use commands that call a GoCloudStorage subclass' custom <code><a href="../storage/api/symbols/GoCloudStorage.html#ui">ui</a></code>,
|
|
you must 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 <code><a href="../storage/api/symbols/GoCloudStorage.html#iconsRelativeDirectory">iconsRelativeDirectory</a></code> parameter. The default value is
|
|
"../goCloudStorageIcons/".
|
|
</p>
|
|
<p>
|
|
Exactly what the UI looks like varies between GoCloudStorage subclasses, though it certainly contains references to storage service icons. Without providing this
|
|
parameter, it's likely the space where these images go will appear blank.
|
|
</p>
|
|
<p>
|
|
Please refer to the full <a href="../storage/api/index.html">documentation</a> for details on class-specific UIs.
|
|
</p>
|
|
|
|
<h3 id="ObtainingClientIDs">Obtaining Client IDs</h3>
|
|
<p>
|
|
All GoCloudStorage subclasses (except <a href="../storage/api/symbols/GoLocalStorage.html">GoLocalStorage</a>) require a client ID as a parameter during construction.
|
|
This lets the storage service provider (i.e. Google, Dropbox...) and the user know the identity of the application trying to manipulate their remote filesystems.
|
|
Therefore, obtaining a client ID for the storage service you wish to use is a requirement to using the corresponding GoCloudStorage subclass.
|
|
</p>
|
|
<p>
|
|
The process for this varies from service to service, though the general steps are the same.
|
|
</p>
|
|
<ol>
|
|
<li><strong>Register an account</strong></li>
|
|
<p>
|
|
If you do not already have an account with the storage service provider, make one.
|
|
</p>
|
|
<li><strong>Register a web application</strong></li>
|
|
<p>
|
|
This step varies most from service to service. Create and register an application with the storage service provider.
|
|
</p>
|
|
<li><strong>Locate your new application's Client ID</strong></li>
|
|
<p>
|
|
Your newly registered application has a Client ID -- a long string like the one we saw in <a href="#GoCloudStorageSubclassConstruction">GoCloudStorage
|
|
Subclass Construction</a>. Use this string as the <code><a href="../storage/api/symbols/GoCloudStorage.html#clientId">clientId</a></code> parameter for your
|
|
instance of GoCloudStorage.
|
|
</p>
|
|
</ol>
|
|
<p>
|
|
These storage-specific pages can help walk you through the process of creating / registering an application with their service.
|
|
<ul>
|
|
<li><a href="https://developers.google.com/drive/v3/web/quickstart/js">GoGoogleDrive</a></li>
|
|
<li><a href="https://docs.microsoft.com/en-us/onedrive/developer/rest-api/getting-started/app-registration">Microsoft OneDrive (Graph)</a></li>
|
|
<li><a href="https://www.dropbox.com/developers">Dropbox</a></li>
|
|
</ul>
|
|
</p>
|
|
|
|
<h3 id="SavingLoadingData">Saving / Loading Data </h3>
|
|
<p>
|
|
Now that you have a working instance of a GoCloudStorage subclass, let's start saving and loading GoJS Diagram model data. We will continue with our
|
|
GoGoogleDrive example from <a href="#GoCloudStorageSubclassConstruction">GoCloudStorage Subclass Construction</a>, referring to our specific GoGoogleDrive instance as
|
|
<code>ggd</code>.
|
|
</p>
|
|
<p>
|
|
We can save the model data of <code>ggd.managedDiagrams</code> to Google Drive in a variety of ways.
|
|
</p>
|
|
|
|
<h4>Save vs. Save With UI</h4>
|
|
<p>
|
|
All GoCloudStorage subclasses have the functions <code>save()</code> and <code>saveWithUI()</code>. What's the difference?
|
|
</p>
|
|
<p>
|
|
<code>saveWithUI()</code> shows the <a href="../storage/api/symbols/GoCloudStorage.html#ui">ui</a> element of the invoking instance of
|
|
GoCloudStorage, letting the user graphically specify a file name and/or save location.
|
|
</p>
|
|
<p>
|
|
<code>save()</code> is more nuanced. There are three cases. Let's return to our GoGoogleDrive example and explore them.
|
|
</p>
|
|
<ol>
|
|
<li><strong>Saving With a Specified Path</strong></li>
|
|
<p>
|
|
A call to <code>ggd.save(<valid path string>)</code> will save to that specific path in Google Drive, without showing any UI.
|
|
</p>
|
|
<p>
|
|
<strong>Note</strong>: What constitutes a valid path string parameter varies from service to service. See
|
|
<a href="../storage/api/symbols/GoCloudStorage.html#getFile"> documentation</a> for more details.
|
|
</p>
|
|
<li><strong>Saving With a Valid Current Diagram File</strong></li>
|
|
<p>
|
|
If no path is supplied, but <code>ggd</code> has a valid <code><a href="../storage/api/symbols/GoCloudStorage.html#currentDiagramFile">currentDiagramFile</a></code>
|
|
(a representation of the file from Google Drive <code>ggd</code> has currently open, and whose contents are loaded in <code>ggd.managedDiagrams</code>' models),
|
|
then the diagram file content at the path in Google Drive corresponding to <code>ggd.currentDiagramFile.path</code> is updated with the model contents of
|
|
<code>ggd.managedDiagrams</code>.
|
|
</p>
|
|
<li><strong>Saving With Neither</strong></li>
|
|
<p>
|
|
If no path is supplied and <code>ggd.currentDiagramFile</code> is not valid, <code>ggd.saveWithUI()</code> is called, prompting the user for a save name / location.
|
|
</p>
|
|
</ol>
|
|
<h4>Loading</h4>
|
|
<p>
|
|
Loading file data is more straightforward.
|
|
</p>
|
|
<p>
|
|
<code><a href="../storage/api/symbols/GoCloudStorage.html#load">load(<valid path string>)</a></code> loads file contents from the cloud storage service and
|
|
into each of <code>managedDiagrams</code>' models. No UI appears.
|
|
<br />
|
|
<strong>Example</strong>: <code>ggd.load('ahjdhe^3n4dlKd4r')</code>
|
|
</p>
|
|
<p>
|
|
<code><a href="../storage/api/symbols/GoCloudStorage.html#loadWithUI">loadWithUI()</a></code> displays the
|
|
<a href="../storage/api/symbols/GoCloudStorage.html#ui">ui</a> and lets the user graphically choose which file to load.
|
|
<br />
|
|
<strong>Example</strong>: <code>ggd.loadWithUI()</code>
|
|
</p>
|
|
<p>
|
|
<strong>Note 1</strong>: 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
|
|
<code><a href="../storage/api/symbols/GoCloudStorage.html#managedDiagrams">managedDiagrams</a></code>. Otherwise, it will not be clear to the GoCloudStorage subclass
|
|
where to load model data to.
|
|
<br />
|
|
<strong>Note 2</strong>: Model data loaded into <code>managedDiagrams</code> from storage must be processed appropriately within the
|
|
application containing the invoking instance of GoCloudStorage (via <a href="templateMaps.html">node / link templates</a> or some other method). The GoCloudStorage
|
|
class system does not store any information other than model data.
|
|
</p>
|
|
</p>
|
|
|
|
<h3 id="CreatingRemovingData">Creating / Removing Data </h3>
|
|
<h4>Creating Files</h4>
|
|
<p>
|
|
Continuing with our GoGoogleDrive example, how would you create a new file in storage to save <code>ggd.managedDiagrams</code> to? Call the <code>create</code> function.
|
|
</p>
|
|
<p>
|
|
<code>create()</code> sets each of <code>ggd.managedDiagrams</code> to <code>ggd.defaultModel</code> (assigned at construction, back in
|
|
<a href="#GoCloudStorageSubclassConstruction">GoCloudStorage Subclass Construction</a>). If
|
|
<code><a href="../storage/api/symbols/GoCloudStorage.html#isAutoSaving">ggd.isAutoSaving</a></code> is true, you will be prompted to
|
|
save your newly refreshed <code>managedDiagrams</code> to Google Drive via an automatic call to <code>saveWithUI()</code>.
|
|
</p>
|
|
<p>
|
|
Optionally, the <code>create</code> function can accept a path parameter, just as the <code>save()</code> and <code>load()</code> functions described in
|
|
<a href="#savingLoadingData">Saving / Loading Data</a>. If supplied, once each of <code>ggd.managedDiagrams</code> is reset to <code>defaultModel</code>,
|
|
their model data is saved to the given path in Google Drive, and no UI appears.
|
|
</p>
|
|
|
|
<h4>Removing Files</h4>
|
|
<p>
|
|
To remove a file from Google Drive, simply call <code>ggd.remove(<some valid path string>)</code>. The file at the given path in Google Drive will be removed,
|
|
without showing any UI.
|
|
</p>
|
|
<p>
|
|
To remove a file from Google Drive with the <a href="../storage/api/symbols/GoCloudStorage.html#ui">ui</a> element, call <code>ggd.removeWithUI()</code>.
|
|
</p>
|
|
|
|
<h3 id="GoCloudStorageManager">Go Cloud Storage Manager </h3>
|
|
<p>
|
|
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
|
|
<a href="../storage/api/symbols/GoCloudStorageManager.html">Go Cloud Storage Manager</a> is for.
|
|
</p>
|
|
|
|
<h4>Constructing the GoCloudStorageManager</h4>
|
|
<p>
|
|
Observe the standard GoCloudStorageManager construction process:
|
|
<pre data-language="javascript">
|
|
// Construct the CloudStorage subclasses you wish to manage
|
|
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];
|
|
|
|
// Create the GoCloudStorageManager instance
|
|
storageManager = new gcs.GoCloudStorageManager(storages, "../storage/goCloudStorageIcons/");
|
|
</pre>
|
|
Despite all that code, there are only two parameters GoCloudStorageManager takes.
|
|
</p>
|
|
<ul>
|
|
<li><strong><a href="../storage/api/symbols/GoCloudStorageManager.html#storages">Storages</a></strong></li>
|
|
<p>
|
|
The first parameter, <code>storages</code>, is a either an Array or <a href="../api/Set.html">Set</a> of GoCloudStorage subclasses.
|
|
This tells the GoCloudStorageManager instance, <code>storageManager</code>, what storage services are being managed and how those services are managing their diagrams.
|
|
</p>
|
|
<li><strong><a href="../storages/api/symbols/GoCloudStorageManager.html#iconsRelativeDirectory">Icons Relative Directory</a></strong></li>
|
|
<p>
|
|
The second parameter is a string, and corresponds to the
|
|
<code><a href="../storage/api/symbols/GoCloudStorageManager.html#iconsRelativeDirectory">iconsRelativeDirectory</a></code> property of GoCloudStorageManager. This
|
|
is analogous to the <code>iconsRelativeDirectory</code> discussed in <a href="#GoCloudStorageSubclassConstruction">GoCloudStorage Subclass Construction</a>. The only
|
|
difference is the GoCloudStorageManager applies this property to each of the GoCloudStorage subclasses' <code>iconsRelativeDirectory</code> properties. This parameter
|
|
is optional, but not supplying it may mean there are blank spaces in the <a href="../storage/api/symbols/GoCloudStorageManager.html#ui">ui</a> where the storage service
|
|
icons are supposed to be.
|
|
</p>
|
|
</ul>
|
|
|
|
|
|
|
|
<h4>Using the GoCloudStorageManager</h4>
|
|
|
|
<div style="text-align: center; padding: 20px;">
|
|
<figure >
|
|
<img src="images/gcsmSelectStorageService.png" />
|
|
<figcaption>The UI the appears after calling selectStorageService()</figcaption>
|
|
</figure>
|
|
</div>
|
|
<p>
|
|
First, set the GoCloudStorage subclass you want to use at the moment. This is done through a UI, which is brought up with a
|
|
call to <code><a href="../storage/api/symbols/GoCloudStorageManager.html#selectStorageService">storageManager.selectStorageService()</a></code>.
|
|
<code><a href="../storage/api/symbols/GoCloudStorageManager.html#currentStorageService">storageManager.currentStorageService</a></code> is set
|
|
to the GoCloudStorage subclass managing the storage service selected in the resultant UI.
|
|
|
|
</p>
|
|
|
|
<p>
|
|
The GoCloudStorageManager assumes a desire for mainly graphical manipulation of data, so calls to <code>save()</code>, <code>load()</code>, <code>create()</code>, and
|
|
<code>remove()</code> do not take any parameters and all launch the proper <a href="../storage/api/symbols/GoCloudStorage.html#ui">ui</a> for
|
|
<code>storageManager.currentStorageService</code> (set by the the previous step).
|
|
</p>
|
|
|
|
<p>
|
|
You may want to update your page display or perform some other actions based on the saving / loading / removal / creation of data using GoCloudStorageManager.
|
|
All GoCloudStorageManager core methods (<code>save()</code>, <code>load()</code>, <code>create()</code>, and <code>remove()</code>) return Promises that resolve with
|
|
a <a href="../storage/api/symbols/DiagramFile.html">DiagramFile</a>, 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:
|
|
<pre data-language="javascript">
|
|
// resolving the Promise returned after the Load action
|
|
storageManager.load().then(function(fileData){
|
|
// the fileData is a DiagramFile object
|
|
alert(fileData.name + " (file ID " + fileData.id + ") loaded from path " + fileData.path);
|
|
});
|
|
</pre>
|
|
<strong>Note</strong>: There are three guaranteed fields in any DiagramFile object: the <a href="../storage/api/symbols/DiagramFile.html#name">name</a>,
|
|
<a href="../storage/api/symbols/DiagramFile.html#id">id</a>, and <a href="../storage/api/symbols/DiagramFile.html#path">path</a> of the represented file.
|
|
</p>
|
|
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|