Wikinews:Assistant:Context/doc
 |
This page is documentation for the Context assistant. |
| This page is documentation for the Context assistant. |
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 —starting it, or modulating its behavior— is template {{Assistant:Context}}. The primary site of activity for the assistant is page Wikinews:Assistant:Context (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 context-requests that provides a list of parameter names. (For example, a template {{foo}} would request parameters via subtemplate {{foo/context-requests}}.)
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.
subject— required — name of the page to display.context-requests— optional — what parameters to allow and disallow, and what templates have requested what parameters; a wikilisp list of lists. First is a list withtruefollowed by strings naming allowed parameters; second a list withfalsefollowed 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.
context-transform— optional — template to modify the raw wiki markup of the page to display.context-delta— optional — things to add tocontext-requests; a wikilisp list of lists, with the same format ascontext-requests.
The delta parameter is held separate from context-requests until arrival at the assistant page, so that the button originating the view action doesn't have to access context-requests (and, in particular, doesn't have to have access to context-requests). Immediately on arrival here, context-delta is applied to modify context-requests, 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 context-request, and to initialize local-preview-parameters.
The following parameters are automatically whitelisted unless explicitly blacklisted.
USERNAME— account name of the current user.USER-GROUPS— list of groups the current user belongs to, separated by spaces.
Although SUBJECT-CONTENT 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.
The target page content, transformed per context-transform and then augmented per context-requests (as modified by context-delta), is presented via {{dialog/preview}}, with local-preview-parameters initialized according to the computed whitelist.
Internals
[edit]Updating context-requests according to context-delta is delegated to auxiliary template {{Assistant:Context/merge}}. This is done twice: it is needed for {{dialog/init}} both in itself, to locally adjust context-requests; and as an input to {{Assistant:Context/preview}}, to locally determine preview. 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 {{Assistant:Context/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.
Access: template.
Call this template on a page to produce a button that feeds information to templates on that page via the Context assistant (of which this template is a part). The information provided is cumulative; such a button may add a specified template to the list of templates to be informed, and may add some data to the list of information to be provided to templates upon their request.
Parameters:
template— optional — an additional template to be informed.label— optional — the label on the button; if omitted, the label isinform {{{template|}}}.- unnamed parameters — optional — names of dialog parameters to be made available to any informed templates that request them (by passing them through the button and adding them to the whitelist). As of this writing, up to twenty six parameters may be specified (four fewer than supported by {{dialog/view}}).
page— optional — name of the page to be viewed; defaults to current page.transform— optional — name of a template to transform the page content before viewing, replacing any transform already in place; explicit blank means no transform.
Additional templates to be informed may be specified via optional parameters template2, template3, template4.
Test
[edit]cols=&rows=&viewxcols=&rows=&Wikinews:Assistant:Contextxcols=&rows=&Wikinews:Assistant:Context/testxcols=&rows=&( ( true ) ( false ) )x
Internals
[edit]The max number of informing parameters provided by this template is bounded by the capacity of {{dialog/view}}; as of this writing, {{dialog/view}} supports up to thirty dialog parameters, and this template uses up to four administrative dialog parameters, described at Wikinews:Assistant:Context/doc#Wikinews:Assistant:Context. This template delegates construction of outgoing dialog parameter context-delta to subtemplate {{Assistant:Context/delta}}; re the number of templates-to-be-informed supported, see the subtemplate documentation.
Access: template.
This subtemplate of {{Assistant:Context}} constructs dialog parameter context-delta for the parent template, using parameters passed to the parent.
Examples
[edit]| code | output |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Internals
[edit]At this writing, this subtemplate supports specifying up to four additional-templates-to-be-informed. The number four has no special significance; it's a smallish number greater than one. Considering plausible applications, one was deemed not enough. The templates-to-be-informed can't be specified in a single-parameter unbounded list because Module:TScope is pointedly designed to disallow unbounded branching of template calls based on the output of calculation; and a large number of templates-to-be-informed would therefore involve bulkily repetitious wiki markup. Hopefully, four is neither uncomfortable small nor clumsily large.
Access: template.
This auxiliary template for Wikinews:Assistant:Context constructs an updated context-requests list. Parameters:
- first unnamed — required — previously established
context-requestslist, or blank. - second unnamed — required — output of {{Assistant:Context/delta}}.
Examples
[edit]| code | output |
|---|---|
|
|
|
|
|
|
|
|
|
Access: template.
This auxiliary template for Wikinews:Assistant:Context constructs the content to be previewed. Parameters:
- first unnamed — required — the
context-requestslist to be applied. - second unnamed — required — the content to be previewed.
Examples
[edit]| code | output |
|---|---|
|
|
|
Internals
[edit]If a template call to a requesting template occurs within a call to another requesting template, only the outermost of those calls is provided with requested parameters.
Parameters when provided are placed before explicit parameters, so that explicit parameters override those provided.
This is where the whitelist and blacklist are applied; elsewhere the whitelist, blacklist, and requests are propagated uncritically. Any changes to the whitelist or blacklist therefore have the potential to alter the effect of pre-existing requests, in keeping with the conceptually global nature of whitelists and blacklists.