Help:Dialog

You can install and test Dialog tools at your wiki, if you have access to MediaWiki namespace. This will allow you to write interactive wiki pages to streamline routine or confusing page editing tasks. For details, see #Source, or ask a question here.

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.

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; by default, the box is initially empty.

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.

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.

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 simply be 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.

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" navigation 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. Authentication is provided by the software only if the origin page—from which a button-click requested the action—has asked for its outgoing requests to be authenticated, and the software finds that the requesting page satisfies all prerequisites.

The origin page must satisfy 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 specify what criteria it requires for authentication of its outgoing requests. The origin page can use any sort of logic for this, but ultimately the origin page must express its choice by using template calls to tell the dialog software what, if anything, to require of the incoming action-request to the origin page. 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. (Thus, if some of the content of the page is transcluded from some other unprotected page, this additional content may prevent authentication that would otherwise have occurred, but cannot cause authentication that would not otherwise have occurred.) Authentication can be prevented entirely by calling {{dialog/require origin}} with no unnamed template parameters, since this requires an incoming authenticated request from some page listed on a empty list of admissible pages.

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. (Note that both parameters are present on the page, although only one of them is visible.)

Actions

The actions performed by buttons are embodied by pages with names of the form Wikinews: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 the 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 if 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 the dialog field local-error to a nonblank value; following standard handling of local parameters, the error-handling page can access the value at a 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|echo=1}}, 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|echo=1}} were on a page being viewed directly rather than via do/view.)

To help keep track of the state of an ongoing dialog, at the bottom of the view panel is a three-column diagnostic display, collapsed by default, by which the user can inspect the dialog parameters passed to the view, the parameters as locally customized, and any current internal diagnostic messages.

A dialog page may require the user to answer 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 blocks but not