+Event passing
+-------------
+
+The primary method of communication between components of the widget
+set -- specifically, between teams and their widgets -- is event
+passing. Widgets subscribe to named events; when something relevant
+happens (such as the reception of a message from metasearch
+middleware), the event is published, along with the relevant data. All
+widgets that susbcribed to the event are then notified, and can take
+appropriate action.
+
+Different kinds of events have different data associated with
+them. This data is passed when the event is published, and so is made
+available to the subscribing code.
+
+The possible events, and their associated data, are described
+[below](#events).
+
+
Defining new types of widget
----------------------------
* You can add functionality to a widget by subscribing it to an
event's queue using `this.team.queue("EVENT").subscribe`. The
argument is a function which is called whenever the event is
- published. The arguments to the event-callback function are
- different for different events.
+ published.
* As with so much JavaScript programming, the value of the special
variable `this` is lost inside the `subscribe` callback function,
Events
------
-FIXME: list of events that can be usefully subscribed to.
-
+The following events are generated by the widget-set code:
+
+* `authenticated` (authName, realm) --
+ When authentication is completed successfully, this event is
+ published to _all_ teams. Two parameters are passed: the
+ human-readable name of the library that has been authenticated
+ onto, and the correponding machine-readable library ID.
+
+* `ready` --
+ Published to _all_ teams when they are ready to search. No
+ parameters are passed. This event is used to implement
+ automatic searching, and should probably not be used by
+ application code.
+
+* `stat` (data) --
+ Published to a team when a `stat` response is reveived from
+ Pazpar2. The data from the response is passed as a parameter.
+
+* `firstrecords` (hitcount) --
+ Published to a team when the first set of records is found by
+ a search. The number of records found (so far) is passed as
+ the parameter.
+
+* `complete` (hitcount) --
+ Published to a team when a search is complete, and no more
+ records will be found (i.e. all targets have either responded
+ or failed with an error). The final number of records found is
+ passed as the parameter.
+
+* `targets` (data) --
+ Published to a team when a `bytarget` response is reveived from
+ Pazpar2. The data from the response is passed as a parameter.
+
+* `facets` (data) --
+ Published to a team when a `term` response is reveived from
+ Pazpar2. The data from the response is passed as a parameter.
+
+* `pager` (data) --
+ Published to a team when a `show` response is reveived from
+ Pazpar2. The data from the response is passed as a
+ parameter. This event is used to update the pager, showing how
+ many records have been found, which page is being displayed,
+ etc.
+
+* `records` (data) --
+ Also published to a team when a `show` response is reveived
+ from Pazpar2. The data from the response is passed as a
+ parameter. This event is used to update the displayed records.
+
+* `record` (data) --
+ Published to a team when a `record` response is reveived from
+ Pazpar2 (i.e. the full data for a single record). The data
+ from the response is passed as a parameter.
+
+* `navi` --
+ Published to a team when a new search is about to be
+ submitted. This is a signal that the navigation area, showing
+ which filters are in effect, should be updated. No parameter
+ is passed: the event handler should consult `team.filters` to
+ see what the prevailing set is.
+
+* `log` (teamName, timestamp, message) --
+ Published to a team when a message is about to be logged to
+ the console for debugging. Three arguments are passed: the
+ name of the team that generated the log message, a timestamp
+ string, and the message itself. Note that this event is _not_
+ published when the widget-set core code generates a log
+ message -- only when a team or a widget does.
- - -