Glossaire_XH - User manual

Welcome on the user manual of plugin Glossaire_XH v2 for CMSimple_XH (v1.7.x).

I - Description

Glossaire_XH can display a definition on mouse over of certain words in your articles and also in newsboxes. This definition may be titled and illustrated.

Once configuration validate one first time for the template in used, simply go to the admin and record a first word and its definition.

When reading one of your articles, if the word is present in the text, it will display the definition on mouseover, as would a tooltip.

This word appears highlighted with a dotted line (configurable)
Number of occurrences is configurable (allowing a definition of the first appearance of the word only, for example)
The aspect of the definition displayed is configurable for each template.
Work on multilingual site.
Recognition of plural (for supported languages).

The intervention on the text takes place at the level of the content variable and just before the display of the article. Word lists (one per language) and the associated definitions are stored in text format in the data folder of the plugin.

II -languages

The plugin can work in all languages supported by CMSimple_XH,

its plural detector (let the words created to be recognized when they are plural in the article) currently supports the following languages: Cs, Da, De, Fr, It, Nl, Ru, Sk.

Danish : Create the word in its indefinite form. Therefore, the plural detector will find its definite form and the plurals (definite and indefinite). Example for a car = bil, the words bilen, biler, bilerne will be also detected.

Slovak and Czech : Create the word in its nominative form (basic). The plural detector will try to find other forms and their plural.
Only the names are concerned, and all cases are not provided.

The administration is available in the following languages (default English):

French
English (personal translation, tell me the errors that may be present)
German - translation and german help file provided by Michael Zajusch
Slovak - translation provided by Tata
Czech - translation provided by Oldnema

To add a new language to this plugin, it requires two conditions :

Translate the language file.
That I add the plural recognition for the language.

If you wish to use this plugin in a language other than those already proposed, contact me. You can propose me your own translation of language file, thank you.

2.1 - Use in multilingual site

Glossaire_XH respects the philosophy of CMSimple_XH. The plugin interface appears in the language in use (according to the languages supported by the plugin, if not in English) and the words and definitions created are placed in a specific folder of the data folder of the plugin. If your site includes for example two languages, English and German, the words created in English and their definitions are therefore placed in data/en/ of plugin. For German, it will be data/de/.

III - Installation

Transfer the contents of the zip to the root of your site (same level than plugins/ folder).

Pay attention to the limitations of your host. OVH, for example, folders must have a = chmod 705 and files 604 (the most permissive for files and scripts being 755). This field must be populated with the number "705" in the case of OVH.

Check this with your FTP software (eg FileZilla).

To use the plugin, simply validate a first configuration (Configuration page) for the template used. The template.htm file of your template will be modified by adding init_Glossaire(). A copy of the original file will be performed (template.htm.bak).

According to the limitations of your host, the operation may not be possible; In this case you will be prompted to perform this add manually by editing the template.htm file of your template. Add the code bellow before the echo of content() :

<?php init_Glossaire(); ?>

For convenience of automation, the plugin add this code just after the end tag </head>.

It is possible to disable the plugin for a template (Configuration page). When active, a check box is provided for deactivation.

3.1 - Updates

Glossaire_XH is compatible with updatecheck plugin (by Holger Irmler) which allows to indicate to the webmaster if updates are available for installed plugins on the site or for the CMS itself.

IV - Configuration

This page allows you for each template to :

Disable the plugin on your site (underlined words and definitions overview).
Activate the plugin for the newsboxes.
If you want the plugin also works in the text of your newsboxes.
Configure the number of occurrences to be replaced in article.
Enter a number (eg 1 if you want only the first occurrence of the word appearing in the article is "defined"). If you want all instances be treated, enter -1 (minus sign followed by a number, no spaces) [do not put anything else in this field]
Determine the display width of the definition. For a long definition (do not forget that the definitions are added at the end of articles, in source), the default width of the display appear insufficient, the displayed frame stretching too high.

Two widths are configurable : The first "default" is the width that will be applied to all definitions displayed. 20em normally be fine but you can change this value.

Why "em" and not "px" : em is a relative unit that allows resizing text. The definition display and maintain its proportions if the visitor changes the text size displayed by the browser. The second value set at 30em default (you can change it) will be the width of only some definitions provided to check the option at the time of publishing them.
Determine the aspect of the occurrence in the article. The word will be underlined with a solid line, dashed or dotted lines that you can choose the color.
Determine the aspect of the definition displayed. An preview of the aspect of the definition allows you to view the choices made immediately.

You'll notice the option to choose a template other than the default. In this case, the page is reloaded with the selected template, allowing you to more easily compare with the definition preview of the right side form (this preview directly shows the settings in the ASPECT part of the configuration). Once the form is validated, the template is still selected and displayed unless you choose another or choose another page.

Important: As long as the configuration template has not been validated, the plugin is not working for your visitors.

Tip: Make rather short definitions, whatever the field.

V - Words and Definitions

This page allows you to manage the list of words and definitions related thereto.

5.1 - The list of words

It displays existing words, access to their editing or creation of a word and its definition, it also allows to simply delete a word and its definition.

5.1.1 - The filter

Comes in the form of an alphabetical list.
If you click on a letter of the filter, the table will be filtered according to the letter and classified in alphabetical order according to the words column.

5.1.2 - Sorting

Each column heading in the table(Id, Words) has a link sorting. You can sort the table according to the column of your choice, the title will be highlighted. (Sort alphabetically but abbreviations will be placed first). The dimensions of the table are fixed. When the number of words will be sufficient to exceed the height of the table, you will can browse the list of lines with the mouse wheel or by using the scrallbar to the right. The use of the filter so will reduce the number of rows displayed.

5.1.3 - The list

The list has one column for the id and one for the words. Simply click on a word line to access the edit page (same page than for creation). A check box located at the end of each line is used to select one or more words for delete. Then, a "Delete" button appears at the bottom of the table, with an indication of the number of selections. Delete a word causes the deletion of its definition.

5.2 - Create word and definition

At the bottom of the list, click "Create a word".

You are now on the "WORD and DEFINITION" page where you'll write the word, the title of the definition (optional)*, and the definition itself.

Regarding the title, this is the title of the definition displayed area. *To not have a title area, just leave the field blank.

An ID is displayed at the top for page. This is the number identifying the word and its definition, it is not editable.

In WORD and TITLE fields, do not put HTML code or other. Fill in the fields with your keyboard without using copy/paste for example. This is important especially for accents.

Note: The research to be carried out in the article is not "case sensitive". However, for abbreviations (eg A.B.C.D. or ABCD) and only in this case, the search will ONLY on capital (a.b.c.d. will not be found or abcd).

DEFINITION : The editor (depending on the choice made in the admin of CMSimple_XH) allows you to create the definition. You can place an image (note the definition that will be displayed is not very wide, so use a small image if it will be truncated).

The colors (titles and texts and their backgrounds), font, border colors are configurable in Aspect part of Configuration page.

Down just before the submit button, a check box allows to expand the width of displayed definition.

Another option allows you to set the comportment of displayed definition during its mouseover. If checked, the definition will stay freeze after cursor mouseover its content. A close button is added in its upper right corner (It will also close if another definition is displayed). Without this option, the definition closes as soon as the cursor is not over.
This can be useful if the text contains several links, for example.

Once the form is filled, click "Save" at the bottom.

You are now back to the list of words and appears in this one the word you just created.

5.3 - Sound and video

First, it must be borne in mind that if a word is defined in the article posted, the definition is necessarily in the flow of the page (in the end). It is of course obvious that if the word in question is flown but it is there. In case you want to insert an audio or video player, the following problems arise:

How to start playing automatically.
How to stop it when the definition closing.

The script glossary can drive a player if it can be controlled by javascript. It automatically calls two functions, one for playing when the definition appears, another stop it when the definition is closed. You will need to create a javascript file named fonct_util.js and that you put in the js folder of the plugin (plugins/glossaire/js/). It should contain the following functions must be adapted to the player used:

For playback : demLect(id)
To stop : stopLect(id)

where id is the id of the player object tag . It will add an id to your object tag player as follows: vidgpop + the id number of the word to which the definition (the id is at the top of the form creation/editing of the word) .

For example, the definition of id n°35, the id will be <object id="vidgpop35"...

5.3.1 - Concrete Example

1) Reader's Choice (or 'players')
These flash players. The advantage is that they will find server side (on your site, so) and they will be displayed on almost all configurations. It is, for video flv player :
http://flv-player.net/players/maxi/preview/ and for audio, Flash mp3 player :
http://flash-mp3-player.net/fr/players/maxi/ Both are well documented and are by the same author which is an advantage because the javascript commands are the same.
2) Installation Files
Download the players and place them in the folder userfiles/media/.
3) Create the file fonct_util.js
You can use an editor for this but a simple text file created using Windows Notepad enough.
Right click, new, text document, open it and copy/paste the following code:
```
function demLect(id){
var elt= document.getElementById(id);
if (elt != null) elt.SetVariable("player:jsPlay", "");
}
function stopLect(id){
var elt= document.getElementById(id);
if (elt != null) elt.SetVariable("player:jsStop", "");
}
```
Save the file and rename it fonct_util.js
Finally, load it in the js folder of Glossaire_XH (in plugins/glossaire/js/)

The script of the glossary will be responsible for recognizing the presence of the file and use the functions demLect and stopLect when the time comes.
4) Insert the video player in a definition.
For example, a word whose id is 43 (this id appears in the list of words). A video file .flv will be included in its definition. The video file is named video.flv (in this example), place it in the folder userfiles/media/. To create flv files, there are free converters. Here is an example:

Free FLV Converter on http://www.koyotesoft.com/

Code inserted in the definition, id vidgpop43 is added :
```
<object id="vidgpop43" type="application/x-shockwave-flash" data="userfiles/media/player_flv_maxi.swf" width="320" height="240">
 <param name="movie" value="userfiles/media/player_flv_maxi.swf" />
 <param name="FlashVars" value="flv=video.flv" />
 </object> 
```
Paths can be relative to the root of the site, as above. The path of the flv file, meanwhile, is relative to the location of the player.

In the case of a multilingual site: When it is not the primary language of the site, add ../ before userfiles/ like this:
```
"../userfiles/media/player_flv_maxi.swf"
```
Important reminder : For inclusion in a definition must be added to the object tag an id equal to the id of the word in question (here vidgpop43). This is the id that will be targeted by demLect and stopLect functions.
5) Insert the mp3 player
Place the mp3 file into the folder userfiles/media/ (and the reader if it is not already). Same method as for the video file, sample code inserted in the definition of the word with id 45 (mp3 file of the example is called eagles.mp3) and where the id given to the object tag becomes vidgpop45:
```
<object id="vidgpop45" type="application/x-shockwave-flash" data="userfiles/media/player_mp3_maxi.swf" width="200" height="20">
 <param name="movie" value="userfiles/media/player_mp3_maxi.swf" />
 <param name="FlashVars" value="mp3=eagles.mp3" />
 </object>
```
Finally, the option to can freeze a definition can be checked (at the bottom of the create/edit page of a word) for the insertion of an audio/video player. The close button which then appears at the top right of the definition, also will stop the playback.

VI - Printing

When printing an article, every word remains highlighted and defined with a link to its definition placed at end of article (underline does not necessarily appear in the preview used depending on the css of template). The definitions thus accumulated are preceded by a title "Glossary". If printing is done to a pdf, the links remain active and link to each relevant definition (anchor).

Note : An article also includes its glossary of defined words when printing. The number of printed pages will depend on the length of the article but also that of its definitions. The advantage of using short definitions takes on its meaning.

The definitions are nevertheless displayed in two columns and a smaller font size.

VII - Uninstall

On Configuration page, disable the plugin for each template in the list.

This means delete init_Glossaire() in the template.htm file of each template.

Then delete all the plugin files, this means removing the "glossaire" folder: plugins/glossaire/