No default value documented for sp_auth_path.

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

diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown
index 05a46ea..1d65439 100644 (file)
--- a/doc/mkws-manual.markdown
+++ b/doc/mkws-manual.markdown
@@ -41,7 +41,7 @@ flexibility against convenience:
   [Drupal](https://www.drupal.org/)
   sites.
 
   [Drupal](https://www.drupal.org/)
   sites.
 

-All of these approaches require programming to a greater or lesser
+All but the last of these approaches require programming to a greater or lesser

 extent. Against this backdrop, we introduced
 [MKWS (the MasterKey Widget Set)](http://mkws.indexdata.com/)
 -- a set of simple, very high-level HTML+CSS+JavaScript
 extent. Against this backdrop, we introduced
 [MKWS (the MasterKey Widget Set)](http://mkws.indexdata.com/)
 -- a set of simple, very high-level HTML+CSS+JavaScript

@@ -171,22 +171,6 @@ is part of the `aux` team.
 Widgets that do not have a team specified (as in the examples above)
 are placed in the team called `AUTO`.
 
 Widgets that do not have a team specified (as in the examples above)
 are placed in the team called `AUTO`.
 

-Old and new-style class-names
------------------------------
-
-**NOTE.** Versions of MKWS before v1.0 used camel-case class-names:
-without hyphens and with second and subsequent words capitalised. So
-instead of `mkws-search`, it used to be `mkwsSearch`. And the classes
-used to specify team names used an `mkwsTeam_` prefix (with an
-underscore). So instead of `mkws-team-foo`, it used to be
-`mkwsTeam_foo`.
-
-The 1.x series of MKWS releases recognise these old-style class-names
-as well as the canonical ones, as a facility for backwards
-compatibility. However, **these old class-names are deprecated, and
-support will be removed in v2.0**. Existing applications that use them
-should be upgraded to the new-style class names as soon as convenient.
-

 Configuring widgets
 ===================
 
 Configuring widgets
 ===================
 

@@ -202,16 +186,14 @@ like this:
            lang_options: [ "en", "da" ]
            lang: "da",
            sort_default: "title",
            lang_options: [ "en", "da" ]
            lang: "da",
            sort_default: "title",

-           query_width: 60

          };
        </script>
        <script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
 
 This configuration restricts the set of available UI languages English
 and Danish (omitting German), sets the default to Danish (rather than
          };
        </script>
        <script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
 
 This configuration restricts the set of available UI languages English
 and Danish (omitting German), sets the default to Danish (rather than

-the English), initially sorts search results by title rather than
-relevance (though as always this can be changed in the UI) and makes
-the search box a bit wider than the default.
+the English), and initially sorts search results by title rather than
+relevance (though as always this can be changed in the UI).

 
 The full set of supported configuration settings is described in the
 reference guide below.
 
 The full set of supported configuration settings is described in the
 reference guide below.

@@ -945,13 +927,6 @@ pp2_path                  _global_  string  *Note 4*  Unless overridden by the `
                                                       Proxy). Set this to connect to a service on a different host from the
                                                       default.
 
                                                       Proxy). Set this to connect to a service on a different host from the
                                                       default.
 

-query_width               _search_  int     50        The width of the query box, in characters.
-
-responsive_design_width   _global_  int               If defined, then the facets display moves between two locations as the
-                                                      screen-width varies. The specified number is the threshhold width, in
-                                                      pixels, at which the facets move between their two locations. The `switch`
-                                                      and `lang` widgets also disappear entirely below this threshhold.
-

 scan_all_nodes            _global_  bool    false     An internal setting that changes how MKWS scans the HTML documen to discover
                                                       widgets. If set to true, a different approach is used which may be faster
                                                       under some circumstances.
 scan_all_nodes            _global_  bool    false     An internal setting that changes how MKWS scans the HTML documen to discover
                                                       widgets. If set to true, a different approach is used which may be faster
                                                       under some circumstances.

@@ -963,7 +938,7 @@ service_proxy_auth        _global_  url               If defined, this is the UR
                                                       fetched once at the beginning of each session to authenticate the user and
                                                       establish a session that encompasses a defined set of targets to search
                                                       in. When not defined, the URL is assembled from `auth_hostname` or
                                                       fetched once at the beginning of each session to authenticate the user and
                                                       establish a session that encompasses a defined set of targets to search
                                                       in. When not defined, the URL is assembled from `auth_hostname` or

-                                                      `pp2_hostname`, `sp_auth_path`, `sp_auth_query` and
+                                                      `pp2_hostname`, `pp2_path` or `sp_auth_path`, `sp_auth_query` and

                                                       `sp_auth_credentials`. See the [Assembling Pazpar2
                                                       URLs](#assembling-pazpar2-urls) section below.
 
                                                       `sp_auth_credentials`. See the [Assembling Pazpar2
                                                       URLs](#assembling-pazpar2-urls) section below.
 

@@ -999,10 +974,10 @@ sp_auth_credentials       _global_  string            If defined, this must be a
                                                       initialisation. See the [Assembling Pazpar2 URLs](#assembling-pazpar2-urls)
                                                       section below.
 
                                                       initialisation. See the [Assembling Pazpar2 URLs](#assembling-pazpar2-urls)
                                                       section below.
 

-sp_auth_path              _global_  string  *Note 6*  Part of the URL used for authentication. See the [Assembling Pazpar2
+sp_auth_path              _global_  string            Part of the URL used for authentication. See the [Assembling Pazpar2

                                                       URLs](#assembling-pazpar2-urls) section below.
 
                                                       URLs](#assembling-pazpar2-urls) section below.
 

-sp_auth_query             _global_  string  *Note 7*  Part of the URL used for authentication. See the [Assembling Pazpar2
+sp_auth_query             _global_  string  *Note 6*  Part of the URL used for authentication. See the [Assembling Pazpar2

                                                       URLs](#assembling-pazpar2-urls) section below.
 
 target                    facet,    string            One of three ways to select which targets an auto-searching widgets uses. See
                                                       URLs](#assembling-pazpar2-urls) section below.
 
 target                    facet,    string            One of three ways to select which targets an auto-searching widgets uses. See

@@ -1041,20 +1016,15 @@ template                  details,  string            Numerous widgets use Handl
                           switch,
                           targets
 
                           switch,
                           targets
 

-<!--- The widget called "record" is a special-case of "records"; both also use "summary" -->
-

 text                      builder   string  "Build!"  Specifies what text to use for the Builder button.
 
 use_service_proxy         _global_  bool    true      If true, then a Service Proxy is used to deliver searching services rather
                                                       than raw Pazpar2. An authentication phase is run during initialisation.
 ----
 
 text                      builder   string  "Build!"  Specifies what text to use for the Builder button.
 
 use_service_proxy         _global_  bool    true      If true, then a Service Proxy is used to deliver searching services rather
                                                       than raw Pazpar2. An authentication phase is run during initialisation.
 ----
 

-(Perhaps we should get rid of the `show_lang`, `show_perpage`,
-`show_sort` and `show_switch` configuration settings, as we display the relevant menus
-only when their containers are provided -- e.g. an `mkws-lang` element
-for the language menu. But for now we retain these, as an easier route
-to lightly customise the display than by providing a full HTML
-structure.)
+The `show_lang`, `show_perpage`, `show_sort` and `show_switch` configuration settings are technically redundant, as the relevant
+widgets, like all widgets, are displayed only when they are provided. But they are retained as an easier route to lightly
+customise the display than by providing a full HTML structure.

 
 ### Notes
 
 
 ### Notes
 

@@ -1064,21 +1034,47 @@ structure.)
 
 3. The default for `pp2_hostname` is `"sp-mkws.indexdata.com"`
 
 
 3. The default for `pp2_hostname` is `"sp-mkws.indexdata.com"`
 

-4. The default for `pp2_path` is `"service-proxy"`
+4. The default for `pp2_path` is `"service-proxy/"`

 
 5. The default for `sort_options` is `[["relevance"], ["title:1", "title"], ["date:0", "newest"], ["date:1", "oldest"]]`
 
 
 5. The default for `sort_options` is `[["relevance"], ["title:1", "title"], ["date:0", "newest"], ["date:1", "oldest"]]`
 

-6. The default for `sp_auth_path` is `"service-proxy/"`.
-
-7. The default for `sp_auth_query` is `"command=auth&action=perconfig"`.
+6. The default for `sp_auth_query` is `"command=auth&action=perconfig"`

 
 ### Indirect settings
 
 
 ### Indirect settings
 

-FIXME !query!q, !path!2, etc.
+The values of any setting are generally interpreted literally. However, it is possible to specify a value indirectly -- for
+example, by reference to a query parameter -- and this is often useful in contexts such as specifying an autosearch
+query. Settings of this kind have values beginning with an exclamation mark, and take the form `!`_type_`!`_value_.
+
+The currently supported types are:
+
+* `param` -- uses the value of the specified query parameter for the URL. For example
+`<div class="mkws-results" autosearch="!param!term">` will auto-search for the word "sushi" if the page containing that widget is
+invoked from the URL `http://example.com/magic/example.html?term=sushi`
+
+* `path` -- uses the value of the _n_th component of the URL path, as specified by the value. For example
+`!path!3` will auto-search for the word "dinosaur" if the page containing that widget is
+invoked from the URL `http://example.com/magic/lookup/dinosaur`
+
+* `var` -- uses the value of the named JavaScript global variable. This is a very powerful and general mechanism. For example, to
+  search for the reversed value of the query parameter called `reverseTerm`, you might write a JavaScript function to do the
+  extraction and reversing, the use the HTML:
+
+<!--- Due to a bug in pandoc, we need this comment to force the following code-block to be recognised -->
+
+               <script>var _reversedParam = extractAndReverse("term");</script>
+               <div class="mkws-results" autosearch="!var!_reversedParam">

 
 ### Assembling Pazpar2 URLs
 
 
 ### Assembling Pazpar2 URLs
 

-FIXME describe how `pazpar2_url` is assembled from `pp2_hostname` and `pp2_path`; and how `service_proxy_auth` is assembled from
+Most of MKWS's functionality is achieved by use of the Pazpar2 middleware. This is accessed on an endpoint URL which is usually
+assembled from the two configuration sessings `pp2_hostname` and `pp2_path`. However, if for some reason an unusual Pazpar2
+endpoint must be used, that endpoint can be specified in the `pazpar2_url` setting, and that will be used instead.
+
+In the common case where Pazpar2 is accessed via the Service Proxy, an authentication call is made during initialisation. The call
+is generally made to the same endpoint as the other requests. However, 
+
+and how `service_proxy_auth` is assembled from

 `auth_hostname` or `pp2_hostname`, `sp_auth_path`, `sp_auth_query` and `sp_auth_credentials`.
 
 Language specification
 `auth_hostname` or `pp2_hostname`, `sp_auth_path`, `sp_auth_query` and `sp_auth_credentials`.
 
 Language specification

@@ -1245,6 +1241,30 @@ and .CLASS indicates an instance of a class.
          span.clients
          span.records
 
          span.clients
          span.records
 

+
+Appendix: compatibility roadmap
+===============================
+
+FIXME: more to write here.
+
+
+Old and new-style class-names
+-----------------------------
+
+**NOTE.** Versions of MKWS before v1.0 used camel-case class-names:
+without hyphens and with second and subsequent words capitalised. So
+instead of `mkws-search`, it used to be `mkwsSearch`. And the classes
+used to specify team names used an `mkwsTeam_` prefix (with an
+underscore). So instead of `mkws-team-foo`, it used to be
+`mkwsTeam_foo`.
+
+The 1.x series of MKWS releases recognise these old-style class-names
+as well as the canonical ones, as a facility for backwards
+compatibility. However, **these old class-names are deprecated, and
+support will be removed in v2.0**. Existing applications that use them
+should be upgraded to the new-style class names as soon as convenient.
+
+

 - - -
 
 Copyright (C) 2013-2014 Index Data ApS. <http://indexdata.com>
 - - -
 
 Copyright (C) 2013-2014 Index Data ApS. <http://indexdata.com>