X-Git-Url: http://lists.indexdata.dk/cgi-bin?a=blobdiff_plain;f=doc%2Fmkws-manual.markdown;h=1066f63fadbff802bb0157b2a2edaf04ee3b2944;hb=aee13a01ec7a7ab15d571e63e5f8671ce599b05e;hp=5d42e8c193fd5d2bffa6dd10cf607491bbcd3b96;hpb=b90200d944d9d273d901a0152d1db6e5d6aec315;p=mkws-moved-to-github.git diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown index 5d42e8c..1066f63 100644 --- a/doc/mkws-manual.markdown +++ b/doc/mkws-manual.markdown @@ -1,6 +1,6 @@ % The MKWS manual: embedded metasearching with the MasterKey Widget Set % Mike Taylor -% October 2014 +% November 2014 Introduction @@ -542,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: @@ -865,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). @@ -882,8 +882,8 @@ limit facet, string Allows a partial search to records, chapter of the Pazpar2 manual results ](http://www.indexdata.com/pazpar2/doc/pazpar2_protocol.html) -log_level _global_ int 1 Level of debugging output to emit. 0 = none, 1 = messages, 2 = messages with - datestamps, 3 = messages with datestamps and stack-traces. +log_level _global_ string info The lowest level of logging output to emit. Acceptable values are + `trace`, `debug`, `info`, `warn`, `error` and `fatal`. maxrecs facet, int Limits the metasearching middleware to retrieving no more than the specified facets, number of records from each target. @@ -1072,10 +1072,14 @@ assembled from the two configuration sessings `pp2_hostname` and `pp2_path`. How 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, +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. -and how `service_proxy_auth` is assembled from -`sp_auth_hostname` or `pp2_hostname`, `pp2_path` or `sp_auth_path`, `sp_auth_query` and `sp_auth_credentials`. +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 ---------------------- @@ -1096,46 +1100,64 @@ 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 -------------------------- The MasterKey Widget Set can be invoked in a popup window on top of the page. -Note that when using the `popup` layout, facilities from the jQuery UI -toolkit are used, so it's necessary to include both CSS and JavaScript -from that toolkit. The relevant lines are: +Note that the `popup` widget uses facilities from the jQuery UI, so +it's necessary to include both CSS and JavaScript from that +toolkit. The relevant lines are: +Popup windows can contain any HTML, not just MKWS widgets. + +The properties of the `popup` widget are as follows: + ---- Element Type Default Description -------- ----- ------- ------------ -popup_width string 880 Width of the popup window (if used), in - pixels. +popup_width int 880 Width of the popup window, in pixels. -popup_height string 760 Height of the popup window (if used), in - pixels. +popup_height int 760 Height of the popup window, in pixels. -popup_button string `input.mkwsButton` A click on this selector will trigger the - popup to open +popup_button string `input.mkwsButton` A jQuery selector identifying the element which, which clicked, pops up the window. -popup_modal string 0 Modal confirmation mode. Valid values are 0 or 1 +popup_modal bool 0 Indicates whether the popup is modal (blocks access to the background page until + dismissed). Set to 1 if a modal popup is required. -popup_autoOpen string 1 Open popup window on load. Valid values are 0 or 1 +popup_autoOpen bool 1 Indictaes whether to pop up the window automatically when the page is loaded. ---- -You can have more than one mkws-popup widgets on a page. Please use a different -popup_button value to address the right ones. +Multiple `popup` widgets can co-exist on a page. In this case, different +`popup_button` values must be used for each. -The structure of the HTML generated by the MKWS widgets -------------------------------------------------------- +Structure of HTML generated by widgets +-------------------------------------- In order to override the default CSS styles provided by the MasterKey Widget -Set, it's necessary to understand that structure of the HTML elements that are -generated within the widgets. This knowledge make it possible, for example, -to style each `