This manual was created to provide information and working instructions about Business Dictionary (BuDict), in Confluence, to end users and administrators. This document describes BuDict's options and functions.

3. Basic information

In Confluence, BuDict displays an information bubble above highlighted words. The information bubble contains an explanation, or other specified text, relevant to the highlighted word. The information bubble is displayed only when the mouse cursor is hovered over the word, as shown in the picture below.

Picture: Demo

A separate page is created for every highlighted word or sentence. The page name is given after the word or sentence in the information bubble. If the word appears more than once, every occurrence is highlighted and referenced to the same page, as shown above.

There is an IT demo dictionary supplied with BuDict. This demo dictionary is created during the process of BuDict space creation, see chapter Creating of BuDict space and needed pages.

4. Licensing

4.1. Trial version

From version 2.0.0, users are able to access a fully functional version of BuDict for a limited trial period. The trial period is 1 month from installation. The current version and expiration date is shown in the information bubble. See the picture below. After expiration of the trial period, functions of BuDict will be inaccessible and the information bubble will show a message with a link to the Atlassian marketplace where licenses can be bought or downloaded. A trial license can also be purchased via Confluence's standard Plugin manager.

Picture: Trial version

4.2. Licensed version

A unique license key can be purchased and generated through Altlassian marketplace. A licensed version will be activated after entering the requested license key, see chapter License activation. The license is always active for one year from the date of purchase (it will be sent to the customer via e-mail). Once the license expires the license period must be extended, otherwise functions within BuDict will cease to work. Licenses can also be bought via Confluence's standard Plugin manager.

Expired license:

Picture: Expired license

5. Installation

Initial installation and setup of BuDict is required.

5.1. Installation BuDict-x.x.x.jar

Installation is executed in Confluence administration by Confluence Admin > Add-ons > Manage add-ons > Upload add-on. Package BuDict-x.x.x.jar will be installed.

5.2. Functions' description

Name	Description
Plugin administration	Allows setting of user roles and administration of single sections of the plugin.
Styles & behaviour	This section allows users to set the look and behaviour of the BuDict bubbles for selected spaces.
License administration (obsolete)	Generation of trial license or purchasing of new license and entering of license (obsolete).
Create BuDict space and demo phrases	Creates BuDict space and updates to included dictionary.
Dictionary management	Allows user to manage dictionaries and add/delete/edit phrases.
Markup rules management	Allows user to define rules for marking.
Import dictionary from XLS/CSV	Imports dictionaries from CSV, XLS files through a prepared template.
Export dictionary from XLS/CSV	Exports dictionaries to CSV, XLS files.
Export dictionary to XML	Exports dictionaries to XML file.

5.3. User roles

Since version 4.0, access permissions has to be set via Budict control / Plugin administration (see next chapter) for individual users or groups:

Source	Role	Description
Confluence	Confluence administrator	The highest permission level. Can administrate the whole Confluence and set the initial permission settings for spaces and plugins, too.
Confluence	Space administrator	Can set the basic access permissions (vie / edit pages, etc.) for the proper space.
Budict	Plugin administration	Has all Budict Control sections available. Can also set plugin administration permissions within the Budict itself and other settings (e.g. Styles & Behavior of information bubbles).
Budict	Dictionary administration	Has access to the Budict control / Dictionaries management section only. Maintains dictionaries (add / edit / remove dictionaries and / or phrases depending on corresponding space permissions) and can import / export dictionaries and add phrases directly from page's Tools menu (see below) too.
Budict	Markup rules administration	Has access to the Budict control / Markup rules management section only. Defines and enables / disables the markup rules (which dictionaries on which space / pages apply).
Budict	Add phrase from pages	Can add Budict phrases directly from page's Tools menu (depending on corresponding space permissions).

5.4. Plugin administration (permission settings)

The Confluence administrator is to set the initial roles and permissions to allow users to access the different sections of BuDict. Additional permissions can be set by the user with the role Plugin administrator.

Permission settings of user roles can be set from Tools > BuDict Control > Plugin administration. User roles can be set in two ways:

List of groups (comma separated).
List of users (comma separated).

Picture: Plugin administration

5.5. Creating of BuDict space and needed pages

Creating BuDict space is essential for the successful running of BuDict. This can be carried out from Tools > BuDict Control > Create BuDict space and demo phrases.

Only User with BuDict space permission can update BuDict Space.

The following protocol is shown after BuDict space creation.

Picture: Plugin administration

5.5.1. BuDict Control

The picture below shows the BuDict Control menu designed to work with BuDict. The user can access this menu through Tools > BuDict Control, see picture below.

Picture: Menu BuDict Control for managing BuDict functions

Picture: Access to the BuDict Control menu is provided through menu Tools.

5.6. License activation

As previously mentioned, the License key is valid for one year. It is therefore necessary to extend the license after the license expiration (ie. purchase the license for the next period). Activation of the license is carried out via Confluence's standard Plugin Manager ~~BuDict Control > License Administration~~. ~~The following window is shown~~.

Picture: License activation (obsolete)

After entering the valid license key, complete information for the lincense is shown

Picture: License activated (obsolete)

5.7. Language localization

The plugin is available in Czech and English language.

To utilise the Czech language the Czech language pack must be installed (by the Confluence administrator).

After installation of the language pack, each user can set their own personal preferred language through: User >Settings > Language.

Picture: User language selection

If Czech language is set all product communication will be in the Czech language, else it will be in English.

6. Working with BuDict

This section is devoted to working with BuDict, setting of marking and linking of selected pages.

6.1. Space restrictions in reference to BuDict

When working with BuDict, the access rights space permissions are respected. The settings of space permissions restrict working with BuDict as follows.

Picture: Dictionaries management

Dictionary administration:

restriction
View	Dictionaries in this space will be shown in the menu.	Dictionaries in this space will NOT be shown in the menu.
Add (pages)	User can add/edit phrases in dictionary.	User can list the dictionary, but cannot add/ edit phrases.
Remove (pages)	User can remove phrases from dictionary and remove prefix dictionaries in current space.	User cannot remove phrases from dictionary or prefix dictionaries in current space.
Admin (space)	User can remove space dictionary.	User cannot remove space dictionary.

Marking administration:

restriction
View	Dictionaries in this space will be shown in the menu.	Dictionaries in this space will NOT be shown in the menu.

Standard Confluence permission dependency

Every prefix dictionary is placed in the BuDict space. User must have the proper space permissions (view space, add pages) to work with the prefix dictionary.

If not, please contact your Confluence administrator!

6.2. Types of dictionaries

There can be more than one dictionary used and two basic methods for working with them: Dictionaries as separate spaces or dictionaries in one space with different prefixes. It is possible to combine both methods.

	Spaces	Prefixes
	Increases the number of spaces within Confluence	Every word must have it's written prefix to be recognised
	Dictionaries are clearly separated	Everything is together in one space

6.2.1. Spaces

This variant uses a single space for every dictionary.

6.2.2. Prefixes

In this variant all dictionaries are in space BuDict. Dictionaries are sorted by prefixes in the page name. The prefix is in the dictionary name and is split by an exclamation mark '!'.

Example:

for the keyword contract, in the dictionary Business, the page name will exist as Business!contract.

It can be specified in BuDict which prefix (dictionary) should be used.

6.3. Dictionaries managing

Each dictionary and its keywords can be managed by the Dictionaries manager. Dictionary manager is found here: BuDict Control > Dictionaries management

Dictionaries can be managed only by users that are predefined in section Plugin administration. These users can manage only the permitted dictionaries in reference to standard space restrictions.

Picture: Dictionaries management

Dictionaries list - Enables selection of an existing dictionary from the list box. (After this choice dictionary detail is loaded.)

Create New dictionary - displays a dialogue window for new dictionary creation
Delete - removes selected dictionary after deletion is confirmed

User can create a new dictionary.

Dictionary detail - When a dictionary is chosen, a list of keywords will be displayed. The user can add a keyword or alternatively edit or delete the selected keyword.

Add phrase - opens a dialog box for keyword definition
Edit - opens a dialog window where a user can edit keyword meanings and synonyms
Delete - after confirmation the selected keyword will be deleted

If you do not have proper Confluence / space permissions (delete pages), you can not delete phrases or any prefix dictionaries.

Listing of phrases in dictionary

Since version 4.0, a navigation toolbar has been added to Dictionaries management. The user can easily move between dictionary phrases. The toolbar is located under the list of phrases. See picture below.

Obrázek: Listing of phrases in dictionary

First - Move to the first page of the list.

Prev - Move to the previous page of the list.

Next - Move to the next page of the list.

Last - Move to the last page of the list.

Page size - User can select the number of phrases for a page (10,15,20,30,40,50,100).

Go - Enter the page number in the edit box beside the Go button and click on Go to move to the selected page (Number must be inserted).

6.3.1. Add new dictionary

A new dictionary can be created through BuDict control > Dictionaries management > Add new dictionary. The following dialogue window is shown.

Picture: Add new dictionary

User must insert the name of the dictionary and choose the dictionary type:

as prefix
as space

Creation is confirmed by the button Create.

6.3.2. Add phrase / Edit

6.3.2.1. Via BuDict control / Dictionaries management

Click Edit or Add phrase and the following form will display:

Picture: Adding /editing of phrases (before checking)

Picture: Adding /editing of phrases (after checking)

Dictionary - Name of the dictionary where the keyword will be added/edited (this is selected before adding a new keyword and cannot be changed in the dialog).

Phrase - Name of the keyword.

Check phrase - When adding a new keyword, a user should check whether the keyword is not already present in the dictionary. If so, the user will be diverted to edit mode. Note that if a word is edited, its name cannot be changed. If a name change is required, a new keyword must be created and the existed one deleted.

Synonyms - List of synonyms separated by a comma.

Description - Description of the keyword.

6.3.2.2. Via page menu

New phrases can be also created from the page menu Tools (or from menu Add - before Confluence 5) > BuDict add phrase.

BuDict add phrase is visible only for users defined in the section Plugin administration > Add phrase from pages. User can add/edit phrases only in permitted dictionaries (with reference to space restrictions).

Picture: Adding /editing of phrases from Confluence pages

The same form, as in the Dictionaries management, will display.

6.4. Marking manager

Here a permitted user can define the rules for marking. It is accessible from BuDict Control > Markup rules management. Since version 4.0, marking is an automatic process. User only needs to define the marking rules to set whether pages will/will not be marked.

Only permitted users can manage the marking rules. This user has to be set in BuDict Control > Plugin administration > Dictionary administration. User can work only with permitted dictionaries in reference to space restrictions.

Picture: Managing of marking rules

6.4.1. Working with marking manager

There are two kinds of marking rules

Inclusion rules - these pages will be marked
Exclusion rules - these pages will not be marked

If there are pages defined in both rules (Inclusion and Exclusion) then these pages will not be marked. Exclusion rules have higher priority.

Configuration buttons:

Add - create a new marking rule
Edit - edit existing marking rule
Delete - delete selected marking rule
Enable/Disable - enable/disable particular rule

6.4.1.1. Defining/editing Inclusion rule

After clicking on the Add or Edit button the following dialog box appears.

Picture: Add/edit inclusion marking rules

All spaces - if selected, markup all spaces

Spaces - space name(s), where the rule is to be applied (not available if All spaces selected).

Pages - page name, where the rule is to be applied (not available if All spaces selected) or page names (comma separated). If left empty, the whole space will be marked/unmarked.

Include subpages - specifies whether subpages will be marked/unmarked (only when the page name is selected).

Dictionaries - the list of dictionaries that will be applied (comma separated).

Since version 3.0.0, BuDict has an interactive whisper. When the user begins to write a drop-down menu will appear.

6.4.1.2. Defining/editing Exclusion rule

Pages using the Exclusion rule will never be marked.

After clicking on the Add or Edit button the following dialog box appears.

Picture: Add/edit exclusion marking rules

Spaces - space name(s), where the rule is to be applied.

Pages - page name, where the rule is to be applied or page names (comma separated). If empty, the whole space will be marked/unmarked.

Include subpages - specifies whether subpages will be marked/unmarked (Only when the page name is selected).

Since version 3.0.0, BuDict has an interactive whisper. When the user begins to write a drop-down menu will appear.

6.4.2. Styles and behaviour management

It is possible to customise the look and the behaviour of the information bubble & link. This capability is found in BuDict control > Styles & behaviour. The default bubble style, and specific space styles, can be defined together with bubble & link appearance behaviour. Note, from version 4.0.19 the bubble can be shown only when ctrl is pressed (optional), from version 4.1 hyperlink navigation to phrase's page in dictionary can be disabled.

Lorem ipsum example for every created bubble style definition is previewed.

Only the user defined in BuDict control > Plugin administration > Plugin administration can administer the information bubble styles.

Picture: Styles & behaviour management

Configuration buttons:

Add - create a new bubble style
Edit - edit existing bubble style
Delete - delete selected bubble style

6.4.2.1. Add/edit bubble style

A new style can be created through BuDict control > Styles & Behavior > Add/Edit. Style definition is made through CSS style sheets. Standard bubble settings will be inserted when creating a new style.
There is an example of the current bubble style in the lower part of the window.

Picture: Add/edit bubble styles

Apply to

Spaces (empty for default style) - The list of spaces (comma separated) for a selected style.

Style

Style of link that shows bubbles (css) - Set how the appearance highlighting.
Width of bubble (px) - Set the bubble width.
Style of bubble header (css) - Set the bubble header.
Style of bubble body (css) - Set the body of text.
URL of image shown in header (absolute url) - URL of the icon in the upper left corner of the bubble.
Whole bubble style (css) - Set the color style of the whole bubble.
Style of bubble tail (css) - Set the bubble tail.

Behaviour

Show bubble only when ctrl is pressed (from version 4.0.19, not in image) - otherwise bubble is directly displayed.
Navigate to dictionary through hyperlink (from version 4.0.22) - otherwise stay in present page (navigate to the top of the page).
Whitelist of html tags to markup in (comma separated, e.g. "p,td,th"). If empty, then all are markups (from version 4.1) - Setting of content that is to be marked.

After clicking the Create button the following window is displayed.

Picture: Confirmation of style saving

7. Import/Export

7.1. Import/Export from/to CSV/XLS

Dictionaries can be imported from an external file. The file must have a defined structure for the functionality to work correctly. An exported dictionary will have this same structure. Export and import can be also combined to transfer a dictionary to another instance of Confluence.

7.1.1. Templates for a dictionary

7.1.1.1. MS EXCEL

Data entry is very simple and intuitive.

Firstly, a dictionary name should be specified by filling in the following cells.

Dictionary name - e.g. DENTIST
Sphere of action - e.g. HEALTHCARE
Language - e.g. EN

_

These fields combine to create the page name of the dictionary after import, e.g. DENTIST_HEALTHCARE_CZ.

Proper naming of the dictionaries makes usage and selection much simpler.

A list of keywords is to follow. It is possible to enter synonyms as singular or plural for every keyword.

Picture: Template for XLS import/export

This template can be downloaded at www.budict.com.

Import/export functionality works only with the file extension *.xls. Files with extension *.xlsx (format used by Excel 2007) cannot be imported. If a user uses Excel 2007, the SAVE AS function in MS EXCEL should be used to save in the correct format (Excel 97-2003) with the extension XLS.

7.1.1.2. CSV

A CSV file can be created from an XLS template in MS EXCEL > Save as (CSV file) or it can be downloaded from the website www.budict.com.

Picture: Template for CSV import/export

7.1.2. Import dictionary from CSV/XLS

Use this function to import dictionaries from XLS or CSV file. Each keyword contained in the source file is imported to the target dictionary. Import is executed from Tools > BuDict Control > Import dictionary from {*}CSV/XLS.*

Attachments are not imported with this function.

Each keyword which is imported as keyword of new prefix dictionary will be added below new parent page with defalt title like "title_sphere_language".

New keyword added to imported prefix dictionary via Add phrase feature wil be aded on the same level as parent page.

Picture: Import from CSV/XLS

To complete the import, a user must fill in the required information:

choose a source CSV or XLS file (more than one source file can be selected)
specify the target dictionary by either:
- selecting an existing dictionary from the drop down menu (keywords will then be added to an existing space or have a prefix added to them)
- creating a new dictionary by entering a new prefix

The following message will be shown after a successful import.

Picture: Import from CSV/XLS

7.1.3. Export dictionary to CSV/XLS

This function exports selected dictionaries to a CSV/XLS file. A user selects the dictionary to be exported and the file format needed. Files can be received in CSV or XLS format by clicking on the appropriate button. Export is executed from BuDict Control *> Export dictionary to CSV/XLS. *Exported files follow the described templates, see chapter #Templates for a dictionary.

Picture: Export to CSV/XLS

It is necessary to use code page 1250 for countries from East and Central Europe. This code page represents languages that use Latin script, such as Polish, Czech, Slovak, Hungarian, Slovene, Bosnian, Croatian, Serbian, Romanian and Albanian. It may also be used with the German language.

7.2. Export dictionary to XML

Dictionaries can also be exported to XML. XML export is executed from BuDict Control > Export dictionary to XML. Multiple dictionaries can be selected at once.

If multiple dictionaries are selected all dictionaries will be exported to one single XML file.

Picture: Export to XML

Structure of XML

8. Other useful functionality

8.1. List of dictionaries

A list of dictionaries, including their content or keywords, can be written out by macro BuDictDir. BuDictDir macro uses the parameter dictionaries. This parameter determines which dictionary is shown. Multiple dictionaries can be selected at once (comma separated).

If user does not have the permission, for a particular dictionary, it will not be shown in the list.

Syntax:

Example:

Picture: BuDictDir - list of dictionaries.

8.2. Space label settings

Space label settings are made from the main screen Dashboard by clicking on the Browse Space icon of the corresponding space (see the left portion of the below picture). In the next step choose Advanced > Space Labels (see the right portion of the below picture, marked by a red arrow). The user can add or modify a space label after clicking on Edit.

Picture: Space label

9. Troubleshooting

9.1. Information bubble

Problem

HTML code is displayed in the information bubble in place of normal text.

Solution

The file budictbox.js is needed to correctly display text and pictures within the information bubble. Typically this file is automatically copied to the destination folder when a user runs Create, however if this does not happen, it can be copied manually from the package budict-0.jar to the folder confluence/includes/js/.

10. Known bugs

Bug	Fix in Version
XLS/CSV Export can only be applied to prefix dictionaries	4.01

Labels

None
Edit Labels

BUDICT (Business Dictionary) plugin documentation

1. Table of Content

2. Purpose of this manual