X-Git-Url: http://jsfdemo.indexdata.com/?a=blobdiff_plain;f=tools%2Fhtdocs%2Fwhitepaper.markdown;h=6f9e0c7975b89e2407bff24238083db375aabdf1;hb=d722f8bb58a64b8699691a38ea86a64036eabcd9;hp=a91a7de631b6b2c4162c3a94a546bae21665d538;hpb=3c427bf864ee83d27420628f58a036cfd923f4f0;p=mkws-moved-to-github.git
diff --git a/tools/htdocs/whitepaper.markdown b/tools/htdocs/whitepaper.markdown
index a91a7de..6f9e0c7 100644
--- a/tools/htdocs/whitepaper.markdown
+++ b/tools/htdocs/whitepaper.markdown
@@ -273,7 +273,8 @@ 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.
+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
@@ -288,60 +289,236 @@ lang string en Code of the default language to displ
English, `de` = German, `da` = Danish, and whatever additional languages are configured
using `language_*` entries (see below).
-lang_display array
+lang_options array [] A list of the languages to offer as options. If empty (the default), then all
+ configured languages are listed.
-lang_menu bool
+show_lang bool true Indicates whether or not to display the language menu. ### We should get rid of this
+ setting, and simply display the menu if there's an `mkwsLang` element.
-language_* hash
+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*
+pazpar2_url string *Note 2* The URL used to access the metasearch middleware if `use_service_proxy` is false. ###
+ It's silly that you have to provide a different setting depending on whether
+ `use_service_proxy` is set. Should just use pazpar2_url in all cases.
-perpage array *Note 3*
+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
+perpage_default string 20 The initial value for the number of records to show on each page.
-perpage_menu bool true
+show_perpage bool true Indicates whether or not to display the perpage menu. ### We should get rid of this
+ setting, and simply display the menu if an appropriate container is provided.
-query_width int
+query_width int 50 The width of the query box, in characters.
-responsive_design bool
+responsive_design bool false If true, then the facets display moves between two locations as the screen-width
+ varies, as described above. ### This entry should not exist: the design should be
+ responsive whenever `responsive_design_width` has a defined value.
-responsive_design_width int 980
+responsive_design_width int 980 If `responsive_design` is true, this is the threshhold width, in pixels, at which the
+ facets move between their two locations.
-service_proxy_auth url
+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.
-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.
+service_proxy_url string *Note 5* The URL on which the service proxy is accessed if `use_service_proxy` is true. This
+ service must be configured to provide search results, facets, etc.
-sort array *Note 5*
+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
+sort_default string relevance The label of the default sort criterion to use. Must be one of those in the `sort`
+ array.
-sort_menu bool true
+show_sort bool true Indicates whether or not to display the sort menu. ### We should get rid of this
+ setting, and simply display the menu if an appropriate container is provided.
-use_service_proxy bool true
+use_service_proxy bool true If true, then a Service Proxy is used to deliver searching services rather than raw
+ Pazpar2. ### Do we even need this? Can't we just assume that the Service Proxy is in
+ use when and only when `service_proxy_auth` is defined? Alternatively, retain this, but
+ use the same entry to specify the URL in either case.
---
#### Notes
-1: ["sources", "subjects", "authors"]
+1. ["sources", "subjects", "authors"]
-2: /pazpar2/search.pz2
+2. /pazpar2/search.pz2
-3: ###
+3. [10, 20, 30, 50]
-4: http://mkws.indexdata.com/service-proxy/
+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`.
-5: ###
### 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
- - -