Wikibooks:Dialog/do/doc

Behavior
This dialog action performs any of several operations. Putting all these operations within a single action enables much faster sequential operations, because there is no need for separate page loads between operations.

Incoming dialog parameter  selects the operation. If this parameter is omitted, or if its value is unrecognized, operation  is selected.

If the action page is not accessed through a dialog action request, but the access url contains query parameters including one called, the url query parameters are converted into a dialog action request.

Verb: view
Operation  displays a specified page, with modifications to the display based on incoming dialog parameters. The page to be displayed is named by incoming dialog parameter. Page processing has four phases.
 * 1) If the specified page asks for a template parameter with the name of a provided dialog parameter, the template parameter is substituted for.  Template parameters are ignored if they contain nesting (thus,  would allow substitution for   but not for  ).  Also, certain template parameters are treated specially; see below.
 * 2) Any calls to dialog/init are processed, possibly overriding incoming dialog parameter values, but without effect on template-parameter substitution since that has already occurred.
 * 3) The page as a whole is template-expanded and formatted for display, per the wiki software.
 * 4) If any interactive dialog field on the specified page has the same name (id) as an incoming dialog parameter (or provided via dialog/init), the value of the parameter is substituted in as the initial content of that interactive field.

Reserved parameters &mdash; any dialog parameter whose name starts with an upper-case letter and does not contain any lower-case letters &mdash; cannot be passed via buttons and cannot be overridden via dialog/init; any attempt to pass or override them is ignored.

Local parameters &mdash; any dialog parameter whose name starts with  &mdash; cannot be passed directly via buttons, but can be set via dialog/init; any local parameter provided by the requester is converted to a reserved parameter by shifting its name to all upper-case and prefixing.

Various reserved parameters are substituted for with values extracted from elsewhere. Some of them are always assigned when available; others are not fetched unless they occur as template parameters (but once fetched, they're available to initialize dialog fields, as well).
 * is the authenticated origin page name of the incoming request, or undefined if the incoming request isn't authenticated.
 * is the page name of the incoming request, even if not authenticated.
 * is a list of dialog parameters just explicitly passed by a button; the list is both -separated and  -delimited.  This can be used to distinguish parameters deliberately set from parameters carried along by delegation.
 * is the wikimedia account name under which the user is editing, or blank if the user is not logged in.
 * is a list of the user groups to which the user belongs, separated by spaces.
 * is either  or , depending on whether the page named by dialog parameter   exists.
 * if fetched is the raw wiki markup content of the subject page.
 * if fetched is the timestamp of the most recent revision of the subject page.
 * if fetched is a list of the names of all categories to which the subject page belongs, delimited by double-quotes and separated by spaces.
 * if fetched is the flaggedrevs status of the subject page:,  , or.
 * is the page name of the preload page associated with the page being viewed.
 * if fetched is the raw wiki markup content of the preload page, with inclusion directives processed for transclusion.
 * identifies the in-use version of the dialog gadget.
 * identifies the in-use version of the receive module.
 * identifies the in-use version of the  action.

A non-blank value for  via dialog/init initiates delegation to an error-handling page, whose name appends   to the name of the current dialog page. Since any incoming dialog parameter starting with  is diverted to a reserved parameter,   can only be non-blank via dialog/init. Delegation requires that the name of the current dialog page not end with, and that the error-handling page exist. The current field values are delegated to the error-handling page (except that  becomes the name of the error-handling page). The error-handling page receives the  of the delegating page, and its  ; the local parameter is diverted, per above, to reserved parameter.

Several reserved template parameters starting with  request information about the revision history of the page named by. The request must be confirmed by non-blank  through dialog/init. Information is gathered on up to 50 revisions. The data is placed in reserved parameters,  ,  ,  ,  , and  ; each is an  -delimited list of the named data for each revision. can specify the direction of listing, with value  listing revisions by increasing time,   by decreasing time. If there are more revisions after those reported,  contains a value that can be used to request further revisions, in a later request for page history, by placing the value in.

Several reserved template parameters starting with  request information about the members of the category whose page is named by. Remember to include prefix  in the page name. The request must be confirmed by non-blank  through dialog/init. Information is gathered on up to 50 members, and placed in reserved parameters,  , and  ; each is an  -delimited list of the named data for each member. ,, and   can modulate the resultant list; see mw:API:Categorymembers. If there are more members after those reported,  contains a value that can be used to request further revisions, in a later request for category members, by placing the value in.

Reserved template parameter  requests template-expansion of the raw wiki markup contained in non-blank.

Various reserved template parameters starting with  request information about the file whose page is named by. The request must be confirmed by nonblack. Basic information about the unscaled image is placed in reserved parameters,  , and. Metadata is placed in reserved parameters starting with ; see mw:API:Imageinfo, particularly.

If there are any dialog states saved on the internal stack, the number of them is provided as reserved parameter. If the current page is fully protected, non-blank  names another incoming dialog parameter; if the named parameter is non-blank, an attempt is made to "pop" a state from the stack, i.e., remove the most recent saved state from the stack and enter that state. Otherwise, if the current page is fully protected, non-blank  names an incoming dialog parameter and if the named parameter is non-blank, an attempt is made to "push" the dialog state from which the current request was made, i.e., save it onto the top of the stack. Push is only allowed if the current request did not delegate and the stack was not already full. If the push succeeds, reserved parameter  is assigned non-blank, otherwise reserved parameter   is assigned an error message explaining the failure.

Verb: edit
Operation  modifies or creates a specified page, mediated by a form page that determines both permissibility of the action and new content of the modified or created page. Dialog parameter  names the page to be modified or created, and   names the mediating page. These two parameters are required. The form page must exist and must be fully protected.

The incoming action request must be authenticated against the form viewed in noinclude mode. That is, the form page must transclude template dialog/null requirement or dialog/require origin to specify where the incoming action request is permitted to come from. Template parameters and dialog/init calls are processed as for verb view. When not authenticating, best practice introduces an explicit call to dialog/require origin (so that even a surreptitiously inserted dialog/null requirement cannot induce authentication).

Dialog parameters  and   specify the expected pre-existing status of the subject page. One or the other, but not both, must be provided, necessarily via dialog/init since they're local. If  is provided, the subject page must exist and have that timestamp. If  is provided it must have value ,  , or  ; when   the subject page must not exist, when   the subject must exist.

For the new content of the subject page, the form is loaded as if transcluded at the subject page. Again, template parameters and dialog/init calls are processed as for verb view. dialog/init calls are processed before noinclude directives, so they are unaffected by choice of transcluding page. A custom edit summary for use on success may be provided through dialog parameter.

Further variations of the operation are possible through dialog parameters,  ,  , and  ; see mw:API:Edit.

After successful subject modification or creation, if dialog parameter  is provided, all the dialog parameters passed to this action are passed on to verb view. If no dialog parameter  is provided, the user is left viewing the modified/created page.

If the action tries, but fails, to authenticate, a custom error message may be provided through dialog parameter. The action considers passing the dialog parameters to another page, named by appending  to the name of the form; if this page exists and is fully protected, its name is copied to dialog parameter   and the dialog parameters are passed to verb view. If that page doesn't exist or isn't fully protected, or if the action fails for some other reason, 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.

Action sequences
Under circumscribed conditions, a single button click can cause a series of actions without further user intervention. This is a potent capability and should be used with caution, as a significant amount of damage could be caused by a single click. During an ongoing action-sequence, a button appears at the top of the page, which does not abort an action already in the pipeline but prevents the sequence from continuing (after an apparent lag of one or two actions before the stop button takes effect).

The maximum action-sequence length as of this writing is 10 actions (the minimum necessary to avoid the "small" feeling of single-digit numbers). A viewed page automatically triggers the next action in a sequence if all of the following conditions are met: As a corollary of outgoing authentication, the page must be fully protected. therefore cannot be forged since dialog/init only functions when it occurs directly on the page; and as long as one sequence-button is provided on the page, the sequence cannot be hijacked by transcluding an additional button (through some unprotected template used on the page) because a sequence does not proceed when presented with multiple sequence-buttons.
 * The page assigns a non-blank value to dialog parameter  via dialog/init.
 * Exactly one button on the page is marked as a sequence button; see dialog/button.
 * The sequence button delegates to action do.
 * The page has outgoing authentication.
 * The page does not use dialog/preview.

Url conversion
If the action page is accessed without a dialog action request, and the access url contains query parameters including one called, the url query parameters are converted into a dialog action request.

If the link to the action page is followed from within a page view via verb view, the link is converted, when clicked, into a delegating action request. In this case, a query parameter  may specify a comma-separated list of fields to be passed through the action request as if by a button; these may also use colon-notation as a button to pass a field value under a different parameter name.

Otherwise, a new action ID number is usually allocated for the converted dialog action request. Action ID numbers distinguish different action requests from each other, so that dialog data can be stored under that ID, and one can navigate one's web browser away from the request, come back to it, and (up to a point) the stored data is recovered. A non-delegating button click embeds a freshly allocated ID number in the url of the action page access, in a query parameter called ; and verb   does the same for any url-based action query linked on the viewed page. However, a querying url does not contain an embedded ID; so if you navigate away from it and come back, a fresh action request is issued with a freshly allocated action ID.

Pseduo-action Dialog provides a more general, but slower, form of url conversion. That pseudo-action is capable of generating an authenticated action request, always allocates a fresh ID and accesses the resulting url, and always produces a url with restorable state, for any action (not just ), at the cost of about two seconds for the intermediate page access.