dmx-api 2.0.0 → 3.0.0

package/README.md

@@ -2,6 +2,73 @@
 
 ## Version History
 
+**3.0** -- May 19, 2023
+
+Version 3.0 of the `dmx-api` library extends/modifies the API in order to support a wider variety of frontend
+applications. Additionally, depending on application type, the launch time is reduced as less data is transferred from
+server ([#497](https://git.dmx.systems/dmx-platform/dmx-platform/-/issues/497),
+[#501](https://git.dmx.systems/dmx-platform/dmx-platform/-/issues/501)). This required some breaking changes in the
+library's `init()` function.
+
+* BREAKING CHANGES
+    - changed behavior of the library's `init()` function:
+        - The client-side type cache is not fully pre-populated by default anymore. Instead the application pass
+          `topicTypes` config to pre-populate selectively, or pass `all`. Depending on application type this results in
+          less data transfer at application launch.
+        - The SVG utility for FontAwesome icons is not initialized by default anymore. Instead an application can
+          initialize it on-demand (by calling `dmx.icons.init()`). Applications who don't need it launch quicker as
+          downloading the FontAwesome SVG data (450K) is omitted.
+    - rename class `Type` -> `DMXType`
+    - remove `getPosition()` from `ViewTopic`. Use the new `pos` getter instead.
+* Improvement:
+    - The library's `init()` function optionally opens the WebSocket for client-synchronization (if `messageHandler`
+      config is passed). The application no longer depends on
+      [dmx-websocket](https://github.com/dmx-systems/dmx-websocket) module then.
+    - Vanilla [axios](https://github.com/axios/axios) http instance (without error interceptor set by application) is
+      exported as `rpc._http`.
+* Model:
+    - change `Type`'s `newFormModel()`:
+        - `object` parameter is now optional
+        - add `allChildren` parameter (optional)
+    - add `panX`, `panY`, `zoom`, `bgImageUrl` getters to `Topicmap`
+    - add `updateTopic()`, `updateAssoc()` to `Topicmap` (part of
+      [dmx-topicmap-panel](https://github.com/dmx-systems/dmx-topicmap-panel) protocol)
+    - add `pos` getter to `ViewTopic`
+* RPC:
+    - add `getTopicType()` and `getAssocType()`
+    - add `includeChildren` parameter to `getTopicmap()`
+    - add `includeChildren` and `includeAssocChildren` parameters to `getAssignedWorkspace()`
+    - add `getMemberships()` to get the members of a workspace
+    - add `bulkUpdateUserMemberships()` and `bulkUpdateWorkspaceMemberships()`
+    - add `deleteWorkspace()`
+    - change `updateTopic()`: returns `Topic` plus directives (formerly just directives)
+    - change `login()`: returned promise resolves with username (formerly undefined)
+* Utils:
+    - add `stripHtml()`
+* Fix:
+    - fixed a bug where nested entities loose their child values while update request
+
+**2.1** -- Jun 13, 2021
+
+* Model:
+    * add class `RoleType`
+    * add `isEditable` getter to `DMXObject`
+    * add `isRoleType` getter to `DMXObject`
+    * add `asRoleType()` to `Topic`
+    * add `arrowShape` and `hollow` getters to `Player`
+    * add `isNoneditable` getter to `Type`
+* RPC:
+    * add `getAllRoleTypes()`
+    * add `getTopicTypeImplicitly()`, `getAssocTypeImplicitly()`, `getRoleTypeImplicitly()`
+    * add `getConfigDefs()`, `getConfigTopic()`, `updateConfigTopic()`
+* Utils:
+    * add `formatFileSize()`
+    * add `round()`
+* Fixes:
+    * Model: fix `TopicType.newTopicModel()` regarding identity attributes
+    * Model: `_newInstance()` fills in `0` object value as is (not as `''`)
+    * Type cache: `initTypeCache` action returns promise
+
 **2.0** -- Dec 30, 2020
 
 * BREAKING CHANGES
@@ -198,7 +265,8 @@
 
 **0.13** -- Mar 25, 2018
 
-* Model: `Topicmap.revealTopic()`'s `pos` param is optional. If not given it's up to the topicmap renderer to position the topic.
+* Model: `Topicmap.revealTopic()`'s `pos` param is optional. If not given it's up to the topicmap renderer to position
+  the topic.
 * Utils: `clone()` for deep-cloning arbitrary objects
 * Depends on module `clone` instead `lodash.clonedeep`
 
@@ -248,4 +316,4 @@
 
 ------------
 Jörg Richter  
-Dec 30, 2020
+Jun 13, 2021

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "dmx-api",
-  "version": "2.0.0",
-  "description": "DMX 5 base types and API",
+  "version": "3.0.0",
+  "description": "API and utilities for DMX 5 based frontends",
   "author": "Jörg Richter <jri@dmx.berlin>",
   "license": "AGPL-3.0",
   "main": "src/index.js",
-  "unpkg": "dist/dmx-api.min.js",
   "repository": {
     "type": "git",
     "url": "https://github.com/dmx-systems/dmx-api.git"

package/src/icons.js

@@ -6,11 +6,17 @@ import rpc from './rpc'
 let faFont              // Font Awesome SVG <font> element
 let faDefaultWidth      // Default icon width
 
-// a promise resolved once the Font Awesome SVG is loaded
-const svgReady = rpc.getXML(fa).then(svg => {
-  faFont = svg.querySelector('font')
-  faDefaultWidth = faFont.getAttribute('horiz-adv-x')
-})
+/**
+ * Initializes the Icons-Toolkit.
+ *
+ * @returns   a promise resolved once the toolkit is ready for `faGlyph()` calls (Font Awesome SVG is loaded).
+ */
+function init () {
+  return rpc.getXML(fa).then(svg => {
+    faFont = svg.querySelector('font')
+    faDefaultWidth = faFont.getAttribute('horiz-adv-x')
+  })
+}
 
 function faGlyph (unicode) {
   try {
@@ -25,6 +31,6 @@ function faGlyph (unicode) {
 }
 
 export default {
-  ready: svgReady,
+  init,
   faGlyph
 }

package/src/index.js

@@ -1,22 +1,23 @@
-import {
-  DMXObject, Topic, Assoc, Player, RelatedTopic, Type, TopicType, AssocType, Topicmap, ViewTopic, ViewAssoc,
-  setIconRenderers
-} from './model'
-import rpc       from './rpc'
-import typeCache from './type-cache'
-import permCache from './permission-cache'
-import utils     from './utils'
-import icons     from './icons'
-
-console.log('[DMX-API] 2.0')
+import * as model   from './model'
+import rpc          from './rpc'
+import permCache    from './permission-cache'
+import utils        from './utils'
+import icons        from './icons'
+import DMXWebSocket from './websocket'
+import {default as typeCache, init as initTypeCache, storeModule} from './type-cache'
+
+console.log('[DMX-API] 3.0')
 
 let adminWorkspaceId    // promise
 
-export default {
+const clientId = newClientId()
+updateClientIdCookie()
 
-  /* eslint object-property-newline: "off" */
-  DMXObject, Topic, Assoc, Player, RelatedTopic, Type, TopicType, AssocType, Topicmap, ViewTopic, ViewAssoc,
+window.addEventListener('focus', updateClientIdCookie)
 
+export default {
+
+  ...model,
   rpc,
   typeCache,
   permCache,
@@ -24,10 +25,12 @@ export default {
   icons,
 
   init (config) {
-    config.iconRenderers && setIconRenderers(config.iconRenderers)
-    config.onHttpError && rpc.setErrorHandler(config.onHttpError)
     adminWorkspaceId = rpc.getAdminWorkspaceId()
-    return typeCache.init(config.store)
+    config.store.registerModule('typeCache', storeModule)
+    config.messageHandler && new DMXWebSocket(rpc.getWebsocketConfig(), config.messageHandler)
+    config.onHttpError && rpc.setErrorHandler(config.onHttpError)
+    config.iconRenderers && model.setIconRenderers(config.iconRenderers)
+    return initTypeCache(config.topicTypes)
   },
 
   /**
@@ -37,3 +40,12 @@ export default {
     return adminWorkspaceId.then(id => permCache.isWritable(id))
   }
 }
+
+function updateClientIdCookie () {
+  // DEV && console.log('dmx_client_id', clientId)
+  utils.setCookie('dmx_client_id', clientId)
+}
+
+function newClientId () {
+  return Math.floor(Number.MAX_SAFE_INTEGER * Math.random())
+}

package/src/model.js

@@ -17,7 +17,7 @@ class DMXObject {
 
   constructor (object) {
     if (!object) {
-      throw Error(`invalid object passed to DMXObject constructor: ${object}`)
+      throw Error(`invalid object passed to DMXObject constructor: ${JSON.stringify(object)}`)
     } else if (object.constructor.name !== 'Object') {
       throw Error(`DMXObject constructor expects Object, got ${object.constructor.name} ${JSON.stringify(object)}`)
     }
@@ -68,6 +68,17 @@ class DMXObject {
     return rpc.getRelatedTopicsWithoutChilds(this.id)
   }
 
+  /**
+   * @return  true if this object is editable *in principle*, independent of user's authorization.
+   *
+   *          For entity topics, assocs and types <code>true</code> is returned, provided "Noneditable" is
+   *          not set in the type's view config.
+   *          For value topics, or if "Noneditable" is set, <code>false</code> is returned.
+   */
+  get isEditable () {
+    return (this.isAssoc || this.isType || this.type.isEntity) && !this.type.isNoneditable
+  }
+
   /**
    * @return  a promise for a true/false value
    */
@@ -153,6 +164,10 @@ class Topic extends DMXObject {
            this.typeUri === 'dmx.core.assoc_type'
   }
 
+  get isRoleType () {
+    return this.typeUri === 'dmx.core.role_type'
+  }
+
   get isCompDef () {
     return false    // topics are never comp defs
   }
@@ -171,7 +186,6 @@ class Topic extends DMXObject {
   }
 
   update () {
-    console.log('update', this)
     return rpc.updateTopic(this)
   }
 
@@ -207,6 +221,14 @@ class Topic extends DMXObject {
       throw Error(`not a type: ${this}`)
     }
   }
+
+  asRoleType () {
+    if (this.isRoleType) {
+      return typeCache.getRoleType(this.uri)
+    } else {
+      throw Error(`not a role type: ${this}`)
+    }
+  }
 }
 
 class Assoc extends DMXObject {
@@ -270,6 +292,10 @@ class Assoc extends DMXObject {
     return false    // assocs are never types
   }
 
+  get isRoleType () {
+    return false    // assocs are never role types
+  }
+
   get isCompDef () {
     return this.typeUri === 'dmx.core.composition_def'
   }
@@ -288,7 +314,6 @@ class Assoc extends DMXObject {
   }
 
   update () {
-    console.log('update', this)
     return rpc.updateAssoc(this)
   }
 
@@ -343,6 +368,14 @@ class Player {
     return this.getRoleType().value
   }
 
+  get arrowShape () {
+    return this.getRoleType().getViewConfig('dmx.webclient.arrow_shape') || 'none'
+  }
+
+  get hollow () {
+    return this.getRoleType().getViewConfig('dmx.webclient.hollow') || false
+  }
+
   isTopicPlayer () {
     return this.topicId >= 0    // Note: 0 is a valid topic ID
   }
@@ -380,13 +413,13 @@ class RelatedTopic extends Topic {
   }
 }
 
-class Type extends Topic {
+class DMXType extends Topic {
 
   constructor (type) {
     super(type)
     this.dataTypeUri = type.dataTypeUri
     this.compDefs   = utils.instantiateMany(type.compDefs, CompDef)
-    this.viewConfig = utils.mapByTypeUri(utils.instantiateMany(type.viewConfigTopics, Topic))    // TODO: rename prop?
+    this.viewConfig = utils.mapByTypeUri(utils.instantiateMany(type.viewConfigTopics, Topic))
   }
 
   get isSimple () {
@@ -418,6 +451,7 @@ class Type extends Topic {
   }
 
   // ### TODO: copy in CompDef
+  // ### TODO: copy in RoleType
   getViewConfig (childTypeUri) {
     // TODO: don't hardcode config type URI
     const configTopic = this.viewConfig['dmx.webclient.view_config']
@@ -437,18 +471,32 @@ class Type extends Topic {
     return this.getViewConfig('dmx.webclient.color#dmx.webclient.background_color')
   }
 
+  get isNoneditable () {
+    return this.getViewConfig('dmx.webclient.noneditable')
+  }
+
   /**
    * Creates a form model for this type.
    *
-   * @param   object  optional, if given its values are filled in. ### FIXDOC
-   *                  The object is expected to be of *this* type.
+   * @param   object        optional, if given 1) its values are filled in, and 2) is manipulated in-place, that
+   *                        includes a) adding empty fields, and b) removing fields when "Reduced Details" is
+   *                        switched on (the default, see "allChildren" parameter).
+   *                        The given object is expected to be of *this* type.
+   * @param   allChildren   optional, if true all children are included in the returned form model, that is
+   *                        "Reduced Details" is switched off. Default is false.
    *
-   * @return  the created form model. ### FIXDOC
+   * @return  the created form model. If "object" is given the (in-place manipulated) object is returned.
+   *          Otherwise a newly created form model with empty values is returned.
    */
-  newFormModel (object) {
-    const o = this._newFormModel(object)
-    object.children = utils.instantiateChildren(o.children)
-    return object
+  newFormModel (object, allChildren) {
+    const o = this._newFormModel(object, allChildren)
+    if (object) {
+      object.children = utils.instantiateChildren(o.children)
+      // FIXME: o.assoc is not used
+      return object
+    } else {
+      return o
+    }
   }
 
   /**
@@ -457,14 +505,14 @@ class Type extends Topic {
    *
    * @return  a newly constructed plain object
    */
-  _newFormModel (object) {
+  _newFormModel (object, allChildren, level = 0, compDef) {
 
     function _newFormModel (object, type, level, compDef) {
       const o = type._newInstance(object)
       if (type.isComposite) {
         type.compDefs.forEach(compDef => {
           // Reduced details: at deeper levels for entity types only their identity attributes are included
-          if (level === 0 || type.isValue || compDef.isIdentityAttr) {
+          if (allChildren || level === 0 || type.isValue || compDef.isIdentityAttr) {
             const compDefUri = compDef.compDefUri
             const childType = compDef.childType
             const child = object && object.children[compDefUri]
@@ -487,45 +535,42 @@ class Type extends Topic {
       return o
     }
 
-    return _newFormModel(object, this, 0)
+    return _newFormModel(object, this, level, compDef)
   }
 
   _newInstance (object) {
-    // console.log('_newInstance', this, object)
-    const o = {
-      id:      object && object.id      || -1,                                    /* eslint no-mixed-operators: "off" */
-      uri:     object && object.uri     || '',
-      typeUri: object && object.typeUri || this.uri,
-      value:   object && object.value   || '',
+    return {
+      id:      object ? object.id      : -1,
+      uri:     object ? object.uri     : '',
+      typeUri: object ? object.typeUri : this.uri,
+      value:   object ? object.value   : '',
       children: {}
     }
-    return o
   }
 }
 
-class TopicType extends Type {
+class TopicType extends DMXType {
 
-  // TODO: drop this method in favor of newFormModel() and fill in the default value(s) afterwards?
   /**
-   * @returns   a plain object.
+   * Creates a form model for this topic type, and fills in the given value.
+   *
+   * @returns   a newly constructed plain object.
    */
   newTopicModel (simpleValue) {
+    const topic = this._newFormModel()
+    initTopicValue(topic, this)
+    return topic
 
-    function _newTopicModel (type) {
-      const topic = {typeUri: type.uri}
+    function initTopicValue (topic, type) {
       if (type.isSimple) {
         topic.value = simpleValue
       } else {
         const compDef = type.compDefs[0]
-        const child = _newTopicModel(compDef.childType)
-        topic.children = {
-          [compDef.compDefUri]: compDef.isOne ? child : [child]
-        }
+        const children = topic.children[compDef.compDefUri]
+        const child = compDef.isOne ? children : children[0]
+        initTopicValue(child, compDef.childType)
       }
-      return topic
     }
-
-    return _newTopicModel(this)
   }
 
   get icon () {
@@ -549,7 +594,7 @@ class TopicType extends Type {
   }
 }
 
-class AssocType extends Type {
+class AssocType extends DMXType {
 
   get isTopicType () {
     return false
@@ -591,8 +636,6 @@ class CompDef extends Assoc {
     if (isIdentityAttr) {
       this.isIdentityAttr = isIdentityAttr.value
     } else {
-      // ### TODO: should an isIdentityAttr child always exist?
-      // console.warn(`Comp def ${this.compDefUri} has no identity_attr child (parent type: ${this.parentTypeUri})`)
       this.isIdentityAttr = false
     }
     //
@@ -600,8 +643,6 @@ class CompDef extends Assoc {
     if (includeInLabel) {
       this.includeInLabel = includeInLabel.value
     } else {
-      // ### TODO: should an includeInLabel child always exist?
-      // console.warn(`Comp def ${this.compDefUri} has no include_in_label child (parent type: ${this.parentTypeUri})`)
       this.includeInLabel = false
     }
   }
@@ -638,7 +679,7 @@ class CompDef extends Assoc {
     return topic && topic.value
   }
 
-  // ### TODO: principal copy in Type
+  // ### TODO: principal copy in DMXType
   _getViewConfig (childTypeUri) {
     // TODO: don't hardcode config type URI
     const configTopic = this.viewConfig['dmx.webclient.view_config']
@@ -658,13 +699,32 @@ class CompDef extends Assoc {
     return 'dmx.core.composition'
   }
 
-  emptyChildInstance () {
-    const topic = this.childType._newFormModel()
+  emptyChildInstance (level) {
+    const topic = this.childType._newFormModel(undefined, false, level, this)
     topic.assoc = this.instanceLevelAssocType._newFormModel()
     return new Topic(topic)
   }
 }
 
+class RoleType extends Topic {
+
+  constructor (roleType) {
+    super(roleType)
+    this.viewConfig = utils.mapByTypeUri(utils.instantiateMany(roleType.viewConfigTopics, Topic))
+  }
+
+  getViewConfig (childTypeUri) {
+    // TODO: don't hardcode config type URI
+    const configTopic = this.viewConfig['dmx.webclient.view_config']
+    if (!configTopic) {
+      // console.warn(`Type "${this.uri}" has no view config`)
+      return
+    }
+    const topic = configTopic.children[childTypeUri]
+    return topic && topic.value
+  }
+}
+
 class Topicmap extends Topic {
 
   constructor (topicmap) {
@@ -741,17 +801,16 @@ class Topicmap extends Topic {
   }
 
   /**
-   * Returns the position of the given topic/assoc.
-   *
-   * Note: ViewTopic has getPosition() too but ViewAssoc has not
-   * as a ViewAssoc doesn't know the Topicmap it belongs to.
+   * Returns the position of the given topic/assoc of this topicmap.
    *
    * @param   id      a topic ID or an assoc ID
    */
   getPosition (id) {
+    // Note: a ViewAssoc can't have a `pos` getter (like ViewTopic) as assoc pos is calculated from the player objects
+    // and the assoc only has its IDs and no reference to the Topicmap. So we make `getPosition()` a Topicmap method.
     const o = this.getObject(id)
     if (o.isTopic) {
-      return o.getPosition()
+      return o.pos
     } else {
       const pos1 = this.getPosition(o.player1.id)
       const pos2 = this.getPosition(o.player2.id)
@@ -763,22 +822,28 @@ class Topicmap extends Topic {
   }
 
   /**
+   * Adds the given topic to this topicmap.
+   * If the topic is contained in the topicmap already (ID-check) it is replaced.
+   *
    * @param   topic   a dmx.ViewTopic
    */
   addTopic (topic) {
     if (!(topic instanceof ViewTopic)) {
-      throw Error(`addTopic() expects a ViewTopic, got ${topic.constructor.name}`)
+      throw Error(`addTopic() expects ViewTopic, got ${topic.constructor.name}`)
     }
     // reactivity is required to trigger "visibleTopicIds" getter (module dmx-cytoscape-renderer)
     Vue.set(this._topics, topic.id, topic)
   }
 
   /**
+   * Adds the given assoc to this topicmap.
+   * If the assoc is contained in the topicmap already (ID-check) it is replaced.
+   *
    * @param   assoc   a dmx.ViewAssoc
    */
   addAssoc (assoc) {
     if (!(assoc instanceof ViewAssoc)) {
-      throw Error(`addAssoc() expects a ViewAssoc, got ${assoc.constructor.name}`)
+      throw Error(`addAssoc() expects ViewAssoc, got ${assoc.constructor.name}`)
     }
     // reactivity is required to trigger "visibleAssocIds" getter (module dmx-cytoscape-renderer)
     Vue.set(this._assocs, assoc.id, assoc)
@@ -850,6 +915,21 @@ class Topicmap extends Topic {
     return op
   }
 
+  // the following 4 methods are part of the Topicmap Panel protocol
+
+  updateTopic (topic) {
+    if (this.id === topic.id) {
+      Vue.set(
+        this.children,
+        'dmx.base.url#dmx.topicmaps.background_image',
+        topic.children['dmx.base.url#dmx.topicmaps.background_image']
+      )
+    }
+  }
+
+  updateAssoc (assoc) {
+  }
+
   /**
    * Note: if the topic is not in this topicmap nothing is performed.
    */
@@ -910,6 +990,23 @@ class Topicmap extends Topic {
 
   // Topicmap
 
+  get panX () {
+    return this.viewProps['dmx.topicmaps.pan_x']
+  }
+
+  get panY () {
+    return this.viewProps['dmx.topicmaps.pan_y']
+  }
+
+  get zoom () {
+    return this.viewProps['dmx.topicmaps.zoom']
+  }
+
+  get bgImageUrl () {
+    const url = this.children['dmx.base.url#dmx.topicmaps.background_image']
+    return url && url.value
+  }
+
   setViewport (pan, zoom) {
     this.viewProps['dmx.topicmaps.pan_x'] = pan.x
     this.viewProps['dmx.topicmaps.pan_y'] = pan.y
@@ -965,8 +1062,7 @@ class ViewTopic extends viewPropsMixin(Topic) {
     return rpc.getTopic(this.id, true, true)
   }
 
-  // TODO: make it a "pos" getter?
-  getPosition () {
+  get pos () {
     return {
       x: this.getViewProp('dmx.topicmaps.x'),
       y: this.getViewProp('dmx.topicmaps.y')
@@ -1004,9 +1100,10 @@ export {
   Assoc,
   Player,
   RelatedTopic,
-  Type,
+  DMXType,
   TopicType,
   AssocType,
+  RoleType,
   Topicmap,
   ViewTopic,
   ViewAssoc,

package/src/rpc.js

@@ -1,7 +1,7 @@
 import http from 'axios'
 import permCache  from './permission-cache'
 import utils from './utils'
-import {Topic, Assoc, RelatedTopic, TopicType, AssocType, Topicmap} from './model'
+import {Topic, Assoc, RelatedTopic, TopicType, AssocType, RoleType, Topicmap} from './model'
 
 // Vanilla instance without error interceptor.
 // In contrast the default http instance allows the caller to set an error handler (see setErrorHandler()).
@@ -108,9 +108,11 @@ export default {
   },
 
   updateTopic (topicModel) {
-    return http.put(`/core/topic/${topicModel.id}`, topicModel).then(response =>
-      response.data
-    )
+    return http.put(`/core/topic/${topicModel.id}`, topicModel).then(response => {
+      const topic = new Topic(response.data)
+      topic.directives = response.data.directives
+      return topic
+    })
   },
 
   deleteTopic (id) {
@@ -204,6 +206,18 @@ export default {
 
   // Topic Types
 
+  getTopicType (topicTypeUri) {
+    return http.get(`/core/topic-type/${topicTypeUri}`).then(response =>
+      new TopicType(response.data)
+    )
+  },
+
+  getTopicTypeImplicitly (topicId) {
+    return http.get(`/core/topic-type/topic/${topicId}`).then(response =>
+      new TopicType(response.data)
+    )
+  },
+
   getAllTopicTypes () {
     return http.get('/core/topic-types').then(response =>
       utils.instantiateMany(response.data, TopicType)
@@ -224,6 +238,18 @@ export default {
 
   // Association Types
 
+  getAssocType (assocTypeUri) {
+    return http.get(`/core/assoc-type/${assocTypeUri}`).then(response =>
+      new AssocType(response.data)
+    )
+  },
+
+  getAssocTypeImplicitly (assocId) {
+    return http.get(`/core/assoc-type/assoc/${assocId}`).then(response =>
+      new AssocType(response.data)
+    )
+  },
+
   getAllAssocTypes () {
     return http.get('/core/assoc-types').then(response =>
       utils.instantiateMany(response.data, AssocType)
@@ -244,9 +270,21 @@ export default {
 
   // Role Types
 
-  createRoleType (topicModel) {
-    return http.post('/core/roletype', topicModel).then(response =>
-      new Topic(response.data)
+  getRoleTypeImplicitly (assocId, roleTypeUri) {
+    return http.get(`/core/role-type/${roleTypeUri}/assoc/${assocId}`).then(response =>
+      new RoleType(response.data)
+    )
+  },
+
+  getAllRoleTypes () {
+    return http.get('/core/role-types').then(response =>
+      utils.instantiateMany(response.data, RoleType)
+    )
+  },
+
+  createRoleType (roleTypeModel) {
+    return http.post('/core/role-type', roleTypeModel).then(response =>
+      new RoleType(response.data)
     )
   },
 
@@ -276,8 +314,12 @@ export default {
     )
   },
 
-  getTopicmap (topicmapId) {
-    return http.get(`/topicmaps/${topicmapId}`).then(response =>
+  getTopicmap (topicmapId, includeChildren) {
+    return http.get(`/topicmaps/${topicmapId}`, {
+      params: {
+        children: includeChildren,
+      }
+    }).then(response =>
       new Topicmap(response.data)
     )
   },
@@ -344,7 +386,6 @@ export default {
   },
 
   setTopicmapViewport: utils.debounce((topicmapId, pan, zoom) => {
-    // console.log('setTopicmapViewport')
     roundPos(pan, 'x', 'y')
     http.put(`/topicmaps/${topicmapId}/pan/${pan.x}/${pan.y}/zoom/${zoom}`)
   }, 3000),
@@ -362,6 +403,10 @@ export default {
     )
   },
 
+  deleteWorkspace (workspaceId) {
+    http.delete(`/workspaces/${workspaceId}`)
+  },
+
   getAssignedTopics (workspaceId, topicTypeUri, includeChildren, includeAssocChildren) {
     return http.get(`/workspaces/${workspaceId}/topics/${topicTypeUri}`, {
       params: {
@@ -376,8 +421,13 @@ export default {
   /**
    * @return  the workspace topic, or empty string if no workspace is assigned
    */
-  getAssignedWorkspace (objectId) {
-    return http.get(`/workspaces/object/${objectId}`).then(response =>
+  getAssignedWorkspace (objectId, includeChildren, includeAssocChildren) {
+    return http.get(`/workspaces/object/${objectId}`, {
+      params: {
+        children: includeChildren,
+        assocChildren: includeAssocChildren
+      }
+    }).then(response =>
       // Note: if no workspace is assigned the response is 204 No Content; "data" is the empty string then
       response.data && new Topic(response.data)
     )
@@ -398,7 +448,10 @@ export default {
       headers: {
         Authorization: authMethod + ' ' + btoa(credentials.username + ':' + credentials.password)
       }
-    }).then(() => permCache.clear())
+    }).then(() => {
+      permCache.clear()
+      return credentials.username
+    })
   },
 
   logout () {
@@ -424,6 +477,34 @@ export default {
     )
   },
 
+  getMemberships (id) {
+    return http.get(`/access-control/workspace/${id}/memberships`).then(response =>
+      utils.instantiateMany(response.data, RelatedTopic)
+    )
+  },
+
+  bulkUpdateUserMemberships (username, addWorkspaceIds, removeWorkspaceIds) {
+    return http.put(`/access-control/user/${username}`, undefined, {
+      params: {
+        addWorkspaceIds: addWorkspaceIds.join(','),
+        removeWorkspaceIds: removeWorkspaceIds.join(',')
+      }
+    }).then(response =>
+      utils.instantiateMany(response.data, RelatedTopic)
+    )
+  },
+
+  bulkUpdateWorkspaceMemberships (workspaceId, addUserIds, removeUserIds) {
+    return http.put(`/access-control/workspace/${workspaceId}`, undefined, {
+      params: {
+        addUserIds: addUserIds.join(','),
+        removeUserIds: removeUserIds.join(',')
+      }
+    }).then(response =>
+      utils.instantiateMany(response.data, RelatedTopic)
+    )
+  },
+
   getAdminWorkspaceId () {
     return http.get('/access-control/workspace/admin/id').then(response =>
       response.data
@@ -467,6 +548,31 @@ export default {
     )
   },
 
+  // === Config ===
+
+  getConfigDefs () {
+    return http.get(`/config`).then(response =>
+      response.data
+    )
+  },
+
+  getConfigTopic (configTypeUri, topicId, includeChildren, includeAssocChildren) {
+    return http.get(`/config/${configTypeUri}/topic/${topicId}`, {
+      params: {
+        children: includeChildren,
+        assocChildren: includeAssocChildren
+      }
+    }).then(response =>
+      new RelatedTopic(response.data)
+    )
+  },
+
+  updateConfigTopic(topicId, configTopic) {
+    return http.put(`/config/topic/${topicId}`, configTopic).then(response =>
+      response.data.directives
+    )
+  },
+
   // === Timestamps ===
 
   getCreationTime (id) {
@@ -499,7 +605,9 @@ export default {
         return Promise.reject(error)
       }
     )
-  }
+  },
+
+  _http
 }
 
 function toPath (idLists) {

package/src/type-cache.js

@@ -1,16 +1,17 @@
-import {Topic, TopicType, AssocType} from './model'
+import {Topic, TopicType, AssocType, RoleType} from './model'
 import rpc from './rpc'
 import utils from './utils'
 import Vue from 'vue'
 
+const typeP = {}      // intermediate type promises
+
 // Note: the type cache is reactive state. E.g. new topic types appear in the Search Widget's
 // type menu automatically (see "createTopicTypes" getter in search.js of module dmx-search).
-
 const state = {
-  topicTypes: undefined,    // object: type URI (string) -> TopicType
-  assocTypes: undefined,    // object: type URI (string) -> AssocType
-  dataTypes:  undefined,    // object: data type URI (string) -> data type (Topic)
-  roleTypes:  undefined     // object: role type URI (string) -> role type (Topic)
+  topicTypes: {},     // object: topic type URI (string) -> TopicType
+  assocTypes: {},     // object: assoc type URI (string) -> AssocType
+  roleTypes:  {},     // object: role type URI (string) -> RoleType
+  dataTypes:  {}      // object: data type URI (string) -> data type (Topic)
 }
 
 const actions = {
@@ -27,6 +28,13 @@ const actions = {
     _putRoleType(roleType)
   },
 
+  /**
+   * Re-populates the type cache with *all* types readable by current user.
+   */
+  initTypeCache () {
+    return initAllTypes()
+  },
+
   // WebSocket messages
 
   _newTopicType (_, {topicType}) {
@@ -70,9 +78,12 @@ const actions = {
       case 'UPDATE_TOPIC_TYPE':
         putTopicType(dir.arg)
         break
-      case 'UPDATE_ASSOCIATION_TYPE':
+      case 'UPDATE_ASSOC_TYPE':
         putAssocType(dir.arg)
         break
+      case 'UPDATE_ROLE_TYPE':
+        putRoleType(dir.arg)
+        break
       }
       // Note: role types are never updated as they are simple values and thus immutable
     })
@@ -83,10 +94,10 @@ const actions = {
         case 'DELETE_TOPIC_TYPE':
           removeTopicType(dir.arg.uri)
           break
-        case 'DELETE_ASSOCIATION_TYPE':
+        case 'DELETE_ASSOC_TYPE':
           removeAssocType(dir.arg.uri)
           break
-        case 'DELETE_TOPIC':
+        case 'DELETE_TOPIC':      // TODO: DELETE_ROLE_TYPE
           if (dir.arg.typeUri === 'dmx.core.role_type') {
             removeRoleType(dir.arg.uri)
           }
@@ -97,29 +108,17 @@ const actions = {
   }
 }
 
-function init (store) {
-  store.registerModule('typeCache', {
-    state,
-    actions
-  })
-  // init state
-  return Promise.all([
-    rpc.getAllTopicTypes().then(topicTypes => {
-      state.topicTypes = utils.mapByUri(topicTypes)
-      _putTopicType(bootstrapType())
-    }),
-    rpc.getAllAssocTypes().then(assocTypes => {
-      state.assocTypes = utils.mapByUri(assocTypes)
-    }),
-    rpc.getTopicsByType('dmx.core.data_type').then(dataTypes => {
-      state.dataTypes = utils.mapByUri(dataTypes)
-    }),
-    rpc.getTopicsByType('dmx.core.role_type').then(roleTypes => {
-      state.roleTypes = utils.mapByUri(roleTypes)
-    })
-  ]).then(() => {
-    // console.log('### Type cache ready!')
-  })
+function init (topicTypes) {
+  if (topicTypes) {
+    let p
+    if (topicTypes === 'all') {
+      p = initAllTypes()
+    } else {
+      topicTypes.forEach(_initTopicType)
+      // TODO: return promise
+    }
+    return p
+  }
 }
 
 // ---
@@ -141,9 +140,9 @@ function getRoleType (uri) {
 }
 
 function getType (uri, className, prop) {
-  const type = state[prop] && state[prop][uri]
+  const type = _getType(uri, prop)
   if (!type) {
-    throw Error(`unknown ${className} "${uri}"`)
+    throw Error(`${className} "${uri}" not in type cache`)
   }
   return type
 }
@@ -161,7 +160,7 @@ function getTypeById (id) {
 
 // TODO: the following 4 functions return async data so they should return promise
 
-// IMPORTANT: call these methods only from a reactive context, otherwise you might get undefined
+// IMPORTANT: calling these methods must be synced, otherwise you might get undefined
 
 function getAllTopicTypes () {
   return getAllTypes('topicTypes')
@@ -188,6 +187,67 @@ function getAllTypes (prop) {
 
 // ---
 
+function initAllTypes () {
+  return Promise.all([
+    // init state
+    rpc.getAllTopicTypes().then(topicTypes => {
+      state.topicTypes = utils.mapByUri(topicTypes)
+      _putTopicType(bootstrapType())
+    }),
+    rpc.getAllAssocTypes().then(assocTypes => {
+      state.assocTypes = utils.mapByUri(assocTypes)
+    }),
+    rpc.getAllRoleTypes().then(roleTypes => {
+      state.roleTypes = utils.mapByUri(roleTypes)
+    }),
+    rpc.getTopicsByType('dmx.core.data_type').then(dataTypes => {
+      state.dataTypes = utils.mapByUri(dataTypes)
+    })
+  ])
+}
+
+function _initTopicType (uri) {
+  _initType(uri, 'topicTypes', TopicType, rpc.getTopicType).then(topicType => {
+    topicType.compDefs.forEach(compDef => {
+      _initTopicType(compDef.childTypeUri)
+      _initAssocType(compDef.instanceLevelAssocTypeUri)
+    })
+  })
+}
+
+function _initAssocType (uri) {
+  _initType(uri, 'assocTypes', AssocType, rpc.getAssocType).then(assocType => {
+    assocType.compDefs.forEach(compDef => {
+      _initTopicType(compDef.childTypeUri)
+      // TODO: call _initAssocType()?
+    })
+  })
+}
+
+function _initType (uri, prop, typeClass, fetchFunc) {
+  const type = _getType(uri, prop)
+  if (type) {
+    return Promise.resolve(type)
+  } else {
+    let p = typeP[uri]
+    if (!p) {
+      p = fetchFunc(uri).then(type => {
+        _putType(type, typeClass, prop)
+        delete typeP[uri]
+        return type
+      })
+      typeP[uri] = p
+    }
+    return p
+  }
+}
+
+function _getType (uri, prop) {
+  return state[prop] && state[prop][uri]
+}
+
+// ---
+
 function putTopicType (topicType) {
   _putTopicType(new TopicType(topicType))
 }
@@ -197,7 +257,7 @@ function putAssocType (assocType) {
 }
 
 function putRoleType (roleType) {
-  _putRoleType(new Topic(roleType))
+  _putRoleType(new RoleType(roleType))
 }
 
 // ---
@@ -211,7 +271,7 @@ function _putAssocType (assocType) {
 }
 
 function _putRoleType (roleType) {
-  _putType(roleType, Topic, 'roleTypes')
+  _putType(roleType, RoleType, 'roleTypes')
 }
 
 function _putType (type, typeClass, prop) {
@@ -252,8 +312,9 @@ function bootstrapType () {
   })
 }
 
+// public API
+
 export default {
-  init,
   getTopicType,
   getAssocType,
   getDataType,
@@ -264,3 +325,8 @@ export default {
   getAllDataTypes,
   getAllRoleTypes
 }
+
+// module internal API
+
+export {init}
+export const storeModule = {state, actions}

package/src/utils.js

@@ -159,6 +159,37 @@ function fulltextQuery (input, allowSingleLetterSearch) {
 
 // ---
 
+/**
+ * @param   size    File size in bytes.
+ */
+function formatFileSize (size) {
+  const units = ["bytes", "KB", "MB", "GB"]
+  let i
+  for (i = 0; i <= 2; i++) {
+    if (size < 1024) {
+      return result()
+    }
+    size /= 1024
+  }
+  return result()
+
+  function result() {
+    const decimals = Math.max(i - 1, 0)
+    return round(size, decimals) + " " + units[i]
+  }
+}
+
+function round (val, decimals) {
+  const factor = Math.pow(10, decimals)
+  return Math.round(factor * val) / factor
+}
+
+function stripHtml (html) {
+  return html.replace(/<.*?>/g, '')     // *? is the reluctant version of the * quantifier (which is greedy)
+}
+
+// ---
+
 export default {
   instantiateMany,
   instantiateChildren,
@@ -173,5 +204,8 @@ export default {
   getCookie,
   setCookie,
   deleteCookie,
-  fulltextQuery
+  fulltextQuery,
+  formatFileSize,
+  round,
+  stripHtml
 }

package/src/websocket.js

@@ -0,0 +1,77 @@
+const IDLE_INTERVAL   = 60 * 1000     // 60s
+const RECONNECT_DELAY =  5 * 1000     // 5s
+
+/**
+ * A WebSocket connection to the DMX server.
+ *
+ * The URL to connect to is determined automatically, based on the server-side `dmx.websockets.url` config property.
+ * WebSocket messages are expected to be JSON. Serialization/Deserialization performs automatically.
+ *
+ * Properties:
+ *   `url` - url of the WebSocket server
+ *   `ws`  - the native WebSocket object
+ */
+export default class DMXWebSocket {
+
+  /**
+   * @param   messageHandler
+   *              the function that processes incoming messages.
+   *              One argument is passed: the message pushed by the server (a deserialzed JSON object).
+   */
+  constructor (config, messageHandler) {
+    this.messageHandler = messageHandler
+    config.then(config => {
+      this.url = config['dmx.websockets.url']
+      // DEV && console.log('[DMX] CONFIG: WebSocket server is reachable at', this.url)
+      this._connect()
+    })
+  }
+
+  /**
+   * Sends a message to the server.
+   *
+   * @param   message   the message to be sent (arbitrary type). Will be serialized as JSON.
+   */
+  send (message) {
+    this.ws.send(JSON.stringify(message))
+  }
+
+  _connect () {
+    DEV && console.log('[DMX] Opening WebSocket connection to', this.url)
+    this.ws = new WebSocket(this.url)
+    this.ws.onopen = e => {
+      this._startIdling()
+    }
+    this.ws.onmessage = e => {
+      const message = JSON.parse(e.data)
+      DEV && console.log('[DMX] Receiving message', message)
+      this.messageHandler(message)
+    }
+    this.ws.onclose = e => {
+      DEV && console.log('[DMX] Closing WebSocket connection (' + e.reason + '), try reconnect in ' +
+        RECONNECT_DELAY / 1000 + ' seconds')
+      this._stopIdling()
+      this._reconnect()
+    }
+    this.ws.onerror = e => {
+      DEV && console.warn('[DMX] WebSocket error')
+    }
+  }
+
+  _reconnect () {
+    setTimeout(this._connect.bind(this), RECONNECT_DELAY)
+  }
+
+  _startIdling () {
+    this.idleId = setInterval(this._idle.bind(this), IDLE_INTERVAL)
+  }
+
+  _stopIdling () {
+    clearInterval(this.idleId)
+  }
+
+  _idle () {
+    DEV && console.log('[DMX] WebSocket connection idle')
+    this.send({type: 'idle'})
+  }
+}