MediaWiki

Extension:BoilerRoom: Difference between revisions

Browse history interactively
← Older edit
Content deleted Content added
VisualWikitext
OoEyes (talk | contribs)
42 edits
No edit summary
Replaced content with "{{Archived extension|6065449}}"
Tag: Replaced
 
(31 intermediate revisions by 12 users not shown)
Line 1:
{{Archived extension|6065449}}
{{Extension
|name = BoilerRoom
|status = stable
|type1 = parser function
|type2 = tag
|type3 = extended syntax
|hook1 = EditFormPreloadText
|hook2 = EditPageBeforeEditToolbar
|hook3 = LanguageGetMagic
|hook4 = ParserBeforeStrip
|hook5 = ParserFirstCallInit
|username = OoEyes
|author = Shawn Bruckner
|description = Allows wiki users to create boilerplate text in the Boilerplate namespace which can then be used on new pages.
|image =
|imagesize =
|version = 1.23
|update = 2013-12-21
|mediawiki = 1.16.x - 1.21.x
|php =
|needs-updatephp = No
|license = {{EL|GNUGPL2}}
|download = [http://sw.aeongarden.com/download/BoilerRoom-1.23.zip external source]
|readme =
|changelog =
|parameters = * $wgbrNamespaceIndex
* $wgbrUseLargeSelector
|tags = <p></p>
* boilerplate
* boilerroombox
* brbox
|rights =
|example =
|compatibility =
|bugzilla =
}}
 
'''BoilerRoom''' is a extension that allows you to create boilerplate article text, like document templates in a word processor, and easily load them in the edit textbox when using the source editing feature.
 
More technically speaking, it is a dynamic text preloading extension which 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 onto 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 editing with the boilerplate text preloaded into the edit box.
 
BoilerRoom is different in its approach from similar extensions in that it was designed to allow the creation of boilerplate text without any need for text escaping. It deliberately does not respect <tt>&lt;includeonly&gt;</tt>, <tt>&lt;onlyinclude&gt;</tt>, and <tt>&lt;noinclude&gt;</tt> tags, instead providing its own mechanism through the special behavior of the provided <tt>&lt;boilerplate&gt;</tt> tag. This behavior simplifies certain situations, such as creating boilerplates for templates, where unusual escape mechanisms like &lt;include&lt;includeonly&gt;only&gt; would be necessary to achieve the same effect. Other <tt>&lt;boilerplate&gt;</tt> tags can be even placed inside without any need for an escape mechanism.
 
__TOC__
== Compatibility ==
 
{| class="wikitable"
|-
!Version !!Release date !!Known compatibility<ref>There is a good chance BoilerRoom versions 1.01 and earlier are compatible with MediaWiki versions before 1.16.5, but this has not been tested. Compatibility with versions after 1.19 is not yet tested.</ref>
|-
|1.23 (Latest) ||2013 December 21 ||MediaWiki 1.17 to 1.21
|-
|1.22 ||2013 October 21 ||MediaWiki 1.17 to 1.21
|-
|1.21<ref name="editbug">'''Important note''': These old versions have a critical bug that prevents editing when there are no articles in the Boilerplate namespace. If you are using these versions, upgrading to version 1.22 or later is strongly recommended.</ref> ||2013 October 21 ||MediaWiki 1.17 to 1.21 (but see note below)
|-
|1.2 <ref name="editbug" /><ref>Versions 1.2 and earlier are incompatible with MediaWiki's built-in preloading features, preventing them from working. This makes these versions incompatible with similar extensions like CreateBox and InputBox. This was fixed in 1.21.</ref> ||2013 May 5 ||MediaWiki 1.17 to 1.21 (but see note below)
|-
|1.1 ||2012 July 29 ||MediaWiki 1.17 to 1.19
|-
|1.01 ||2012 February 8 ||MediaWiki 1.16.5 to 1.18
|-
|1.0 ||2011 November 4 ||MediaWiki 1.16.5 to 1.17
|-
|0.93 ||2011 September 25 ||MediaWiki 1.16.5 to 1.17
|-
|0.92 ||2011 September 14 ||MediaWiki 1.16.5 to 1.17
|-
|0.91 ||2011 September 11 ||MediaWiki 1.16.5 to 1.17
|-
|0.9 ||2011 September 5 ||MediaWiki 1.16.5 to 1.17
|}
<references />
 
==Installation==
#Extract this extension to the <tt>extensions</tt> subdirectory of your MediaWiki installation directory. It should be contained in a <tt>BoilerRoom</tt> subdirectory within <tt>extensions</tt>.
#If your wiki has custom namespaces using the indexes 450 and 451, add the following line to <tt>LocalSettings.php</tt> (changing <tt>xxx</tt> to an unused even index, ensuring that the following index is also unused):
#:<tt><nowiki>$wgbrNamespaceIndex = xxx;</nowiki></tt>
#Add the following lines to <tt>LocalSettings.php</tt>. Due to the unique nature of the <tt>&lt;boilerplate&gt;</tt> 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 <tt>$wgbrNamespaceIndex</tt> line if that is needed):
#:<tt><nowiki>require_once( "{$IP}/extensions/BoilerRoom/BoilerRoom.php" );</nowiki></tt>
 
'''Note''': Versions 0.92 and earlier used namespace indexes 300 and 301 as the defaults. If you are ''upgrading'' from those versions and you were using the default, you should add the following line before the <tt>require_once</tt> line:
:<tt><nowiki>$wgbrNamespaceIndex = 300;</nowiki></tt>
 
Alternatively, if you are comfortable manipulating the database directly, you can update the namespace indexes of the page. Another option is to create a temporary custom namespace at index 300 and move them to new Boilerplate namespace manually.
 
==Configuration==
;<tt>$wgbrNamespaceIndex</tt>
:Sets the index at which the Boilerplate namespace will be created.
:As of version 0.93, this is 450 by default. The Boilerplate talk namespace will be created at the following index, which is 451 by default.
:In earlier versions, this was 300 by default, with the Boilerplate talk namespace being created at 301 by default.
;<tt>$wgbrUseLargeSelector</tt>
:Available in 1.0, this option allows you to use a large version of the four-button selector that appears above the standard toolbar rather than to the right of it by setting this option to <tt>true</tt>. This option has no effect for users using the advanced toolbar of the WikiEditor extension.
 
==Usage==
===Creating boilerplate articles===
The <tt>&lt;boilerplate&gt;</tt> 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. It's more of an extended syntax than a true tag. Specifically, it has the following behavior:
 
*You must use <tt>&lt;boilerplate&gt;</tt> and <tt>&lt;/boilerplate&gt;</tt> 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''' <tt>&lt;boilerplate&gt;</tt> tag and '''last''' <tt>&lt;/boilerplate&gt;</tt> tag on the page are considered.
**This allows you to place <tt>&lt;boilerplate&gt;</tt> tags into the content.
**Additionally, tags such as <tt>&lt;includeonly&gt;</tt> and <tt>&lt;noinclude&gt;</tt> don't require any unusual escaping. They are treated as plain-text content within <tt>&lt;boilerplate&gt;</tt> tags.
*The boilerplate content opens at the first line after the <tt>&lt;boilerplate&gt;</tt> tag and closes at the end of the final line before the <tt>&lt;/boilerplate&gt;</tt> tag. Content on the same lines as the tags is simply ignored if it is between the tags.
 
Or to show this information visually:
<div style="font-family: monospace,'Courier New'; padding: 1em; border: 1px dashed #2f6fab; background-color: #f9f9f9;">
<span style="color: #006600;">Header text describing the boilerplate may be placed here, as well as any other wikicode.<br />
It will appear when directly viewing boilerplates and when transcluding them like templates.<br /></span>
<span style="color: #000099;">&lt;boilerplate&gt;</span><span style="color: #888888;"> Text here is simply ignored and will not appear.</span><br />
<span style="color: #000000;">This line is where the boilerplate text begins.<br />
<br />
&lt;boilerplate&gt;<br />
Since only the first opening and last closing tags are considered, <br />
boilerplate tags inside the boilerplate text are treated as plain text and will be <br />
included as part of the boilerplate without modification.<br />
&lt;/boilerplate&gt;<br />
<br />
&lt;includeonly&gt; and similar tags are also treated as plain text within the <br />
boilerplate tags and will be included in boilerplate text without modification, so it <br />
even works well for providing a boilerplate (or multiple) for templates.<br />
&lt;/includeonly&gt;<br />
<br />
This line is where the boilerplate text ends.</span><br />
<span style="color: #888888;">Whereas this text is simply ignored.</span><span style="color: #000099;">&lt;/boilerplate&gt;</span><br />
<br />
<span style="color: #006600;">You can place any footer text here you wish, and this is a good spot for any categories<br />
you want to include the boilerplate article itself in. That can be done in the header as<br />
well.</span><br />
</div>
 
===The BoilerRoom selectors===
====The four-button selector====
The four-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. There are two different versions of the selector. The first is the small selector which is used by default in version 1.0:
 
[[File:ExtensionBoilerRoom4ButtonSmallSelector.png]]
 
Optionally, by setting <tt>$wgUseLargeSelector</tt> to true, a wiki can opt instead for the large selector:
 
[[File:ExtensionBoilerRoom4ButtonLargeSelector.png]]
 
<b>Note</b>: In versions before 1.0, the large selector was the only one available. Additionally, it was only a three button selector, as [[:File:ExtensionBoilerRoom3ButtonSelector.png|shown here]].
 
It shows only the articles available within the Boilerplate namespace, excluding any redirects. As you can see, it does not display the <tt>Boilerplate</tt> portion of the title. Note, though, that even articles without <tt>&lt;boilerplate&gt;</tt> 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 four-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 or into existing content.
 
[[File:ExtensionBoilerRoom1ButtonSelector.png]]
 
 
===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 <tt>&lt;boilerroombox&gt;</tt> and <tt>&lt;brbox&gt;</tt> tags or the <tt><nowiki>{{#boilerroombox}}</nowiki></tt> and <tt>{{#brbox}}</tt> parser functions. (<tt>brbox</tt> and <tt>boilerroombox</tt> are synonyms for each other and function identically.)
 
[[File:ExtensionBoilerRoomBox.png]]
 
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.
<div style="float: left; width: 49%;">
'''Tag form'''
<nowiki>&lt;boilerroombox&gt;
boilerplate=
title=
label=
align=
width=
&lt;/boilerroombox&gt;</nowiki>
</div>
<div style="float: right; width: 49%;">
'''Parser function form'''
<nowiki>{{#boilerroombox:
|boilerplate=
|title=
|label=
|align=
|width=
}}</nowiki>
</div>
<div style="clear: both;"></div>
 
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.
 
;<tt>boilerplate</tt>
:This identifies the article to preload into the edit box. It only loads content defined by <tt>&lt;boilerroom&gt;</tt> as explained [[#Creating boilerplate articles|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.
;<tt>title</tt>
: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.
;<tt>label</tt>
:This is the text that appears on the button which opens the requested page for editing. The default label is "Edit".
;<tt>align</tt>
:The align can be <tt>left</tt>, <tt>right</tt> or <tt>center</tt>. This is applied as a CSS rule, so <tt>inherit</tt> is also a valid value. There is no default; if not included, no <tt>text-align</tt> rule is applied.
;<tt>width</tt>
: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).
 
 
==Version History==
{| class="wikitable"
|-
!Version
!Release Date
!Changes
|-
|1.23
|2013 December 21
|Corrected cosmetic issue where characters appeared at the bottom of edit pages.
|-
|1.22
|2013 October 21
|Corrected critical error preventing editing when there are no articles in the Boilerplate namespace.
|-
|1.21
|2013 October 21
|Corrected conflict with built-in preloading feature, making [[Extension:InputBox|InputBox]] and [[Extension:CreateBox|CreateBox]] compatible.
|-
|1.2
|2013 May 5
|Now works with WikiEditor. More refactoring to improve coding practices.
|-
|1.1
|2012 July 29
|Moderate refactoring to improve compatibility with future MediaWiki versions.
|-
|1.0
|2011 November 4
|Added small selector option and insert at cursor functionality.
|-
|0.93
|2011 September 25
|Default namespace index changed to the apparently unused value of 450.
|-
|0.92
|2011 September 14
|Input validation for the BoilerRoomBox greatly improved.
|-
|0.91
|2011 September 11
|Changed <tt>&lt;boilerroom&gt;</tt> to <tt>&lt;boilerplate&gt;</tt>.
|-
|0.9
|2011 September 5
|Initial beta release.
|}
 
==Known Issues==
===Unusual text appearing at bottom of edit pages (fixed in 1.23)===
In versions 1.20 to 1.22, a minor issue was inadvertently introduced that causes the characters <tt>/*]]>*/</tt> to appear at the bottom of edit pages. This is merely a cosmetic error that has no known effect on wiki functionality and has been fixed in version 1.23.
 
===Error when editing when no boilerplates are available (fixed in 1.22)===
Some recent versions of BoilerRoom, including 1.21, cause an error when open pages for editing if there are no pages in the Boilerplate namespace.
 
'''The easiest way to fix this is to install version 1.22 or later.'''
 
If this isn't an option, you can work around it by performing the following steps:
 
<ol>
<li>Temporarily uninstall BoilerRoom by adding a <tt>#</tt> to beginning of the line containing <tt><nowiki>require_once( "{$IP}/extensions/BoilerRoom/BoilerRoom.php" );</nowiki></tt> in LocalSettings.php.</li>
<li>Temporarily add the following lines below it:</li>
<nowiki>
define("NS_BOILERPLATE", isset( $wgbrNamespaceIndex ) ? $wgbrNamespaceIndex : 450);
define("NS_BOILERPLATE_TALK", isset( $wgbrNamespaceIndex ) ? $wgbrNamespaceIndex + 1 : 451);
$wgExtraNamespaces[NS_BOILERPLATE] = "Boilerplate";
$wgExtraNamespaces[NS_BOILERPLATE_TALK] = "Boilerplate_talk";
</nowiki>
<li>Now, navigate to the wiki and create any page in the Boilerplate namespace (any page beginning with "Boilerplate:").</li>
<li>Return to LocalSettings.php and remove the lines and <tt>#</tt> you added in step 1 and 2 to reinstall BoilerRoom.</li>
</ol>
 
===Overrides built-in preloading feature (fixed in 1.21)===
Versions of BoilerRoom before 1.21 currently prevent the built-in text preloading feature of MediaWiki from working correctly. This affects extensions like InputBox and CreateBox that use this feature. This issue has been corrected in version 1.21.
 
===Selectors don't clear floats (fixed in 1.0)===
There is a simple workaround for this issue. Paste the following CSS into MediaWiki:Common.css on your wiki:
<nowiki>.boilerRoomFieldSet {
clear: both;
}</nowiki>
 
[[Category:User interface extensions]][[Category:Page creation extensions]][[Category:Form extensions]]
Retrieved from "https://www.mediawiki.org/wiki/Extension:BoilerRoom"