X-Git-Url: http://sru.miketaylor.org.uk/?a=blobdiff_plain;f=doc%2Fmkws-manual.markdown;h=bf888ca92843270b6bd1ba0717f72f5df8f44337;hb=c88fa21be6641e7364f50e96f5a1e1a175a00b0a;hp=519a9852b6477990c9aadb559daabdb5c525ff83;hpb=39bcd614b870ddc18d6806a9795589dfa47e675c;p=mkws-moved-to-github.git
diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown
index 519a985..bf888ca 100644
--- a/doc/mkws-manual.markdown
+++ b/doc/mkws-manual.markdown
@@ -41,7 +41,7 @@ flexibility against convenience:
[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
@@ -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`.
-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
===================
@@ -202,16 +186,14 @@ like this:
lang_options: [ "en", "da" ]
lang: "da",
sort_default: "title",
- query_width: 60
};
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.
@@ -932,21 +914,19 @@ perpage facet, int Specifies the number of re
perpage_default _team_ string 20 The initial value for the number of records to show on each page.
-perpage_options ranking array *Note 3* A list of candidate page sizes. Users can choose between these to determine
+perpage_options ranking array *Note 2* A list of candidate page sizes. Users can choose between these to determine
how many records are displayed on each page of results.
-pp2_hostname _global_ string *Note 7* Unless overridden by the `pazpar2_url` setting, this is used together with
+pp2_hostname _global_ string *Note 3* Unless overridden by the `pazpar2_url` setting, this is used together with
`pp2_path` to construct the URL to the Pazpar2 service (or Service
Proxy). Set this to connect to a service on a different host from the
default.
-pp2_path _global_ string *Note 8* Unless overridden by the `pazpar2_url` setting, this is used together with
+pp2_path _global_ string *Note 4* Unless overridden by the `pazpar2_url` setting, this is used together with
`pp2_hostname` to construct the URL to the Pazpar2 service (or Service
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`
@@ -989,7 +969,7 @@ sort facet, string Specifies the order in whi
sort_default _team_ string relevance The default sort criterion to use. Must be one of those in the
`sort_options` array.
-sort_options ranking array *Note 6* List of supported sort criteria. Each element of the list is itself a
+sort_options ranking array *Note 5* List of supported sort criteria. Each element of the list is itself a
two-element list: the first element of each sublist is a pazpar2
sort-expression such as `data:0` and the second is a human-readable label
such as `newest`.
@@ -999,10 +979,10 @@ sp_auth_credentials _global_ string If defined, this must be a
initialisation. See the [Assembling Pazpar2 URLs](#assembling-pazpar2-urls)
section below.
-sp_auth_path _global_ string *Note 9* Part of the URL used for authentication. See the [Assembling Pazpar2
+sp_auth_path _global_ string *Note 6* Part of the URL used for authentication. See the [Assembling Pazpar2
URLs](#assembling-pazpar2-urls) section below.
-sp_auth_query _global_ string *Note 10* Part of the URL used for authentication. See the [Assembling Pazpar2
+sp_auth_query _global_ string *Note 7* 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
@@ -1049,37 +1029,32 @@ use_service_proxy _global_ bool true If true, then a Service Pr
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
-1. ["xtargets", "subject", "author"]
-
-2. ### unused
-
-3. [10, 20, 30, 50]
+1. The default for `facets` is `["xtargets", "subject", "author"]`
-4. ### unused
+2. The default for `perpage_options` is `[10, 20, 30, 50]`
-5. "http://sp-mkws.indexdata.com/service-proxy/"
+3. The default for `pp2_hostname` is `"sp-mkws.indexdata.com"`
-6. [["relevance"], ["title:1", "title"], ["date:0", "newest"], ["date:1", "oldest"]]
+4. The default for `pp2_path` is `"service-proxy"`
-7. "sp-mkws.indexdata.com"
+5. The default for `sort_options` is `[["relevance"], ["title:1", "title"], ["date:0", "newest"], ["date:1", "oldest"]]`
-8. "service-proxy"
+6. The default for `sp_auth_path` is `"service-proxy/"`.
-9. The default for `sp_auth_path` is `"service-proxy/"`.
-
-10. The default for `sp_auth_query` is `"command=auth&action=perconfig"`.
+7. The default for `sp_auth_query` is `"command=auth&action=perconfig"`.
### Indirect settings
+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. FIXME
+say more.
+
FIXME !query!q, !path!2, etc.
### Assembling Pazpar2 URLs
@@ -1251,6 +1226,30 @@ and .CLASS indicates an instance of a class.
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.