X-Git-Url: http://jsfdemo.indexdata.com/?a=blobdiff_plain;f=tools%2Fhtdocs%2Fwhitepaper.markdown;h=04bd8f494cbb84346947264bcd2490b78bf3b1b2;hb=6274957bedbb5a4612b35be81333f545cd4f43ce;hp=2f7f392243408bd1e583be53104d5ecd03018c17;hpb=b01d755386bdd52efcc7cd6d95a33857b88863d2;p=mkws-moved-to-github.git diff --git a/tools/htdocs/whitepaper.markdown b/tools/htdocs/whitepaper.markdown index 2f7f392..04bd8f4 100644 --- a/tools/htdocs/whitepaper.markdown +++ b/tools/htdocs/whitepaper.markdown @@ -207,20 +207,59 @@ but will be hidden when a search is made. ### Responsive design - responsive_design: true - responsive_design_width: 500 -
-
+Metasearching applications may need to appear differently on +small-screened mobile devices, or change their appearance when +screen-width changes (as when a small device is rotated). To achieve +this, MKWS supports responsive design which will move the termlists to +the bottom on narrow screens and to the sidebar on wide screens. + +To turn on this behaviour, set the `responsive_design_width` to the desired +threshhold width in pixels. For example: + + + +If individual result-related components are in use in place of the +all-in-one mkwsResults, then the redesigned application needs to +specify the locations where the termlists should appear in both +cases. In this case, wrap the wide-screen `mkwsTermlists` element in a +`mkwsTermlistContainer1` element; and provide an +`mkwsTermlistContainer2` element in the place where the narrow-screen +termlists should appear. ### Popup results with jQuery UI -TODO +The [jQuery UI library](http://en.wikipedia.org/wiki/JQuery_UI) +can be used to construct MKWS applications in which the only component +generally visible on the page is a search box, and the results appear +in a popup. The key part of such an application is this invocation of +the MKWS jQuery plugin: + + + +The necessary scaffolding can be seen in an example application, +http://example.indexdata.com/index-popup.html ### Authentication and target configuration -TODO +By default, MKWS configures itself to use a demo account on a service +hosted by mkws.indexdata.com. This demo account provides access to +about a dozen free data sources. Authentication onto this service is +via an authentication URL on the same server, which MKWS uses by +default so no configuration is needed. + +Access to a customised set of resources (including resources that +require authentication) can be provided. In this case, a +customer-specific authentication URL is used to gain access to these +rather than the default set. Contact Index Data on info@indexdata.com +for details. Reference Guide @@ -228,15 +267,253 @@ Reference Guide ### Configuration object -TODO +The configuration object `mkws_config` may be created before including +the MKWS JavaScript code to modify default behaviour. This structure +is a hash, whose entries are described in the table below. All entries +are options, but if specified must be given values of the specified +type. If ommitted, each setting takes the indicated default value; +long default values are in footnotes to keep the table reasonably narrow. + +--- +Element Type Default Description +-------- ----- --------- ------------ +debug int 1 Level of debugging output to emit. 0 = none, 1 = messages, 2 = messages with + datestamps, 3 = messages with datestamps and stack-traces. + +facets array *Note 1* Ordered list of names of facets to display. Supported facet names are + `sources`, `subjects` and `authors`. + +lang string en 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). + +lang_options array [] A list of the languages to offer as options. If empty (the default), then all + configured languages are listed. + +show_lang bool true Indicates whether or not to display the language menu. + +language_* hash Support for any number of languages can be added by providing entries whose name is + `language_` followed by the code of the language. See the separate section below for + details. + +pazpar2_url string *Note 2* The URL used to access the metasearch middleware. This service must be configured to + provide search results, facets, etc. It may be either unmediated or Pazpar2 the + MasterKey Service Proxy, which mediates access to an underlying Pazpar2 instance. In + the latter case, `service_proxy_auth` must be provided. + +perpage_options array *Note 3* A list of candidate page sizes. Users can choose between these to determine how many + records are displayed on each page of results. + +perpage_default string 20 The initial value for the number of records to show on each page. + +show_perpage bool true Indicates whether or not to display the perpage menu. + +query_width int 50 The width of the query box, in characters. + +responsive_design_width int If defined, then the facets display moves between two locations as the screen-width + varies, as described above. The specified number is the threshhold width, in pixels, + at which the facets move between their two locations. + +service_proxy_auth url *Note 4* A 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. + +sort_options array *Note 6* 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`. + +sort_default string relevance The label of the default sort criterion to use. Must be one of those in the `sort` + array. + +show_sort bool true Indicates whether or not to display the sort menu. + +use_service_proxy bool true If true, then a Service Proxy is used to deliver searching services rather than raw + Pazpar2. +--- + +Perhaps we should get rid of the `show_lang`, `show_perpage` and +`show_sort` configuration items, and simply display the relevant menus +only when their containers are provided -- e.g. an `mkwsLang` element +for the language menu. But for now we retain these, as an easier route +to lightly customise the display than my changing providing a full HTML +structure. + +#### Notes + +1. ["sources", "subjects", "authors"] + +2. /pazpar2/search.pz2 + +3. [10, 20, 30, 50] + +4. http://mkws.indexdata.com/service-proxy-auth + +5. http://mkws.indexdata.com/service-proxy/ + +6. [["relevance"], ["title:1", "title"], ["date:0", "newest"], ["date:1", "oldest"]] + + +### Language specification + +Support for another UI language can be added by providing an entry in +the `mkws_config` hash whose name is `language_` followed by the name +of the language: for example, `language_Arabic` to support +Arabic. Then value of this entry must be a hash, mapping the +English-language strings of the UI into their equivalents in the +specified language. For example: + + var mkws_config = { + language_Arabic: { + "Authors": "الكتاب", + "Subjects": "المواضيع", + // ... and others ... + } + } + +The following strings occurring in the UI can be translated: +`Displaying`, +`Next`, +`Prev`, +`Records`, +`Search`, +`Sort by`, +`Targets`, +`Termlists`, +`and show`, +`found`, +`of`, +`per page` +and +`to`. + +In addition, facet names can be translated: +`Authors`, +`Sources` +and +`Subjects`. + +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`. + + ### jQuery plugin invocation -TODO +The MasterKey Widget Set can be invoked as a jQuery plugin rather than +by providing an HTML skeleton explicitly. When this approach is used, +the invocation is a single line of JavaScript: + + + +This code should be inserted in the page at the position where the +metasearch should occur. + +When invoking this plugin, a hash of named options may be passed in to +modify the default behaviour, as in the exaple above. The available +options are as follows: + +--- +Element Type Default Description +-------- ----- --------- ------------ +layout string popup Specifies how the user interface should + appear. Options are `table` (the default, + with facets at the bottom), `div` (with + facets at the side) and `popup` (to + obtain a popup window). + +width int 880 Width of the popup window (if used), in + pixels. + +height int 760 Height of the popup window (if used), in + pixels. + +id_button string input#mkwsButton (Never change this.) + +id_popup string #mkwsPopup (Never change this.) +--- + +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: + + + + ### The structure of the HTML generated by the MKWS widgets -TODO +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 components. This knowledge make it possible, for example, +to style each `
` with class `term` but only when it occurs inside an +element with ID `#mkwsTermlists`, so as to avoid inadvertently styling other +elements using the same class in the non-MKWS parts of the page. + +The HTML structure is as follows. As in CSS, #ID indicates a unique identifier +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 + tr + td + #mkwsTermlists + div.title + div.facet* + div.termtitle + ( a span br )* + td + div#mkwsRanking + form#mkwsSelect + select#mkwsSort + select#mkwsPerpage + #mkwsPager + #mkwsNavi + #mkwsRecords + div.record* + span (for sequence number) + a (for title) + span (for other information such as author) + div.details (sometimes) + table + tbody + tr* + th + td + #mkwsTargets + #mkwsBytarget + table + thead + tr* + td* + tbody + tr* + td* + + #mkwsStat + span.head + span.clients + span.records - - -