Topincs

The core technology of Topincs is Topic Maps. A familarity with this semantic technology is recommended from this point onward. A Topincs installation can host any number of web databases which are rooted at an URL prefix, e.g. /products/. This prefix appended to the protocol and the host name of your server forms the store URL which displays the start page of a store when opened in a browser. At this start page you find an index of all topics in the topic map grouped by their topic type. Initially the store is empty and you need to model one or more topic types in order to see something on the start page.

For modeling you need to sign in as an administrator. After this you will notice the admin mode status message to the lower left. By moving your mouse pointer over this message the admin menu becomes visible and from there you can reach the schema page which is the modeling center of your Topincs store. You also notice a switch to turn on admin mode. In admin mode all schematic page elements are highlighted and react to right-click with the modeling context menu for viewing, editing, or deleting the topic (or topics) related to that element.

The schema page has four sections: types, constraints, programming, and miscellaneous. You can start all your modeling tasks here. If you want to model a new type, use the + in the bar of Topic type.

Modeling a topic type requires you to name it and create one or more constraints which roughly correspond to input fields in the form for editing instances of that type. When modeling a topic type you will need to create additional statement types. There is no need to create them before hand, you can create all necessary topics along the way by entering sub forms.

Topincs processes constraints in order to generate a form for instances of a topic type. The 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 one. In a symmetric relationship you will need one constraint for one role type with minimum and maximum cardinality of two.

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 require to upload a file to the server where it will be stored and published at an 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. If you should upload the same file twice you will notice that Topincs recognizes the file and avoids to create a new topic but rather attaches all additional statements made to the existing topic which already represents this file.

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.

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.

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.