DMX User Guide

The DMX User Interface

The Toolbar

The upper toolbar contains some of the crucial steering tools for DMX.

Tool bar with workspace and topicmap selector

The Workspace Selector

In the upper left corner there is a drop-down menu called “Workspace”. This is the workspace selector. Workspaces are the highest level of content organization in DMX. You can think of workspaces as the folders you put your different projects into. When you start to work on a blank DMX installation and you are not logged in, the only visible workspace is called “DMX”. Read more about workspaces in the section Introduction to workspaces and sharing modes.

_images/workspace-selector.png

The Topicmap Selector

Next to the workspace selector there is another drop-down menu called “Topicmap”. This is the topicmap selector. A topicmap represents an individual working situation. The user chooses what is relevant to the current context and visualizes it by revealing the relevant topics and associations from the database in a topicmap. Thus it shows a situation-based selection of the whole database content. In the beginning, there is only one topicmap, it’s called “untitled”. Find out how to add topicmaps in the section Organizing the working context.

_images/topic-map-selector.png

The Fit Button

Next to Topicmap Selector you can find the fit button. It has for arrows pointing from the center to the corners of a square. This button adjusts the zoom level of a topicmap to make it fit into the browser window.

Tool bar with highlighted fit button

The Reset Zoom Button

Next, there is the reset zoom button. It has two arrows pointing from the corners to the center of a square. It resets the zoom level to “1” and centers the topicmap in its original position.

Tool bar with highlighted reset zoom button

The Login Button

The “Login” button is located in the upper right corner of the toolbar.

The Help Button

In the very corner there is the Help button. The menu that you can open here contains links to this documentation and to the DMX Forum. “About DMX” displays information about the software version you are currently running.

Tool bar with highlighted help button

The Topicmap Panel

The topicmap panel is the main area of the DMX user interface. It displays the currently chosen topicmap. The topicmap panel is as big as your browser window unless you open the detail panel.

_images/topic-map-panel.png

The Context Menu

The context menu is opened with a right-click on items. It has four buttons to interact with the item:

  • You can display its details.
  • You can edit it.
  • You can hide it from the current topicmap
  • You can show what is related to this item.

To close the context menu without any action, click into its middle.

_images/context-menu.png

Note that the context menu shows whether you have write permission to an item or not. If the terms “edit” or “delete” are grayed out, you cannot edit the content.

_images/context-menu-no-permission.png

In-map Details

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

_images/in-map-details.jpg

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.

_images/search-create.png

The Detail Panel

The detail panel is located at the right side of the screen when it is open. You open it by clicking “Details”, “Edit”, or “Related” in the context menu.

_images/detail-panel.png

The detail panel offers much more features to explore and edit your data than the in-map details shown above. Depending on what you want to do you can choose where you want to display details - in-map or in the detail panel. DMX avoids to display redundant information by not opening both at the same time (unless you explicitly pin the in-map details to your map to leave them open).

The detail panel can only be opened if you have selected an item on the map. The default behavior is that it stays open as long as you have selected an item. Once you unselect an item by clicking somewhere onto your topicmap the detail panel closes. You can control whether the detail panel shall stay opened by pinning it with the little pin icon in its upper right corner. You close the detail panel by unpinning it with the same button.

_images/pin-detail-panel.png

Note that the detail panel can only display details of a single selected item, not when you bulk select several items.

The “Info” tab

The first tab is a general info tab. You get there by selecting “Details” from the context menu. The “Info” tab is always labelled with the type of the selected item, e.g. “Person” or “Event”. It shows the direct child topics of what is currently selected as this is the most commonly wanted information. In its display mode it shows only those fields containing data. You can reveal the listed child topics on the current topicmap by clicking the little eye symbol.

_images/detail-panel-reveal-button.png

The first tab also has an edit button at the bottom. From a topicmap you can enter the editing mode directly by clicking “Edit” in the context menu. If you enter the editing mode, you get all fields that you can fill in for the respective topic type or association type. These fields come from the type definitions. (Please see the section about Modeling.)

_images/detail-panel-editing-mode.jpg

The “Meta” tab

The third tab “Meta” displays a summary of metadata about the selected item:

  • the item’s unique identifier (ID)
  • the 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 is in as well as the workspace owner’s name
  • the topic type
  • all topicmaps the item is currently revealed on

Note that in contrast to the Meta tab the “Related tab” lists all related database content, e.g. also topicmaps the item was revealed on at some point in time.

_images/detail-panel-meta-tab.png

The “View” tab

The fourth tab “View” allows you to view and edit the configuration of types. Thus, the tab is grayed out if the selected item is not a topic type or an association type but an individual topic or an association. (Read more about the background of the data model in the section about Modeling.) What you can configure in this “View config” has nothing to do with editing the actual data model. These changes just have an impact on how items are rendered on your topicmap: You can assign custom icons to topic types, or colors to association types. (This is covered below in the sections about Assigning icons to topic types and Assigning colors to association types.)

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:

_images/simple-login-dialog.png

In some cases this dialog looks different. This can be the case when the DMX installation you are working with is run by your organization and you were told to 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.

_images/basic-login.png _images/ldap-login.png

Note

Learn how to install plugins in our Admin Documentation.

Content Authoring

Creating a topic

Right-click onto the topicmap. The search/create dialog appears.

_images/search-create.png

DMX wants to make sure that you do not create something that already exists. That’s why you enter whatever you want to create into the search field. Enter a term, e.g. a person’s given name.. DMX will answer “No match”. Select “Person” from the predefined topic types and click “Create”.

_images/create-person.png

You will see a rectangle on your topicmap. It contains the name you entered and it states that this is the person’s first name.

_images/person-created.png

Whenever you create a new topic the dialog proposes you to create something of the same topic type as last time. You can change this by seleting a different topic type from the drop-down menu.

DMX’s default topic types

DMX comes with a few predefined topic types that you can select from:

  • person,
  • organization,
  • note,
  • event,
  • bookmark.

Each topic type brings certain fields you can fill in: While events have dates and locations, persons can have telephone numbers and web resources have a URL.

These topic types all come from classical PIM applications (Personal Information Management). The special feature here is that you have different types of information in one interface and not spread out in address books, calendars, browsers and files. Using DMX for PIM is just one proposal for a use case.

Creating an association

To create an association between two topics you grab the little gray dot at the upper border of one of the topics.

_images/create-association-1.png

Drag it onto the other topic until that topic is highlighted by a blue border.

_images/create-association-2.png

Then let go and a rectangle will open that shows you the in-map details of the newly created association. Click somewhere into the map to hide the in-map details.

Note that an association does not necessarily connect two topics: You can also create associations between a topic and an association or between two associations. To do so, attach an association to the little dot in the middle of the assocation.

_images/create-assoc-with-assoc.png

Now what is important is that there are different association types. If you just draw a line between two things to create an association you will see a gray line. Its association type is just “association”. You can use these associations to visualize that two items are somehow related to each other without being specific about the meaning of the association.

_images/generic-association.png

If you need qualified associations you have to give your associations a meaning. This is explained step-by-step in the section about Modeling.

Thinking of real-world examples, you will find that there is often more than one association between two things. DMX can represent this: You can simply create another association between them.

_images/multiple-assocs.jpg

Editing content

Editing in the detail panel

To add more details to a topic you use the detail panel on the right side. Use the edit button from the context menu to open it (see above).

The detail panel opens so that you have the topicmap on the left side of your screen and the detail panel on the right side. There is an in-depth explanation of the detail panel’s features further up. Here is what is looks like. There is a “Save” button at the very bottom of the form.

_images/detail-panel-edit-intro.png

Inline editing

For quick changes of fields you already filled in you can use the inline editing mode. Click to select the topic and move your mouse to the upper right corner of the displayed square. A little closed lock appears. Click to unlock it.

_images/inline-editing-unlock.jpg

Double-click onto the content you want to change, do your edit and save the change.

_images/inline-editing.jpg

Uploading or embedding images

To upload or embed an image, you have to go via the richtext editor right now. The richtext editor is accessible in all HTML fields, e.g. in a Note. Write text into the HTML field and select some of it. The richtext editor opens.

_images/richtext-editor-upload-embed.png

The image icon lets you upload an image from your computer into the DMX database. The film icon lets you embed an image from a website. (For the detailed use, please see the respective modeling example below.)

Deleting things

Warning

There is an important difference between hiding items and deleting them. If you delete items they are removed from the database forever. If you hide them, they are just no longer visible on the topicmap but you can bring them back by revealing them.

You delete things via the context menu on the topicmap. Keep the “Alt” key pressed and left-click onto the item you want to delete. To delete drag your mouse anywhere into the red area. To abort let go of both the “Alt” key and the mouse button while the cursor is in the middle of the circle.

_images/delete-item.png

When you select “Delete” a dialog window opens. It informs you about the number of items you are about to delete. You can confirm or cancel the deletion.

_images/confirmation-dialog-delete.png

Bulk deletion

To delete several items in one go select all of them by clicking them with the CTRL key pressed.

_images/bulk-delete-1.png

Then proceed as above: Left-click onto the item and drag your mouse onto the delete button.

_images/bulk-delete-2.png

When you select “Delete” the same confirmation dialog window opens: It informs you about the number of items you are about to delete. You can confirm or cancel the deletion.

Organizing the working context

The DMX database contains your knowledge at large. Everything you enter is saved in the database until you delete it. What is important: Every item is saved in the database once only, even if you use it in many different contexts.

To make use of your knowledge base in different working situations you use topicmaps. On each topicmap you can reveal what is relevant from the same underlying database. 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 lots 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.

Illustration of DMX topicmaps each with a set of data revealed from the same underlying database.

Creating a topicmap

To start working in a new context or on a different part of your larger project you can create a new topicmap. This is done just like always: Open the search/create dialog. Choose a name for the topicmap, search if it already exists, and create it by selecting the topic type “Topicmap”.

_images/create-topic-map.png

For topicmaps, the creation dialog has an additional choice between (usual) topicmaps and geo maps (see below). Once created, the new empty topicmap is opened. You can see its name in the Topicmap Selector and use it to switch between topicmaps.

Displaying Geodata

DMX comes with built-in support for geodata. Every topic with an address can be shown on a geographical map. The so-called geomaps are a special type of topicmap in DMX. Geomaps are based on openstreetmap.org. Here is an example of how to create and populate them: Edit a person or an organization and add an address.

_images/add-address.png

Open the search and create dialog. Enter a name for the new topicmap, e.g. “Our Geomap”. In the topic type selector choose “Topicmap”. Underneath it you can now choose the type of topicmap you want to add. Select “Geomap” and press “Create”.

_images/add-geomap.jpg

Open the topicmap selector in the upper toolbar and select your newly created geomap. The map is displayed with all items you assigned an address to.

_images/topic-map-selection.jpg

If you click onto an item the in-map details show you what is there.

_images/display-map-item.jpg

Again, you return to the other topicmaps via the Topicmap Selector.

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.

Moving topics

Grab individual items with your mouse and drag them where you want them to be.

Panning/zooming the topicmap

Zooming in or out is done by scrolling up or down. Your cursor is the focus for panning. The fit and reset zoom buttons in the upper toolbar help you to readjust a topicmap to your screen respectively to its original position.

Hiding things

Note

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

Pinning things

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.

_images/in-map-details-pinning.png

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.

Bulk operations

Bulk selection

You can bulk select several items by keeping the CTRL key pressed and drawing a rectangle around the items you want to select. You can also click them with the CTRL 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.

_images/bulk-select.jpg _images/bulk-move.jpg

Hiding multiple items

To hide several items at once select them by keeping the CTRL key pressed and drawing a rectangle around them or by clicking them with the CTRL key pressed.

_images/bulk-hide.png

Customizing the Look & Feel

Assigning icons and colors to topic types

You can assign icons from the Font Awesome collection to your topic types. Editing the view configuration is explained with the topic type “Publication”. In the section about Modeling you will learn how to create such a topic type. Let’s say you have a topic type “Publication” and you want all publications in your map to have a book icon.

  • Click onto the topic type “Publication”, not onto an individual publication you already added. You are about to modify the general concept of all your publications, not an existing instance of it.
  • 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”.
_images/open-icon-selection.png
  • You can either select an icon directly or use the search box.
_images/icon-picker.png
  • Hit save to apply the icon to all topics that are publications.
_images/new-icon.jpg

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.

_images/color-picker.png

After saving, all instances of that topic type are recolored to match your setting.

_images/topic-type-icon-bg-color.png

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 details panel and open the fourth tab “View”. Choose a color for your association type and save it.

_images/new-assoc-color.png

Collaboration and Sharing

Creating user accounts

Note

If you have existing users in an LDAP directory we recommend you to use our LDAP plugin. Learn how to install it in our Admin Documentation.

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.

_images/user-account-creation.png _images/user-account-password.png

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.

_images/user-name-related.jpg

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

_images/workspace-selector.png

DMX comes with four default workspaces with the following sharing modes:

  • DMX: This workspace a public, it is the one that 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.
_images/system-workspace.png

Sharing a workspace

Here is how creating a shared workspace works:

  • Log in as an unprivileged user and go to your private workspace where you can edit.
  • Open the search field and create a workspace. Make it a collaborative workspace to give others write permission.
_images/workspace-creation.png
  • The new workspace automatically opens. Click onto the blue information icon next to the workspace selector to reveal the workspace topic itself on the topicmap.
  • To add members to the workspace you can just search for their user names and click them to reveal them on the map. As mentioned above, all user names are visible to all other logged in users. In DMX, membership is tied to user names.
  • If you don’t know their user names you search for the topic type “Username” and navigate its “Related” tab to see the existing user names in the detail panel. Reveal those you want to give access.
  • Now that you have the workspace itself and a user name on your topicmap you can just create an association between the user name and the workspace.
  • Next you have to qualify this association as a membership: Edit the association.
_images/edit-ws-assoc.png
  • In the detail panel you can now select the association type “Membership”. You are done!
_images/edit-ws-assoc2.png
  • Here are the details of the workspace membership association.
_images/view-ws-assoc.png
  • The user you shared your workspace with can now log in, select your collaborative workspace and add something, e.g. a note. This note is now accessible to all members of the workspace. It will appear on the selected topicmap, visible to all workspace members looking at the same topicmap.

Note

You can create membership associations to every workspace that you have write permission in.

Modeling

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:

Types versus instances

To understand the fundamental concepts of DMX it is very important to understand the distinction between topics and topic types, respectively between associations and association types. 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 visualize both, types and instances, even in the same topicmap.

Topics and topic types

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

Note

In DMX every topic is an in instance of a specific topic type.

Associations and association types

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

Note

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 “year”.
  • 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 both composite types: value and identity.

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 “identity” and “value”.

The composite type “identity”

In DMX, identity 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.

_images/composite-identity.png

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 “identity”, topic type person name is a composite of the data type “value”:

_images/composite-value.png

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.

_images/changing-a-persons-name1.png

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.

_images/changing-a-persons-name2.png

Defining your own Type URIs

Upon creation every type gets an automatically generated Type URI. It looks like this:

_images/generated-type-uri.png

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 domain.project.typename. 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 dmx.demo.publication.

You can edit the Type URIs via the edit button.

Note

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 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 “Identity” 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 “Title”.
  • 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.
_images/composition-definition.png

Note

Identity Attributes

For a composite with the data type “identity” 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.)
_images/select-identity-attribute.png
  • 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.
_images/include-in-label.png
  • 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 an association type

One of the strengths of DMX is that you can build your own association types in the same user interface. Let’s say you want to express the relationship between persons and publications. A person can be the author, the publisher, the reader, or even the subject of a publication.

  • Create a topic type “Publication”.
  • Create an association type and give it a name, e.g. “Relationship publication - person”.
  • Select “Composite” as a data type.
_images/create-machine-readable-association.jpg
  • Create a topic type, name it “Role referring to publication” or anything that suits you. Its data type is “Text”.
  • Create an association between the topic type and the association type and edit the newly created association between them. Click onto the “View” tab and then “Edit” to edit its configuration.
  • Open the “Widget” setting and select “Select”. This will allow you to select roles from a predefined list when adding content later.
  • There are two more checkboxes called “clearable” and “customizable”. It only makes sense to use them in connection with “Widget: Select”. Both have an effect on editing association types later on. Here is what they do: “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.
_images/selectable-role.jpg
  • Create a topic “Author” that has the topic type “Role referring to publication” which is selectable from the create menu. If you want to have more roles, add them likewise.
  • Create a person.
  • Create a publication.
  • Create an association between the person and the publication and edit the association. Open the drop-down menu under “Association Type” and select “Relationship publication - person”. Hit the save button and the edit button again. There is a new drop-down menu that lets you select the role the person shall have related to the publication.
_images/select-role.jpg

You now have a map like this. On the left side you see the data model. There is your topic type “Publication” with a title and a year. And there is the association type you built with a few selectable roles.

On the right side you see the actual content, the instances. To continue working with a less crowded map, you might want to bulk select and hide the data model.

_images/topic-map-with-own-assoc-and-instances.jpg

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. Custom Association Types are used to represent parent-child relationships when you create instances. Their semantics are carried over to all instances without you creating associations manually in each instance. At the same time you benefit from DMX’s model-driven form generator: The form you edit parent instances with will contain fields for all identity attributes of child instances. You thus get a form with all properties you want to add.

Note

When to use Custom Association Types?

  1. 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.
  2. If your data model does not have a such clear parent-child relationship we recommend to create associations manually.

The same context as shown above can be modeled using a Custom Association Type.

  • Create the topic types “Publication” (data type “identity”) and “Publication Title” (text).
  • Reveal the built-in topic type “Year”.
  • 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.
_images/create-custom-association.png

Your Composition Definition looks like this:

_images/comp-def-with-custom-assoc-type.png

This is your data model:

_images/data-model-with-custom-assoc-type.png

Use this model to create an instance:

  • Create a person or reveal an existing one.
  • Create a new publication by entering a title into the search/create dialog and selecting the topic type publication.
  • Edit the publication.
  • In the form you now have fields for the year and 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.
_images/custom-association-instance.png

Creating a role type

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”.
_images/create-role-type.png

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.
_images/without-custom-role-type.png
  • Edit the association again and edit the roles of both players. The role types you created are selectable from the drop-down menu.
_images/with-custom-role-type.png

This is what your result looks like:

_images/custom-role-type.png

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

_images/person-related.png

The detail panel on the right side will open. You are now looking at the Related tab. It displays a list of all items that are logically related to this concrete person:

  • 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 and you can again click onto the link, show what is related and you can see that this association is an “instantiation”: The topic is one 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 you entered so far.

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.

_images/intro-data-model.png

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:

_images/edge-connection.jpg

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 “identity”.

Note

The data type “identity”

  1. 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.
  2. You choose “identity” (not “value”) because upon a change of properties you still mean the same tree. You want to add, remove, or change properties, the number of properties might grow over time. By choosing the data type “identity” 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”.

Note

The data type “value”

  1. 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.
  2. You choose “value” (not “identity”) because your data will just 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 plant).

To add dates to your topic type “Blooming period”, just use the predefined date topic type: Search for it and reveal it on the topicmap.

_images/search-results-date.png

Investigate it by looking at the in-map details.

_images/details-date.png

In the next step you assign two dates to the topic type “Blooming period”: The start date and the end date.

Note

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

_images/custom-association-type-from.png

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:

_images/modeling-time-span.png

To check, create an instance, a tree, click edit, you now have a form for dates.

_images/time-span-form.png

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:

_images/change-field-order1.jpg

Both fields are associated to a composite “Blooming period”. Edit that composite.

_images/change-field-order2.png

In the detail panel you can now drag the child types into the right order with your mouse.

_images/change-field-order3.png

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.

_images/cluttered-create-menu.png

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.

_images/remove-from-create-menu.png