Wikinews:Assistant:Context/doc

This is a dialog-based framing assistant to support context-sensitive templates in displaying a page.

The core idea is that a template, called on a subject page, wants more information than is explicitly provided by parameters specified on the subject page; perhaps even information that isn't available on the subject page but may be available when the page is viewed; so it requests the information, and the dialog may provide requested information to it through additional template parameters injected during page view.

The primary means of wielding the assistant &mdash;starting it, or modulating its behavior&mdash; is template undefined. The primary site of activity for the assistant is page (as usual for a framing assitant).

The central facility of the frame allows templates to request certain parameters be provided to the template even though not explicitly specified by the call on the subject page. The template must be called directly on the subject page (so that the call is in the subject's unexpanded wiki markup); and the template requests the information through a subtemplate that provides a list of parameter names. (For example, a template would request parameters via subtemplate .)

To enable the frame to apply this central facility in a general way, the frame can be told to use some transform template to modify the raw markup of the subject page before possibly-adding parameters and displaying it.

The assistant frames a subject page by accessing the primary assistant-page via dialog view. Parameters to the assistant specify which templates may receive dialog parameters upon request, and which dialog parameters are and are not to be provided upon request. When admissible, the assistant adds the appropriate parameters to the template calls in the raw wiki markup for the view (after transform, if specified); from a requesting template's perspective, the added parameters are ordinary template parameters.

Access: viewable.

Inputs:
 * The first two inputs are most basic for understanding how the assistant works.


 * &mdash; required &mdash; name of the page to display.
 * &mdash; optional &mdash; what parameters to allow and disallow, and what templates have requested what parameters; a wikilisp list of lists. First is a list with   followed by strings naming allowed parameters; second a list with   followed by strings naming disallowed parameters; after those two, each later list starts with a string naming a template followed by strings naming parameters it has requested.
 * Other parameters may be provided for use-on-request by templates.
 * &mdash; optional &mdash; template to modify the raw wiki markup of the page to display.
 * &mdash; optional &mdash; things to add to ; a wikilisp list of lists, with the same format as.

The delta parameter is held separate from until arrival at the assistant page, so that the button originating the view action doesn't have to access  (and, in particular, doesn't have to have access to ). Immediately on arrival here, is applied to modify, before computing the current view.

Requestable parameters are those whitelisted (that is, included on the first list of strings), plus some automatically added (see below), minus any blacklisted (that is, excluded by the second list of strings). The resulting whitelist is used both to filter parameter-requests from templates before adding them to, and to initialize.

The following parameters are automatically whitelisted unless explicitly blacklisted. Although is available, it isn't whitelisted by default because for large pages it can be quite expensive to inject multiple copies of the raw wiki markup of the page, so should require some deliberation.
 * &mdash; account name of the current user.
 * &mdash; list of groups the current user belongs to, separated by spaces.

The target page content, transformed per and then augmented per  (as modified by ), is presented via dialog/preview, with  initialized according to the computed whitelist.

Internals
Updating  according to  is delegated to auxiliary template /merge. This is done twice: it is needed for dialog/init both in itself, to locally adjust ; and as an input to /preview, to locally determine. Calling an ordinary template twice is effectively free, performance-wise, compared to calling dialog/init twice, because each call to dialog/init requires a separate two-way client-server exchange across the internet (which is why dialog/init supports compound definiends, to define multiple localized parameters via a single call). In theory, one might imagine calling dialog/init once to compute /preview and store the value, then calling dialog/init again to use that previously computed value; but such mutual dependencies between calls to dialog/init are discouraged and accordingly are not made easy to arrange, both because multiple calls to dialog/init are undesirable and because the logic would be unavoidably difficult to follow.