Directions for use of Annotation Extension for Mozilla Firefox

Installing

1. After you click to download link, you must confirm installation and restart Firefox.
2. For automatic updates it's recommended to add our server knot.fit.vutbr.cz to your Browser - Tools - Preferences - Security - Allowed Sites - Software installation.

Connecting to the server

1. Click to extension icon on addon bar.
2. Click to sesstings icon (with gear wheel) on the right upper corner of extension panel and in section Server set up the server address and port. For local testing, address is localhost and port is probably 8080, for our public testing server it is a knot09.fit.vutbr.cz and port is 8080
3. Close settings and fill in login and password (for our server we can supply it, for local testing it can be found in the database table user - details are in section about server).

Creation of an simple annotation

1. Select range of annotated text by mouse.
2. Select type of annotation (described later).
3. Optionally you can fill in textual content of annotation (your note).
4. Save annotation (click to icon with paper with green plus sign on the right).

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, but now it's not fully functional). 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. Write to the Type field and press Enter key.
  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 Select 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 green button with plus sign on right down corner of area with tree with attributes. 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 column with types. In the left column are simple types, in the right are types of annotations (see below). New types of annotations can be added in this dialogue too.
• Type of 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. If you select name of type which can be simple type or type of annotation, dialog with two buttons for differentiating between them will be displayed (it's only way how to solve it in current version of Mozilla Firefox).
• 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.
       • Person can contain e-mail address of user of annotation server. It's not recommended to use this type, because it is obsolete and can be removed in further versions.
     • 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 after clicking to button Select on the right side of "Selected text" field. After you select the text, you must end selecting by clicking to the button "End Selection".
          • 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 red button with plus sign on right bottom corner of area with tree with attributes.
          • 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 not see it in the tree with attributes and 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 on the right side of "Selected text" field. All annotations of selected type of attribute will be highlighted and you can select it by one click. After you select the annotation, you must end selecting by clicking to the button "End Selection".
       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 can create it as nested annotation, but select more fragments of text with Ctrl button. In "Selected text" field you can see all of fragments separated by sign choosed in settings, or individual fragment (switched by arrows in front of field).
          • In editation of annotation you can add or remove fragment (or more precisely whole nested annotation) by use of red and green buttons with plus sign and minus sign under the arrows for switching between fragments.
       4. List of linked annotations
          
          • Annotations in the list must have same type.
          • You can create it as annotation link, but after you click to "End Selection" button, you can use green button with plus sign in front of "Selected text" field and select second annotation. After you click to "End Selection" again, you can add more links by the same way.

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 don't fill in value of attribute, it will not saved with annotation. 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, in dialog displayed by the button "Change Attribute Setting". You can remove attribute from template checkbox in this dialog 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. Fragments of nested annotations will be highlighted in the same time.
• If you click to fragmenty by the left mouse button, window with annotation stay displayed, until you close it by button on the right upper corner of window.
• 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.
• In the left upper corner 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 button on the left of button for saving of changes. Right button 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 small button with paper on the left upper corner of extension panel instead of selecting of fragment of text.
• Annotations of whole document are displayed in side panel, which can be displayed in menu of your Firefox (View -> Sidebar -> Annotation extension).

Settings

• For displaying of dialog with settings you can click to sesstings icon (with gear wheel) on the right upper corner of extension panel.
• In the section "Window" you can set appearance of extension panel (window).
• In the section "Text selection" you can set character which will be used to separate individual fragments in "Selected text" field in case of selecting multiple ranges of text.
• In the section "Server", informations about server can be set (only if you aren't connected).
• In the section "Groups", you can join or leave user groups (types of annotations and annotations are shared in groups).
• In the section "Other" you can set other properties, for which separate sections is not available (see below).

Section Others in settings dialog (setting of colors of highlighting)

• Each parameter of settings have name and value.
• Settings is saved on the server as list of parameters for each user.
• Start of name of parameter can be used to distinguish between settings for server, other clients and Firefox extension.
• New parameter can be added with button with green plus sign on the right down corner.
• Parameter can be edited by clicking by left mouse button.
• Parameter can be deleted by clicking by right mouse button (confirmation dialog will be displayed).
• For Firefox extension, only colors for highlight of annotated fragments can be set here:
  
  • Parameter with color is named "ClientFFExtTypeColor:?", when ? is name of type of annotation (linearized name - see before).
  • In dialog for adding of parameter, there is separate tab for setting of color. You can fill it directly as "rgba(red,green,blue,alpha)", where color compounds can have value 0 - 255 and alpha (transparency) can have value 0 - 1. Or you can use button and select color from supplied grid and then adjust only value of alpha.
  • If you set too small value for alpha, highlighting may be badly visible, but if you set too greater value, overlapping fragments may not be distinguishable.
  • Setting of colors will be simplified and improved in next versions of extension.