X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=tools%2Fhtdocs%2Fwhitepaper.markdown;h=a91a7de631b6b2c4162c3a94a546bae21665d538;hb=354aeaca2902f9847fe993fbfb24d788c7458cec;hp=8e69e832cac153b5de84009fa31fb1ede84eac6e;hpb=260103177619b5879db9d3988228a048d3327cde;p=mkws-moved-to-github.git diff --git a/tools/htdocs/whitepaper.markdown b/tools/htdocs/whitepaper.markdown index 8e69e83..a91a7de 100644 --- a/tools/htdocs/whitepaper.markdown +++ b/tools/htdocs/whitepaper.markdown @@ -1,6 +1,6 @@ % Embedded metasearching with the MasterKey Widget Set % Mike Taylor -% 26 July 2013 +% July-September 2013 Introduction @@ -10,9 +10,10 @@ There are lots of practical problems in building resource discovery solutions. One of the biggest, and most ubiquitous is incorporating metasearching functionality into existing web-sites -- for example, content-management systems, library catalogues or intranets. In -general, even when access to metasearching is provided by simple -web-services such as [Pazpar2](http://www.indexdata.com/pazpar2), -integration work is seen as a major part of most projects. +general, even when access to core metasearching functionality is +provided by simple web-services such as +[Pazpar2](http://www.indexdata.com/pazpar2), integration work is seen +as a major part of most projects. Index Data provides several different toolkits for communicating with its metasearching middleware, trading off varying degrees of @@ -20,8 +21,8 @@ flexibility against convenience: * libpz2.js -- a low-level JavaScript library for interrogating the Service Proxy and Pazpar2. It allows the HTML/JavaScript programmer - to implement simple JavaScript functions to display facets, records, - etc. + to create JavaScript applications display facets, records, etc. that + are fetched from the metasearching middleware. * masterkey-ui-core -- a higher-level, complex JavaScript library that uses libpz2.js to provide the pieces needed for building a @@ -85,11 +86,11 @@ header, which are loaded from the tool site mkws.indexdata.com: * `mkwsStyle.css` provides the default CSS styling -Second, the `
` elements with special IDs that begin `mkws` can be -provided. These are filled in by the MKWS code, and provide the -components of the searching UI. The very simple application above has -only two such components: a search box and a results area. But more -are supported. The main `
`s are: +Second, within the HTML body, `
` elements with special IDs that +begin `mkws` can be provided. These are filled in by the MKWS code, +and provide the components of the searching UI. The very simple +application above has only two such components: a search box and a +results area. But more are supported. The main `
`s are: * `mkwsSearch` -- provides the search box and button. @@ -126,35 +127,141 @@ To see all of these working together, just put them all into the HTML Configuration ------------- -TODO +Many aspects of the behaviour of MKWS can be modified by setting +parameters into the `mkws_config` hash. **This must be done *before* +including the MKWS JavaScript** so that when that code is executed it +can refer to the configuration values. So the HTML header looks like +this: + + + -resposive resize +This configuration sets the UI language to Danish (rather than the +default of 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 full set of supported configuration items is described in the +reference guide below. Control over HTML and CSS ------------------------- -TODO - More sophisticated applications will not simply place the `
`s together, but position them carefully within an existing page framework -- such as a Drupal template, an OPAC or a SharePoint page. -Breaking up mkwsResults +While it's convenient for simple applications to use a monolithic +`mkwsResults` area which contains record, facets, sorting options, +etc., customised layouts may wish to treat each of these components +separately. In this case, `mkwsResults` can be omitted, and the +following lower-level components provided instead: -overriding styles +* `mkwsTermlists` -- provides the facets +* `mkwsRanking` -- provides the options for how records are sorted and + how many are included on each page of results. -Popup results with jQuery UI ----------------------------- +* `mkwsPager` -- provides the links for navigating back and forth + through the pages of records. -TODO +* `mkwsNavi` -- when a search result has been narrowed by one or more + facets, this area shows the names of those facets, and allows the + selected values to be clicked in order to remove them. +* `mkwsRecords` -- lists the actual result records. -Authentication and target configuration ---------------------------------------- +Customisation of MKWS searching widgets can also be achieved by +overriding the styles set in the toolkit's CSS stylesheet. The default +styles can be inspected in `mkwsStyle.css` and overridden in any +styles that appears later in the HTML than that file. At the simplest +level, this might just mean changing fonts, sizes and colours, but +more fundamental changes are also possible. -TODO +To properly apply styles, it's necessary to understand how the HTML is +structured, e.g. which elements are nested within which +containers. The structures used by the widget-set are described in the +reference guide below. + + +Refinements +----------- + + +### Message of the day + +Some applications might like to open with content in the area that +will subsequently be filled with result-records -- a message of the +day, a welcome message or a help page. This can be done by placing an +`mkwsMOTDContainer` division on the page next to `mkwsResults` or +`mkwsRecords`. The contents of this element are initially displayed, +but will be hidden when a search is made. + + +### Responsive design + +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` configuration +element to `true`, and `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 + +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 + +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 @@ -162,7 +269,71 @@ 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. + +--- +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_display array + +lang_menu bool + +language_* hash + +pazpar2_url string *Note 2* + +perpage array *Note 3* + +perpage_default string + +perpage_menu bool true + +query_width int + +responsive_design bool + +responsive_design_width int 980 + +service_proxy_auth url + +service_proxy_url string *Note 4* The URL on which the service proxy is accessed. This service must be configured to + provide search results, facets, etc. + +sort array *Note 5* + +sort_default string + +sort_menu bool true + +use_service_proxy bool true +--- + +#### Notes + +1: ["sources", "subjects", "authors"] + +2: /pazpar2/search.pz2 + +3: ### + +4: http://mkws.indexdata.com/service-proxy/ + +5: ### + ### jQuery plugin invocation