DMX User Guide¶
The DMX User Interface¶
The upper toolbar contains some of the crucial steering tools for DMX.
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.
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.
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.
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.
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. Read more on how to create content in the section about Content Authoring.
The search in DMX is run by the powerful Lucene search engine. You can run simple queries by just entering a search term. If this brings up too many results from your database, you can narrow down your search with more complex queries. DMX supports the Lucene Query Parser Syntax. Let’s look at a few examples:
Enter more than one character to start searching.
When your search term consists of letters, you will only get results starting with this string. You won’t see results containing the search term in the middle of a word. In the following example with the search term “cd” you see that “cde” is displayed in the results, while “bcd” or “abcdef” are not.
If you add a wildcard symbol in the beginning you ask for items beginning with one or multiple other characters and ending with the search term. Add another wildcard at the end of the search term to query for items containing it somewhere in the middle. There are two wildcard symbols:
?The question mark represents one character.
*The asterisk represents zero, one or multiple characters.
If you enter more than one search term into the Search/Create Dialog the search engine interprets a logical AND connection between them. In this example we search for everything containing “abc” AND “def” but not the standalone “abc”.
If you want to find all items that contain either “abc” OR “def” OR even both you replace the logical AND with a logical OR like so:
To get the exact search phrase consisting of multiple words enter it surrounded by double quotes.
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.
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.
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.
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.)
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.
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:
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.
Learn how to install plugins in our Admin Documentation.
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.
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”.
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.
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.
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”.
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.
If you click onto an item the in-map details show you what is there.
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.
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 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.
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.
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”.
- 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 details 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.
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.
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.
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)
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|
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|
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.
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”:
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 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.
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.)
- 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 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.
- 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.
- 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.
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.
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.
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.
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.
Your Composition Definition looks like this:
This is your data model:
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.
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”.
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 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.
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 “identity”.
The data type “identity”
- 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 “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”.
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 “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.
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”.
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.