Topincs

This document is an introduction into modeling with Topincs. It requires the reader to be familiar with the semantic technology Topic Maps.

Topincs uses Topic Maps as the core technology for web databases. A Topincs installation can host any number of web databases which are located under an URL prefix, e.g. /products/. At this startpage you find an index of all topics in the topic map and can navigate to their pages. The URL of the topic page functions as a subject identifier. On creation every topic receives a numeric id, the last segment of the URL. You can also assign a synonym to make the subject identifier meaningful to you and your users.

On the start page of a Topincs store you find to the lower right a link to the admin page which links to the schema page. The schema page is the center for modeling your Topincs store. On the top there are types listed, followed by the most important constraints, and everything else below. You can start all your modeling tasks here. If you want to model a new type, use the + in the bar of Topic type. After every schema change you need to empty the Topincs server cache to make the changes effective.

Modeling topic types initially only requires you to name them. Same goes for name types and occurrence types. For association types it is recommended to provide names for all perspectives, e.g. on the page of a person it should say Author of while on the page of the work the same association is titled Written by. It needs some practice to get that right.

Topincs processes constraints in order to generate a form for instances of a topic type. The upcoming Topic Maps Constraints Language defines a set of constraint types and their meaning.

Constraints for topic types are needed to specify which statements are possible or required for instances of a topic type. You can create constraints in the field Constraints when editing the topic type or directly from the schema page. The user interface guides you through the constraint creation.

Topic occurrence constraint

Enables instances of the topic type to have an occurrence of a certain type, e.g. a person has a date of birth.

Topic name constraint

Enables instances of the topic type to have a name of a certain type, e.g. a person has a first name.

Topic role constraint

Enables instances of the topic type to play a role of a certain type in associations of a certain type, e.g. a person may be an author in an authorship relation.

In order for everything to work out we need constraints for statement types as well.

Occurrence datatype constraint

Specifies the datatype of an occurrence type. Special value editors exist for the standard datatypes date, time, dateTime, duration, boolean, anyURI, integer, positiveInteger, nonPositiveInteger, negativeInteger, nonNegativeInteger, and decimal.

Role constraint

One or more such constraints specifies the form of an association, e.g. you need two role constraints to model the authorship relationship. The minimum and maximum cardinality of a role constraint is usually 1. In a symmetric relationship you will need one constraint for one role type with minimum and maximum cardinality of 2.

Role combination constraint

Specifies which topic types go together in an association type, e.g. books contain chapters and chapters contain sections.

Scope constraint

Specifies which topic types can be scoping topics for statements of a certain type.

There are several custom constraint types to achieve certain tasks which are not covered by the TMCL standard.

Filing constraint

When a filing constraint is present at a topic type, the form editing an instance of that type will allow to upload a file to the server where it will be stored and published at a URL. This URL will be the subject locator of the instance edited. It is required to make this topic type a subtype of Topincs file. The file upload field only appears when creating new instances since the connection between the topic and the file cannot be changed. A different file is a different topic.

Value space constraint

A value space constraint can be used to restrict the value space of an occurrence type. The supported data types will appear formatted in the select box.

List type constraint

A list type constraint can be used in conjuction with the custom datatype topic-reference-list to create a list of topics of a certain type in an occurrence.

An association is like a hyperlink between two topics. But it has a type and is named differently depending on the perspective. In order to get an association type working, you need to do the following:

• create an association type, e.g. motherhood
• create two role types, e.g parent and child
• create two role constraints that state which role types an association type uses, e.g. motherhood needs exactly one parent and exactly one child.
• create at least two topic role constraints: one stating that a woman (a subtype of person) can be parent in motherhood 0 to n times, and another stating that a person can play the role child in motherhood exactly once (minimum and maximum cardinality is 1).
• edit the association type and add two perspective names, e.g. 'Mother of' from the role type mother and 'Mother' from the role type child.

There is service which displays one form to create all necessary types and constraints. You can access it from the schema page.

The order in which statements are presented in a subject or form page can be influenced by an occurrence of type Field order on the topic type. This occurrence is of a custom datatype for listing subjects. The field order can be edited on the page of the topic type. You need to take care to only add constraints that belong to the topic type or a super type thereof. To make a field order change effective you will have to empty the store cache.

The label of a topic can be a computed value. Label rules are created on the schema page and take a topic type and a tiny piece of PHP code to specify the computation of such labels. The topic is referred to with this. The member id holds the id of the topic. The following methods can be called on this:

nvalue

Takes a topic reference to a name type as the only argument and returns the value of the name.

ovalue

Takes a topic reference to an occurrence type as the only argument and returns the value of the occurrence.

cplayer

Takes an association type as the only argument and returns the label of the other player.

cplayers

Takes an association type as the only argument and returns the array of the labels of all other players.

This code labels a person with the first name (id of the name type is "55") and last name ("56") separated by a space.

Label rules can be varied depending on the perspective by scoping them with a role type and optionally a language. Usually some segments of the unscoped label rule needs to be left out since it is given in the context.