X-Git-Url: http://sru.miketaylor.org.uk/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fmkws-manual.markdown;h=d5332cb95ba1046e48ab2d5bf396120c18d64e62;hb=81ed4f1429a0f6171891d10b384aaace9ef12ec6;hp=429e8ce69a1e1ada5b153a6306f46e98ec3373ce;hpb=9a18fee5262c0f2e21861574e29bc4f3f44ea687;p=mkws-moved-to-github.git
diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown
index 429e8ce..d5332cb 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
@@ -1155,9 +1155,9 @@ 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 `
` with class `term` but only when it occurs inside an
-element with class `mkws-facets`, 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
+Set, it's necessary to understand the structure of the HTML elements that are
+generated within the widgets. The HTML structure is as follows. As in CSS,
+_.class_ indicates an instance of a class. A trailing `*` indicates zero or
+more instances; a trailing `?` indicates zero or one instance.
+
+ .mkws-progress
+ span.mkws-done
+ span.mkws-waiting
+
+ .mkws-search
+ form.mkws-search-form
+ input.mkws-query
+ input.mkws-button
+
+ .mkws-results
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)
+ td.mkws-facets-container-wide
+ div.mkws-facets
+ div.mkws-facet*
+ div.mkws-facet-title
+ div.mkws-term*
+ a
+ span
+ td.mkws-motd-container
+ div.mkws-ranking
+ form
+ select.mkws-sort
+ option*
+ select.mkws-perpage
+ option*
+ div.mkws-pager
+ div
+ div
+ span.mkws-prev
+ span.mkws-current-page
+ a*
+ span.mkws-next
+ div.mkws-navi
+ div.mkws-records
+ div.mkws-summary*
+ div.mkws-field-data
+ span.mkws-field-NAME*
+ div.mkws-details?
table
tbody
tr*
th
td
- #mkwsTargets
- #mkwsBytarget
- table
- thead
- tr*
- td*
- tbody
- tr*
- td*
-
- #mkwsStat
- span.head
- span.clients
- span.records
-
+ tr
+ td
+ div.mkws-facets-container-narrow
+
+ .mkws-targets
+ table
+ thead
+ tr
+ td*
+ tbody
+ tr*
+ td*
+
Appendix: compatibility roadmap
===============================
-FIXME: more to write here.
+Wherever possible, we ensure that all functional changes in MKWS are
+backwards-compatible, so that applications written against old versions of the
+toolkit will continue to work when running against newer versions.
+
+However, a few aspects of functionality unavoidably change in backwards
+incompatible ways. We ensure that **this only happens with new major
+versions** -- so it should _always_ be safe to upgrade to a new minor version.
+As an aid to porting old applications, we here note the specific
+backwards-incompatible changes in the various major releases, and those
+planned for future major releases.
-Old and new-style class-names
------------------------------
+Major version 1.x
+-----------------
-**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`.
+Versions of MKWS before v1.0 (including the only prior release, v0.9.1) 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