Help:Dialog

From Wikinews, the free news source you can write!
(Redirected from Help:Wndialog)
Jump to: navigation, search

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 facility is implemented using JavaScript, and is designed to be extensible via additional actions also using JavaScript, while some supplementary functionality is implemented in Lua.

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 {{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; 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 {{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 intial 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 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.

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

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

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

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

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 time and avoiding repeated disruption of the page display with "please wait" messages.

Verb: view[edit]

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, 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 calls 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 localviewerror to a nonblank value, which is passed on to the error-handling page as errormessage.

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.

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.)

Verb: edit[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.

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 consistent with incoming dialog parameters basetimestamp and creation, one or the other of which must be provided.

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 redirects the incoming action request elsewhere.

  • On completion, if an incoming dialog parameter, or {{dialog/init}} field on the form, page is provided, the request is forwarede 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/field page, the user is simply left on the target page.
  • On failure, the incoming request is forwarded, with an error message saved as dialog field errormessage. The preferred forwarding destination is a subpage /onfailure of the form, or if the form doesn't exist, WN:Dialog/edit/onfailure; but this destination is only used if fully protected, otherwise forwarding is to verb echo.

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.

Verb: echo[edit]

The echo verb displays the dialog parameters passed to it, and the authenticated names, if any, of the origin and proxy pages of the incoming action-request. Because this is under the aegis of the do action, it can be delegated to by other verbs without the time and display-disurption of the separate action echo, though it is usually less useful than the separate action since, unlike the separate action, delegation within the do action cannot be undone by using the web browser's back navigation button.

Action: 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 {{dialog/edit|echo=1}} or {{dialog/view|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:Dialog with query parameters added. When using this technique on-wiki, put {{hidden use|WN:Dialog}} 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:Dialog?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:Dialog:

[{{fullurl:WN:Dialog|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:Dialog).

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

Adding new actions[edit]

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 WN: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 WN: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 entire 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: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:Dialog/ 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.