Documentation

Tabel of Content

1. Introduction 2. Compatibility 3. Integration 4. Customizing the Appearance 5. Triggering the Functionality

1. Introduction

Basically Tucent consists of two components - one is the Tucent client, which runs in the web browser, the other is the Annotation Web Service (AWS) on the server side. The client communicates with the AWS to get annotations for a specific URL, to create new annotations or to change existing ones.

If a website has integrated the Tucent script tag into its HTML code, the browser of a visitor will load and execute the Tucent client automatically when showing the website. The first thing, the Tucent client does, is to send a request to the AWS, requesting the annotations for the current URL. If annotations are available for this URL the AWS will respond by sending this annotations back to the client. Then the client processes the HTML document trying to anchor the annotations into the content. If the website's content has changed since the ceration of the annotation, this operation may fail silently for one or more annotations - although Tucent uses a robust algorithm to be insensible in regards to changes in website contents.

In the following sections you find a documentation about the compatibility and the integration of the Tucent client. If you have questions please use Tucent to create an annotation at the specific location or send a mail to info@tucent.net.

2. Compatibility

The Tucent client is based on the ECMA 262 standard. This standard defines the "ECMAScript 3rd edition", which has been implemented by all major internet browsers. Due to this fact is Tucent compatible to Firefox, Internet Explorer, Safari, Google Chrome etc.
Furthermore, Tucent is very insensible in regards to exisiting JavaScript code and can be used without problems with JavaScript libraries like Prototype or script.aculo.us altogether.

3. Integration

The Tucent client can be integrated into an arbitrary HTML site via a script tag:

The script tag should be placed at the bottom of the HTML body, so rendering and usability of the site can not be affected negatively by the loading of the Tucent client. The statement defer="defer" is needed to avoid possible problems of the Internet Explorer regarding DOM manipulations.

The URL for the src attribute is made up of the following parts:

<protocol>://tucentserver.appspot.com/client/<version>/<params>

protocol	Until now only HTTP is supported. HTTPS support may be added in the near future.
version	The version of the Tucent client. Until now only version 1 is supported.
params	The URL encoded parameters (a description of the various parameters can be found in the next section).

Client Parameters

The parameters are passed as URL encoded parameters of the following form:

?param1=...&param2=...&param3=...

The complete listing of available parameters:

forum_id	The ID of the forum the client should use for its communication with the AWS. f.e. forum_id=3442
amax	(optional, default=8) A number between 1 and 50, specifying the maximum number of annotations displayed on the website. Only the amax 'hottest' annotations are shown. Older annotations can be accessed by clicking the floating button and navigating through the list of threads - older annotations can become hot again, if a new message is posted in the specific thread. f.e. amax=20
lang	(optional) A string defining the language of the client. If this parameter is not set, the language will be taken from the Accept-Language HTTP header. f.e. lang=de
approve	(optional, default=0) Specifies, if annotations are allowed inside approved parts of the document only. Specific parts od the document can be approved by giving the outmost HTML element the attribute class="tucent". f.e. approve=1
ignore_search	(optional, default=0) Specifies, if the search parameters of the URL should be ignored. In that case http://test.net/?sid=336234 and http://test.net/ are treated as the same URL. This is useful if a website passes the session via URL parameter. f.e. ignore_search=1
trackback	(optional, default=1) Defines, if the client should try to extract the trackback URL from the website's HTML. For this trackback detection to work, the website's HTML must contain trackback information in RDF format. If trackbacks are enabled in the forum settings also, a trackback notification is send back to the website if a new annotation has been created. This feature can be used to increase the comments count of a blog post. f.e. trackback=1
sensitive_tm	(optional, default=1) This parameter defines, if the textmarks on the website should be mouse-sensitive. If yes, the textmarks will react when hovered with the mouse cursor. f.e. sensitive_tm=1
fl_btn	(optional, default=1) Defines, if the floating button should be displayed in the lower right corner of the browser window. If you don't like this button, the same functionality can be triggered by any other element of your choice by calling the function "tucent.showList()" (see section 5.1). f.e. fl_btn=1
window_size	(optional, default=468,400,1) Commma seperated values defining the (initial) dimensions (width, height) of the discussion window. The last value specifies if the window should be fixed ('1') or resizeable ('0'). f.e. window_size=600,400,0
ad_height	(optional, default=60) Value defining the height of the advertisement area. You need to upgrade your forum to Tucent Revenue to see this area. f.e. ad_height=60

4. Customizing the Appearance

Until now the basic layout can't be changed and is set to a light, restrained gray. Nevertheless the appearance of Tucent can be customized to match the branding of your website. To do that you need to host the different images for floating button, icon, logo on your own webspace accessible by a URL. In the forum settings you can deposit the following URLs:

logo_icon	Logo in the frame of the Tucent window.
fl_btn	Floating button in the lower right corner of the browser window.
sel_btn	Selection button, that appears next to the cursor if the user has selected an arbitrary text passage.
comment_icon	Icon decorating comments in the Tucent window.
textmark_icon	Icon indicating comments inside the content of the website.

The following figure visualizes the different branding URLs:

Also you can set the primary color which will be used insted of the Tucent green. Note that this color needs to be specified as HTML color (f.e. "#2a3f22").

To adjust the appearance of the text passages associated with annotations you need to define the following CSS classes:

tucent_textmark	Defines the appearance of text passages associated with annotations.
tucent_textmark_highlight	Defines the appearance of text passages associated with annotations when highlit (f.e. when hovered with the mouse cursor).

So, in order to give the text passages a blue background and underline, you must add the following line to your site's CSS:

.tucent_textmark { 
	background-color:blue !important; text-decoration: underline !important; 
}

Note that the attribute "!important" is needed to overrule the default values of Tucent!

5. Triggering the Functionality

Tucent offers the possibility to control its behaviour via function calls. The individual functions are located in the namespace "tucent" and will be introduced in the following sections.

5.1 List of Comments

Normally Tucent offers a floating button in the lower right corner of the browser window. The use of this button is to show a list over all annotations/comments for the current URL. The button can be disabled with the parameter fl_btn=0 and the same functionality can be achieved by calling the following function:

tucent.showList()

Example:

<img src="foo.gif" onclick="tucent.showList()">

5.2 Refresh

If a website uses AJAX to reload content, annotations inside the loaded/changed area are not displayed automatically. In such case Tucent must be triggered to refresh all its annotations using the following function:

tucent.refresh()