X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fmkws-manual.markdown;h=429e8ce69a1e1ada5b153a6306f46e98ec3373ce;hb=9a18fee5262c0f2e21861574e29bc4f3f44ea687;hp=81daf67b1f5b7d23e9c64cf15b54e39cf1141ee6;hpb=c314534198b725ec7113ca62b1a6282fb1a7626c;p=mkws-moved-to-github.git diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown index 81daf67..429e8ce 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. @@ -560,7 +542,7 @@ its own User Access record. 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: @@ -860,11 +842,6 @@ default values are in footnotes to keep the table reasonably narrow. ---- 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, @@ -888,7 +865,7 @@ facet_max_* facet int Specifies how many terms a 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). @@ -932,26 +909,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` - 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. @@ -962,8 +932,8 @@ sentences reference int Limits the number of sente 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. @@ -989,7 +959,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 +969,15 @@ 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_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 @@ -1023,17 +998,16 @@ targets facet, string One of three ways to selec records, results -template details, string Numerous widgets use Handlebars templates ### say more! - done, - facet, - facets, - images, - lang, +template details, string Numerous widgets use Handlebars templates to render HTML. In general, each + done, of these by default uses a template with the same name as the widget + facet, itself. Individual widgets can be customised to use a template of a + facets, different name by means of their `template` setting. The `records` widget + images, (and `record`, an equivalent that shows only a single record) use the + lang, `summary` template as well as the `records` template. navi, pager, progress, ranking, - record, records, reference, results, @@ -1042,51 +1016,70 @@ template details, string Numerous widgets use Handl switch, targets - - 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 +`
` 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: + + + + +
### 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 ---------------------- @@ -1107,37 +1100,55 @@ in the specified language. For example: } 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 -------------------------- @@ -1179,7 +1190,7 @@ 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 +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 @@ -1197,18 +1208,18 @@ and .CLASS indicates an instance of a class. #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 @@ -1246,12 +1257,36 @@ and .CLASS indicates an instance of a class. 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.