X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fmkws-developer.txt;h=693df63ae9a4521c7f29c9881aacee6e8a3a7a3d;hb=a37f91e96993b6ad08502ede33240afd32be33d8;hp=3b0619f45440b96f27246c6a3b53f72b4bf50955;hpb=729fde8d371b1b72f6caf2b7ee6fd3e1bbaaf7e9;p=mkws-moved-to-github.git diff --git a/doc/mkws-developer.txt b/doc/mkws-developer.txt index 3b0619f..693df63 100644 --- a/doc/mkws-developer.txt +++ b/doc/mkws-developer.txt @@ -71,37 +71,46 @@ that you want to specialise from -- in this case, "Records" -- using the promotion function that's been registered for that type. Once this has been done, the specialisations can be introduced. In -this case, it's a very matter of changing the "maxrecs" configuration -setting to 1 unless it's already been given an explicit value. (That -would occur if the HTML used an element like
, though it's not obvious why anyone would do that.) +this case, it's a very simple matter of changing the "maxrecs" +configuration setting to 1 unless it's already been given an explicit +value. (That would occur if the HTML used an element like
, though it's not obvious why anyone +would do that.) WIDGET PROPERTIES AND METHODS ============================= -String this.type -- a string containing the type of the widget. +String this.type + A string containing the type of the widget. -Team this.team -- the team object to which this widget belongs. The - team has several additional important properties and methods, - described below. +Team this.team + The team object to which this widget belongs. The team has + several additional important properties and methods, described + below. -DOMElement this.node -- the DOM element of the widget +DOMElement this.node + The DOM element of the widget -Hash this.config -- a table of configuration values for the - widget. This table inherits missing values from the team's - configuration, which in turn inherits from the top-level MKWS - configuration, which inherits from the default - configuration. Instances of widgets in HTML can set - configuration items as HTML attributes, as in
. +Hash this.config + A table of configuration values for the widget. This table + inherits missing values from the team's configuration, which + in turn inherits from the top-level MKWS configuration, which + inherits from the default configuration. Instances of widgets + in HTML can set configuration items as HTML attributes, as in +
. -String this.toString() -- a function returning a string that briefly - names this widget. Can be useful in logging. +String this.toString() + A function returning a string that briefly names this + widget. Can be useful in logging. -Void this.log(string) -- a function to log a string for debugging - purposes. The string is written on the browser console, and - also published to any "log" subcribers. +Void this.log(string) + A function to log a string for debugging purposes. The string + is written on the browser console, and also published to any + "log" subcribers. + +String this.value() + A function returning the value of the widget's HTML element. TEAM METHODS @@ -116,38 +125,64 @@ Bool team.submitted() Num team.perpage() Num team.totalRecordCount() Num team.currentPage(); -String team.currentRecordId() -- simple accessor functions that - provide the ability to read properties of the team. - -Array team.filters() -- another accessor function, providing access to - the array of prevailing filters (which narrow the search - results by means of Pazpar2 filters and limits). This is - really too complicated an object for the widgets to be given - access to, but it's convenient to do it this way. See the - "Navi" widget, which is the only place it's used. - -Hash team.config() -- access to the team's configuration - settings. There is almost certainly no reason to use this: the - settings that haven't been overridden are accessible via - this.config. +String team.currentRecordId() +String team.currentRecordData() + Simple accessor functions that provide the ability to read + properties of the team. + +Array team.filters() + Another accessor function, providing access to the array of + prevailing filters (which narrow the search results by means + of Pazpar2 filters and limits). This is really too complicated + an object for the widgets to be given access to, but it's + convenient to do it this way. See the "Navi" widget, which is + the only place it's used. + +Hash team.config() + Access to the team's configuration settings. There is almost + certainly no reason to use this: the settings that haven't + been overridden are accessible via this.config. Void team.set_sortOrder(string) -Void team.set_perpage(number) -- "setter" functions for the team's - sortOrder and perpage functions. Unlikely to be needed outside - of the "Sort" and "Perpage" widgets. +Void team.set_perpage(number) + "Setter" functions for the team's sortOrder and perpage + functions. Unlikely to be needed outside of the "Sort" and + "Perpage" widgets. Queue team.queue(eventName) Returns the queue associated with the named event: this can be used to subscribe to the event (or more rarely to publish it). Bool team.targetFiltered(targetId) - - -team.log(string) -team.newSearch(query, sortOrder, maxrecs, perpage, limit, targets, targetfilter) -team.recordElementId(recordId) -team.currentRecordData() -team.renderDetails(recordData) -team.loadTemplate(templateName) -team.resetPage() -team.reShow() + Indicates whether the specified target has been filtered by + selection as a facet. + +Void team.newSearch(query, sortOrder, maxrecs, perpage, limit, targets, targetfilter) + Starts a new search with the specified parameters. All but the + query may be omitted, in which case the prevailing defaults + are used. + +Void team.reShow() + Using the existing search, re-shows the result records after a + change in sort-order, per-page count, etc. + +String team.recordElementId(recordId) + Utility function for converting a record identifer (returned + from Pazpar2) into a version suitable for use as an HTML + element ID. + +String team.renderDetails(recordData) + Utility function returns an HTML rendering of the record + represented by the specified data. + +Template team.loadTemplate(templateName) + Loads (or retrieves from cache) the named Handlebars template, + and returns it in a form that can be invoked as a function, + passed a data-set. + +Some of these methods either (A) are really too low-level and should +not be exposed, or (B) should be widget-level methods. The present +infelicities reflect the fact that some code that rightly belongs in +widgets is still in the team. When we finish migrating it, the widget +API should get simpler. +