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.

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.

 

{{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/checkbox|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" 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 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 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 <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|echo=1}} or {{dialog/view|echo=1}}; 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 Wikinews: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 Wikinews:Dialog/do or Wikinews:Dialog; using Wikinews:Dialog/do is faster, usually by about two seconds, and can mimic some of the behaviors of a delegating button, although Wikinews:Dialog covers some edge cases not handled by Wikinews:Dialog/do.

With page Wikinews: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.wikinews.org/wiki/Wikinews: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=Wikinews:Dialog/do:

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

Query URLs based on Wikinews: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 Wikinews: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 Wikinews:Dialog, query parameter dialog-action=action is required, naming the action requested. The Wikinews: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.wikinews.org/wiki/Wikinews:Dialog?dialog-action=echo&foo=one&bar=two]

Ordinarily the generated action-request is not authenticated. With page Wikinews: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 Wikinews:Dialog).

[//en.wikinews.org/wiki/Wikinews: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. The three-column collapsible inspection display at the bottom of each view panel can help the user track the internal state of the dialog. More generally, a diagnostic panel is provided to allow you to browse through the contents of all these sets of data currently held in session storage. 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 Wikinews: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 Wikinews: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/Wikinews:Dialog/action. (The project is configured in MediaWiki:Common.js so that when loading any page page, JavaScript MediaWiki:Common.js/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 Wikinews:Dialog/ is added, and only admins are allowed to click the button (non-admins who try to 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.

Internal architecture

Dialog state, which consists mostly of dialog parameters, is kept in session storage, which is maintained by the client's web browser. In contrast, template parameters are processed entirely by the wiki server, as an integral part of rendering wiki markup into HTML (the first phase of which is template expansion). The internal architecture of the dialog software is mostly about arranging smooth integration of the client-side dialog state into the functioning of the server-side wiki platform.

In a URL to access a wiki page, the three main parts (after the protocol prefix, http:// or https://) are the domain, page name, and query parameters. The domain tells internet nodes what server to send the request to. The page name tells the server what specific resource is being requested; usually a wiki page, although the server also provides some "special pages". The query parameters, if included, are interpreted by the server as modulating how the resource is to be accessed; by default, the server renders the wiki markup of the page into HTML and sends the HTML back across the internet to the client, whereas, for example, query parameter action=edit requests a panel for editing the wiki markup of the page. If the URL includes query parameters that the server doesn't recognize, the server ignores them; but they are still there in the URL, available to be found on inspection by the dialog JavaScript running client-side. The dialog software uses a single query parameter, wikidialogid. For each dialog action (canonically a page view), the incoming parameters and other state in session storage are indexed by a non-negative id number, and when running the dialog JavaScript for a particular action, the javascript retrieves dialog state under the index specified by the wikidialogid of the current URL.

Two different hooks in the Wikimedia platform are used to run JavaScript to support dialog.

For one, there is a dialog gadget (MediaWiki:Gadget-wikidialog.js). It is not possible to directly specify input fields or buttons, nor the JavaScript to be run when a button is clicked, using HTML embedded in wiki markup, because the wiki platform filters out most HTML tags from the raw wiki markup (as a matter of security). The gadget compensates for this. Allowed HTML does include <span> elements (with certain attributes being allowed through), and dialog formatting templates such as {{dialog/button}} generate span elements containing the information needed to set up the appropriate HTML element. After the page is rendered, the JavaScript dialog gadget runs on the client, first replacing these span elements with suitable input elements and buttons; and then implementing the behavior for {{dialog/ifsupported}} by toggling visibility of the elements generated by the template, so that if the gadget doesn't run, the first parameter remains hidden and the second parameter remains visible. The gadget also attaches to each button the JavaScript to be run when the button is clicked. On click, this code does some simple validation of the action page (it has to exist and be fully protected, and has to have the usual sort of name unless it's in userspace and the requesting user is an admin); looks in a central session-storage location for the next unused ID number, using this number to construct a suitable URL for the action-request, and incrementing the centrally stored next-id-number; collects the appropriate dialog parameters (and a bit of other state) and stashes them under the ID used for the constructed URL; and loads the constructed URL.

The second JavaScript hook is needed to execute the JavaScript that implements the behavior of an action when it is requested. Each wiki page view runs a common JavaScript file universal to the project, MediaWiki:Common.js. A small piece of code in this common JavaScript file enables each page on the wiki to have its own custom JavaScript file that is executed just when that particular page is viewed. (Like all the JavaScript for dialog, these page-specific javascript files are in Mediawiki: space, so that they can only be created or modified by users with the interface administrator privilege; the precise naming convention for page-specific javascript files may vary between projects, and is regulated by {{dialog/js prefix}}.) The page-specific JavaScript for an action follows a simple pattern to check for, and load if not already present, the receive module (MediaWiki:Dialog/receive), which is most notably responsible for retrieving the dialog parameters-and-state from session storage.

Nontrivial actions are usually oriented toward a specific wiki page; e.g., a page to be viewed, or an edit form. Incoming dialog parameters may feed into this target page in two ways — one for feeding forward into dialog on the page, and one for feeding into the template processing of the page. If the target page is to be viewed, and therefore can have input fields on it, each of these input fields has an identifying name, and when this identifying name matches the name of an incoming dialog parameter, the input field is set to the value of the dialog parameter. If the target page has markup to receive template parameters —delimited by triple curly braces, {{{}}}— (provided they aren't nested, such as {{{1|{{{2}}}}}}) the dialog software splices in the value of the dialog parameter in place of the template parameter; this splicing, handled by the receive module, is the primary means by which client-side dialog data is injected directly into server-side wiki processing.

In the generic case, as described, dialog parameters are passed through an action-request button-click which stashes them in session storage indexed by the id. However, there are deviations from this basic behavior.

• In delegation (discussed from an external perspective above under buttons), there is no fresh loading of an action page. The action page itself doesn't usually play any fundamental role in the action behavior; it's the page-specific JavaScript that's needed; so if the action being requested is the same one already in-progress, and if it's tolerable to discard the current dialog state, one can effectively overwrite the dialog state under the current ID with the state for the new action-request — so-called "delegation". This also has the often-convenient property that the old incoming dialog-parameters for that id are left intact if not explicitly overwritten by the new button-click, so that the delegating request modifies the previous dialog state rather than erasing it.
• Incoming dialog fields can be simulated on a target page by means of {{dialog/init}}. The simulated value is not placed in session storage but is instead kept in a JavaScript data structure; however, because the value expression to {{dialog/init}} is expanded before other parts of the page, the simulated parameter can be used elsewhere on the page, either to initialize an input field or to inform a template parameter. Because these value parameters are expanded —a server-side operation— separately from the rest of the page, each call to {{dialog/init}} requires an additional client-server handshake across the internet, adding perhaps a second or two (in well-connected areas) to the total time for the action; it is therefore undesirable to use multiple {{dialog/init}} calls on a target page. This is, on the other hand, the most robust general way to inject the output of server-side template-expansion into client-side dialog processing. The absence of the simulated parameter from session storage means its value disappears at the next button-click unless deliberately preserved; on can set up a hidden input field to hold the value, and then explicitly pass that hidden field on the next button-click to get it into session storage.
• Reserved dialog parameter names —anything starting with an upper-case letter and not containing any lower-case letters— can only be provided by the dialog software itself. The software ignores any attempt to pass these as parameters or to simulate them via {{dialog/init}}. When the dialog software makes information available for use by a target page, it uses a reserved dialog-parameter name.

• Local dialog parameter names —anything starting with "local-"— cannot be passed, but can be simulated via {{dialog/init}}. When the dialog software needs to be given information by the target page, and be sure that it has been explicitly handled by the target page rather than leaving it to some preceding page in an ongoing process (above and beyond authentication of the incoming request), the dialog software requires the information to be provided under a local parameter name.

  Although local parameters cannot be passed in the conventional sense, they are transmuted through a button into reserved parameters; the name of each local parameter is converted to upper-case and prefixed by INCOMING-. (E.g., suppose a page contains {{dialog/init|local-quux|baz}} and an outgoing button to some other page. The page has to be viewed through dialog for the local parameter to be generated; if, while viewing it via dialog, a user clicks the button, the destination page receives a reserved parameter INCOMING-LOCAL-QUUX with value baz.)

Source

The underlying JavaScript files for the dialog tools are found here:

• Category:Dialog javascript pages
  • MediaWiki:Gadget-wikidialog.js (main gadget script)
  • MediaWiki:Dialog/receive (receive module)
  • MediaWiki:Common.js/Wikinews:Dialog/do (do action, through which everything goes)

Installation instructions

Please see MediaWiki talk:Dialog/receive#Dialog installation for installation instructions.