Document auth-name and builder widgets.

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

diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown
index a315a22..46f507c 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
 -----------
@@ -567,19 +568,24 @@ containing the username and password separated by a slash:
 
 ### (Optional): conceal credentials from HTML source
 
-Using a credential-based Service-Proxy authentication URL such as the
-one above reveals the the credentials to public view -- to anyone who
-does View Source on the MKWS application. This may be acceptable for
-some libraries, but is intolerable for those which provide
-authenticated access to subscription resources.
-
-In these circumstances, a more elaborate approach is necessary. The
-idea is to make a URL local to the customer that is used for
-authentication onto the Service Proxy, hiding the credentials in a
-local rewrite rule. Then local mechanisms can be used to limit access
-to that local authentication URL. Here is one way to do it when
+Using credential-based authentication settings such as those above
+reveals the the credentials to public view -- to anyone who does View
+Source on the MKWS application. This may be acceptable for some
+libraries, but is intolerable for those which provide authenticated
+access to subscription resources.
+
+In these circumstances, a different approach is
+necessary. Referer-based or IP-based authentication may be
+appropriate. But if these are not possible, then a more elaborate
+approach can be used to hide the credentials in a web-server
+configuration that is not visible to users.
+
+The idea is to make a Service Proxy authentication URL local to the
+customer, hiding the credentials in a rewrite rule in the local
+web-server's configuration. Then local mechanisms can be used to limit
+access to that local authentication URL. Here is one way to do it when
 Apache2 is the application's web-server, which we will call
-yourname.com:
+yourname.com`:
 
 Step 1: add a rewriting authentication alias to the configuration:
 
@@ -587,9 +593,9 @@ Step 1: add a rewriting authentication alias to the configuration:
        RewriteRule /spauth/ http://sp-mkws.indexdata.com/service-proxy/?command=auth&action=check,login&username=U&password=PW [P]
 
 Step 2: set the MKWS configuration item `service_proxy_auth` to
-<http://yourname.com/spauth/>
+`http://yourname.com/spauth/`.
 
-Step 3: protect access to the local path <http://yourname.com/spauth/>
+Step 3: protect access to the local path `http://yourname.com/spauth/`
 (e.g. using a `.htaccess` file).
 
 
@@ -632,6 +638,96 @@ attribute as follows:
 Reference guide
 ===============
 
+Widgets
+-------
+
+The following widgets are provided in the core set. (Others can be
+added: see the [MKWS developers' guide](mkws-developer.html).)
+
+----
+Name              Description
+----              -----------
+`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.
+
+`button`          x
+
+`categories`      x
+
+`config`          x
+
+`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`       x
+
+`details`         x
+
+`done`            x
+
+`facet`           x
+
+`google-image`    x
+
+`images`          x
+
+`lang`            x
+
+`log`             x
+
+`lolcat`          x
+
+`motd-container`  x
+
+`motd`            x
+
+`navi`            x
+
+`pager`           x
+
+`per-page`        x
+
+`progress`        x
+
+`query`           x
+
+`ranking`         x
+
+`record`          x
+
+`records`         x
+
+`reference`       x
+
+`results`         x
+
+`search-form`     x
+
+`search`          x
+
+`sort`            x
+
+`stat`            x
+
+`switch`          x
+
+`targets`         x
+
+`termlists`       x
+----
+
+
 Configuration object
 --------------------