# Class: Client

## Client

#### new Client(gmeConfig)

  The Client class represents the Client API which is the way to communicate with your project from your user-defined UI pieces. It allows project selection, project tracking, model interpretation and model manipulation.

  !! Documentation of the class is incomplete !!

  What is mainly missing are the node setters. Until added here use the Core documentation and simply replace any Core nodes in the arguments with the id/path of the nodes instead.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `gmeConfig` | GmeConfig | the main configuration of the WebGME that holds information about the server and other options.

### Methods

#### abortPlugin(executionId)

  Initiates the abort of the given plugin execution.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `executionId` | string | unique identifier that identifies the plugin execution

#### addLibrary(name, blobHashLibraryInfoOrSeedName, callback)

  Sends a server request to add specified library to the current project and branch.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `name` | string | Name of new library (cannot contain dots or exist already)

  `blobHashLibraryInfoOrSeedName`

  string | object

  If blobHash string given will import library from blob, if string will import from seed, otherwise project at info (will also be added to info at library).

  ###### Properties

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `projectId` | string |  | The projectId of your library.
  `branchName` | string | <optional> | The branch that your library follows in the origin project.
  `commitHash` | string | <optional> | The commit-hash of your library.

  `callback`

  function

  Invoked when request completed.

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `err` | null | Error | If request failed.
  `result` | module:Storage~CommitResult | Result from the commit made.

#### addUI( [ui], eventHandler [, guid])

  Adds a "user" for receiving events regarding nodes in a specified territory.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---

  `ui`

  object

  <optional>

  Object with additional methods to be invoked.

  ###### Properties

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `reLaunch` | function | <optional> | Triggered when active project/branch is switched.

  `eventHandler`

  function

  Function invoked at changes for, or initial loading of, nodes within the "user's" territory.

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `events` | Array.<object> | Array of event data for affected nodes within the territory.

  `guid` | string | <optional> | Unique id of user (if not provided one will be generated).

  ##### Returns:

  The id (guid) of the newly added "user".

  Type
    string

  ##### Example

      // The eventHandler is invoked whenever there are changes to the nodes
       // matching any of the patterns.
       // There are three cases when it is triggered:
       // 1) updateTerritory was invoked by us.
       // 2) Another client made changes to nodes within the territory.
       // 3) We made changes to any of the nodes (via the setters).
       function eventHandler(events) {
        var i,
            nodeObj;
        for (i = 0; i < events.length; i += 1) {
          if (events[i].etype === 'load') {
            // The node is loaded and we have access to it.
            // It was either just created or this is the initial
            // updateTerritory we invoked.
            nodeObj = client.getNode(events[i].eid);
          } else if (events[i].etype === 'update') {
            // There were changes made to the node (or any of its bases, meta-types and/or reverse relationships).
            // The node is still loaded and we have access to it.
            nodeObj = client.getNode(events[i].eid);
          } else if (events[i].etype === 'unload') {
            // The node was removed from the model (we can no longer access it).
            // We still get the path/id via events[i].eid
          } else {
            // "Technical events" not used.
          }
        }
      }

       var userId = client.addUI(null, eventHandler);

#### canRedo(branchName)

  Returns true if the provided branchName matches the selected and if there were no commits after the previous undo.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `branchName` | string | Must match the active branch.

  ##### Returns:

  True if it's fine to call client.redo()

  Type
    boolean

#### canUndo(branchName)

  Returns true if the provided branchName matches the selected and if the current user did made the latest change.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `branchName` | string | Must match the active branch.

  ##### Returns:

  True if it's fine to call client.undo()

  Type
    boolean

#### closeProject(callback)

  Closes the currently selected project. If a branch is opened it will be closed as well. Will resolve with error if no project is opened.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---

  `callback`

  function

  Invoked when request completed.

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `err` | null | Error | If the request failed.

  ##### Fires:

  - Client#event:PROJECT_CLOSED
  - Client#event:BRANCH_CLOSED
  - Client#event:BRANCH_CHANGED

#### completeTransaction( [msg] [, callback])

  Completes any open transaction and persists the changes to server.

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `msg` | string | <optional> | ']' | End of commit-message.
  `callback` | function | <optional> |  | Optional callback that's invoked when the commit has reached the server.

  ##### Example

      var nodeId = 'someIdToANodeThatIsLoaded';
       client.startTransaction('start of commitMessage');

       // While transaction is open nothing will be committed to the server.
       client.setAttributes(nodeId, 'name', 'newName', 'changes within the transaction');

       client.setRegistry(nodeId, 'position', {x: 100, y:200}, 'some more changes');

       // When we have made all of our changes we make a single commit.
       client.completeTransaction('end of commitMessage', function (err, result) {
        // Here we have the option to get notified when the commit has reached the server
        // and been persisted in the database.

        // The commit hash of the new state of our model.
        console.log(result.hash);

        // If we are working in a branch - this is the status of our commit.
        // 'SYNCED', 'FORKED'.
        console.log(result.status);
      });

#### connectToDatabase(callback)

  Establishes a websocket-connection to the storage/database on the server. If already connected - it will resolve immediately. Note that the client itself attempts to reconnect on unintended disconnections. To monitor the status register for the client.CONSTANTS.NETWORK_STATUS_CHANGED event.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---

  `callback`

  function

  Invoked when request completed.

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `err` | null | Error | If the request failed.

  ##### Fires:

  - Client#event:NETWORK_STATUS_CHANGED

#### copyMoreNodes(parameters [, msg])

  Copies the given nodes into the parent (does not enforce meta-rules and requires all participating nodes to be loaded in the client)

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---

  `parameters`

  object

  the parameters holding parentId and nodes to be copied indexed by their ids/paths ( see example)

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `parentId` | string | the id/path of the parent where the new copies should be created

  `msg` | string | <optional> | optional commit message, if not supplied a default one with the function name and input parameters will be used

  ##### Example

      client.copyMoreNodes({
         parentId: '',
         '/4': {},
         '/5': {
           attributes: {
             name: 'MyNamedCopy'
           },
           registry: {
             position: {x: 100, y:100}
           }
         }
      }, 'Copied two nodes with some additional init data.');

#### copyNode(path, parentId [, desc] [, msg])

  Copies the given node into parent (does not enforce meta-rules and requires all participating nodes to be loaded in the client)

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `path` | string |  |  | the id/path of the node to copy
  `parentId` | string |  |  | the id/path of the parent where the new copy should be created

  `desc`

  object

  <optional>

  {}

  named attributes and/or registries to set for the new node (see example)

  ###### Properties

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `attributes` | object | <optional> | {} | named attributes to set for the new node
  `registry` | object | <optional> | {} | named registries to set for the new node

  `msg` | string | <optional> |  | optional commit message, if not supplied a default one with the function name and input parameters will be used

  ##### Returns:

  - the newly created node if it could be copied
  Type
    GMENode | undefined

  ##### Example

      var nodeCopy1 = client.copyNode('/4', '');
      var nodeCopy2 = client.copyNode('/4', '', {
        attributes: {
          name: 'CopiedNode'
        },
        registry: {
          position: {x: 100, y: 100}
        }
      }, 'Created node with specific name and position.');

#### copyNodes(paths, parentId [, msg])

  Copies the given nodes into the parent (does not enforce meta-rules and requires all participating nodes to be loaded in the client)

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `paths` | Array.<string> |  | array of the ids/paths of the nodes to copy
  `parentId` | string |  | the id/path of the parent where the new copies should be created
  `msg` | string | <optional> | optional commit message, if not supplied a default one with the function name and input parameters will be used

  ##### Returns:

  - the newly created nodes if all could be copied
  Type
    Array.<GMENode> | undefined

  ##### Example

      var nodeCopies1 = client.copyNodes(['/4', '/3'], '');
      var nodeCopies2 = client.copyNodes('/4', '/3'], '', 'Copied two nodes');

#### disconnectFromDatabase(callback)

  Ends the websocket-connection to the storage/database on the server.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---

  `callback`

  function

  Invoked when request completed.

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `err` | null | Error | If the request failed.

  ##### Fires:

  - Client#event:NETWORK_STATUS_CHANGED

#### filterPlugins(pluginIds [, nodePath])

  Helper method for filtering out the registered plugins from the available ones.

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `pluginIds` | Array.<string> |  |  | Typically all available plugins on the server.
  `nodePath` | string | <optional> | '' | Node to get the validPlugins from.

  ##### Returns:

  Filtered plugin ids.

  Type
    Array.<string>

#### getActiveBranchName()

  Returns the name of currently selected branch. Returns null if no branch is open.

  ##### Returns:

  The name of the selected branch.

  Type
    string | null

#### getActiveCommitHash()

  Returns the current commit-hash of either the opened branch or the selected commit. Return null if none is selected.

  ##### Returns:

  The active commit-hash.

  Type
    string | null

#### getActiveProjectId()

  Returns the id of currently selected project. Returns null if no project is opened.

  ##### Returns:

  The project-id of the selected project.

  Type
    string | null

#### getActiveProjectKind()

  Returns the kind of currently selected project at the time it was opened. Returns null if no project is opened and returns undefined if the field is not specified for the project. (To get the latest info from the server use client.getProjectObject() followed by project.getProjectInfo.)

  ##### Returns:

  The project-kind of the selected project.

  Type
    string | null | undefined

#### getActiveProjectName()

  Returns the name of currently selected project. Returns null if no project is opened.

  ##### Returns:

  The project-name of the selected project.

  Type
    string | null

#### getActiveRootHash()

  Returns the current root-hash the client is at. If there are changes inside a transaction the root-hash will correspond to the state that is being updated. Returns null if no no branch or commit selected is selected.

  ##### Returns:

  The active root-hash.

  Type
    string | null

#### getAllMetaNodes(asObject)

  Returns all meta-nodes as GMENodes.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `asObject` | boolean | If true return an object with ids/path as keys and nodes as values.

  ##### Returns:

  If the node is loaded it will be returned, otherwise null.

  Type
    Array.<GMENode> | object

#### getBranchStatus()

  Returns the current status of the opened branch. Returns null if no branch is opened.

  ##### Returns:

  One of client.CONSTANTS.BRANCH_STATUS. SYNC/AHEAD_SYNC/AHEAD_NOT_SYNC/PULLING/ERROR.

  Type
    string | null

#### getConnectedStorageVersion()

  Returns the version (package.json version of webgme-engine) of the server the initial connection was established to.

  ##### Returns:

  null if it was never connected.

  Type
    string | null

#### getCoreInstance( [options], callback)

  Creates a new core instance using the state of the client and loads a new root node. Resolves with error if no project or root-hash is active.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---

  `options`

  object

  <optional>

  ###### Properties

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `commitHash` | string | <optional> | %state.commitHash% | If a different commit-hash should be loaded.
  `logger` | GmeLogger | <optional> | %clientLogger% | Logger passed to the core instance.

  `callback`

  function

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `err` | Error | null | Non-null if failed to retrieve result.

  `result`

  object

  The result object

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `core` | Core | Newly created core instance
  `rootNode` | Core~Node | The root-node that was loaded.
  `commitHash` | string | The commitHash used as basis for loading the root-node.
  `project` | Project | A reference to the project.

  ##### Returns:

  The core instance.

  Type
    Core | null

#### getCurrentPluginContext(pluginId [, activeNodeId] [, activeSelectionIds])

  Helper method for obtaining the context for a plugin execution. If WebGMEGlobal is defined it is used to get the activeNode and activeSelection (if not specified). The model context, that is project, branch, commitHash is obtained using the state of the client. If there is an activeNode - the namespace will be the namespace of the first base that defines the pluginId at the "validPlugins" registry.

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `pluginId` | string |  |  | Id of plugin.
  `activeNodeId` | string | <optional> | WebGMEGlobal.State.getActiveObject() || '' | Specific id for active node.
  `activeSelectionIds` | Array.<string> | <optional> | WebGMEGlobal.State.getActiveSelection() || [] | Specific ids for active-selection.

  ##### Returns:

  The context needed for runBrowserPlugin/runServerPlugin.

  Type
    object

#### getLibraryInfo(libraryName)

  Returns the info associated with the library in the current project and commit/branch.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `libraryName` | string | Name of library.

  ##### Returns:

  - Info stored at library.
  Type
    object

#### getLibraryNames()

  Returns an array of all libraries at the current project and commit/branch.

  ##### Returns:

  - Fully qualified names of libraries (including libraries of libraries)
  Type
    Array.<string>

#### getNetworkStatus()

  Returns the current connection state or null if connectToDatabase was never invoked.

  ##### Returns:

  One of client.CONSTANTS.STORAGE. CONNECTED/DISCONNECTED/RECONNECTED/INCOMPATIBLE_CONNECTION/CONNECTION_ERROR

  Type
    string | null

#### getNode(path)

  Returns the GMENode of the given node if it has been loaded.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `path` | string | the path of the node in question.

  ##### Returns:

  If the node is loaded it will be returned, otherwise null.

  Type
    GMENode | null

#### getProjectAccess()

  Returns the access the current user had to the selected project when it was opened. Returns null if no project is open. (To get the latest info from the server use client.getProjectObject() followed by project.getProjectInfo.)

  ##### Returns:

  The access levels to the project.

  Type
    object | null

  ##### Example

      { read: true, write: false, delete: false }

#### getProjectInfo()

  Returns the info of the selected project when it was opened. Returns null if no project is open. (To get the latest info from the server use client.getProjectObject() followed by project.getProjectInfo.)

  ##### Returns:

  The project info - see project.getProjectInfo

  Type
    object | null

#### getProjectObject()

  Returns the project object of the selected project. Returns null if no project is open.

  ##### Returns:

  The project instance.

  Type
    ProjectInterface | null

#### getRunningPlugins()

  Gathers the list of running plugins and information about them.

#### getUserId()

  Get the identity of the current user of the client/storage.

  ##### Returns:

  the userId

  Type
    string

#### isCommitReadOnly()

  Returns true if a specific commit is selected (no branch opened).

  ##### Returns:

  True if a commit is selected

  Type
    boolean

#### isConnected()

  Returns true if a connection to the database/storage has been established and is not in a disconnected state.

  ##### Returns:

  True if connected to the database/storage.

  Type
    boolean

#### isProjectReadOnly()

  Returns true if the selected project is read-only for the connected user.

  ##### Returns:

  True if the user only has read-access to the project.

  Type
    boolean

#### isReadOnly()

  Returns true if either the selected project is read-only for the connected user or if a commit is selected, i.e. if either isReadOnlyCommit or isProjectReadOnly return true.

  ##### Returns:

  True if in read-only state.

  Type
    boolean

#### notifyUser( [notification])

  Trigger the client to dispatch a NOTIFICATION (in the generic UI the notification widget listens to these).

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---

  `notification`

  object | string

  <optional>

  Notification to user (if string given will be set at notification.message)

  ###### Properties

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `message` | string |  |  | Message of notification
  `severity` | string | <optional> | 'info' | Notification severity level ('success', 'info', 'warn', 'error')

#### redo(branchName, callback)

  Redo the latest undo. Will immediately resolve with error if the provided branchName is not the same as the selected or if there were commits after the previous undo (see canRedo).

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `branchName` | string | Must match the active branch.

  `callback`

  function

  Invoked when request completed.

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `err` | null | Error | If the request failed.
  `commitResult` | module:Storage~CommitResult | The status of the commit made.

#### removeLibrary(libraryName)

  Remove the library from the current project and branch.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `libraryName` | string | Name of library to remove.

#### removeUI(guid)

  Removes the user at guid and no more events will be triggered at its event-handler.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `guid` | string | The unique id of the "user" to remove.

  ##### Example

      var id = client.addUI(null, function (events) {
           // Say we only wanted the initial updateTerritory event.
           client.removeUI(id);
       });

       client.updateTerritory(id);

#### renameLibrary(oldName, newName)

  Rename the library in the current project and branch.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `oldName` | string | Name of library to rename.
  `newName` | string | New name of library.

#### runBrowserPlugin(pluginId, context, callback)

  Execute the specified plugin inside the browser at the provided context.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `pluginId` | string | Id of plugin.

  `context`

  object

  ###### Properties

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---

  `managerConfig`

  object

  Where the plugin should execute.

  ###### Properties

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `project` | ProjectInterface |  |  | Project (can be obtained via client.getProjectObject()).
  `activeNode` | string | <optional> | '' | Path to activeNode.
  `activeSelection` | string | <optional> | [] | Paths to selected nodes.
  `commitHash` | string |  |  | Commit hash to start the plugin from.
  `branchName` | string | <optional> |  | Branch which to save to.
  `namespace` | string | <optional> | '' | Used namespace ('' represents root namespace).

  `pluginConfig` | object | <optional> | %defaultForPlugin% | Specific configuration for the plugin.

  `callback` | function |

  ##### Fires:

  - Client#event:PLUGIN_INITIATED
  - Client#event:PLUGIN_FINISHED

#### runServerPlugin(pluginId, context, callback)

  Execute the specified plugin on the server at the provided context. Before invoking a plugin on the server you need to make sure that the given commitHash has been persisted in the database.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `pluginId` | string | Id of plugin.

  `context`

  object

  ###### Properties

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---

  `managerConfig`

  object

  Where the plugin should execute.

  ###### Properties

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `project` | ProjectInterface | string |  |  | Project or id of project.
  `activeNode` | string | <optional> | '' | Path to activeNode.
  `activeSelection` | string | <optional> | [] | Paths to selected nodes.
  `commitHash` | string |  |  | Commit hash to start the plugin from.
  `branchName` | string | <optional> |  | Branch which to save to.
  `namespace` | string | <optional> | '' | Used namespace ('' represents root namespace).

  `pluginConfig` | object | <optional> | %defaultForPlugin% | Specific configuration for the plugin.

  `callback` | function |

  ##### Fires:

  - Client#event:PLUGIN_INITIATED
  - Client#event:PLUGIN_FINISHED

#### selectBranch(branchName, callback)

  Selects a branch in the currently opened project. It will close any currently opened branch. If the same branch is opened it will close and reselect it (this differs from how selectProject works).

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `branchName` | string | Name of branch to open.

  `callback`

  function

  Invoked when request completed.

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `err` | null | Error | If the request failed.

  ##### Fires:

  - Client#event:BRANCH_OPENED
  - Client#event:BRANCH_CLOSED
  - Client#event:BRANCH_CHANGED

#### selectCommit(commitHash, callback)

  Selects a specific commit and enters "read-only" mode see isReadOnly and isReadOnlyCommit. If a branch is opened it will be closed. Will resolve with error if the commit does not exist.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `commitHash` | string | Unique id for the commit to select.

  `callback`

  function

  Invoked when request completed.

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `err` | null | Error | If the request failed.

  ##### Fires:

  - Client#event:BRANCH_CLOSED
  - Client#event:BRANCH_CHANGED

#### selectProject(projectId [, branchName], callback)

  Selects a new project and opens a branch for monitoring. Any previously opened project/branch will be closed. If the same project is already open - it will resolve immediately and keep that project open. (To only change the branch use selectBranch instead). If branchName is given and it does not exist, the project will be closed and the callback will resolve with an error. If branchName is NOT given it will attempt proceed in the following in order and break if successful at any step:

  1. Select the 'master' if available.
  2. Select any available branch.
  3. Select the latest commit.
  4. Close the project and resolve with an error.

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `projectId` | string |  |  | Id of project to be selected
  `branchName` | string | <optional> | 'master' | branch to open

  `callback`

  function

  Invoked when request completed.

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `err` | null | Error | If the request failed.

  ##### Fires:

  - Client#event:PROJECT_OPENED
  - Client#event:PROJECT_CLOSED
  - Client#event:BRANCH_OPENED
  - Client#event:BRANCH_CLOSED
  - Client#event:BRANCH_CHANGED

#### sendMessageToPlugin(executionId, messageId, content)

  Sends a message to a running plugin.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `executionId` | string | unique identifier that identifies the plugin execution
  `messageId` | string | the identifier of the message which has been specified by the plugin
  `content` | any | the content of the message

#### startTransaction( [msg])

  Starts a transaction where all changes to nodes are bundled into a single commit. All commit-messages for each change will be joined and separated by '\n'.

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `msg` | string | <optional> | '[' | Start of commit-message.

  ##### Example

      var nodeId = 'someIdToANodeThatIsLoaded';
       client.startTransaction('start of commitMessage');

       // While transaction is open nothing will be committed to the server.
       client.setAttributes(nodeId, 'name', 'newName', 'changes within the transaction');

       client.setRegistry(nodeId, 'position', {x: 100, y:200}, 'some more changes');

       // When we have made all of our changes we make a single commit.
       client.completeTransaction('end of commitMessage', function (err, result) {
        // Here we have the option to get notified when the commit has reached the server
        // and been persisted in the database.

        // The commit hash of the new state of our model.
        console.log(result.hash);

        // If we are working in a branch - this is the status of our commit.
        // 'SYNCED', 'FORKED'.
        console.log(result.status);
      });

#### undo(branchName, callback)

  Undo the latest change/commit, i.e. sets the branch-hash to point to the previous commit. Will immediately resolve with error if the provided branchName is not the same as the selected or if the current user did not make the latest change (see canRedo).

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `branchName` | string | Must match the active branch.

  `callback`

  function

  Invoked when request completed.

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `err` | null | Error | If the request failed.
  `commitResult` | module:Storage~CommitResult | The status of the commit made.

#### updateLibrary(name, blobHashLibraryInfoOrSeedName, callback)

  Sends a server request to update the specified library at the current project and branch.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `name` | string |  | Name of library to update.
  `blobHashLibraryInfoOrSeedName` | string | object |  | If blobHash string given will update library from blob, if string will update from seed, otherwise project at info (will also be added to info at library).
  `blobHashOrLibraryInfo.projectId` | string |  | The projectId of your library.
  `blobHashOrLibraryInfo.branchName` | string | <optional> | The branch that your library follows in the origin project.
  `blobHashOrLibraryInfo.commitHash` | string | <optional> | The commit-hash of your library.

  `callback`

  function

  Invoked when request completed.

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `err` | null | Error | If request failed.
  `result` | module:Storage~CommitResult | Result from the commit made.

#### updateProjectFromFile(projectId, branchName, blobHashOrSeedName, callback)

  Updates the given project and branch name with the provided context.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `projectId` | string | Id of project to update.
  `branchName` | string | Branch that should be updated.
  `blobHashOrSeedName` | string | If blobHash string will update from the webgmex at the blob, if string will update from the webgmex seed.

  `callback`

  function

  Invoked when request completed.

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `err` | null | Error | If request failed.
  `result` | module:Storage~CommitResult | Result from the commit made.

#### updateTerritory(guid, patterns)

  Updates the patterns for the territories defined for the "user" at guid.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `guid` | string | The unique id of the added "user".
  `patterns` | object | The definition for the new territory.

  ##### Example

      // The patterns are defined by using the ids of the nodes and optionally specifying a depth in the containment-
      hierarchy from that node
       client.updateTerritory('ae1b4f8e-32ea-f26f-93b3-ab9c8daa8a42', {
              '/a/b': {
                  children: 0 // Will only add '/a/b' to the territory
              },
              '/a/c': {
                  // children can be left out, implies 0
              },
              '/a/d': {
                  children: 1 // '/a/d' and all its children are included
              },
              '/a/e': {
                  children: 3 // We can go arbitrarily deep down (note in large models too big territories can be slow!)
              }
          });

### Events

#### BRANCH_CHANGED

  Fired when the open branch changed. The event could either return the name of the newly opened branch or null if there no longer is a branch opened.

  ##### Type: string | null

#### BRANCH_CLOSED

  Fired when the currently opened branch is closed.

  ##### Type: string

#### BRANCH_OPENED

  Fired when a branch is opened.

  ##### Type: string

#### BRANCH_STATUS_CHANGED

  Fired when the branch status changes. The returned value is one of:

  - `'SYNC'` - The local branch is in sync with the server.
  - `'AHEAD_SYNC'` - There are changes in the local branch that has not been sent to the server. The latest commit was synchronized.
  - `'AHEAD_NOT_SYNC'` - There are changes in the local branch that has not been sent to the server. The latest commit did not update the branch head. An action is required.
  - `'PULLING'` - External changes to the branch are being pulled into the branch.
  - `'ERROR'` - Some unexpected error happened.
  - (`'MERGING'` - a forked commit is attempted to be merged by the server (this is disabled by default))

  ##### Type: object

#### CONNECTED_USERS_CHANGED

  Fired when there are changes among the users connected to the same branch-room (have the same project and branch opened).

  ##### Type: object

  ##### Properties:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `type` | string |  | 'BRANCH_ROOM_SOCKETS', 'CLIENT_STATE_NOTIFICATION'
  `projectId` | string |  | The id of the project
  `branchName` | string |  | The name of the branch
  `userId` | string |  | The user-id of the user who joined or left
  `socketId` | string |  | The unique socket-id of the user who joined or left (this can become hashed)
  `join` | boolean | undefined | <optional> | Whether or not the user joined or left the room (undefined -> false) this only applies to the 'BRANCH_ROOM_SOCKETS' event.

  `state`

  object | null

  <optional>

  This only applies to the 'CLIENT_STATE_NOTIFICATION' event and is defined by the return value of the function passed in at client.registerUIStateGetter. Behind the scenes this emitted by the client when it receives a 'BRANCH_ROOM_SOCKETS' event in order to notify that new client that it has a user in the same room. But can also be emitted from the GUI by invoking client.emitStateNotification() (which is invoked by the generic webgme UI whenever its state changes). The state in the example below is specific for the generic webgme UI.

  ##### Examples

      {
        "type": "CLIENT_STATE_NOTIFICATION",
        "state": {
          "activeAspect": "All",
          "activeTab": 0,
          "layout": "DefaultLayout",
          "activeVisualizer": "ModelEditor",
          "activeProjectName": "demo+SignalFlowSystem",
          "activeBranchName": "master",
          "activeCommit": null,
          "_toBeActiveObject": "/682825457/607500954",
          "activeObject": "/682825457/607500954",
          "activeSelection": [
            "/682825457/607500954"
          ]
        },
        "projectId": "demo+SignalFlowSystem",
        "branchName": "master",
        "userId": "demo",
        "socketId": "nczll3cDYPfoK7IeAAAT"
      }

      {
        "projectId": "demo+SignalFlowSystem",
        "branchName": "master",
        "userId": "demo",
        "socketId": "nczll3cDYPfoK7IeAAAT",
        "type": "BRANCH_ROOM_SOCKETS",
        "join": true
      }

#### NETWORK_STATUS_CHANGED

  Fired when the network status changes. The returned value is one of:

  - `'CONNECTED'` - The websocket connection has been established (a project can be selected)
  - `'DISCONNECTED'` - The websocket connection is broken, the user can continue offline and any commits will be pushed automatically by the client when reconnected.
  - `'RECONNECTED'` - After a disconnect, the connection has been established again.
  - `'INCOMPATIBLE_CONNECTION'` - If the version of webgme-engine the server is different from the one loaded in the client at this point the browser must be refreshed.
  - `'CONNECTION_ERROR'` - Some unexpected error happened and the browser needs to be refreshed.

  ##### Type: string

#### NOTIFICATION

  A notification with a message to the end-user. Could be generated by plugins or add-ons, but also by GUI widgets.

  ##### Type: object

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `message` | string | The content of the message.
  `severity` | string | One of 'success', 'info', 'warn', 'error'

#### PLUGIN_FINISHED

  Fired when the execution of a plugin - initiated by this given client - finished. The event data contains information about the executed plugin.

  ##### Type: object

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `id` | string | the id of the plugin
  `name` | string | the name of the plugin
  `executionId` | string | unique identifier that can be used for managing the execution and communicating with the running plugin
  `metadata` | object | the original metadata of the plugin
  `context` | object | the context of the plugin that has information about the project, active object, and configuration settings for the run
  `canBeAborted` | boolean | flag that show if the plugin can be aborted
  `start` | string | the exact time of the initiation of the plugin
  `clientSide` | boolean | flag showing if the execution is done on the client or the server side
  `result` | object | the result of the plugin - once it became available

#### PLUGIN_INITIATED

  Fired when the client initiates a plugin execution. The event data contains information about the executed plugin.

  ##### Type: object

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `id` | string | the id of the plugin
  `name` | string | the name of the plugin
  `executionId` | string | unique identifier that can be used for managing the execution and communicating with the running plugin
  `metadata` | object | the original metadata of the plugin
  `context` | object | the context of the plugin that has information about the project, active object, and configuration settings for the run
  `canBeAborted` | boolean | flag that show if the plugin can be aborted
  `start` | string | the exact time of the initiation of the plugin
  `clientSide` | boolean | flag showing if the execution is done on the client or the server side
  `result` | object | the result of the plugin - once it became available

#### PLUGIN_NOTIFICATION

  Fired when the plugin sends a notification to the initiating client. The event data contains information about the executed plugin.

  ##### Type: object

  ##### Properties:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `pluginId` | string |  | the id of the plugin
  `pluginName` | string |  | the name of the plugin
  `pluginVersion` | string |  | the version of the plugin normally in the form of x.y.z
  `executionId` | string |  | unique identifier that can be used for managing the execution and communicating with the running plugin
  `projectId` | string |  | the id of the project context the plugin uses
  `branchName` | string | <optional> | the name of the branch the plugin runs in.
  `commitHash` | string | <optional> | the hash of the commit that represent the version that the plugin runs at.

  `notification`

  object

  the content of the notification, as the plugin control the content there are no mandatory fields

  ###### Properties

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `message` | string | <optional> | the text content of the notification
  `severity` | string | <optional> | the severity of the notification ('debug', 'info' (default), 'warning', 'error').

  `type` | string |  | the exact type of the notification which should always be 'PLUGIN_NOTIFICATION'.

#### PROJECT_CLOSED

  Fired when the currently opened project is closed.

  ##### Type: string

#### PROJECT_OPENED

  Fired when a project is opened.

  ##### Type: string

#### Search results