Template:Dialog/button
 | This is a dialog formatting template. It is meant for use on interactive dialog pages, and may involve interactions between wiki markup, HTML, and JavaScript. Please carefully test any edits before making them. |
This template sets up a button to perform an action, parameterizing the action by the contents of selected dialog fields on the page. It functions via supporting javascript code.
Usage
Parameters:
- action — required — the name of the action to be performed when the button is clicked.
- label — optional — the text label on the button. If omitted, defaults to the action template parameter. Optional parameters
boldanditalicmay be nonblank to give the label those attributes. - unnamed template parameters — optional — dialog parameters passed to the action target when the button is clicked; currently up to thirty two dialog parameters are supported. Each dialog parameter may be specified in any of three ways.
- A dialog parameter name, a colon, and the id of a dialog field. The value of that field is passed under the given name. Parameter name and id should each be made up of letters, digits, and hyphens.
- A dialog parameter name, alone. The omitted id defaults to the parameter name.
- A dialog parameter name, two colons, and additional text (which may be blank). The additional text is taken to be the literal value for the parameter, as if a dialog field had been declared using {{dialog/textarea}} with the given text as its initial value.
- If the given value contains a colon, it is presumed to be a file name and is also passed to {{hidden use}}. See {{dialog/page}}.
- delegable — optional — if set to
no, the action of the button is not delegated; see below. Delegation is not always possible, and even when possible and not suppressed via this parameter, in the most general case it may be permitted rather than required. - echo — optional — if non-blank, a second button appears after the first, which sends the same dialog parameters to action echo; may aid dialog debugging.
- norollback — optional — if non-blank, and not delegating, the button does not support rollback. Has no effect when delegating.
- rescript — optional — if non-blank, and not delegating, the button removes all cached wikidialog javascript functions before performing the action. Has no effect when delegating. May be used when testing new versions of wikidialog javascript to avoid accidentally mixing new versions of some functions with old versions of others.
- sequence — optional — if non-blank, the button may be triggered automatically as part of an action-sequence.
- live — optional — if non-blank, the button is not disabled when it occurs in a non-live preview.
When practical, use a more specialized template to specify a button, such as {{dialog/view}} or {{dialog/edit}}.
Behavior
When the button is clicked, it attempts to pass the specified dialog parameters to a target page. Ordinarily, the target page name is formed by prefixing Wikibooks:Dialog/ to the action name. The target is required to be fully protected.
If a single dialog field id, specified to be passed by the button, occurs on more than one field on the page, by preference the button uses the value of the first such field after the button (or, failing that, the first such field on the page). This allows data for a button to be stored in fields immediately after the button without worrying about name collisions.
If the action name begins with "User:", the target page name is just the unmodified action name. However, a button with a userspace target will only work if clicked by an admin.
Delegation of the outgoing action means it does not create a new set of dialog parameters, but instead modifies the existing dialog parameters by which the current page is being viewed. This is only possible if the current page view is the result of an incoming dialog action, so that there are existing parameters to modify. Delegation occurs only if not blocked by template parameter delegable and delegation is technically possible; even then the button is only required to attempt to delegate if the target action is the same as the current action. Delegation has two potential advantages. It allows the action to send forward dialog parameters that the current button doesn't know about; and — when the outgoing action is the same as the incoming action — it may allow the outgoing action to take place without reloading the action page or its page-specific javascript, both saving time for page accesses and reducing thrashing of the browser view (no "please wait" message between views).
Example
Wiki markup
{{dialog/button|action=do|verb::view|page:::Indian space agency launches five foreign satellites}}
specifies a button instructing action do to view page "Indian space agency launches five foreign satellites". It specifies dialog parameter verb with literal value view, and dialog parameter page with literal value Indian space agency launches five foreign satellites. It produces
- cols=&rows=&viewxcols=&rows=&:Indian space agency launches five foreign satellitesx
and is equivalent to
{{dialog/button|action=do|verb:button-local-field-verb|page:button-local-field-page}}{{dialog/textarea|id=button-local-field-verb|view|hidden=1}}{{dialog/textarea|id=button-local-field-page|:Indian space agency launches five foreign satellites|hidden=1}}{{hidden use|:Indian space agency launches five foreign satellites}}
Internals
The template sets up a span element of class wikidialog-button, containing the specs for the button. Associated javascript code converts the span element into a button. When the button is clicked, an event handler confirms that the target page is fully protected, then collects the named field values and passes them via sessionStorage (per HTML5) to the target page. Page-specific javascript at the target is responsible for processing the data passed to it.
Javascript code to format dialog fields and buttons is contained in the dialog gadget. Javascript code to retrieve passed data at an action is contained in the receive module.
If a parameter name is specified using a double-colon for a literal value, the value is stored separately from the button itself in a hidden {{dialog/textarea}} field button-local-field-name. (Since these fields are placed immediately after the button, the button picks up their values in preference to any other fields with the same id.)
The template uses several subtemplates (seven, as of this writing). This keeps each template simple enough to maintain with high reliability, which was deemed more important than minimizing template count, although the suite is also organized to minimize the number of calls to {{evalx}}. The primary template itself makes sure template parameter action is non-blank, takes care (once and for all) of all necessary calls to {{dialog/button/1-nam}}, and delegates all remaining operations to {{dialog/button/core}}.