Help:Dialog

The dialog facilities enable building interactive, dynamic wiki pages. The facilities have two main parts: a set of templates used to specify interactive elements on a wiki page, and a set of versatile "actions" that can be directed by those interactive elements.

Using the facilities is meant to involve writing only wiki markup, so the interactive pages can be developed and maintained by the wiki community.

From the user's perspective, interactive pages allow data to be entered through dialog boxes and similar input elements, and allow this data to flow to input elements of other pages, to template parameters, and to actions.

Internally, the core of the facilities is implemented using JavaScript, and is designed to be extensible via additional actions also using JavaScript, while some supplementary functionality is implemented in Lua (cf. {{evalx}}).

Higher-level interactive assistants are based on these facilities.

Page elements

Interactive wiki pages are arranged using a number of templates, which are gathered together in Category:Dialog formatting templates.

Fields

Four kinds of input fields are supported: text, textarea, select, and checkbox. These are specified using, respectively, templates {{dialog/text}}, {{dialog/textarea}}, {{dialog/select}}, and {{dialog/checkbox}}.

Each template requires a parameter id=name specifying a name for the field. In theory, each ID must be unique amongst input fields on that page, and if two input fields on the same page have the same ID, Something Bad may happen. In practice, sometimes there's no good way to guarantee uniqueness; but there's a technique that prevents Bad Things from happening in the most usual case, explained below under buttons.

A text field is a one-line text input box. Optional parameter size=width specifies how many characters wide the box should be; this affects how the box is displayed, but not how large its content can be. Optionally, an unnamed parameter specifies the initial content of the text box; by default, the box is initially empty.

 

{{dialog/text|id=foo-text|size=10}}   would produce:   size=10&x

A textarea field is a multi-line text input box. Optional parameters cols=width and rows=length specify how many columns wide and how many rows long the box should be; this affects how the box is displayed, but not how large its content can be. On some web browsers, the box is always the same width, no matter what width may be specified. Optionally, an unnamed parameter specifies the initial content of the textarea box; be default, the box is initially empty.

 

{{dialog/textarea|id=bar-textarea|rows=2|cols=10|content}}   would produce:   cols=10&rows=2&contentx

A select field is a menu of options to choose from. Unnamed parameters specify the options. The unnamed parameters come in pairs: one parameter specifies an option that appears on the menu, and the next parameter specifies the internal value selected by that menu item. Initially, the first option is selected.

 

{{dialog/select|id=baz-select|one|1|two|2|three|3}}   would produce:   one&1&two&2&three&3&

A checkbox field is an on/off value that can be toggled. Its internal value is either "yes" or "" (blank). Optional parameter checked=non-blank causes the checkbox to be initially on; otherwise, it is initially off.

 

{{dialog/select|id=quux-checkbox}}   would produce:   checked=

Buttons

Buttons are generally specified using template {{dialog/button}}. More specialized templates are provided for creating buttons of some specific kinds, and may be used whenever suitable for the intended purpose.

The function of a button, when clicked, is to send data to an action. Template parameter action=name specifies the name of the action. Optional template parameter label=text specifies what text appears on the button; by default, the button is labeled with the name of the action. Unnamed template parameters specify dialog parameters to be passed to the action.

Each dialog parameter is specified in one of three ways. First, the template parameter may be simply the ID of a dialog field on the page, in which case, when the button is clicked, the content of that field is passed to the action as a dialog parameter whose name is the ID of the field. Second, the content of the field may be passed to the action under a different name, by specifying the different name, a colon, and the field's ID. Third, the name of the dialog parameter, to be passed to the action, may be followed by two colons, and then a value to be passed under that name, as if the value had been specified as the initial value of a {{dialog/textarea}} from which the value was then drawn (which is what happens, internally). If the specified value contains a colon, it is presumed to be the name of a page, and is linked via {{hidden use}}; if the value is known to be a page name, but might not contain a colon, use {{dialog/page}} to guarantee a colon. Specialized templates are provided for some types of buttons; as of this writing, {{dialog/view}} and {{dialog/edit}}, described in the view and edit verb sections below.

 

{{dialog/button|action=echo|foo-text|bar-textarea|baz-select|quux::42}}   would produce:   action=echo&label=echo&foo-text&bar-textarea&baz-select&quux:button-local-field-quux&‍cols=&rows=&42x

Sometimes a template needs to generate a dialog field simply to hold a value for use by a generated button — though you probably won't have to set this up yourself, since {{dialog/button}} already handles values this way. To prevent the holder field from cluttering the page, use {{dialog/textarea}} parameter hidden=non-blank. However, in such cases, there may be no good way to guarantee a field ID unique for the entire page. To ensure the button finds the correct field despite a possibly-redundant field ID, put the field immediately after the button; when a button looks up the value of a dialog field with a given ID, it starts looking at the point where the button occurs in the page, and takes the first field it finds with the correct ID, only looking at the start of the page if it doesn't find any such fields later than the button.

An optional template parameter delegable=no prevents the button from delegating its action to the target — which it would otherwise try to do. Delegation by a button is only possible if the current page is being viewed by means of an action; at present, this action would have to be do. Instead of passing to its target action just those dialog parameters specified by the button, a delegating button modifies the dialog parameters that were passed to the current view, and passes this modified set of dialog parameters to its target action.

• Even when delegation is technically possible and is permitted by the delegable template parameter, the button is only required to attempt to delegate if the target action is the same action by which the current page is being viewed. The do action only delegates in this required case.
• When the current and target actions are the same, delegation avoids making a fresh action-page access, which both saves time and server load, and avoids disruptively replacing the current view with a "please wait" message before displaying the target view.
• Dialog parameters received by the current view, but not specified by the button, are passed to the target during delegation. The target view may be able to take advantage of these additional dialog parameters when delegation makes them available.
• A potential drawback of delegation is that, because delegation destructively updates the received dialog parameters, the current view cannot then be recovered by clicking the "back" nagivation button on your web browser; "back" will usually take you to the most recent page view that did not delegate to its successor view.

Optional template parameter echo=non-blank causes a second button to appear next to the primary button, identical to the first except that its target action is action echo; this aids in debugging a dialog, by allowing the dialog composer to see what data is passed by the button and whether or not the outgoing action-request is authenticated.

Authentication

When an action is requested to do something with significant consequences, the action may require some proof that the request is legitimate. This is done using action-request authentication provided by the dialog software. An authenticated action-request comes from a button-click originating on a page satisfying all four of these criteria:

• The origin page must either be an action page, or be displayed by an action page. Currently, the only supported action that displays another page is do.
• The origin page must be fully protected.
• The origin page must contain one or more template calls specifying what, if anything, must be authenticated about the incoming action-request that caused the origin page to be displayed. These templates are explained below.
• The action responsible for displaying the origin page must internally call for authentication. This internal call is both how the action determines whether its incoming action-request satisfies the page's requirements, and how the action provides authentication of its outgoing action-requests.

Requirements on incoming action-requests are specified via templates {{dialog/null requirement}} and {{dialog/require origin}}.

• {{dialog/null requirement}} does not require any authentication of the incoming action-request.
• {{dialog/require origin}} requires an authenticated incoming action-request from one of a fixed list of allowed origins; these allowed origins are named by unnamed template parameters. An optional template parameter proxy=name indicates that the origin page is displayed by the named action page, rather than the origin being itself an action page.

If multiple incoming-authentication template calls are used on a single page, all of these template calls must be satisfied in order to authenticate the incoming action-request. In particular, if {{dialog/require origin}} is called with no unnamed template parameters, the incoming action-request cannot be authenticated no matter what other calls occur on the page.

Note carefully that authentication is of an action request; any particular action page view is potentially concerned with two separate requests — an incoming request, whose origin is whatever page was viewed before the current one, and potentially some outgoing request, whose origin is the current page. Authentication of the incoming request depends entirely on the previously viewed page; authentication of outgoing requests depends on the current page, including its use of aforementioned templates {{dialog/null requirement}} and {{dialog/require origin}}.

Ifsupported

If a page uses dialog facilities, often it matters to design the page to behave reasonably if the user's browser doesn't support the dialog facilities. This is done using template {{dialog/ifsupported}}. The template takes two unnamed parameters. If the dialog facilities are available, the first template parameter is visible while the second template parameter is hidden. If the dialog facilities are not available, the first template parameter is hidden while the second is visible.

Actions

The actions performed by buttons are embodied by pages with names of the form Wikibooks:Dialog/action, where action is the name by which the button invokes the action. The actions are gathered together in Category:Dialog actions.

Action: do

The do action performs any of several different functions, selected by incoming dialog parameter verb. Putting all these functions under a single action allows delegation from one function to another, saving much time (probably one or two seconds per button click) and avoiding repeated disruption of the page display with "please wait" messages.

Verb: view

The view verb displays a page in an ongoing dialog sequence, allowing the displayed content to depend on preceding dialog.

Incoming dialog parameter page names the page to display, with incoming dialog parameters substituted for template parameters on the displayed page; and if the displayed page has any dialog field with the same name as an incoming dialog parameter, the incoming value becomes the initial value of the dialog field.

Incoming dialog parameter values ordinarily are not interpreted as wiki markup. Template {{dialog/preview}} interprets the value of incoming dialog parameter preview as wiki markup.

The view verb specially handles incoming dialog parameters REQUESTING-PAGE, INCOMING-AUTHENTICATED, USERNAME, USER-GROUPS, SUBJECT-EXISTS, SUBJECT-CONTENT, SUBJECT-TIMESTAMP, SUBJECT-CATEGORIES, and SUBJECT-FLAGGED. REQUESTING-PAGE names the page from which the action request came; INCOMING-AUTHENTICATED is non-blank iff the incoming action request is authenticated. USER-GROUPS names all the user groups the viewing user belongs to, delimited by double-quotes and separated by spaces. SUBJECT-* provide information about the page named by incoming dialog parameter subject.

View asks for outgoing authentication, but specifying authentication requirements (via {{dialog/null requirement}} or {{dialog/require origin}}) is the responsibility of the displayed page, and view proceeds regardless of whether authentication succeeds.

When specifying a button with do/view and a fixed page to be displayed, template {{dialog/view}} may be used instead of generic template {{dialog/button}}. The specialized template takes care of the action and verb and loudly objects if not given template parameter page.

The displayed page may request that the view verb be diverted to display instead an error-handling page; this is typically done if incoming dialog parameters fail some validation check. The error-handling page appends /error to the name of the displayed page. The diversion request is honored only if the requesting page name does not end with "error", and the error-handling page exists. Diversion is requested by using {{dialog/init}} to set dialog field local-error to a nonblank value; following standard handling of local parameters, the error-handling page can access the value at reserved incoming dialog parameter INCOMING-LOCAL-ERROR. Revision-history information about the page named by subject can be requested through reserved parameters starting with SUBJECT-HISTORY-; members of a category named by category can be requested through reserved parameters starting with CATEGORY-MEMBERS-; metadata on a file named by file can be requested through reserved parameters starting with FILE-INFO-; and wiki markup can be template-expanded through reserved parameter EXPANDED-TEXT; with all these advanced queries regulated through local parameters specified via {{dialog/init}}.

When viewing a page via do/view, the page name displayed at the top of the page is the name of the displayed page, and the tabs refer to the viewed page (history, edit, etc.); a small parenthesized wikilink to the right of the title provides access to the action page. At the time of this writing, related links on the sidebar (such as WhatLinksHere) still refer to the action page rather than the displayed page.

If you navigate away from viewing a page —by means other than delegation— the do action saves the values of dialog fields in the display. If you back up to return to the displayed view, the values of the dialog fields are automatically restored to what they were when you left. Only a certain number of these saved page-states are kept, so if you do a bunch of other things before coming back, the data may have been discarded; but, for an important example, if the displayed page contains a {{dialog/button}}, you could click the echo button to see what values are being passed, then back up to click the primary button without having to reenter all the field values on the displayed page. (This wouldn't work, though, if the {{dialog/button}} were on a page being viewed directly rather than via do/view.)

A dialog page may require the user to a confirmation question (cancel/OK) before viewing the page through the view verb, via template {{dialog/confirm view}}.

If the destination of a view request is fully protected, it can request to save the requesting dialog state for later restoration, or to restore a dialog state saved that way, using fields specified through {{dialog/init}} (see here).

Verb: edit

The edit verb modifies or creates a page, based on a mediating form that determines whether the operation is permissible and, if so, what the new content of the edited page is to be. The page to be modified or created is named by incoming dialog parameter subject, and the mediating page by incoming dialog parameter form; these incoming dialog parameters must be provided by the requester.

The operation is permissible only if the incoming request satisfies outgoing authentication requirements specified on the form as a standalone page (thus, including <noinclude> blocks but not <includeonly> blocks). The form should therefore usually contain a noinclude block calling {{dialog/require origin}} or {{dialog/null requirement}}; permission for the edit operation may be denied by conditional transclusion of {{dialog/require origin}} with no parameters (which prohibits authentication regardless of any other conditions transcluded). The operation is also witheld if the status of the target page — existence, and timestamp if existing — is inconsistent with incoming dialog parameters local-basetimestamp and local-creation, one or the other of which must be provided via {{dialog/init}}.

The new content of the subject page is determined by substituting for template parameters as does the view verb, interpreting the form as if transcluded on the subject page (thus, omitting noincluded blocks), and expanding templates. In effect, the form thus computes the new content for the subject.

On completion or failure, the edit verb may redirect the incoming action request elsewhere.

• On completion, a custom edit summary may be provided through incoming dialog parameter local-summary. If an incoming dialog parameter page is provided, the request is forwarded to verb view; view thus receives the same dialog parameters provided to edit, as modified by any {{dialog/init}} calls on the form. On completion in the absence of a parameter page, the user is simply left on the target page.
• On failure because the form doesn't authenticate, a custom error message may be provided through incoming dialog parameter local-error. If the form has a fully protected subpage /error, the incoming request is forwarded to that subpage; following standard handling of local parameters, the subpage can access the custom error message at reserved incoming dialog parameter INCOMING-LOCAL-ERROR.
• On other failures, an error message is reported to the user and, if possible, the user is returned to the dialog state from which the edit request was made. If the previous dialog state cannot be restored, a list of options is provided, advising the user on what to do next.

When specifying a button with do/edit and a fixed mediating form, template {{dialog/edit}} may be used instead of generic template {{dialog/button}}. The specialized template takes care of the action and verb and loudly objects if not given template parameter form.

Action: echo

The echo action displays the dialog parameters passed to it, and the authenticated names, if any, of the origin and proxy pages of the incoming action-request. This may be useful for debugging a dialog, as with {{dialog/edit}} or {{dialog/view}}; see above.

Action sequences

A dialog can be set up to perform a series of actions in response to a single button click. This power is strictly limited, and alternatives should be carefully considered before resorting to it.

When the user manually clicks a button, an upper bound is set on the length of action-sequence that can be performed before another manual click is required; as of this writing, this bound is initially 10 actions. When viewing a page, if this sequence bound is greater than zero, and the page is appropriately marked, with a single button on the page designated for sequence use, that button is triggered automatically and the sequence-length bound is decremented. For details, see Wikibooks:Dialog/do/doc#Action sequences.

URLs to invoke actions

An action-request can be encoded as a URL, so that loading the URL in your browser issues a request to the action. The url consists of a page link with query parameters added. The page link may be to either Wikibooks:Dialog/do or Wikibooks:Dialog; using Wikibooks:Dialog/do is faster, usually by about two seconds, and can mimic some of the behaviors of a delegating button, although Wikibooks:Dialog covers some edge cases not handled by Wikibooks:Dialog/do.

With page Wikibooks:Dialog/do, query parameter verb=verb is required, naming the verb requested. Additional query parameters specify other dialog parameters to be passed to the action. Do not use a parameter name action, as the wiki software would try to interpret this. Query parameters are suffixed to the url, with a ? before the first parameter and a & between consecutive parameters. For example:

[//en.wikibooks.org/wiki/Wikibooks:Dialog/do?verb=view&page=Help:Dialog]

Alternatively, you could use the {{fullurl:...}} magic word to assemble a url like this, if you don't mind that this technique also passes a spurious parameter title=Wikibooks:Dialog/do:

[{{fullurl:{{SITENAME}}:Dialog/do|verb=view&page=Help:Dialog}}]

Query urls based on Wikibooks:Dialog/do are "unstable" in the sense that if, having visited such a url either from off-wiki or from a wiki page viewed directly (rather than through action do), one navigates away from it and then back to it, the query is converted to a fresh action request; any dialog data previously associated with the page view is lost. On the other hand, when these urls are used from within a page viewed through Wikibooks:Dialog/do verb view, the url when clicked is converted automatically into a delegating action request (though as of this writing it doesn't authenticate the delegating request). When delegating this way, a reserved query parameter FIELDS can specify fields on the page to pass through the action request similarly to a button (see here).

With page Wikibooks:Dialog, query parameter dialog-action=action is required, naming the action requested. The Wikibooks:Dialog pseudo-action converts the url into an action request (internally, it actually constructs a non-delegating button and automatically clicks it). For example:

[//en.wikibooks.org/wiki/Wikibooks:Dialog?dialog-action=echo&foo=one&bar=two]

Ordinarily the generated action-request is not authenticated. With page Wikibooks:Dialog, specifying a query parameter dialog-confirm=non-blank alters the behavior of the url, so that instead of immediately issuing an unauthenticated request, it instead presents a button for the user to click, with the proposed dialog parameters displayed below the button, and the button when clicked issues an authenticated action request (with origin Wikibooks:Dialog).

[//en.wikibooks.org/wiki/Wikibooks:Dialog?dialog-action=echo&foo=one&bar=two&dialog-confirm=yes]

Diagnostic panel

At any given moment there may be several sets of dialog data held in storage on your local client, so that if you navigate back (not too far) to a dialog page, the data that was there when you left will still be there when you get back. A diagnostic panel is provided to allow you to browse through the contents of all these these sets of data. The panel also has an expert mode allowing access to additional internal meta-data about those data sets, and in some cases allowing access to tentative sets of dialog data that haven't been fully committed to the central system.

Adding new actions

Admins can create new actions. This is most likely when developing an upgrade for an existing action (almost certainly action do). The facilities are intended to provide a small powerful set of highly versatile actions, carefully limited by safety checks such as fully protected pages and action-request authentications; those creating new actions are strongly encouraged to maintain this strategy.

An action is defined by two pages.

• The public face of the action is page Wikibooks:Dialog/action, where action is the name used to specify the action to {{dialog/button}}. This page should contain a call to {{dialog/action page}}, contained in an html div element allowing convenient replacement of the 'please wait' message when the action is invoked, and categorized in Category:Dialog actions with a suitable sort key. For a canonical example, see Wikibooks:Dialog/do.

Template {{dialog/action page}} on the action page provides a link for creating an action documentation page, to describe the behavior of the action.

• The JavaScript implementation of the action's behavior is page MediaWiki:Common.js/w/Wikibooks:Dialog/action. (The project is configured in MediaWiki:Common.js so that when loading any page page, JavaScript MediaWiki:Common.js/w/page is executed.) The basic skeleton of the JavaScript for an action, and instructions for invoking various dialog facilities within the JavaScript, are provided at MediaWiki talk:Dialog/receive. Admins undertaking to code new actions should study the JavaScript of the existing actions.

Development of a new action should be done in userspace. Ordinary users cannot invoke actions in userspace, but admins can. If a button specifies an action page in user space, no prefix Wikibooks:Dialog/ is added, and only admins are allowed to click the button (non-admins who try get an error alert message). Each dialog action may have a menu of test pages, which can be used by admins to test an alternative to the action in user space. Once the action is ready to deploy, it can be recreated in project space.