Wikinews:Dialog/do/doc

This is a documentation page for dialog action do.

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 verb selects the operation. If this parameter is omitted, or if its value is unrecognized, operation view is selected.

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

Verb: view

Operation view 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. Page processing has four phases.

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, {{{foo|{{{bar|quux}}}}}} would allow substitution for bar but not for foo). Also, certain template parameters are treated specially; see below.
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.
The page as a whole is template-expanded and formatted for display, per the wiki software.
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 — any dialog parameter whose name starts with an upper-case letter and does not contain any lower-case letters — cannot be passed via buttons and cannot be overridden via {{dialog/init}}; any attempt to pass or override them is ignored.

Local parameters — any dialog parameter whose name starts with local — 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 INCOMING-.

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

INCOMING-AUTHENTICATED is the authenticated origin page name of the incoming request, or undefined if the incoming request isn't authenticated.
REQUESTING-PAGE is the page name of the incoming request, even if not authenticated.
ACTIVE-PARAMETERS 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.
USERNAME is the wikimedia account name under which the user is editing, or blank if the user is not logged in.
USER-GROUPS is a list of the user groups to which the user belongs, separated by spaces.
SUBJECT-EXISTS is either true or false, depending on whether the page named by dialog parameter subject exists.
SUBJECT-CONTENT if fetched is the raw wiki markup content of the subject page.
SUBJECT-TIMESTAMP if fetched is the timestamp of the most recent revision of the subject page.
SUBJECT-CATEGORIES 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.
SUBJECT-FLAGGED if fetched is the flaggedrevs status of the subject page: never, pending, or current.
PRELOAD-PAGENAME is the page name of the preload page associated with the page being viewed.
PRELOAD-CONTENT if fetched is the raw wiki markup content of the preload page, with inclusion directives processed for transclusion.
DIALOG-GADGET-VERSION identifies the in-use version of the dialog gadget.
DIALOG-RECEIVE-VERSION identifies the in-use version of the receive module.
DIALOG-DO-VERSION identifies the in-use version of the do action.

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

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

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

Reserved template parameter EXPANDED-TEXT requests template-expansion of the raw wiki markup contained in non-blank local-text-to-expand.

Various reserved template parameters starting with FILE-INFO- request information about the file whose page is named by file. The request must be confirmed by nonblack local-file-info. Basic information about the unscaled image is placed in reserved parameters FILE-INFO-SIZE, FILE-INFO-WIDTH, and FILE-INFO-HEIGHT. Metadata is placed in reserved parameters starting with FILE-INFO-META-; see mw:API:Imageinfo, particularly extmetadata.

Ordinarily, the title at the top of the page is the name of the page being viewed (per incoming dialog parameter page), and the tabs above it provide actions on the viewed page. If the viewed page is fully protected, non-blank local-page-title overrides this, naming the page appearing as the title and linked by the tabs.

If there are any dialog states saved on the internal stack, the number of them is provided as reserved parameter STACK-DEPTH. If the current page is fully protected, non-blank local-pop 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 local-push 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 INCOMING-PUSH is assigned non-blank, otherwise reserved parameter INCOMING-PUSH-ERROR is assigned an error message explaining the failure.

Verb: edit

Operation edit 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 subject names the page to be modified or created, and form 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 local-basetimestamp and local-creation 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 local-basetimestamp is provided, the subject page must exist and have that timestamp. If local-creation is provided it must have value required, prohibited, or optional; when required the subject page must not exist, when prohibited 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 local-summary.

Further variations of the operation are possible through dialog parameters local-section, local-sectiontitle, local-minor, and local-notminor; see mw:API:Edit#Parameters.

After successful subject modification or creation, if dialog parameter page is provided, all the dialog parameters passed to this action are passed on to verb view. If no dialog parameter page 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 local-error. The action considers passing the dialog parameters to another page, named by appending /error to the name of the form; if this page exists and is fully protected, its name is copied to dialog parameter page 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 STOP SEQUENCE 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:

The page assigns a non-blank value to dialog parameter local-sequence 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}}.

As a corollary of outgoing authentication, the page must be fully protected. local-sequence 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.

Url conversion

If the action page is accessed without a dialog action request, and the access url contains query parameters including one called verb, 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 FIELDS 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 wndialogid; and verb view 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 Wikinews: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 do), at the cost of about two seconds for the intermediate page access.