Wikibooks:Assistant

The assistants under this parent page are sets of interactive pages to aid human users in performing various tasks — from newcomers to experts, from everyday tasks to things that might come up every few years. List them here as we write them. They are also categorized at Category:Interactive assistants.

There are some important conventions for writing assistants at the bottom of this page; eventually one would hope for one or more assistants to help with building and maintaining assistants.

List of assistants

Stand-alone

• Breadboard (doc)

Conventions

• Use the {{SITENAME}} magic word for the namespace of dialog actions. This avoids hardwiring the name of the project into pages that might later be used, or adapted for use, on other projects. Global assistants also use that namespace, and if explicitly referring to it the magic word should be used, but other templates usually take care of that, as described below.
• All the pages of a given assistant are subpages of one parent, the assistant root page; or are in template space with corresponding names. The assistant main page and all its subpages belong to a category for the assistant, while the templates belong to a subcategory, and the documentation pages belong to another subcategory.

• There are two naming schemes for assistant main pages, global and local.
• A global main page name has the form {{SITENAME}}:Assistant:<name>. Subpages are {{SITENAME}}:Assistant:<name>/...; templates are Template:Assistant:<name>/... or occasionally Template:Assistant:<name>. The assistant category is Category:Assistant:<name>. Categorization of assistant pages is orchestrated through template {{AssistantCat}}.
• A local main page is a subpage of a (non-assistant) page <page> in any namespace except Template or Category. The main page name has the form <page>/Assistant:<name>. Subpages are <page>/Assistant:<name>/...; templates are Template:<page>/Assistant:<name>/... or occasionally Template:<page>/Assistant:<name>. The assistant category is Category:<page>/Assistant:<name>.
• There are magic word templates to derive the associated assistant page name forms for the assistant that the current page belongs to: {{ASSTDOC}} gives the name of the assistant documentation main page, {{ASSTROOT}} of the assistant main page; {{ASSTCATEGORY}} of the assistant category; {{ASSTTEMPLATE}} of the base name for the assistant's templates. {{ASSTTEXT}} returns a text description of the assistant. (There are also a few others.)

• There are four kinds of assistants:

• Direct assistants. The assistant is a template providing controls to immediately perform simple functions on the transcluding page.
• Framing assistants. The principal assistant page is accessed only through the view verb, and uses {{dialog/preview}} to display a modified form of a target page to be acted on.
• Single-page stand-alone assistants. The assistant consists primarily of a single page, whose layout is substantially not that of a target page (contra framing assistants).
• Multipage stand-alone assistants. The assistant has multiple distinct primary pages.

Any of these may have some subsidiary pages; the distinction between them is different primary emphasis.

• Root page:

• For direct assistants, the root page should be a redirect to the template. Use template {{assistant/direct}} on the template's documentation page.
• For framing assistants, the root page should be the primary framing page; the view verb deliberately does not support a redirected target. Use template {{assistant/framing}}. The corresponding template page usually provides a button to invoke the framing assistant on the transcluding page.
• For single-page stand-alone assistants, the root page should be a content page, as there's no reason to make things more complicated with a redirect. Use {{dialog/ifsupported}} for graceful behavior when accessed directly as a wiki page, and {{assistant/single}}.
• For multipage stand-alone assistants, the root page should be a redirect to a subpage, so all the major content pages in the assistant are on the same level. Categorize the redirecting root (via {{AssistantCat}}, as usual).

• The redirect target should use {{dialog/ifsupported}} for graceful behavior when accessed directly as a wiki page, and {{assistant/viewable}}. Consider naming it {{ASSTROOT}}/start; a recognizable standard name is desirable, since any button entering the assistant via the view verb must target the subpage directly.

• Primary documentation page:

• Always subpage {{ASSTROOT}}/doc, except that if the assistant is direct, this should redirect to the template documentation.
• If the primary page is a redirect for a multipage assistant, the primary documentation page should have a section for each subpage and template. These sections should be consistent with documentation of the individual pages; this can be effected via {{assistant/extract doc}}.
• If the primary page is instead a content page, links to key subpages and templates in the See also section of the documentation should suffice.

• Some pages of an assistant are meant to be accessed by naming them to the view verb; some pages are meant to be transcluded onto another page; and some are made to be accessed either way. Most of the following principles are concerned with managing these different access modes, with their different behaviors.
• Subpages and templates:

• On a subpage, use {{assistant/viewable}}.
• When transcluding, always pass into it all of its input parameters that are available.
• When using a parameter via markup {{{...}}}, don't nest another template parameter in its default value, such as {{{foo|{{{bar}}}}}}. Non-nesting preserves substitutability by dialog parameters, since dialog parameters are (as of this writing) only substituted for non-nested template parameters.
• When specifying a data field corresponding to an input parameter, specify the template parameter as an initial value, such as {{dialog/text|id=foobar|{{{foobar|}}}}}. This works for any combination of page viewed or transcluded, parameter passed by template or not, and parameter passed by dialog or not.
• When specifying a button on any page, always explicitly pass out of it all its input parameters (except things like SUBJECT-CONTENT that aren't passed through an action request). If any of these parameters isn't stored locally as a data field (e.g., via {{dialog/text}} on the current page), explicitly specify the template parameter as a value for the outgoing dialog parameter, such as {{dialog/button/view|...|foobar::{{{foobar|}}}|...}}. This works for, again, any combination of page viewed or transcluded, parameter passed by template or not, and parameter passed by dialog or not.

• Documentation pages for subpages and templates:

• Documenting a subpage, use {{assistant/documentation}}.
• Documenting each page of a multipage assistant, maintain a list of the input parameters it may use, not distinguishing between template parameters and dialog parameters.
• Documenting a template, use {{assistant/template}}.
• Documenting a dialog edit form, use {{assistant/form}}.
• To display documentation correctly when transcluded at the assistant's main documentation page, for page-relative references use {{OBJECTPAGENAME}}.

See also

• List of related general-purpose templates