Help:Wndialog

From Wikinews, the free news source you can write!
Jump to: navigation, search

Wndialog is a set of facilities for building interactive, dynamic wiki pages. It has 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 facility is implemented using javascript, and is designed to be extensible via additional actions also using javascript.

Page elements[edit]

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

Fields[edit]

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

Each template requires a parameter id=name specifying a name for the field. Each id must be unique amongst input fields on that page; if two input fields on the same page have the same id, Something Bad may happen.

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; be 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[edit]

Buttons are generally specified using template {{wndialog/button}}. More specialized templates are provided for creating buttons of some specific kinds, and should 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 the content of a dialog field on the page. The unnamed template parameter specifies this field in either of two ways. The template parameter may be simply the unique id of the field, 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. Alternatively, the content of the field may be passed to the action under a different name, by specifying the different name, a colon, and then the field's unique id.

It is also possible to set up a button so that, in addition to the contents of the dialog fields visible on the page, it will also pass to its action some constant dialog parameters that are not visible on the page. This may be done using a specialized button template, such as {{wndialog/edit}} or {{wndialog/subst}}, described in the subst and edit action sections below. The most general way to do it is to create hidden fields on the page, whose initial content cannot be changed since the user cannot see the field to change it. A hidden field is specified by a textarea with an additional template parameter hidden=non-blank. When using this technique, if the constant value is the name of an existing page, you should also pass the name of that page to template {{hidden use}}.

Optional template parameter delegable=non-blank gives the button permission to delegate its action to the target. 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 subst. 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 subst 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 receieved 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.

Authentication[edit]

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 wndialog 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 action that displays another page is subst.
  • 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 {{wndialog/null requirement}} and {{wndialog/require origin}}.

  • {{wndialog/null requirement}} does not require any authentication of the incoming action-request.
  • {{wndialog/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.

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 {{wndialog/null requirement}} and {{wndialog/require origin}}.

Ifsupported[edit]

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

Actions[edit]

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

Subst[edit]

The subst action is a tool to display pages in ongoing dialog sequences. It allows the displayed content of a page to depend on preceding dialog.

Subst displays the page named by incoming dialog parameter page, with incomng 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 {{wndialog/preview}} interprets the value of incoming dialog parameter preview as wiki markup.

The subst action specially handles incoming dialog parameter INCOMING-AUTHENTICATED, and template parameters SUBJECT-CONTENT and SUBJECT-TIMESTAMP. INCOMING-AUTHENTICATED is non-blank iff the incoming action request is authenticated. SUBJECT-CONTENT and SUBJECT-TIMESTAMP provide information about the wiki page named by incoming dialog parameter subject.

Subst calls for outgoing authentication, but specifying authentication requirements (via {{wndialog/null requirement}} or {{wndialog/require origin}}) is the responsibility of the displayed page, and subst proceeds regardless of whether authentication succeeds.

When specifying a button with action=subst and a fixed page to be displayed, use template {{wndialog/subst}} instead of generic template {{wndialog/button}}. The specialized template takes care of the hidden data field and hidden wikilink as described above. In addition, the specialized template takes an optional template parameter echo=non-blank which causes a second button to appear next to the subst button, identical to the subst button except that its target action is 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.

The displayed page may request that the subst action be diverted to display instead an error-handling page; this is typically done if incoming button data fields fail some validation check. Such diversion requests are honored only if the requesting page name does not end with "error", the requested error handling page name does end with "error", and both pages are fully protected. The recommended template for this purpose is {{wndialog/iferror}}; more primitive template {{wndialog/handle error}} may also be used, but in doing so don't forget to link the error-handling page via {{hidden use}}.

When viewing a page via action subst, the page name displayed at the top of the page is the name of the displayed page, with a small parenthesized wikilink called "dialog" to its left. That wikilink is for editing the displayed page (or viewing its content, since if the displayed page may be part of an authenticated dialog and would therefore be fully protected); one cannot use the edit tab at the top of the page for this purpose, as that tab would edit (or view) the subst action page rather than the displayed page.

If you navigate away from viewing a page via subst, the subst 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 example, if the displayed page contains a {{wndialog/subst|echo=1}}, you could click the echo button to see what values are being passed, then back up to click the subst button without having to reenter all the field values on the displayed page. (This wouldn't work, though, if the {{wndialog/subst|echo=1}} were on a page being viewed directly rather than via subst.)

Edit[edit]

The edit action modifies or creates a page, based on a specified template with incoming dialog parameters substituted for template parameters. The page to be modified or created is named by incoming dialog parameter target, and the template by incoming dialog parameter preload; these incoming dialog parameters must be provided. The preload template is treated as if transcluded on the target page; thus, <noinclude> blocks do not appear on the target page.

This action has four restrictions:

  • It refuses to act unless the incoming action-request is authenticated; this is a stronger condition than imposed by {{wndialog/null requirement}}, though weaker than {{wndialog/require origin}}.
  • It refuses to act unless the preload template is fully protected.
  • It refuses to act unless the incoming request satisfies outgoing authentication requirements specified on the preload template as a standalone page (thus, including <noinclude> blocks but not <includeonly> blocks). The preload template should therefore usuallly contain a noinclude block calling {{wndialog/require origin}}; in theory the block could contain {{wndialog/null requirement}} instead, but caution is recommended since arbitrarily modifying pages should not be done lightly.
  • It refuses to act unless the status of the target page — existing versus not-existing, and timestamp if existing — is consistent with incoming dialog parameters basetimestamp and creation. Without incoming parameter creation, the target page must either match the specified timestamp, or not exist if no timestamp is specified. Incoming parameter creation should be used with caution; it can be used to allow, or require, editing of a pre-existing page with unspecified timestamp.

On completion or failure, this action redirects the incoming action request elsewhere.

  • On completion, if an incoming dialog parameter page is provided, the incoming request is redirected to action subst; subst thus receives all the same dialog parameters provided to edit. On completion in the absence of an incoming dialog parameter page, the user is simply left on the target page.
  • On failure, the incoming request is redirected, with an error message saved as dialog parameter errormessage. If an incoming dialog parameter onfailure is provided, the incoming request is redirected to action subst viewing the named page (the value of dialog parameter onfailure is copied to dialog parameter page); otherwise, the incoming request is redirected to action echo.

When specifying a button with action=edit and a fixed page to be displayed, use template {{wndialog/edit}} instead of generic template {{wndialog/button}}. The specialized template takes care of the hidden preload data field and hidden wikilink as described above. In addition, the specialized template takes an optional template parameter echo=non-blank which causes a second button to appear next to the edit button, identical to the edit button except that its target action is 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.

Echo[edit]

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 {{wndialog/edit|echo=1}} or {{wndialog/subst|echo=1}}; see above.

URLs to invoke actions[edit]

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 link to page WN:Wndialog with query parameters added. When using this technique on-wiki, put {{hidden use|WN:Wndialog}} on the invoking page to make the use easy to find.

Query parameter dialog-action=name names the action to request. Additional query parameters specify 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:Wndialog?dialog-action=echo&foo=one&bar=two]

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:Wndialog:

[{{fullurl:WN:Wndialog|dialog-action=echo&foo=one&bar=two}}]

Ordinarily the generated action-request is not authenticated. 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 WN:Wndialog).

[//en.wikinews.org/wiki/Wikinews:Wndialog?dialog-action=echo&foo=one&bar=two&dialog-confirm=yes]

Adding new actions[edit]

Admins can create new actions. 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 WN:Wndialog/action, where action is the name used to specify the action to {{wndialog/button}}. This page should contain a call to {{wndialog/action page}}, contained in an html div element allowing convenient replacement of the ambox when the action is invoked, and categorized in Category:Dialog actions with a suitable sort key. For a canonical example, see WN:Wndialog/subst.
Template {{wndialog/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:Wndialog/action. (The entire site is configured 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 wndialog facilities within the javascript, are provided at MediaWiki talk:Wndialog/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 WN:Wndialog/ is added, and only admins are allowed to click the button (non-admins who try get an error alert message). Once the action is ready to deploy, it can be recreated in project space.