Directions for use of Annotation extension for JavaSript based WYSIWYG editors

Installing

1. Download and install 4A server (follow the directions in Directions for use of 4A Annotation Server)
2. Run the server.
3. Install Drupal 7 with annotation_editor module (from knot.fit.vutbr.cz).
4. Configure annotation server address in your Drupal on /admin/config/services/annotation_editor
5. Observe annotation extension in TinyMCE on any editation page in Your Drupal.

Displaying of extension GUI

1. To display annotation extension GUI you can click to extension icon on the toolbar of your WYSIWYG editor.
2. To hide the GUI, you can click to the icon again.

Connecting to the server

1. Click to Connect button on annotation extension toolbar.
2. Fill in 4A server address in long format (eg. "http://localhost:8080/Annotations" which is valid for local testing), your login and password.
3. Click to the Ok button

Creation of an simple annotation

1. Select range of annotated text by mouse.
2. Click to Annotate button on annotation extension toolbar to display Annotate window (window is not modal, so you can select annotated text or adjust selection later).
3. Select type of annotation (described later).
4. Optionally you can fill in textual content of annotation (your note).
5. Save annotation by Save button on the right bottom corner of the window.

Selecting type of annotation

• Types of annotations are tags, which denoting meaning of annotated text. They are in the tree (in next version multiple inheritance will be allowed). In the Type field it is a path in the tree is specified and it's called linearized name. Root of the tree is not visible for you, path starts on second level. Types in the path on individual levels on the tree are separated by arrow from dash and greater then sign "->". So example of type is "Person->Employee".
• Only alphabetical characters, numbers and some other characters as "-" (dash), "_" (underline) and "." (dot) are allowed in type name in actual version of system. If multiple words are necessary, they must be delimited by dot or underline, not by space character.
• you can select type of annotation by four methods:
  
  1. You can type name of new or existing type of annotation into Type field directly.
  2. If you starts writing to Type field, autocomplete functionality will be turned on automatically. So you can select offered type.
  3. On the right side from type field it is Browse button. This button shows you the tree with types and you can select type from this tree. You can also enrich the tree in the showed window.
  4. You can combine first three methods described.

Structuring of annotations

• Annotations can be structured via attributes.
• Attributes are creating inner structure of annotation and can be used for creating structure from annotations simultaneously.
• Each attribute have name, type and value.
• Attribute can be added by Add button under the tree with attributes on the left side of Annotate window. In the form for adding of attribute there are name of attribute (for names of attributes we have same rules as for names of types of annotations, but space character can be used) and area for selecting type of attribute. There are two roots of the tree with types. Under the first are simple types, under the second are types of annotations (see below). New types of annotations can be added in this dialogue too.
• Type of existing attribute can be changed in field "Type", which have autocomplete or by using of dialogue displayed by button "Select" on the right of this field.
• There are two types of attributes:
  
  1. Attribute of simple type.
     
     • Type of this attribute is one of supported simple data types:
       
       • Boolean can have value true or false.
       • Decimal can have value of decimal number.
       • Integer can have value of integer number.
       • DateTime can contain date and time (time zone is handled internally).
       • Date can contain date only.
       • Time can contain time only.
       • String can contain any string of characters.
       • URI can contain any URI.
       • GeoPoint have values of latitude and longitude, which points to any point in the globe.
     • If it is possible to find value of attribute in the annotated text, it's not recommended way to copy it to the attribute value - it's better to annotate it and use structured type of attribute.
  2. Attribute of type of annotation (structured attribute)
     
     • Type of this attribute is one of types of annotations and value is annotation or annotations of this type.
     • There are four types of attributes of type of annotation:
       
       1. Nested annotation
          
          • Nested annotation is annotation, which haven't meaning separated (eg. age have not meaning, if we don't know, whose age it is).
          • Annotated text of nested annotation can be selected by mouse, if you have attribute selected in the tree.
          • Textual content of nested annotation can be filled in and attributes can be assigned to this type of annotation too. For adding attribute to annotation in attribute select attribute with nested annotation and use Add button as on upper level.
          • Annotations can be nested to teoretically unlimited number of levels.
       2. Annotation link
          
          • Annotation link is link to the annotation.
          • Linked annotation can have own content and attributes, but if we are creating link to it now, we can't change them there. If we want to change them, we must edit appropriate annotation. It's countermeasure to create unwanted changes.
          • For selecting of linked annotation, click to button Select below "Selection" area. All annotations of selected type of attribute will be highlighted and you can select it by one click.
       3. List of nested annotations
          
          • Annotations in the list must have same type, content and attributes (it's logical, because it's content of one attribute), but can annotate different fragments (eg. attribute "colors of car" can have nested annotations of type "color of car").
          • You will create it in future version of Annotation extension for JavaSript based WYSIWYG editors. In current version it is impossible to create it.
       4. List of linked annotations
          
          • Annotations in the list must have same type.
          • You will create it in future version of Annotation extension for JavaSript based WYSIWYG editors. In current version it is impossible to create it.

Templates for attributes

• Each type of annotation have one template with attributes assigned.
• If you select type of annotation, empty attributes for this type will be added to the list of attributes of newly created annotation.
• If you are creating annotation of some type, you can add attribute to its template. It's accomplished by checkbox in bottom of dialog for adding of attribute.
• If you would like force other users to fill in value of attribute, if they use this type of annotation, you can set attribute as required. It can be done by checking in checkbox under the checkbox for adding attribute to template.
• For existing attributes you can set, whether they are required, by checkboxes in the form for editing of the attribute. There can be set whether update type of existing attribute in the template too.

Viewing of annotations

• Annotated fragments of text are highlighted and if you move your mouse cursor beyond fragment, small window with annotation will be displayed. Note: In Google Chrome it is possible that windows are not appearing. In this case it is necessary to click somewhere to text in TinyMCE. It is a feature of Google Chrome which can not be overcome.
• If you click to fragment by the left mouse button, window with annotation stay displayed, until you close it by button on the right upper corner of window or until you click to another place in the annotated document.
• Attributes of the showed annotation are folded. You can unfold them by clicking to button with down arrow.
• If you click to attribute of type of annotation in the annotation window, window of appropriate annotation will be displayed as if you click to it's fragment.
• If you click to attribute of type GeoPoint, new tab with Google Maps will be opened and point will be showed on the map.
• On the right side of annotation window there are two buttons. Left button with pencil is used for editing of annotation. It will be filled back to form and you can edit it and save by same button as if you are saving new annotation. If you bethink, you can cancel editation by Cancel button on the right of button for saving of changes. Right button with trash bin is used to delete this annotation and all it's nested annotations.

Annotations of whole document

• You can create annotation of whole document by using button "Annotate whole document" below "Selection" area instead of selecting of fragment of text.
• Annotations of whole document are displayed in the panel "Document Annotations", which can be displayed by menu button.

Settings

• For displaying of dialog with settings you can click to "Sesstings" button in menu.
• All the settings is saved on the server as list of parameters for each user.
• In the section "Client" you can set parameters of settings related to client. In the section "Server" you can set parameters of settings related to 4A server. In the section "Common" you can set parameters of settings related to both - client and server.
• In the section "Unknown" you can set all settings which is not recognized by client. It can be settings related to other clients, newer version of server, some special server module and so on. Each parameter of such settings have name and value. Start of name of parameter can be used to distinguish between settings for server and other clients. New parameter can be added with "Add" button under the parameters list. Modified list of settings can be saved by the "Save" button.

Settings - Section Client

• Annotation type colors (setting of colors of highlighting) - You can set color of annotated fragments of given type of annotation. You can fill in type of annotation and color manually or use "Select" button on the given row and use form for creating or editing an entry. In this form you can use autocomplete or selection from the tree for selecting the type of annotation. Color can be selected by color picker and alpha can be set in percents. If fragments can be overlapping, it is recommended to set alpha approximately in range of 20 - 80 (that way so it will be visible and overlapping is clearly recognisable).
• Refuse suggestion - You can set if suggestion refusing needs to be confirmed. Server will not send refused suggested annotations more times, so it can be useful to avoid mistakes by confirming. But in case of many simple suggestions it can be wasting of time to confirm every refuse - it can be simplier to correct mistake by creating an annotation manually.
• Suggestion confidence - Suggestion confidence is a number in percents. Every suggested annotation contains a value in percent reflecting the level of confidence that suggestion is right. If this value of any of suggested annotation is lower than choosen suggestion confidence, client will drop this annotation (automatically refuse it).

Settings - Section Server

• Language - For current version of server only language for warning and error messages can be set. Values are from ISO 639-2 the alpha-3 Codes for the representation of names of languages, alternatives for bibliographic purposes.

Settings - Section Common

• Default user group - Default user group is group in which new types and annotations will be created in case of user is in more user groups.

Suggesting of annotations

• 4A server can suggest annotations to you, so you can only confirm or refuse suggestions. You can edit and save suggestion too.
• For getting of suggestions open the Suggest Annotations dialog from menu and select part of document to which suggestions should be get or click to button for selecting the whole document. You can select type of annotations to be suggested too (if you do not it, annotations of all types will be suggested). Now click to "Suggest" button and suggested annotations appear between other annotations in the document, but it will be marked with dashed borders.
• Each suggested annotation have button with tick in its window, which can be used to confirm the suggested annotation. Icon with trash bin in suggested annotation window can be used to refuse the suggestion.
• If you want to change part of text to which suggestions are taken and displayed or type of suggested annotations,, you can open Suggest Annotations dialog again, change parameters for suggesting and confirm with Suggest button.
• To disable suggesting of annotations and remove suggestions from document, you can open Suggest Annotations dialog and click to "No suggestions" button, thereby select empty part of text for suggesting. After you click to the "Suggest" button, your choice will be confirmed and suggestions dissapear.
• In the Suggested Annotations dialog you can see list of all suggestions, which are now suggested for selected part (or whole) document.

Persons

• In Persons dialog you can see all users of 4A server and their user groups.

User Groups

• In Groups dialog you can see all user groups of 4A server and users in this groups.
• You can join the user group by clicking to arrow from left to right beside the user group. To leave group you can use arrow in oposite direction.
• Last user in Administrators group cannot leave this group. It's not possible to join to Administrators group in the client - it must be done by the user in this group on 4A server's web interface.

Subscriptions

• You can subscribe to annotation taking so client can take only annotations of selected types from selected sources. Source can be user or URI, which can identify user group, 4A server or another generic source.
• After connecting to the server you are automatically subscribed to taking your own annotations and annotations from all yours groups.
• Subscriptions dialog is not completed in this version of client, so it is not possible to use autocomplete here. Automatically subscribed sources are not visible for same reason. If you add new subscription, it will be saved only to session so after disconnect it will be dropped. All this problems will be solved in future versions.

Other features

• "Annotation Dialogs" button can be used for disabling and enabling of displaying of annotation windows if you move your mouse cursor beyond fragment. It can be useful in case you are reading the text and hold the actual position by mouse cursor. In this case this dialogs can be confusing. If you click to fragment, dialog appear in both modes.
• Status bar shows log of communication between client and server. Errors, warnings etc. can be viewed here.
• "Synchronize" button can be used to resynchronize the document. It can be needed in case of error (software is still in alpha version). In future versions this button dissapear, because eventual error recovery will be held on the background.