Restructure authentication sections.

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

diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown
index ef54044..85d1d51 100644 (file)
--- a/doc/mkws-manual.markdown
+++ b/doc/mkws-manual.markdown
@@ -419,48 +419,49 @@ in a popup. The key part of such an application is this invocation of
 the MKWS jQuery plugin:
 
         <div class="mkws-search"></div>
-        <div class="mkws-popup" popup_width="1024" popup_height="650" popup_modal="0" popup_autoOpen="0" popup_button="input.mkwsButton">
-          <div class="mkws-switch"></div>
-          <div class="mkws-lang"></div>
+        <div class="mkws-popup" popup_width="1024" popup_height="650">
           <div class="mkws-results"></div>
-          <div class="mkws-targets"></div>
-          <div class="mkws-stat"></div>
         </div>
 
 The necessary scaffolding can be seen in an example application,
 [popup.html](http://example.indexdata.com/popup.html).
 
-
-Authentication and target configuration
----------------------------------------
-
-By default, MKWS configures itself to use a demonstration account on a
-service hosted by mkws.indexdata.com. This account (username `demo`,
-password `demo`) provides access to about a dozen free data
-sources. Authentication onto this service is via an authentication URL
-on the same MKWS server, so no explicit configuration is needed.
-
-In order to search in a customised set of targets, including
-subscription resources, it's necessary to create an account with
-Index Data's hosted Service Proxy, and protect that account with
-authentication tokens (to prevent unauthorised use of subscription
-resources). For information on how to do this, see the next section.
+The relevant properties (`popup_width`, etc.) are documented
+[below](#jquery-ui-popup-invocation)
+in the reference section.
 
 
 MKWS target selection
 =====================
 
+Introduction
+------------
+
 MKWS accesses targets using the Pazpar2 metasearching engine. Although
 Pazpar2 can be used directly, using a statically configured set of
 targets, this usage is unusual. More often, Pazpar2 is fronted by the
 Service Proxy (SP), which manages authentication, sessions, target
-selection, etc.
-
-This document assumes the SP is used, and explains how to go about
-making a set of targets (a "library") available, how to connect your
-MKWS application to that library, and how to choose which of the
-available targets to use.
+selection, etc. This document assumes the SP is used, and explains how
+to go about making a set of targets (a "library") available, how to
+connect your MKWS application to that library, and how to choose which
+of the available targets to use.
+
+MKWS configures itself to use an account on a service hosted by
+`sp-mkws.indexdata.com`. By default, it sends no authentication
+credentials, allowing the appropriate account to be selected on the
+basis of referring URL or IP address.
+
+If no account has been set up to recognise the referring URL of the
+application or the IP address of the client, then a default "MKWS
+Demo" account is used. This account (which can also be explicitly
+chosen by using the username `mkws`, password `mkws`) provides access
+to about a dozen free data sources.
 
+In order to search in a customised set of targets, including
+subscription resources, it's necessary to create an account with
+Index Data's hosted Service Proxy, and protect that account with
+authentication tokens (to prevent unauthorised use of subscription
+resources).
 
 Maintaining the library
 -----------------------
@@ -849,7 +850,8 @@ popup_width     string  880                 Width of the popup window (if used),
 popup_height    string  760                 Height of the popup window (if used), in
                                             pixels.
 
-popup_button    string  `input.mkwsButton`  (Never change this.)
+popup_button    string  `input.mkwsButton`  A click on this selector will trigger the
+                                           popup to open
 
 popup_modal     string  0                   Modal confirmation mode. Valid values are 0 or 1
 
@@ -857,6 +859,8 @@ popup_autoOpen  string  1                   Open popup window on load. Valid val
 
 ----
 
+You can have more than one mkws-popup widgets on a page. Please use a different 
+popup_button value to address the right ones.
 
 The structure of the HTML generated by the MKWS widgets
 -------------------------------------------------------