# Minibar API

The Minibar web app consists of the following objects:

- Minibar
- Input
- Translations

They are described below.

## The Minibar object

This object implements the complete Minibar web app. It is defined in minibar.js. It also uses the `Input` and `Translations` objects described below, and some auxiliary functions defined in minibar_support.js and support.js, so to use it in an HTML file, you would normally include at least the following:

>     <script type="text/JavaScript" src="minibar.js"></script>
>     <script type="text/JavaScript" src="minibar_input.js"></script>
>     <script type="text/JavaScript" src="minibar_translations.js"></script>
>     <script type="text/JavaScript" src="minibar_support.js"></script>
>     <script type="text/JavaScript" src="support.js"></script>

For an example, see minibar.html.

### Constructor

`var minibar=new Minibar(server,options,target)`

- `server` is the PGF service object.
- `options` is an object where the following properties can be set to override various default options:

  Option | Default | Description
  --- | --- | ---
  show_abstract | false | See Translations, not used directly by Minibar
  show_trees | false
  tree_img_format | "png"
  show_grouped_translations | true
  show_brackets | false
  delete_button_text | "⌫" | See Input, not used directly by Minibar
  default_source_language | null
  startcat_menu | true
  random_button | true
  word_replacements | false
  try_google | true | Include a button to try the current sentence in Google Translate
  feedback_url | null | Include a button to open a feedback form. The HTTP server must be configured to handle form submissions for this to work.
  help_url | null | Include a button to open a help text.

- `target` is the `id` of the HTML element inside which the minibar user interface is created. It can be omitted if the `id` is `minibar`. The HTML document should contain something like this:

  > `<div id="minibar"></div>`

### Methods

There are several internal methods, but since this is a self-contained web app, there is usually no need to call any methods from outside.

## The Input object

This object handles user input. Text can be entered by typing or by clicking on the "refrigerator magnets".

It is defined in minibar_input.js. It also uses some auxiliary functions defined in minibar_support.js and support.js, so to use it in an HTML file, you would normally include at least the following:

>     <script type="text/JavaScript" src="minibar_input.js"></script>
>     <script type="text/JavaScript" src="minibar_support.js"></script>
>     <script type="text/JavaScript" src="support.js"></script>

### Constructor

`var input=new Input(server,translations,options)`

- `server` is the PGF service object
- `options` is an object where the following properties can be set to override various default options:

  Option | Default | Description
  --- | --- | ---
  delete_button_text | "⌫" | The label for the button that deletes the last word.
  default_source_language | null | The concrete language to use for input in case the user's browers doesn't supply a suitable default. If none is provided the first language in alphabetical order will be used.
  startcat_menu | true | Include a menu to choose which start category to use for parsing (instead of the grammar's default start category).
  random_button | true | Include a button to generate a random sentence.
  word_replacements | false | Enable word-for-word replacements. (This is an experimental feature.)

- `translations` is the object that is notified when the input has changed. In the minibar, this is the object that display translations, but other apps might of course use the entered text for other purposes. The following methods will be called:
  - `translations.clear()` is called when there is no entered text.
  - `translations.translateFrom({from:conc,input:string})` is called when the user has entered some text. The `from` property is the name of the concrete syntax and the `input` property is the entered text.

### Properties and user interface

The `input` object created by the `Input` constructor contains the following fields that the caller should add to the user interface:

- `input.main` is the main user interface where the current input and the refrigerator magnets are displayed.
- `input.menus` contains the menu for selecting input language.
- `input.buttons` contains buttons for deleting the last word, clearing the input and generating a random sentence (if enabled in the options).

### Methods

- `input.change_grammar(grammar_info)` should be called after a different grammar is selected in the `server` object. It will clear away old input and magnets, and update the input language menu with the languages available in the new grammar.

## The Translations object

This object displays translations. It is defined in minibar_translations.js. It also uses some auxiliary functions defined in minibar_support.js and support.js, so to use it in an HTML file, you would normally include at least the following:

>     <script type="text/JavaScript" src="minibar_translations.js"></script>
>     <script type="text/JavaScript" src="minibar_support.js"></script>
>     <script type="text/JavaScript" src="support.js"></script>

### Constructor

`var translations=new Translations(server,options)`

- `server` is the PGF service object.

- `options` is an object where the following properties can be set to override various default options:

  Option | Default | Description
  --- | --- | ---
  show_abstract | false | show the abstract syntax in addition to the concrete syntax for the translations
  show_trees | false | add buttons to display syntax trees next to translations.
  tree_img_format | "png" | format for trees & alignment images, can be "gif", "png" or "svg"
  show_grouped_translations | true | in case there are multiple translations, group them by concrete language
  show_brackets | false | show bracketed string

### Properties and user interface

The `translations` object created by the `Translations` constructor contains the following fields that the caller should add to the user interface:

- `translations.main` is the main user interface where the current translations are displayed.
- `translations.menus` contains the menu for selecting a target language. The user can select All or one particular language.

### Methods

- `translations.change_grammar(grammar_info)` should be called after a different grammar is selected in the `server` object. It will clear away old translations and update the target language menu with the languages available in the new grammar.
- `translations.clear()` clears the main output area from old translations.
- `translations.translateFrom({from:conc,input:string})` displays translations of the text given in the `input` property (as an array of words) from the concrete syntax indicated by the `from`.

HTML Last modified: Mon Sep 17 17:52:22 CEST 2012