From b4c0509f7794408e16985bad70c937611cc41743 Mon Sep 17 00:00:00 2001
From: hallgren <hallgren@chalmers.se>
Date: Tue, 9 Aug 2011 15:57:40 +0000
Subject: [PATCH] minibar: more documentation (in minibar-api.html)

---
 .../javascript/minibar/minibar-api.html       | 230 ++++++++++++++++++
 1 file changed, 230 insertions(+)
 create mode 100644 src/runtime/javascript/minibar/minibar-api.html
diff --git a/src/runtime/javascript/minibar/minibar-api.html b/src/runtime/javascript/minibar/minibar-api.html
new file mode 100644
index 000000000..758080815
--- /dev/null
+++ b/src/runtime/javascript/minibar/minibar-api.html
@@ -0,0 +1,230 @@
+<!DOCTYPE html>
+<html>
+<head>
+<title>GF web services API examples</title>
+<meta charset="UTF-8">
+
+<style type="text/css">
+body { background: #eee; }
+h1, h2, h3, small, th { font-family: sans-serif; }
+th { text-align: left; }
+h1,h2 { border-bottom: 2px solid black }
+dt { background: #cef; }
+code { background: #ffc; }
+dt.js { background: white; margin-bottom: 1ex; }
+dt.js em { color: #36f; }
+dd { background: #ffc; margin-top: 1ex; margin-bottom: 1ex; }
+
+dl.apiexamples>dt, dl.apiexamples>dd { font-family: monospace; }
+dl.apiexamples>dd {  white-space: pre; }
+
+table.border { border-collapse: collapse; margin-top: 1ex; margin-bottom: 1ex; }
+table.border td, table.border th { border: 1px solid black; background: #fcfcfc; }
+
+div.modtime { float: right; }
+.modtime { color: #666; white-space: nowrap; }
+
+</style>
+
+<body>
+<h1>Minibar API</h1>
+
+The minibar is structured as three object:
+
+<ul>
+  <li><a href="#Minibar">Minibar</a>
+  <li><a href="#Input">Input</a>
+  <li><a href="#Translations">Translations</a>
+</ul>
+
+They are described below.
+
+<h2 id=Minibar>The Minibar object</h2>
+
+<p>
+This is the complete Minibar web app. It is defined in
+<a href="minibar.js">minibar.js</a>. It also uses the <code>Input</code>
+and <code>Translations</code> objects, and some auxiliary functions defined
+in <a href="minibar_support.js">minibar_support.js</a>
+and <a href="support.js">support.js</a>, so to use it in an
+HTML file, you would normally include at least the following:
+
+<blockquote><pre>
+&lt;script type="text/JavaScript" src="minibar.js">&lt;/script>
+&lt;script type="text/JavaScript" src="minibar_input.js">&lt;/script>
+&lt;script type="text/JavaScript" src="minibar_translations.js">&lt;/script>
+&lt;script type="text/JavaScript" src="minibar_support.js">&lt;/script>
+&lt;script type="text/JavaScript" src="support.js">&lt;/script>
+</pre></blockquote>
+
+<p>
+For an example, see <a href="minibar.html">minibar.html</a>.
+
+<h3>Constructor</h3>
+
+<code>var minibar=new Minibar(server,options,target)</code>
+
+<ul>
+  <li><code>server</code> is the PGF service object.
+  <li><code>options</code> is an object where the following properties
+  can be set to override various default options:
+    <table class=border>
+        <tr><th>Option<th>Default<th>Description
+        <tr><td>show_abstract<td>false<td rowspan=3>See Translations,
+	  not used directly by Minibar
+	<tr><td>show_trees<td>false
+	<tr><td>show_grouped_translations<td>true
+	<tr><td>delete_button_text<td>"⌫"<td rowspan=3>See Input,
+	  not used directly by Minibar
+	<tr><td>default_source_language<td>null
+	<tr><td>random_button<td>true
+	<tr><td>try_google<td>true<td>Include a button to try the current
+	  sentence in Google Translate
+	<tr><td>feedback_url<td>null<td>Include a button to open a feedback
+	  form. The HTTP server must be configured to handle form submissions
+	  for this to work.
+	<tr><td>help_url<td>null<td>Include a button to open a help text.
+    </table>
+  <li><code>target</code> is the <code>id</code> of the HTML element inside
+    which the minibar user interface is created. It can be omitted if
+    the <code>id</code> is <code>minibar</code>. The HTML document should
+    contain something like this:
+    <blockquote><code>&lt;div id="minibar">&lt;/div></code></blockquote>
+</ul>
+
+<h3>Methods</h3>
+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.
+
+<h2 id=Input>The Input object</h2>
+
+This object handles user input. Text can be entered by typing or by clicking
+on the "refrigerator magnets".
+<p>
+It is defined in
+<a href="minibar_input.js">minibar_input.js</a>.
+It also uses some auxiliary functions defined
+in <a href="minibar_support.js">minibar_support.js</a>
+and <a href="support.js">support.js</a>, so to use it in an
+HTML file, you would normally include at least the following:
+
+<blockquote><pre>
+&lt;script type="text/JavaScript" src="minibar_input.js">&lt;/script>
+&lt;script type="text/JavaScript" src="minibar_support.js">&lt;/script>
+&lt;script type="text/JavaScript" src="support.js">&lt;/script>
+</pre></blockquote>
+
+<h3>Constructor</h3>
+
+<code>var input=new Input(server,options,translations)</code>
+
+<ul>
+  <li><code>server</code> is the PGF service object
+  <li><code>options</code> is an object where the following properties
+  can be set to override various default options:
+      <table class=border>
+        <tr><th>Option<th>Default<th>Description
+	<tr><td>delete_button_text<td>"⌫"<td>the label for the button that deletes the last word
+	<tr><td>default_source_language<td>null<td>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.
+	<tr><td>random_button<td>true<td>include a button to generate a
+	  random sentence
+    </table>
+
+  <li><code>translations</code> is the object that is notified when the input
+  has changed. In the minibar, this is the object that display translations.
+  The following methods will be called:
+  <ul>
+    <li><code>translations.clear()</code>
+    <li><code>translations.translateFrom({from:<var>conc</var>,input:<var>string</code>})</code>
+  </ul>
+</ul>
+
+<h3>Properties and user interface</h3>
+
+The <code>input</code> object created by the <code>Input</code>constructor
+contains two field that the caller should add to the user interface:
+<ul>
+  <li><code>input.main</code> is the main user interface where the current
+  input and the refrigerator magnets are displayed.
+  <li><code>input.menus</code> contains the menu for selecting input language,
+  and buttons for deleting the last word, clearing the input and generating
+  a random sentence (if enabled in the options)
+</ul>
+
+<h3>Methods</h3>
+
+<ul>
+  <li><code>input.change_grammar(grammar_info)</code> should be called
+  after a different grammar is selected in the <code>server</code> object. It
+  will clear away old input and magnets, and update the input language menu
+  with the languages available in the new grammar.
+
+</ul>
+
+<h2 id=Translations>The Translations object</h2>
+
+This object display translations. It is defined in
+<a href="minibar_translations.js">minibar_translations.js</a>.
+It also uses some auxiliary functions defined
+in <a href="minibar_support.js">minibar_support.js</a>
+and <a href="support.js">support.js</a>, so to use it in an
+HTML file, you would normally include at least the following:
+
+<blockquote><pre>
+&lt;script type="text/JavaScript" src="minibar_input.js">&lt;/script>
+&lt;script type="text/JavaScript" src="minibar_support.js">&lt;/script>
+&lt;script type="text/JavaScript" src="support.js">&lt;/script>
+</pre></blockquote>
+
+<h3>Constructor</h3>
+<code>var translations=new Translations(server,options)</code>
+<ul>
+  <li><code>server</code> is the PGF service object.
+  <li><p><code>options</code> is an object where the following properties
+  can be set to override various default options:
+      <table class=border>
+        <tr><th>Option<th>Default<th>Description
+        <tr><td>show_abstract<td>false<td>show the abstract syntax in addition
+	  to the concrete syntax for the translations
+	<tr><td>show_trees<td>false<td>add buttons to display syntax trees
+	  next to translations.
+	<tr><td>show_grouped_translations<td>true<td>in case there are
+	  multiple translations, group them by concrete language
+    </table>
+
+</ul>
+
+<h3>Properties and user interface</h3>
+
+
+The <code>translations</code> object created by the
+<code>Translations</code> constructor contains two field that the caller
+should add to the user interface:
+<ul>
+  <li><code>input.main</code> is the main user interface where the current
+  translations are displayed.
+  <li><code>input.menus</code> contains the menu for selecting target language.
+</ul>
+
+<h3>Methods</h3>
+<ul>
+  <li><code>translations.change_grammar(grammar_info)</code> should be called
+  after a different grammar is selected in the <code>server</code> object. It
+  will clear away old translations and update the target language menu
+  with the languages available in the new grammar.
+</ul>
+
+
+<hr>
+<div class=modtime>
+<small class=modtime>
+HTML <!-- hhmts start --> Last modified: Tue Aug  9 17:55:19 CEST 2011 <!-- hhmts end -->
+</small>
+</div>
+
+<address>
+<a href="Http://www.cse.chalmers.se/~hallgren/">TH</a>
+</address>

Option	Default	Description +
show_abstract	false	See Translations, + not used directly by Minibar +
show_trees	false +
show_grouped_translations	true +
delete_button_text	"⌫"	See Input, + not used directly by Minibar +
default_source_language	null +
random_button	true +
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. +
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. +
random_button	true	include a button to generate a + random sentence +
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. +
show_grouped_translations	true	in case there are + multiple translations, group them by concrete language +