DMX User Guide¶
The DMX User Interface¶
The upper toolbar contains the crucial steering tools for DMX: The Workspace selector, the Topicmap selector and the user menu.
The Workspace Selector¶
The Workspace Selector is part of the upper toolbar and lets you select your current Workspace. Workspaces are the highest level of content organization in DMX. You can think of a Workspace as a context in which you organize your work. Items can be connected across different Workspaces.
Everything you create is automatically assigned to the Workspace selected in this menu. Every item in DMX is assigned to exactly one Workspace.
Look at how we recommend to use Workspaces on our Demo Server.
In DMX read and write permissions of users are tied to Workspace memberships: Every user can create, edit and delete their own Workspaces. If you create a new Workspace you become its owner and you can invite users as members to share the Workspace with. If a user has read or write permission for an item depends on whether the user has read or write permission for the Workspace the item is assigned to. DMX’s permissions concept is called sharing modes. You can read more about the five sharing modes in the section Introduction to Workspaces and Sharing Modes.
The DMX Standard Distribution comes with the following pre-installed Workspaces: System, Administration and DMX. Additionally, each user has a private Workspace. Content in a private Workspace cannot be read by anyone other than the Workspace owner.
Your choice in the Workspace Selector has direct influence on the available contents in the next menu, the Topicmap Selector.
The Topicmap Selector¶
The Topicmap Selector is the second drop-down menu in the upper toolbar. It lets you switch between all views in a Workspace. A Topicmap represents an individual working situation in the larger context of the selected Workspace. On a Topicmap you can visualize content that is relevant to the current context. It shows a situation-based view of selected content from the database.
Go to our Demo Server, navigate through the Workspaces and have a look at the different Topicmaps. They all show specific views on parts of the same underlying database.
For the moment, three types of Topicmaps are supported: Topicmaps, Geomaps and Tableviews. Geomaps and Tableviews both are plugins that have to be installed separately.
A new Topicmap is always empty. In the beginning, there is only one Topicmap, it’s called “untitled”. A Topicmap view is like a canvas as it allows you to freely place items. The layout of the Topicmap is persisted over working sessions. Edits to a Topicmap are instantly mirrored to other connected users. The size of a Topicmap can be well beyond the size of your screen. You can move it with your mouse.
The Topicmap Panel¶
The Topicmap Panel is the main area of the DMX user interface. It displays the currently chosen view. The Topicmap panel is as wide as your browser window unless you open the Detail Panel.
When you select an item on a Topicmap, a rectangle opens up displaying details about the selected item. This box is called the in-map details. They only show up if the Detail Panel is not visible.
The Search/Create Dialog¶
The search for existing items and the creation of new ones is done in the same dialog box. The Search/Create Dialog is opened with a right-click into the Topicmap. Advanced search options are explained below in the Navigation section. Read more on how to create content in the section about Content Authoring.
The Detail Panel¶
The Detail Panel is opened by clicking “Details”, “Edit”, or “Related” in the context menu of an item. The Detail Panel shares your screen width with the Topicmap Panel. It has four tabs, “Info”, “Related”, “Meta”, and “View” described below.
The Detail Panel allows DMX to display more information than the in-map details. It is also used for editing data.
The Detail Panel can only be opened if you have selected an item on the map. Once opened, it stays open as long as you have selected an item. When you unselect an item by clicking somewhere onto your Topicmap the Detail Panel closes.
DMX avoids to display redundant information by not opening both the Detail Panel and the in-map details at the same time unless you explicitly pin one of them: To show selected “In-map Details” while the “Detail Panel” is open you can pin the in-map details to your map. Pinning shows “In-map Details” in a Topicmap, no matter what. Vice-versa you can also pin the “Detail Panel” by clicking the little pin icon in its upper right corner. Using the same button you can un-pin and close the Detail Panel.
Note that the Detail Panel only displays details of a single selected item, not when you bulk select several items.
The “Info” tab¶
The “Info” tab is the first section of the Detail Panel. It is named after the type of your current selection, e.g. a topic of type “Person” or “Event”. You can go to the info tab directly by choosing Details from the context menu or by selecting the first tab in the Detail Panel.
In display mode it shows the direct child topics of what is currently selected as this is the most commonly wanted information. It only shows child topics with a value assigned, that is fields containing data.
You can use the display mode to reveal selected child topics in the Topicmap panel by hovering the child topics and using the little eye symbol (at the very right).
The info tab also has an edit mode. You can enter the edit mode either directly from within the Topicmap by clicking “Edit” in the context menu or by clicking the “Edit” button at the bottom of the “Info” tab. If you enter the Edit mode, you get a form with all possible input fields regarding the respective item type. The form is generated using the type definition representing the content (for more details, see our section on Modeling).
The “Meta” tab¶
The “Meta” tab in the “Detail Panel” is the third tab and displays a summary of metadata about the selected item:
- the item’s technical identifier (ID)
- the Uniform Resource Identifier (see Wikipedia: URI)
- the creation date and the author’s user name
- the date of the last modification and the respective author’s user name
- the Workspace this item resides in as well as the Workspace owner’s name
- the Type of the item (DMXType)
- all Topicmaps the item is visible (not hidden) on
Note that in contrast to the Meta tab the “Related tab” lists all related database content, e.g. Topicmaps an item is part of but currently not visible in (hidden).
The “View” tab¶
The fourth tab “View” gives you access to what is called a “View Configuration”. With view configurations you can control the visual appearance of topics and associations of a specific type. So, editing a view configuration influences how items are rendered across all Topicmaps. At the moment, DMX allows you to perform the following customizations:
- with Topic Types:
- assign an icon to be shown in all instances of the Topic Type,
- choose a font color for the display on Topicmaps,
- choose a background color for the boxes the instances are displayed in on Topicmaps
- add the Topic Type to or remove it from the Create Menu
- with Association Types:
- assign an association color used in all instances of the Association Type
- with Composition Definitions:
- add or remove a drop-down menu with the available values
- specify if users can add more values on the fly
- specify if the field can be left empty
For the moment view configurations are only available on a per-type base. This is why the “View” tab is grayed out on any item which does not represent a Type Definition. You can learn more about working with type definitions in the section about Modeling.
Note that at the moment the View tab always offers all of the above settings, even if they are not applicable for a given type. This shall be improved in a future version of DMX.
The Login Dialog¶
In a standard DMX installation, once you click “Login” in the upper toolbar you get this login dialog that prompts you for a user name and a password:
This dialog can look different if the DMX installation is run by your organization. Organizations (as opposed to individuals) are likely to use our LDAP plugin so that you can use your normal credentials you have with the organization. In that case you can select the authentication method from the drop-down menu in the login dialog. To use the user name and password from your organization select the “LDAP” method and enter your credentials.
You can learn how to install the LDAP plugin in our Admin Guide.
Organizing the working context¶
The DMX database contains your knowledge at large, your knowledge base. Everything you enter is saved in the database until you delete it. What is important: Every item is saved in the knowledge base only once, even if you re-enter it or use it in many different contexts.
To visualize your knowledge base in different situations you use Topicmaps. In each Topicmap different items from your knowledge base may be relevant and the rest stays hidden. Thus, every Topicmap represents one view, perspective, or working situation.
The following figure shows the relationship between content and its use in different working situations:
In the lower half you see a representation of a DMX database. It contains your complete knowledge graph made up of topics and associations. (Note that it also contains topic types and association types which are not visualized here for clarity.)
In the upper half there are two different working contexts respectively Topicmaps. On each of them there is a selection of topics and associations revealed depending on what the Topicmap is about. There can be much more content in the database than what you actually display but everything that is visible in Topicmaps is stored in the database.
Working with Topicmaps¶
Creating a Topicmap¶
To document a meeting, prepare for an interview or to do some research you can create a Topicmap. To create a new Topicmap got to the Workspace it shall be assigned to. Open the Search/Create Dialog (right click). Enter the name of the new Topicmap, select Topicmap from the “Create” menu and confirm with “Create”.
For Topicmaps, the creation dialog has an additional drop-down menu. If you have the Geomaps plugin installed, you can choose between a regular Topicmap and a Geomap. Without the plugin, you don’t have to choose anything.
Once created, the new Topicmap is opened. You can see its name in the Topicmap Selector and use it to switch between Topicmaps.
Renaming a Topicmap¶
You can rename a Topicmap by clicking the “i” button next to the Topicmap Selector.
The “i” button reveals the Topicmap topic itself on the Topicmap. Long-click onto it and select “Edit” from the context menu.
The Detail Panel opens and lets you change the name.
After saving the change the new name appears in the Topicmap Selector. You can hide the Topicmap topic from the map via the context menu.
Moving things around¶
Note that you can drag the whole Topicmap into any direction. Just hold the left mouse button pressed somewhere on the Topicmap and drag.
Grab individual items with your mouse and drag them where you want them to be.
There is an important difference between hiding items and deleting them. If you delete items they are immediately removed from the database. If you hide them, they are just no longer visible on the Topicmap but you can bring them back by revealing them.
You can hide items from the Topicmap by long-clicking onto them and using the “Hide” button in the context menu. If you bring them back to the map later by searching them, they will reappear in the same spot in your map. All previously revealed associations do so as well (see Automatic Revelation of Associations).
You can “open” more than one item at the same time by pinning the in-map details. This is very useful for comparisons. Select a topic or an association so that its in-map details open. Click the little pin to keep them open.
Note that the pinnings are persisted in the database along with the Topicmaps. That is why you can prepare a Topicmap with pinned in-map details, knowing that everyone who opens the Topicmap will see it in that very state.
You can bulk select several items by keeping the CTRL or SHIFT key pressed and drawing a rectangle around the items you want to select. You can also click them with the CTRL or SHIFT key pressed. The selected topics now have a blue border.
Moving topic clusters¶
Once you have bulk selected a few items, you can drag the whole selection where you want to place it.
Hiding multiple items¶
To hide several items at once select them by keeping the CTRL or SHIFT key pressed and drawing a rectangle around them or by clicking them with the CTRL or SHIFT key pressed.
Customizing the Look & Feel¶
Assigning icons and colors to topic types¶
You can assign icons from the Font Awesome collection to your topic types. Let’s say you have a topic type “Publication” and you want all publications to have a book icon.
- You are about to modify the general concept of all your publications, not an existing instance of it. Click onto the topic type “Publication”, not onto an individual publication.
- Open the Detail Panel by selecting “Details” from the context menu.
- Go to the fourth tab called “View”. Here you can view and edit the configuration of the topic type. Click “Edit”.
- Click into the white field labeled “Icon”.
- You can either select an icon directly or use the search box.
- Hit save to apply the icon to all topics that are publications.
Adding colors to different topic types can help you to keep track of your content on a populated topic map. You can customize both the icon color and the background of a topic type. The settings are in the “View” tab of a topic type as well. Each of them lets you open a color picker or enter a 6 digit color hexcode.
After saving, all instances of that topic type are recolored to match your setting.
Assigning colors to association types¶
You can assign colors to association types just as you can assign icons to topic types. Select the association type on your map, open the Detail Panel and open the fourth tab “View”. Choose a color for your association type and save it.
Collaboration and Sharing¶
Creating user accounts¶
In DMX, you create user accounts just the way you create everything else, too: Enter a user name into the search field. If the name does not exist yet you create it by selecting the topic type “User Account”. After that, a password field appears. Only privileged accounts (like admin) can create user accounts.
What is displayed after account creation is just the user name. The user account consists of the user name and the password. Investigate the newly created user name via the “Related” button. The user name is associated with some information:
- disk quota: how much space the user can use on the computer
- what type of sharing modes the account owner can select when creating new Workspaces
- if the account owner is allowed to log in at all
It is important that every user account is tied to the “System” Workspace (see below). In short, this allows others to read their user name (only the name) to share content.
Changing a password¶
Users can change their own password by searching for it and editing it. Open the Search/Create Dialog, enter your user name and click it to reveal it on the Topicmap.
Click it to open the in-map details and investigate it: The user account is a composite consisting of a user name and a password. The password is not visible in clear text but it is hashed for more security.
Use the context menu to edit the user account.
Edit the password field in the Detail Panel. Enter the clear text password - DMX will hash it for you when you press “save”.
The admin password can be changed in the same way.
Introduction to Workspaces and Sharing Modes¶
In DMX, Workspaces are the highest level content is organized in. Workspaces can be compared to folders containing everything related to a working area, a project, or an area of life. Each topic and association is tied to exactly *one* Workspace but you can display them in many Topicmaps. A Workspace can have one or many members who have access to its content. Read and write permissions are tied to Workspaces. This feature makes Workspaces the basis of collaboration and the key to the configuration of access control:
DMX has five sharing modes:
- private: In a private Workspace just the owner of the Workspace can read and write.
- confidential: In a confidential Workspace the owner can read and write. Workspace members can read, but not change anything.
- collaborative: A collaborative Workspace can be read and edited by the owner and by all Workspace members.
- public: A public Workspace is world-readable. It can be read and edited by the owner and by all Workspace members. The default “DMX” Workspace is an example of a public Workspace.
- common: For common Workspaces, you can configure the behaviour in the configuration file
config.properties. You can decide whether you want to allow reading and/or writing for non-logged in users. If configured accordingly, a common Workspace on a DMX instance connected to the internet can be readable and writable to everyone on the internet. See our Admin Guide for more details.
Every Workspace has an owner, usually the creator, and optional members. When you are logged in you can access the different Workspaces via the Workspace selector in the upper left corner. Once you log out DMX will switch back to a public (world-readable) Workspace like the default Workspace called “DMX”. All items that are publicly readable stay visible, the rest disappears from the view. In a public Workspace you are no longer able to edit but you still have a customizable view of the Topicmap, which means that you can move items and reveal other world-readable items. If you explicitly do not want or need any of the five sharing modes, you can disable them via configuration.
DMX comes with four default Workspaces with the following sharing modes:
- DMX: This Workspace is public. It is displayed publicly when people come to the site.
- Private Workspace: This is the private Workspace of the respective logged in user. Only this user can see and and edit their items as the Workspace is private.
- Administration: Only the admin or members can view and edit items in this Workspace. Unprivileged user accounts do not have this entry in the menu.
- System: The System Workspace is readable by everyone who is logged in. It contains all user names that exist in this DMX installation. The user names are readable to all users. This is needed for sharing content with others as you will see below.
Moving objects to a different Workspace¶
It is possible to assign existing objects to a different Workspace. For this, you must have write permission on both the selected object and the target Workspace.
An example use case: You have a contact, a “Person” object, in your private Workspace that you want to share with some other user.
Select the object and open the “Meta” tab in the Detail Panel. Hover over the Workspace field with your mouse pointer and click the edit button. You can now select the target Workspace from the drop-down menu and hit “Save”.
This only works for individual selected objects. Bulk operations are not yet supported.
A data model is an abstract model that defines all elements needed to represent items, their properties and their relationships. DMX enables users to create their own data models.
Introduction to Data Modeling¶
DMX is built upon the so-called Associative Model of Data. It uses a suitable database model which can be considered opposed to the widely used Relational Database Management Systems.
If you want to dive deeper into this concept, we recommend the following sources:
- Joseph V. Homan, Paul J. Kovacs: A Comparison Of The Relational Database Model And The Associative Database Model, in: Issues in Information Systems, Volume X, No. 1, 2009 (6 page article)
- Simon Williams: The Associative Model Of Data, in: Journal of Database Marketing, Volume 8, 4, 2001 (24 page article)
- Simon Williams: The Associative Model Of Data, Lazy Software, 2nd edition, 2002 (book, 284 pages)
It depends on your use case how you build your data model. In most cases, there is more than one possible way of achieving what you need. None of them is right or wrong, but one of them might be more suitable. We therefore recommend to consider the possibilities before implementing a data model. To show you what we mean by this, we will discuss different ways of modeling below.
Types versus instances¶
To understand the fundamental concepts of DMX it is very important to understand the distinction between topic types and topics, respectively between association types and associations. This distinction separates an abstract concept (types) from the particular occurences (instances) of the concept.
For example, the particular bicycle in your garage is an instance of the type of thing known as “The bicycle”. Types are the ideas or abstract descriptions of the things you want to represent. They can be sets, collections, object classes or kinds of things.
Instances of a type are the concrete items, the content (topics and associations). In DMX you can create, edit and visualize both, types and instances, even in the same Topicmap.
Topic types and topics¶
On the level of topic types you describe models of the topics you want to create. You can add your own topic types.
|Topic Type||Instances / Topics|
|Fruit||banana, apple, cherry|
|First name||Cathy, Alice, Robin|
|Color||red, yellow, blue, green|
In DMX every topic is an in instance of a specific topic type.
Association types and associations¶
Associations represent the relationships between items. They represent real-world semantics. These can be relationships between topics or between associations or between a topic and an association. The most important characteristic of associations in DMX is that you can qualify them to give them the meaning you need. You do this by creating association types.
|Association type||Related items||Instances / Associations|
|Organizational role||person and organization||founder, member, employee|
|Involvement||person and publication||author, editor, reader, subject|
|Relationship||person and person||friend, enemy, lover, mentor|
Every association is an instance of a specific association type.
Simple data types¶
Every topic or association has a data type. There are six different data types in DMX. Four of them are so-called simple types:
- text: This is the default data type and it contains a text string.
- number: An example is “1984”.
- boolean: yes/no resp. true/false
- html: HTML
Composites and composition definitions¶
The two other data types are composites. First of all, “composite” means that this data type is put together from several simple data types. The name of a person mostly consists of at least a first name and a last name. An address entry is put together from a street name, a number, a postal code, a city.
A composition definition is an association type within a composite: As you will see below you define a composite by creating associations between topic types and/or association types. By doing so you define the parent-child relations, the cardinality of properties, and the identity attributes (unique identifiers) for your data model. This kind of association type is called a composition definition.
For associations there is just one composite data type which is obviously called composite. For topic types DMX has two composite types: value and entity.
These terms exist to clarify what you are referring to when changes occur. Think of real-world contexts and how people are able to understand what changed. If a person has a new address this could mean they moved, but it could also mean the street was renamed. You can model these two different case by using the data types “entity” and “value”.
The composite type “entity”¶
In DMX, entity is used when you want to refer to the same thing as before even if something changes. If an address changes because the street is renamed you would still mean the same house at the same geolocation. If you save a bookmark to refer to an article and the URL of that article changes, the article and its description would be the same as before. If you edit a person’s details in your address book the person itself stays the same, even if their phone number changes.
The composite type “value”¶
The composite data type “value” is used whenever you want to refer to something different upon a change. While the topic type person is a composite of the data type “entity”, the topic type person name is a composite of the data type “value”:
If a person changes their name the change is done by deleting the association to the old name and by creating an association to the new name.
The background to this is the following: In DMX, every item is saved in the database only once. For example, there is one last name called “Jones” in the database. All persons who share this name are associated to it. Technically, this means that many parents share the same child. Upon a change of name, the old name stays in the database because it may be associated to other items: Many people are called Cathy or Jones so the database entries can be considered to be a dictionary of names. The persons are just associated to immutable names but the associations between them can be deleted and redone.
Here is what this change looks like: Before, the person Cathy Jones is related to the person name, a composite of first name and last name. This is shown by the red associations.
To assign a different name to the person, you just edit the person’s entry and change the name. The association between the person and the person name is deleted. A new association is created. The old person name stays in the database, disconnected from this instance of a person. If you are sure you do not need it, you can explicitly delete it.
Defining your own Type URIs¶
Upon creation every type gets an automatically generated Type URI. It looks like this:
URIs (Uniform Resource Identifiers) identify resources unambiguously. For global uniqueness they follow a specific syntax.
When you dive into modeling or development with DMX you should adapt these Type URIs to your own projects with meaningful names. Developers working with the types in a specific project can then address them easily without unintended duplicates or changes.
There is a best practice for choosing your Type URIs:
Namespaces shall follow the pattern
You can use DNS domains for the first part, or just think of an unambiguous abbreviation.
An example for the URI of a topic type “publication” on our own demo server could be
systems.dmx.demo.publication or just
You can edit the Type URIs via the edit button.
You have adapt the TypeURIs before adding any instances!
Creating a simple topic type¶
You can add a topic type via the Search & Create Dialog. Search for what you want to add. If it does not exist in the DMX database, yet, select the topic type “Topic Type” and click “Create”. By default, a new topic type has the simple data type “Text”.
Creating a composite topic type¶
To create your own composite topic type with a few properties here is how to proceed. Let’s say you want to add a topic type “publication”. Each publication shall have a title and a year.
- Open the search field. Enter “Publication”, select “Topic Type” and press “create”.
- Go into editing mode via the context menu. Change the data type from “Text” to “Entity” and hit “Save”. Click somewhere into your map to close the Detail Panel.
- Open the search field and enter “Title”. You will find that two entries already exist. They come from the default topics types “Event” and “Note” which also have titles. Create a new topic type, e.g. “Title of Publication”.
- Create an association between the title item and the publication item. DMX will display what you just created:
- You created an association of the type “Composition Definition”. Composition Definition means that you are defining a more complex context between items on your map: The relationship between a publication, a title and a year.
- “Cardinality: One” means that each publication has exactly one title, not more.
- The rest of the information refers to the role types: The publication is called the parent type, the title is the child type. These are technical terms to define that a publication has a title, but a title does not have a publication.
For a composite with the data type “entity” you should define at least one identity attribute. The identity attribute is the item’s unique identifier - the information that makes it unique. If needed, you can define more than one identity attribute. When modeling a composite it is important that you add the identity attribute as the first child to the parent. This is how you tell DMX to fill in this field with what you enter into the Search/Create Dialog.
- Add an identity attribute. In our example the title shall be the unique identifier of the publication. You thus edit the association you just created between the title and the publication. Tick the checkbox “Identity Attribute”. (In real life, you would maybe use the ISBN number as the identity attribute or as one of several identity attributes.)
- Right below that checkbox there is another one called “Include in Label”. Tick it for the information that should be used in the item’s name. It determines which attribute is shown on the Topicmap and on top in the Detail Panel. In this example we want the book title to appear there.
- Again, click somewhere onto the map and reopen the search field. Search for the year and open the existing topic type “Year”. Pull it onto the publication.
You are now ready to use this data model you just built to add content.
- Open the search field and enter the title of a publication. From the Topic Type menu you can now select “Publication”.
- The title is automatically filled in from the search field.
- Edit your new publication and add a year.
Creating association types¶
One of the strengths of DMX is that you can build your own association types in the same user interface. Association types represent different relationships between items. In their simplest form, associations are “lines” between things without any deeper meaning embedded in the line. Their association type is called “Association”. For semantic authoring more complex associations are needed to qualify relationships.
Please keep in mind that the different ways of modeling associations shown below are options. Often, there is more than one way to do it. None of the different ways is right or wrong but one might suit your use case better than the others. You can achieve the same meaning via different data models, but they differ in the following respects:
- how you enter data on the level of instances and
- how search results are presented.
Creating a simple association type¶
To create a simple association type open the Search/Create Dialog and enter the name of the association. Select “Association Type” from the Topic Type menu and click “Create”.
The data type of a simple association type is “Text”. To use the Association Type in your instances create an association between two topics and edit it:
The direct search for associations is still a planned feature. When you search for one of two connected players, and you sort the results by association type, you get a list of all instances this player is connected to via that association type.
Creating a composite association type¶
Just like Topic Types, Association Types can be composites. You can make them as complex as you need. The Association Type “Organization Involvement” that comes with the DMX standard distribution is an example for a composite association type.
Have a look at the details: The association type includes a composition definition to model the different roles a person can have in an organization.
“Organizational Role” is a simple topic type (data type: text). The actual roles (like “member” or “founder”) are instances of the topic type “Organizational Role”. They are not part of the data model.
For modeling, the composition definition between “Organization Involvement” and “Organizational Role” is important. It has a special view configuration that you can investigate on the view tab of the Detail Panel:
- The “Widget” setting is set to “Select”. This allows you to select roles from a predefined list of instances when adding content (“member”, “founder”).
- The two other checkboxes called “clearable” and “customizable” are ticked. It only makes sense to use them in connection with “Widget: Select”. “Clearable” decides whether you allow instances of this association type to only have the values you explicitly defined or whether it shall be possible to clear the field to leave it empty. In this case, there will be a little cross icon for clearing it. “Customizable” decides whether you allow to enter values on the fly by just typing in something different that was not predefined by you. If both checkboxes are left empty, one of your predefined values has to be selected. The value cannot be empty and there will be no possibility of typing into the field.
On the left side of this screenshot you can see the essentials of this data model. On the right side there are instances of “Organization”, “Person”, “Organization Involvement” and “Organizational Role”.
Search results are presented differently according to your sort mode: When you search for an organization and you open the “Related” tab in the Detail Panel you can either sort by Topic Type and get a list of all related persons. Their roles are then displayed as well.
Sort the same list by association type. As the association is “Organization Involvement” you get the list of persons, too, but their roles are omitted here.
Custom Association Types¶
Custom Association Types are a different way of modeling associations. They are a powerful, semantic authoring tool that is unique to DMX.
In short, they work like this:
- You create an association type.
- You create a composite topic type.
- At least one child topic type in the composition definition is linked to the parent type through your newly created association type.
- When you create instances of the parent type, the according child instances are created and connected with your Custom Association Type automatically.
To grasp the power of Custom Association Types, it is important to consider the consequences of such a model:
- Custom Association Types are used in composition definitions.
- You can benefit from DMX’s model-driven form generator: When you create instances of the composite you defined, the editing form contains fields for all identity attributes of child instances. You thus get a form with all properties you want to add. The child instances linked to the parent by a Custom Association Type are also part of the form. When you fill in those fields, the semantics of the Custom Association type are carried over to the instance. You do not have to drag associations but they are added for you through the form resp. your data model.
Here is an example:
- Create the topic types “Publication” (data type “entity”) and “Publication Title” (text).
- Reveal the built-in topic type “Person”.
- Create an association type called “Author”.
- Create an association between the topic type Person and the topic type Publication. Edit it and open the drop-down menu “Custom Association Type”. Select “Author” and click save.
Your Composition Definition looks like this:
This is your data model:
Use this model to create an instance and see how the semantics of the Custom Association Type are carried over to the instances:
- Create a new publication by entering a title into the Search/Create Dialog and selecting the topic type publication.
- Edit the publication.
- In the autogenerated editing form you now have fields for the author (first name, last name).
- When typing in a name, DMX’s autocompletion offers you existing person names that you can select.
- If the author you enter does not yet exist in the database, DMX creates a new person and directly adds the custom association “Author” between this person and the publication.
When you now search for a publication, the person (the author) cannot be found in the “Related” tab, but in the “Info” tab as it is a direct child topic of the publication.
When to use Custom Association Types?
- If your data model contains a clear parent-child relationship Custom Association Types are the recommended way of modeling these relationships. This is the case when you need a child type to describe the whole entity. (For example you want publications to have authors, and authors are persons.) Create a Composition Definition between parent type and child type and add a Custom Association Type to it as described below.
- If your data model does not have a such clear parent-child relationship we recommend to create associations manually.
Creating a role type¶
You can investigate this example on our Demo Server, in the Workspace “DMX User Guide Data Model”, Topicmap “1 Persons and Organizations”.
Role types refer to the players connected by associations. They are important when creating associations but they are used at the end points of associations.
Oftentimes when you create associations it is clear which of the two connected players is in which role: In the example above, the publication is the parent type and the title is the child type. There are cases though where you want to define your own role types because without them the relationship (or its “direction”) is not clear: This is likely needed when two players of the same type are associated. An example could be a hierarchical relationship between two persons like an employment relation. You would model the employment relation as an association type. But when you create instances of this association you would not see which player is in which role: Which person is the manager and which person is the employee? Here is how to deal with this use case:
- Create the association type “Employment relation”.
- Create two new role types called “Manager” and “Employee”.
Create your content, the instances:
- Create two persons.
- Create an assocation between them, edit it and select the association type “Employment relation”. Look at the in-map details: Both persons have the default role type. You cannot tell who is in which role.
- Edit the association again and edit the roles of both players. The role types you created are selectable from the drop-down menu.
This is what your result looks like:
Exploring the data model¶
You can explore the data model by revealing its parts in Topicmaps. The topic types with all their properties (that is associations to other topic types) are saved in the database just like all your content. To understand how topic types and association types are built you can thus just navigate them.
To explore an example, we can once more refer to the built-in topic type “Person”. To look at the data model of a person, click onto an instance, e.g. a person you created and select “Related”.
- the organization you linked the person to
- the name of the person (because so far this is the only information you added to the person)
- the topic type “person”. Your concrete person is an instance of the general idea of persons, so it is linked to this general idea, the topic type.
- the Topicmap this topic is associated with
- the Workspace the topic is in
You can now click on each of the list items and they will appear on the Topicmap. Click onto the topic type “person”. The topic type “person” is displayed with an association to the instance “Cathy Jones”. The link between both has a different color. You can click onto the link again, show what is related and you can see that this association is an “instantiation”: The topic is an instance of the topic type. To see if there are more instances (more persons), show the “Related” tab of the topic type “person”. Among other information about how the topic type is integrated into the rest of the context you can see all existing persons entered so far. (Or more precisely: All existing instances you have read access to.)
Here you are looking at your data and at a part of the data model it is based upon. Again, you can hide what you do not want to see in your map when you are done exploring.
Visualizing edge connections¶
In the examples above you have seen nodes that are connected by edges, e.g. two topics (or topic types) that are connected by associations. This is not sufficient in a data model that is supposed to show real-world relationships. The associations themselves can be very complex and can have many properties.
With DMX’s associative data model, these complex associations can be modeled and they can even be visualized on Topicmaps: They show as associations connected to other associations.
Let’s return to the example of a publication and its author: The authorship is a qualified description of the association between a person and a publication. If you look at the “Related” tab of such a qualified association you can see the connection between the association and and the association type:
Modeling patterns and pitfalls¶
How to model topic types with dates or time spans?¶
Let’s say you want to model plants. Among other properties, they shall have a blooming period. Here is how to proceed:
Create a topic type “Tree”. Edit it and change its data type to “entity”.
The data type “entity”
- Your tree is more complex than just a text field or a number: You want to add properties to it. You thus do not need a simple but a composite data type.
- You choose “entity” (not “value”) because upon a change of properties you still mean the same type of tree. You want to add, remove, or change properties, the number of properties might grow over time. By choosing the data type “entity” you tell DMX that regardless of those changes you will mean the same thing.
Create a topic type “Tree name”. It can keep the default data type “text”. Create an association between the “Tree name” and the “Tree”. By dragging from the child type (“Tree name”) to the parent type (“Tree”) you assign the right order on the fly.
Create a topic type “Blooming period”. Edit it and change its data type to “value”. Create an association between the topic type “Blooming period” and the topic type “Tree”.
The data type “value”
- Your blooming period is also more complex than a number. Even a single date (instead of a period with a beginning and an end) consists of more than a number, e.g. a day, a month, and a year. So you need a composite data type here, too.
- You choose “value” (not “entity”) because your data will not stay identical when you change it. The blooming periods “April to June” and “June to July” are different blooming periods (even if they change for the same type of plant).
To add dates to your topic type “Blooming period”, use the predefined date topic type: Search for it and reveal it on the Topicmap.
Investigate it by looking at the in-map details.
In the next step you assign two dates to the topic type “Blooming period”: The start date and the end date.
Custom Association Types
You cannot create two or more associations of the same association type between two items. Use Custom Association Types to avoid errors.
Create the first association between the topic type “Date” and the topic type “Blooming period”. Edit the association and open the drop-down menu called “Custom Association Type”. Select “From”. This is a predefined Custom Association Type.
For the end date create another association between the topic type “Date” and the topic type “Blooming period”. Edit it, too, and select the Custom Association Type “To” this time.
Your data model now looks like this:
To check, create an instance, a tree, click edit, you now have a form for dates.
How to change the order of fields in a form?¶
You modeled a composite and when you created your first instance you saw that the fields are in the wrong order? You can fix it. DMX creates the form in the order you created the associations in when modeling. In this example we will change the order of the “To” and “From” fields:
Both fields are associated to a composite “Blooming period”. Edit that composite.
In the Detail Panel you can now drag the child types into the right order with your mouse.
How to unclutter the choice of topic types¶
When you have created many topic types for building composites you will notice that the drop-down menu for topic type creation fills up with topic types you might not need there.
To clean up, reveal a topic type you want to hide from the create menu on your Topicmap. Open the Detail Panel by selecting “Details” from the context menu. In the Detail Panel switch to the fourth tab, the “View” tab and edit the View Configuration. Untick the “Add to Create Menu” checkbox and save the change.