View source for Editing topics and associations

This page is part of Wandora's documentation and covers editing of topics, topic's internal structures and associations. [[Traditional topic panel]] is used as the default editor although it is possible to edit topics and association in other topic panels too.

== Editing base names ==

Topic's base name is modified by changing the contents of base name text field in topic panel. Emptying field removes the base name. Topic may have only one unscoped base name in Wandora. This is little different compared to Topic Maps standard where topic may have multiple scoped base names. By default Wandora represents a topic using it's base name. It is recommended all topics have base name. Also, we strongly encourage you not to use new line characters in base names as Wandora's base name field does not support the character. Next image views [[Traditional topic panel]] with topic '''Schema type'''. Base name field has been marked with a red circle.


[[File:basename_traditional_topic_panel.gif|center]]


Base name is an unique topic property. If two topics have same base name, topics represents same subject and are merged immediately. If you change base name manually and new base name already exists in the topic map (or generally in any [[Layered_topic_map|layer]] of Wandora), Wandora confirms the base name change and consequent merge.

Addition to topic panel editing, base name can also be modified within a topic tree. Clicking the topic three times in the tree changes topic's base name label into an editable base name field.

'''Topics > Base name''' menu contains more advanced base name editing options. These advanced editing options include

* '''Make base name with a subject identifier''' creates a base name for topic. Base name is created using topic's subject identifier. Created base name is the file part of a subject identifier. This feature is useful if you have imported an RDF document and would like to name topic stubs created with URIs. If topic already contains a base name, base name creation fails. You have to remove old base name first.
* '''Make base name with an occurrence''' creates a base name for the topic using an occurrence. If topic already contains a base name, base name creation fails silently. You have to remove old base name first.
* '''Modify base name with a regex''' allows you to modify base name with regular expressions.
* '''Remove new line characters''' removes all new line characters found in topic's base name. This may be necessary if you have imported a topic map to Wandora. Wandora can't view new line characters in base names.
* '''Collapse white spaces''' removes all additional white space characters after a white space. In other words, two or more sequential white space characters are replaced with a single white space character. 
* '''Trim base name''' removes all white space characters starting and ending a base name.
* '''Remove base name...''' removes topic's base name. Base name removal is necessary if you intend to create a new base name for the topic with option '''Make base name with a subject identifier''', for example.


These editing options may sound trivial if you consider modifying one base name. However, applying editing option to multiple topics at once is much more useful.


== Editing subject locators ==

Subject locator is an URL resource that '''is''' the topic. Topic may have zero or one subject locator. If two topics have same subject locator, topics merge automatically.

To modify topic's subject locator open the topic to a topic panel such as [[Traditional topic panel]] and edit panel's subject locator field. Writing URL to the field adds subject locator to the topic. Emptying the field removes topic's subject locator. Next image views [[Traditional topic panel]] and subject locator field marked with a red circle.


[[File:sl_traditional_topic_panel.gif|center]]


Although Wandora's topic map model does not resolve subject locators, Wandora application resolves the URL and views a thumbnail or an icon for the resource. Thumbnail or icon is viewed above the subject locator field in traditional topic panel. Some resource types such as image or HTML document can be modified with context tools. If subject locator resolves image, subject locator icon views the image. Right clicking the image icon reveals context menu with tools for the subject locator. For images the context menu contains tools to resize image, copy image, save image etc.

Advanced subject locator tools locate in '''Topics > Subject locator''' menu. Advanced tools enable the user to check subject locator URL, download subject locator files and construction of subject locators for example. More detailed:

* '''[[OpenSL|Open subject locator...]]''' forks external application (handling URL addresses) and passes the subject locator url to the application. Usually the computer opens up a WWW browser with a page that has the subject locator URL.
* '''Check subject locator...''' resolves subject locator URL and reports whether or not the URL resolves to a real internet resource. This is useful when you have to check if subject locators of an old topic map are still valid.
* '''Download subject locator''' downloads the subject locator resource to a local file system but doesn't change topic's subject locator. This is handy if you want to inspect the subject locator resource closer with an application in your local computer.
* '''Download and change subject locator''' downloads the subject locator resource to a local file system and changes the subject locator to point downloaded copy of subject locator resource.
* '''Extract with subject locator''' contains submenus, one for each Wandora extractor that handles URLs. Selecting an extractor in this context applies the extractor to the subject locator URL.
* '''Modify subject locator with a regex...''' changes topic's subject locator with a user specified regular expression. Wandora uses [http://docs.oracle.com/javase/tutorial/essential/regex/ Java's regular expressions].
* '''Remove subject locator...''' removes topic's subject locator.
* '''Make subject locator with a base name''' construct subject locator for the topic using topic's base name and an URL body specified by the user.
* '''Make subject locator with an occurrence''' constructs subject locator for the topic using topic's occurrence and an URL body specified by the user.

These editing options may sound trivial if you consider modifying one subject locator. However, applying editing options to multiple topics at once is much more useful.

== Editing subject identifiers ==

Each topic has one or more subject identifiers in Wandora. Each topic must have at least one subject identifier. Subject identifiers are practically URLs referring to subject indicators i.e. resources that describe the subject. However, subject identifier URLs do not necessarily resolve. In other words there is no real resource the subject identifier refers. Subject identifiers are unique and topics with same subject identifier are merged automatically.

Topic panel doesn't allow direct edition of subject identifiers. To change a subject indentifier the user needs to add the changed subject identifier to the topic as a new one and then remove the old subject identifier. This rather illogical order of actions is required because topic must always contain at least one subject identifier. If you remove topic's last subject identifier, a default subject identifier is added to the topic.

[[Image:Add_si.gif|center|Subject identifier is added to a topic with external dialog]]

Subject identifier is removed by right clicking the subject identifier and selecting '''Remove selected subject identifiers...'''. Subject identifier is added to a topic by selecting '''Add subject identifier...''' in context menu of the Subject Identiers title header.

More advanced tools to modify subject identifiers is found in '''Topics > Subject identifiers''' menu:

* '''Copy subject identifiers''' copies topic's subject identifiers to the system clipboard. New line character is used as a subject identifier separator. 
* '''Paste subject identifiers''' injects URLs in the system clipboard to the current topic as subject identifiers. If pasted subject identifier already exists in any other topic, topics are instantly merged.  
* '''Remove references in subject identifiers''' modifies topic's subject identifiers by removing URL references. URL reference is a part of URL address that starts with a hash ('''#''') character.
* '''Modify subject identifiers with a regex...''' modifies topic's subject identifiers with a given regular expression.
* '''Fix subject identifiers''' modifies subject identifiers by replacing all illegal characters with an underscore ('''_''') character.
* '''Flatten identity''' removes all but one subject identifier in topic. Remaining subject identifier is arbitrary. This feature is useful if the topic has merged many times and all subject identifiers all temporary.
* '''Make subject identifier with a subject locator''' adds topic new subject identifier identical to topic's subject locator. If topic has no subject locator, no subject identifier is added. 
* '''Make subject identifier with a base name''' adds topic new subject identifier constructed using topic's base name and an URL body given by the user.
* '''Make subject identifier with an occurrence''' adds topic new subject identifier constructed using topic's occurrence and an URL body given by the user.

== Editing variant names ==

Variant names are scoped topic names. Scope is a set of topics and specify the type of a name. Usually a scope contains at least two topics, one for language and one for name type. By default, [[Traditional topic panel]] views variant names in a name field matrix that has language paragraphs. Orientation of the name field matrix is changed with an option '''View > Flip name matrix''' found in a context menu of Variant names title header. Variant names are edited directly in the fields of a [[Traditional topic panel]]. Next image views a [[Traditional topic panel]] with a Variant name matrix marked with a red circle.


[[File:variant_names_traditional.gif|center]]


To view and edit variant names with non-schema scopes, user can right mouse click the '''Variant names''' box title and select context menu option '''View > View all scopes'''. Wandora changes the look of a variant name panel and views now all variant names of the topic. Next image views alternative variant names editor available in [[Traditional topic panel]]. Alternative variant names editor can be used to edit variant names with non-schema scopes.

To add a topic a variant name with non-schema scope, right click the '''Variant names''' box title and select menu option '''Add variant name'''. Wandora opens up a dialog window for a non-schema scoped variant name. Next image illustrates an use case where Wandora user is adding a topic a variant name '''Non-schema variant name here''' with a single scope topic '''Schema type'''.


[[File:add_variant_name.gif|center]]


Notice, non-schema variant names are not viewed in variant name matrix. However, the number beside '''Variant names''' box title counts also non-schema variant names.

For more advanced variant name operations use tools in '''Topics > Variant names'''. Menu includes options:

* '''Copy all variant names''' copies topic's variant names to clipboard. Also invisible variants i.e. variant that are not specified with schema, are copied to clipboard. This can be used to check what kind of variant names topic has. 
* '''Modify variant names with a regex''' is used to modify topic's variant names with a regular expression given by the user.
* '''Remove new line characters''' deletes all new line characters in variant names of current topic.
* '''Remove variant name''' deletes variant name of given type and scope.
* '''Remove all empty variant names''' deletes all zero length variant names in the topic.
* '''Remove all variant names''' deletes all variant names in the topic.
* '''Make display variants with a base name''' copies topic's base name to all display variants.

By default Wandora supports four language topics. These are Finnish, Swedish, English, and Language Independent. By default Wandora supports two name types: a Display name and a Sort name. Extending Wandora's language and the name type support is easy. To add Wandora a language, add new instance topic to '''Wandora language''' topic. To add another name type, add new instance to topic '''Wandora variant name version'''. Both '''Wandora language''' and '''Wandora variant name version''' are instances of '''Schema type''' topic.

=== Additional tips for editing variant names ===

* [[Transform variant names to topics and associations]]
* [[Add missing language scope to variant names]]
* [[Add missing display scope to variant names]]
* [[How to add another variant name language]]
* [[How to add another variant name type]]

== Editing topic classes and instances ==

Each topic may be related to zero or more class topics. Class-instance relation is used to express ''a type'' or ''a kind'' of a topic. Next image views traditional topic panel with a '''Schema type''' topic. Red circles mark topic's classes and instances.


[[File:traditional_topic_panel_class_instances.gif|center]]


Class is added to a topic by right clicking the title header '''Classes''' and selecting '''Add class'''. After selection, Wandora opens a pick-a-topic dialog used to address the topic class. Topic's class is deleted by selecting a row in the '''Classes''' table, right clicking the row, and selecting menu option '''Delete classes...'''. Multiple classes can be removed at once. Notice that deleting a class topic removes only class-instance relation. The topic itself is not removed.

Also '''Topics > Add to topic > Add class''' menu selection adds topic a class and '''Topics > Delete from topic > Delete classes''' deletes the class.

=== Modifying topic instances ===

Instance is added to a topic by right clicking the title header of '''Instances''' table and selecting '''Add instance...'''. Instance is deleted by selecting row in the instance table, right-clicking selected row and selecting '''Delete instances...'''.

Also menu selections '''Topics > Add to topic > Add instance''' and '''Topics >Delete from topic > Delete instances''' can be used to add and delete instances.

=== Additional notes about Wandora's data model and used terminology ===

Wandora models class-instance relations using internal data structures. Wandora doesn't contain a topic that represents the relation type or role types. This means that Wandora user can not use the relation '''class-instance''' nor role types '''class''' and '''instance''' in part of other relations. Wandora user can't set up a superclass of a '''class-instance''', for example.

Wandora speaks of classes and instances while the Topic Maps standard speaks of '''types''' and instances. Reader should note that a '''type''' described in Topic map standard is equivalent to a concept of a '''class''' in Wandora.

== Editing associations ==

Associations link topics together into doubles, triplets etc. Association is a named hyper-edge connecting topics. In Wandora, an association is added by selecting '''Add association...'''. Association is modified by selecting association row in association table and selecting option '''Modify association...'''. Both options open up an association editor. Next image views Wandora's traditional topic panel of a topic '''In No Sense? Nonsense! (album)''' which appears to be one of '''The Art of Noise's''' album. Red circle marks associations where the album plays a role i.e. associations which somehow connect the album topic to other topics.


[[Image:traditional_topic_panel_associations.gif|center|Adding association to a topic]]


Adding association results empty association editor while Modify association fills editor fields with roles, players and type of the selected association. Association editor is used to add and modify one association at time. Next image views an association editor where type and roles have not been selected yet.


[[Image:schemaless_association_editor.gif|center|Adding association to a topic]]


To create an association the user must pick a type, player and role topics for the association. Association creation is discussed more detailed in [[Create new association]].

Wandora includes also more sophisticated association modification options. To reveal available options right click on association table. Context menu should contain at least:

* '''Delete associations...''' is used to remove selected associations in current topic table. Deletion is confirmed from Wandora user.
* '''Change type...''' is used to change association type topic of selected association in current topic table. Wandora asks new type topic with topic request dialog.
* '''Change role...''' is used to change one of the association roles of selected association in current topic table. Wandora asks which role is replaced and which topic replaces old role.
* '''Insert player...''' inserts user selected player (with user selected role) to selected associations. This option is especially handy if you need to add same player to numerous associations.
* '''Delete players...''' is used to remove selected columns i.e. players from selected associations. Note that your selection in association table really defines what players Wandora removes. Wandora confirms deletion from user.
* '''Swap players within''' changes player roles in selected associations. Option creates a symmetric association that has different role order. Option is useful when roles are somehow similar (for example ''neighbour-1'' and ''neighbour-2'') and you need to refactor large number of associations.
* '''Create symmetric associations...''' is similar to '''Swap players within''' but doesn't remove original associations.
* '''Delete symmetric associations...''' compares selected associations to all other associations in Wandora and deletes association if symmetric duplicate is found. Symmetric duplicate is an association with same players and roles but role order is different.
* '''Collect binary to n-ary...''' is used to change multiple binary associations into a single association with multiple players. To work properly all binary association should share one player.
* '''Split n-ary to binary...''' converts one association with multiple players to multiple binary associations. User must select one player as shared player. Shared player ties binary associations together.


== Editing occurrences ==

Occurrence is a solid text block associated to the topic. For historical reasons Wandora calls occurrences also as '''Text datas'''. Occurrence has a '''type''' and a '''scope'''. Type is a topic that describes the occurrence, '''date of birth''' for example. Scope is also a topic describing the occurrence. Usually scope specifies the language of the occurrence. Occurrence is added to a topic by selecting '''Add occurrence...''' menu option. Option opens a dialog window:


[[Image:Schemaless_textdata_editor.gif|center]]


Occurrence creation dialog has a button for occurrence type topic and text fields for all languages in Wandora schema. To create an occurrence, user has to select type topic and write text in one or more text fields, and finally click '''OK''' button.

Occurrence editor doesn't allow user to specify occurrence languages freely. This is usually enough as languages should not vary too much. To add occurrence of non-listed language, add your language topic as an instance to '''Wandora language'''. Read more [[How to add another variant name language|here]].

Topic map standard supports also URL occurrences addition to text occurrences. However, Wandora does '''not''' support URL occurrences as it is possible to set URL's external representation, the string representing URL, as the occurrence. 

After occurrence creation Wandora user can edit occurrences. To edit single occurrence, user has to click the text field showing occurrence's first words and Wandora opens up an occurrence editor. Occurrence editor is shown below. Editor contains some additional features compared to creation dialog. For example, user can strip html elements in occurrence text with a menu option '''Edit > Strip HTML tags'''. '''Refine''' menu contains occurrence text classifiers and topic finders for example.


[[Image:occurrence_editor.gif|center|Editing occurrence after initial addition.]]


More advanced occurrence operations are found in '''Topics > occurrence''' menu of topic tables. These operations include:

* '''Delete occurrences with type''' removes occurrences of given type from context topics.
* '''Delete all occurrences''' removes all occurrences from context topics.
* '''Modify occurrence with a regex...''' modifies an occurrence with a regular expression. This can be used to perform rather complicated search and replace operations for example. 

See also page [[Refining occurrences]] for some advanced occurrence editing options.