Extension:Semantic Text Annotator

MediaWiki extensions manual

SemanticTextAnnotator Release status: beta
Implementation	Page action, Ajax, Special page
Description	Allows to add, edit and observe semantic annotations to texts
Author(s)	Oliver Lutzi (Wingolitalk)
Latest version	0.1 (2014-01-12)
MediaWiki	1.19+
Database changes	No
License	No license specified
Download	v0.1
Hooks used OutputPageBeforeHTML smwInitProperties
Translate the Semantic Text Annotator extension if it is available at translatewiki.net
Check usage and version matrix; code metrics

Semantic Text Annotator is an extension for Semantic MediaWiki developed within the research project SMW-CorA that allows you to add, edit and observe semantic annotations to texts in your wiki. It requires Semantic MediaWiki, SemanticForms, SemanticResultForms and ParserFunctions to work.

We do not recommend to use it in a production system!

Current version (0.1) was only tested on articles containing plain texts! (Simple syntax, e.g., making text bold ('''TEXT''') or italic (''TEXT'') works.)

Does not work with long articles!

highlighted annotation with details shown

§Download

You can download the extension here.

§Installation

1. Unzip the downloaded zip file. Put the folder 'SemanticTextAnnotator' into your wikis extension folder.
2. Include the following line in your LocalSettings.php :

   include_once("$IP/extensions/SemanticTextAnnotator/SemanticTextAnnotator.php");
   

3. Make sure that you include the extensions Validator, Semantic MediaWiki, SemanticForms, SemanticResultForms and ParserFunctions before you include the SemanticTextAnnotator!
4. Don't forget to setup the extension!

§Setup

After the installation you have to visit the page "Special:SemanticTextAnnotator". This will automatically create all templates and forms the extension works with.

§Usage

text selection for new annotation

confirmation of new annotation

creation of details for new annotation

This is a brief introduction on how to use the Semantic Text Annotator.

§Creating annotations

After successful installation, you have to put all pages that you want to annotate in the category "STA_Annotatable" by adding the following text to the source code of the article:

[[Category:STA-Annotatable]]

Once you visit pages of the category "STA_Annotatable", the two buttons New Annotation and View Annotations will appear next to the text "Semantic Text Annotator" on top of the article.

Clicking on the button New Annotation will start the "annotation mode". You can now select a passage in the text with your mouse. A pop-up message will appear when you release the mouse button, where you can confirm your selection or abort the process.

If you confirmed your selection a Semantic Forms popup window will appear showing the default form for text annotations. In this window, you can specify the details of your annotation. By default there are two fields you can put text in to annotate the selected passage. Both fields will be stored as semantic properties. The first property is called "STAannotationType" and the second one "STAcomment". There are plans to make this form customizable in future development. In the current version, you should not change the default form due to unclear dependencies.

After clicking on the "Save"-button you will automatically switch to the "annotation view" where all annotations are displayed.

§Displaying annotations

To display annotations that you have created, click on the button View Annotations. Every annotation is represented by a horizontal line on the left side of the article's text. You can view the information which belong to an annotation by moving your mouse cursor over the respective horizontal line.

§Changing and deleting annotations

When you select an annotation via mouseover you can press the button Change Annotation to change the values of the semantic properties that belong to the observed annotation. By clicking Delete Annotation the annotation will be deleted.

§Query annotations

You can query annotated text passages that have been given a certain value in one of its semantic properties. For example you can query all annotations where the value "King_Speech_Annotation " has been attached to the property "STAannotationType" and that where made by the user "Olutzi" by using the following syntax:

{{#ask: [[STAannotationType::King_Speech_Annotation]] [[STAcreatedBy::Olutzi]]
|? STAannotatedText 
|? STAcomment
|? STAcreatedBy
|? STAannotationDate
}}

In the screenshot, the resulting annotations are ordered by the date of their creation.

query of annotations

§How it works

The Semantic Text Annotator defines a custom namespace for annotations (TextAnnotation:). Each annotation is stored as a unique page in this namespace. The information of an annotation are stored in semantic properties on this page. Some property values are defined by the user through the pop up form window. By default there are two properties the user can define himself:

STAannotationType

Can be used to categorize the selected text passage.

STAcomment

Can be used to briefly describe the selected text passage within its category.

Semantic Text Annotator also defines a few custom properties that are added to an annotation page that are necessary to correctly store and retrieve annotations.

STAannotationSerialNumber

An unique number to identify every annotation.

STAarticleName

The name of the article the annotated text passage belongs to.

STAannotationDate

The date the annotation has been created or changed.

STAcreatedBy

The user that created the annotation.

§Future development

The Semantic Text Annotator is still under heavy development. Feedback, bug reports and feature requests are therefore very welcome!

§Planned features

1. Executability of the extension on articles containing all possible syntax
2. Customizable structure of the user-defined semantic properties
3. Possibility to change the position of an annotated text passage ex post by dragging start and end of the selected area

§Known issues

Currently, the biggest problem of the extension is that it only works properly in short articles containing certain syntax. It has not been tested yet, which syntax causes malfunctions and which syntax can be processed adequately.

§Credits

The Semantic Text Annotator is based on the extension "Semantic Image Annotator" by Felix Obenauer, which provides similiar functionality for image files.