User:Eyes/BoilerRoom extension

Plans

 * I intend to write up a more wiki adimin/regular user-oriented manual later, but it'll be on this wiki.
 * I'll be removing most of the content from this page once I have images up on the copy here.
 * I intend to release it on http://www.mediawiki.org as well.

Installation

 * 1) Download from http://sw.aeongarden.com/wiki/index.php?title=Extension:BoilerRoom
 * 2) Extract this extension to the  subdirectory of your MediaWiki installation directory.  It should be contained in a   subdirectory within.
 * 3) If your wiki has custom namespaces using the indexes 300 and 301, add the following line to  (changing   to an unused even index, ensuring that the following index is also unused):
 * 4) Add the following line to .  Due to the unique nature of the boilerroom tag used by this extension, it is advisable to include this line before any other extension includes to prevent unexpected interactions (but make sure it is placed after the   line if that is needed):
 * 1) Add the following line to .  Due to the unique nature of the boilerroom tag used by this extension, it is advisable to include this line before any other extension includes to prevent unexpected interactions (but make sure it is placed after the   line if that is needed):

Configuration
As of version 0.9, the only configuration option is the following:
 * Sets the index at which the Boilerplate namespace will be created. By default, this is 300.  The Boilerplate talk namespace will be created at the following index, which is 301 by default.
 * Sets the index at which the Boilerplate namespace will be created. By default, this is 300.  The Boilerplate talk namespace will be created at the following index, which is 301 by default.

Overview
BoilerRoom is a dynamic text preloading extension that has the ability to load text from boilerplate pages into the edit textbox of new pages. With AJAX enabled on the server and JavaScript enabled on the user's browser, boilerplate text can even be loaded on existing pages. The extension provides a boilerplate selector on edit pages for this purpose. It also allows you to create input boxes on wiki pages that allow users to input a title and open a new page for edit with the boilerplate text preloaded into the edit box.

Creating boilerplate articles
The  tag is used to define the start and end of boilerplate articles. This is a unique, deliberately non-compliant tag with special behavior designed to prevent the need for any kind of text escaping within the boilerplate content. Specifically, it has the following behavior:


 * You must use  and   exactly as written here.  Though spaces are permissible inside a compliant XML tag, this isn't a compliant tag.  It is also case-sensitive.
 * Only the first  tag and last   tag on the page are considered.
 * This allows you to place even  tags into the content.
 * Additionally, tags such as  and   don't require any unusual escaping.  They are treated as plain-text content within   tags.
 * The boilerplate content opens at the first line after the  tag and closes at the end of the final line before the   tag.  Content on the same lines as the tags is simply ignored if it is between the tags.

Or to show this information visually: Header text describing the boilerplate may be placed here, as well as any other wikicode. It will appear when directly viewing boilerplates and when transcluding them like templates. &lt;boilerroom&gt; Text here is simply ignored and will not appear. This line is where the boilerplate text begins.

&lt;boilerroom&gt; Since only the first opening and last closing tags are considered, boilerroom tags inside the boilerplate text are treated as plain text and will be included as part of the boilerplate without modification. &lt;/boilerroom&gt;

&lt;includeonly&gt; and similar tags are also treated as plain text within the boilerroom tags and will be included in boilerplate text without modification, so it even works well for providing a boilerplate (or multiple) for templates. &lt;/includeonly&gt;

This line is where the boilerplate text ends. Whereas this text is simply ignored.&lt;/boilerroom&gt;

You can place any footer text here you wish, and this is a good spot for any categories you want to include the boilerplate article itself in. That can be done in the header as well.

The three-button selector
The three-button BoilerRoom selector, shown below, appears above the edit textbox on every page if the wiki has AJAX enabled and the user has JavaScript enabled.



It shows only the articles available within the Boilerplate namespace, excluding any redirects. As you can see, it does not display the  portion of the title. Note, though, that even articles without  tags will be displayed as options, but nothing will happen when a user tries to include text from these pages; therefore, you should avoid allowing any non-boilerplate articles within the Boilerplate namespace.

As shown above, users have the ability to load boilerplate content before any existing text, after any existing text, or over existing text by replacing it. Be warned that most browsers will not record this as an undoable action, and as such, the extension asks for confirmation before replacing the existing text.

Note that the three-button selector is the only way BoilerRoom provides for using boilerplates on existing pages.

The one-button selector
The one-button BoilerRoom is shown when AJAX is not enabled on a wiki, or when a user does not have Javascript enabled. This selector only appears and functions on new pages, and unlike the other selector, it must reload the page to function. It does not function dynamically and cannot load boilerplate text over existing content.

The BoilerRoomBox
BoilerRoom also provides the BoilerRoomBox, shown below, which functions very similarly to the one-button selector described above. The most important difference is that the BoilerRoomBox is not automatically displayed anywhere, but is included on pages through the use of the  and   tags or the   and   parser functions. ( and   are synonyms for each other and function identically.)



The usage of either the tag or the parser function is a matter of preference most of the time, but if you want to include a BoilerRoomBox as a parameter to a template, you'll need to use one of the two parser functions. The interactions between the tag form and the parser function may also differ with the tags and parser functions of other extensions, and this is why both forms are included.

The syntax for each is similar, as shown here side-by-side. Tag form &lt;boilerroombox&gt; boilerplate= title= label= align= width= &lt;/boilerroombox&gt; Parser function form

For the tag form, each parameter needs to be on its own line, with the end of line signifying the end of a value. For the parser function version, the pipe symbol signifies the end of the value and must be used between each parameter.

All of the parameters, explained below, are optional.


 * This identifies the article to preload into the edit box. It only loads content defined by   as explained above.  If a namespace isn't included, the Boilerplate namespace is assumed.  To use an article in the Main namespace, prefix the title with a colon .  If none is including, this simply opens the requested page for normal editing and may be handy for skipping the search page when one wishes to proceed directly to the edit page.
 * This identifies the article to preload into the edit box. It only loads content defined by   as explained above.  If a namespace isn't included, the Boilerplate namespace is assumed.  To use an article in the Main namespace, prefix the title with a colon .  If none is including, this simply opens the requested page for normal editing and may be handy for skipping the search page when one wishes to proceed directly to the edit page.


 * This is the default title that appears in the box. It is probably best used to indicate a suggested prefix or suffix for the type of article it is used to create.  The default is an empty box.
 * This is the default title that appears in the box. It is probably best used to indicate a suggested prefix or suffix for the type of article it is used to create.  The default is an empty box.


 * This is the text that appears on the button which opens the requested page for editing. The default label is "Edit".
 * This is the text that appears on the button which opens the requested page for editing. The default label is "Edit".


 * The align can be,   or  .  This is applied as a CSS rule, so   is also a valid value.  There is no default; if not included, no   rule is applied.
 * The align can be,   or  .  This is applied as a CSS rule, so   is also a valid value.  There is no default; if not included, no   rule is applied.


 * The size of the title entry box measured in number of characters. The default is 30.
 * The size of the title entry box measured in number of characters. The default is 30.

Note that like the one-button selector, this cannot automatically load boilerplates on existing pages. It does, however, automatically select the requested boilerplate in the three-button selector if the conditions are right for that selector to appear (AJAX and Javascript enabled).