[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
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
===================
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
-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.
When credential-based authentication is in use (username and
password), it's necessary to pass these credentials into the Service
-Proxy when establishing the session. This is done
+Proxy when establishing the session. This is done
by providing the `sp_auth_credentials` configuration setting as a string
containing the username and password separated by a slash:
----
Element Widget Type Default Description
-------- ------ ----- --------- ------------
-auth_hostname _global_ string If provided, overrides the `pp2_hostname` setting when constructing the
- Service Proxy authentication URL. This need only be used when authentication
- is performed on a different host from the remaining operations (search,
- retrieve, etc.)
-
autosearch facet, string If provided, this setting contains a query which is immediately run on behalf
facets, of the team. Often used with an [indirect setting](#indirect-settings).
record,
facets _team_ array *Note 1* Ordered list of names of facets to display.
-lang _team_ string Two-letter ISO code of the default language to display the UI in. Supported
+lang _team_ string The code of the default language to display the UI in. Supported
language codes are `en` = English, `de` = German, `da` = Danish, and whatever
additional languages are configured using `language_*` entries (see below).
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`
- 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.
service_proxy_auth _global_ url If defined, this is the URL which, when `use_service_proxy` is true, is
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
+ in. When not defined, the URL is assembled from `sp_auth_hostname` or
+ `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.
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`.
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_hostname _global_ string If provided, overrides the `pp2_hostname` setting when constructing the
+ Service Proxy authentication URL. This need only be used when authentication
+ is performed on a different host from the remaining operations (search,
+ retrieve, etc.)
+
+sp_auth_path _global_ string 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 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
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.
----
-(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"]
+1. The default for `facets` is `["xtargets", "subject", "author"]`
-2. ### unused
+2. The default for `perpage_options` is `[10, 20, 30, 50]`
-3. [10, 20, 30, 50]
+3. The default for `pp2_hostname` is `"sp-mkws.indexdata.com"`
-4. ### unused
+4. The default for `pp2_path` is `"service-proxy/"`
-5. "http://sp-mkws.indexdata.com/service-proxy/"
+5. The default for `sort_options` is `[["relevance"], ["title:1", "title"], ["date:0", "newest"], ["date:1", "oldest"]]`
-6. [["relevance"], ["title:1", "title"], ["date:0", "newest"], ["date:1", "oldest"]]
+6. The default for `sp_auth_query` is `"command=auth&action=perconfig"`
-7. "sp-mkws.indexdata.com"
+### Indirect settings
-8. "service-proxy"
+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_.
-9. The default for `sp_auth_path` is `"service-proxy/"`.
+The currently supported types are:
-10. The default for `sp_auth_query` is `"command=auth&action=perconfig"`.
+* `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`
-### Indirect settings
+* `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`
-FIXME !query!q, !path!2, etc.
+* `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
-FIXME describe how `pazpar2_url` is assembled from `pp2_hostname` and `pp2_path`; and how `service_proxy_auth` is assembled from
-`auth_hostname` or `pp2_hostname`, `sp_auth_path`, `sp_auth_query` and `sp_auth_credentials`.
+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, the hostname used for authentication may if necessary be
+overridden using the `sp_auth_hostname` setting, and the path overridden by `sp_auth_path`. In any case, the value of
+`sp_auth_query` is appended; and if `sp_auth_credentials` is set, then it is used to add username and password parameters.
+
+So in the absence of any configuration added by an application, the Service Proxy authentication URL is made up of `pp2_hostname`
+(sp-mkws.indexdata.com) since `sp_auth_hostname` is undefined; and `pp2_path` (service-proxy/) since `sp_auth_path` is undefined;
+and `sp_auth_query` (command=auth&action=perconfig); and no credentials, since `sp_auth_credentials` is undefined. Therefore the
+URL `http://sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig` is generated.
Language specification
----------------------
}
The following strings occurring in the UI can be translated:
-`Displaying`,
-`Next`,
-`Prev`,
-`Records`,
-`Search`,
-`Sort by`,
-`Targets`,
-`Facets`,
-`and show`,
-`found`,
-`of`,
-`per page`
-and
-`to`.
+
+* `Search complete: found`
+* `records`
+* `Displaying`
+* `to`
+* `of`
+* `found`
+* `Prev`
+* `Next`
+* `Sort by`
+* `and show`
+* `per page`
+* `Search`
+* `Active clients`
+* `Retrieved records`
+* `Records`
+* `Targets`
+* `Target ID`
+* `Hits`
+* `Diags`
+* `Records`
+* `State`
In addition, facet names can be translated:
-`Authors`,
-`Sources`
-and
-`Subjects`.
+
+* `Authors`
+* `Sources`
+* `Subjects`
+
+and whatever field captions are defined by `facet_caption_*` settings.
+
+And sort-orders:
+
+* `relevance`
+* `title`
+* `newest`
+* `oldest`
+
+and whatever sort-orders are defined by the `sort_options` setting.
Finally, the names of fields in the full-record display can be
translated. These include, but may not be limited to:
-`Author`,
-`Date`,
-`Location`,
-`Subject`
-and
-`Title`.
-
+* `Title`
+* `Date`
+* `Author`
+* `Links`
+* `Subject`
+* `Locations`
jQuery UI popup invocation
--------------------------
----
-You can have more than one mkws-popup widgets on a page. Please use a different
+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
#mkwsSwitch
a*
-
+
#mkwsLang
( a | span )*
-
+
#mkwsSearch
form
input#mkwsQuery type=text
input#mkwsButton type=submit
-
+
#mkwsBlanket
(no contents -- used only for masking)
-
+
#mkwsResults
table
tbody
tbody
tr*
td*
-
+
#mkwsStat
span.head
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>
projects / mkws-moved-to-github.git / blobdiff