Part of MKWS-322. Change all references from mkws-widget-termlists.js to mkws-widget...

[mkws-moved-to-github.git] / doc / mkws-manual.markdown

diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown
index 5e7b617..7c0dd06 100644 (file)
--- a/doc/mkws-manual.markdown
+++ b/doc/mkws-manual.markdown
@@ -150,7 +150,8 @@ To see all of these working together, just put them all into the HTML
        <div class="mkws-stat"></div>
 
 The full set of supported widgets is described in the
-reference guide below.
+reference guide
+[below](#widgets).
 
 Widget team
 -----------
@@ -646,23 +647,57 @@ added: see the [MKWS developers' guide](mkws-developer.html).)
 ----
 Name              Description
 ----              -----------
-`auth-name`       x
-
-`builder`         x
-
-`button`          x
-
-`categories`      x
-
-`config`          x
-
-`console-builder` x
-
-`cover-art`       x
-
-`details`         x
-
-`done`            x
+`auth-name`       Initially empty, it updates itself to shows the name
+                  of the library that the application is logged in as
+                  when authentication is complete.
+
+`builder`         A button which, when pressed, analyses the current
+                  settings of the team that it is a part of, and
+                  generates the HTML for an auto-searching element
+                  that will replicate the present search. This HTML is
+                  displayed in an alert box: it is intended that this
+                  widget be subclassed to store the generated widget
+                  definitions in more useful places.
+
+`categories`      Obtains from the Service Proxy a list of the target
+                  categories associated with the library in use, and
+                  displays them in a drop-down list. When a category
+                  is selected, searches are limited to the targets
+                  that are part of that category.
+
+`config`          This widget has no functionality of its own, but its
+                  configuration is copied up into its team, allowing
+                  it to affect other widgets in the team. This is the
+                  only way to set configuration items at the team
+                  level.
+
+`console-builder` Like the `builder` widget, but emits the generated
+                  HTML on the JavaScript console. This exists to
+                  provide an example of how to subclass the `builder`
+                  widget.
+
+`cover-art`       Displays cover art for a book by searching in
+                  Amazon. Often used with an `autosearch` attribute to
+                  indicate what book to display. For example,
+                  `<div class="mkws-cover-art" autosearch="isbn=1291177124"></div>`
+                  displays cover art for _All Yesterdays: Unique and
+                  Speculative Views of Dinosaurs and Other Prehistoric
+                  Animals_.
+                  For this widget to work, a library that includes the
+                  AmazonBooks target must be used. For example, the
+                  "DEMO AmazonBooks for MKWS" account, which can be
+                  selected with `sp_auth_credentials="mkws-amazon/mkws"`.
+
+`details`         This widget is generated by the toolkit itself to
+                  hold the full details of records that are initially
+                  listed in summary form.
+
+`done`            Initially empty, this widget is set to display
+                  "Search complete: found _n_ records" when all
+                  targets have completed their work, either returning
+                  a hit-count or an error. The message displayed can
+                  be changed by overriding the `done` template using
+                  `<script class="mkws-template-done" type="text/x-handlebars-template">`.
 
 `facet`           x