Extension:Tabs/Usage

From MediaWiki.org
Jump to navigation Jump to search

This is the documentation for the Tabs extension. If this extension has been enabled, you could also copy the contents from the README.md file into a wiki page to also see live demonstrations of this extension.

Installation[edit]

  • Download and place the file(s) in a directory called Tabs in your extensions/ folder.
  • Add the following code at the bottom of your LocalSettings.php:
    require_once "$IP/extensions/Tabs/Tabs.php";
    
  • Yes Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Configuration[edit]

This extension has no configuration options in LocalSettings.php, but it does have the MediaWiki:tabs-dropdown-bgcolor message associated with it, which is not meant to be translated. This message contains the default value for the background-color style for dropdown menus. This needs to be a valid background-color value.

It also has the following internationalisation messages associated with it:

  • MediaWiki:tabs-tab-label - The default label for a tab. The $1 stands for the index of the tab.
  • MediaWiki:tabs-toggle-open - The default opening label for toggle boxes.
  • MediaWiki:tabs-toggle-close - The default closing label for toggle boxes.
  • MediaWiki:tabs-dropdown-label - The default label for a dropdown menu.

Usage[edit]

Tabs[edit]

Basic Syntax
<tabs>
<tab name="Foo">Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</tab>
<tab name="Bar">Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</tab>
<tab name="Baz">Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</tab>
</tabs>
Result
ExtensionTab tabs.png

Toggle Box[edit]

A single <tab> without a parent <tags> becomes a toggle box.

Basic Syntax
<tab name="My Toggle Box">
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
</tab>
Result
ExtensionTab toggleBox.png

The box defaults to the open state. Add the collapsed attribute to the <tab> tag to change the default state to collapsed:

<tab name="My Toggle Box" collapsed>

Dropdown Menu[edit]

A toggle box with the dropdown attribute becomes a dropdown menu.

Basic Syntax
<tab name="Stationery" dropdown>
* [[Business Cards]]
* [[Letterheads]]
* [[Envelopes]]
</tab>
Result
ExtensionTab dropDownClosed.png

Hover the mouse over the bar to open the menu:

ExtensionTab dropDown.png

General usage information[edit]

Note: This extension uses the bgcolor attribute for dropdown menus. This is in no way meant as encouragement for the use of this deprecated attribute anywhere other than this tag.

For both the <tabs> and <tab> tags, parser functions can be used within the content of the tag, but not in the attributes. To use parser functions within the attributes, the #tag:tabs or #tag:tab parser functions should be used. The #tab parser function will also work, but since the only attributes it can define are the index and name attributes, these don't allow complete support.

For example, this will not work:

<tabs style="color:{{#if:{{{1|}}}|green|red}}">
<tab name="{{{1|}}}">Foo</tab>
<tab name="{{{2|}}}">Bar</tab>
</tabs>

But this will work:

{{#tag:tabs|
{{#tag:tab|Foo|name={{{1|}}}}}
{{#tab:{{{2|}}}|Bar}}
|style=color:{{#if:{{{1|}}}|green|red}} }}

Hotlinking tabs[edit]

It is possible to hotlink tabs the same way as hotlinking sections on pages. Simply put the tab label in the URL, and the page will automatically scroll to the top of the tab, and open the selected tab. This will always open only the very first tab that has the specified tab label (for example, if there are two tab boxes that both have a tab labelled "Tab 1", putting #Tab_1 in the URL will scroll to the first one on the page). If there is already another element on the page that could be scrolled to, such as a page section, that other element will have priority, and the tab will not be focused.

Attributes[edit]

General attributes[edit]

The following attributes are available for both the <tab> tag and the <tabs> tags, in any situation they're used:

Attribute Description
title Determines the tooltip shown (Hover over this text for an example) when hovering over the box.
style Use this attribute to define any styles for the box. This can also affect the box's label.
class Adds classes to the box. Different classes are seperated by spaces. Classes are generally used for altering the appearance of the box via CSS.
id Adds an id to the box. This id must be unique on the page, as per HTML specifications. Ids are generally used for linking scripts to via JavaScript, or they might also be used for altering the appearance of the individual box via CSS.

Tab menu attributes[edit]

The following attributes are available for tab menus:

Attribute Description
For the <tabs> tag
container Use this attribute to define any styles for the tabs container. Styles defined here will only affect the container of the tabs, not the labels.
plain If this attribute is set, the tab interface will be a much more plain layout, without a border around the container, and with the tab labels just being buttons above it, instead of the typical tab layout. This can be used to get more freedom in styling the interface.
For the <tab> tag inside tab menus
inline If this attribute is set, the tab's contents can be placed within text without interrupting the flow of the text. The difference between this and the default state of display:inline-block is that with inline-block, the tab's contents are forced to a new line when placed at the end of a new line, when not the whole of the tab's contents fit on the same line. inline tabs however will use up any space that's left at the end of the line, and fit in with the normal flow of the text just like normal text.
block Converts the tab's contents to a block element. This can be used to assure the tab's contents will be displayed as a block instead of an inline-block, in cases where the tab's contents should not be placed within a line of text. When both the block and inline attributes are available, the inline attribute will be ignored.
index This will determine the index of the tab. This only works if the entered index is already the index of a defined tab. Otherwise, this attribute is ignored. If no valid index or matching name attributes are defined, the index is automatically set to be the next in the list of tabs.
name This attribute is used to define the text the label shows for the tab. If the entered name already exists within the tab, the contents of the <tab> tag are automatically assigned to the existing tab. This also means no two tabs can have an identical label. This attribute will be ignored if the index attribute already refers to an existing tab. Whitespace is automatically removed from the start and end of this attribute's value.

Toggle box attributes[edit]

Attribute Description
collapsed If this attribute is set, the toggle box will appear collapsed when the page loads. Otherwise it will be opened.
inline If this attribute is set, the toggle box can be placed within text without interrupting the flow of the text.
container Use this attribute to define any styles for the toggle box container. Styles defined here will only affect the content of the toggle box, not the label.
Name attributes:[1]
openname The label for the toggle box that indicates that clicking it will close the box. Default value is stored in the MediaWiki:tabs-toggle-open page.
closename Same as openname, but for closing the toggle box. Default is stored in MediaWiki:tabs-toggle-close.
name If neither the openname and closename is defined, this value will be used for both states.
  1. If only one of the openname or closename attributes is defined, the other will take its value. If neither is defined, and the name attribute is also not defined, the default values are taken from the respective MediaWiki pages.

Dropdown attributes[edit]

Attribute Description
inline If this attribute is set, the dropdown menu can be placed within text without interrupting the flow of the text.
container Use this attribute to define any styles for the dropdown menu container. Styles defined here will only affect the content of the toggle box, not the label.
dropdown Must be defined for the toggle box to become a dropdown menu.
openname These attributes are all identical in dropdown menus. It is not possible to make the dropdown switch between 2 values depending on opening state. If the openname attribute is set, that value will be used as label, otherwise the closename value is used, and if neither of those values is set, the name value is used.
closename
name
bgcolor Because of how the background-color styling for dropdown works (background styles are applied to all items within dropdowns, otherwise they would become transparent), background colors need to be defined seperately. This must be done in the bgcolor attribute. This attribute works exactly the same as the background-color style in CSS. This defaults to the value defined in MediaWiki:tabs-dropdown-bgcolor.

Tag information[edit]

Tab menus[edit]

Tab menus can be used to make it possible to switch between different layouts. Anything within <tabs> ... </tabs> tags is rendered as a tab menu. Individual tabs are then defined via a <tab> tag.

Self-closing tabs can be used to define a list of tabs at the top of the tab menu, for later use via the index attribute. Self-closing tabs only have an effect when a name is defined, and no (valid) index is defined. The syntax for self-closing tabs is <tab name="name" />

As an alternative for the tab tag, the {{#tab:}} parser function can also be used to simplify the syntax for tabs. The syntax for this parser function allows the following syntaxes:

Code Description
{{#tab:name1/#1, name2/#2, etc|content 1|content 2|etc}} Each of the defined names will be set as name or index attributes, respectively.
  • All values that are prefixed with #, and are numbers only will be recognised as indices. For indices, surrounding whitespace is allowed, but internal whitespace or any non-number characters such as decimal points aren't.
  • If these condtions are not met, the entered value is interpreted as a name.
  • If the entered value contains only whitespace or is left empty, the index of that tab is automatically calculated.
{{#tab:|content 1|content 2|etc}} No indices or names are defined here, so the indices of the tabs within the parser functions are automatically assigned as index.
{{#tab:name1/#1, , name3/#3, name4/#4|content 1|content 2| |content 4}} The second tab will automatically get index="2", and the third tab will have no content:
  • If the third tab has a name defined in the list of names, then it becomes a self-closing tag.
  • If the third tab has an index defined, this tab is skipped, and no output is generated for this tab.
{{#tab:name1, name2, name3...}} This will define three tabs, "name1", "name2" and "name3" using the self-closing syntax.
{{#tab:#3, #5|content 3|content 5}} This will add "content 3" to the rest of the contents of tab 3, and "content 5" to the rest of the content of tab 5.
{{#tab:name1/#1, etc|content 1|$1}} When the content of a tab is $n (where n is the place of the tab in the parser function), the contents of that tab are copied over to the tab that has $n in it. For this to work, the following conditions must be met:
  • The tab must contain nothing other than a dollar sign and a number directly after it. Surrounding whitespace is allowed.
  • The parser function's nth parameter must be defined. n may also be bigger than the current tab index (so, {{#tab:#3,#5|$2|Hi}} would put "Hi" in both tab 3 and 5).
  • The parser function's nth parameter must contain something other than just whitespace. Recursive references won't work, so {{#tab:|Hi|$1|$2}} will put "Hi" in tabs 1 and 2, and the literal text "$1" in tab 3.
{{#tab:name1/#1, etc|content 1|$1}} When the content of a tab is $n (where n is the place of the tab in the parser function), the contents of that tab are copied over to the tab that has $n in it. For this to work, the following conditions must be met:
  • The tab must contain nothing other than a dollar sign and a number directly after it. Surrounding whitespace is allowed.
  • The parser function's nth parameter must be defined. n may also be bigger than the current tab index (so, {{#tab:#3,#5|$2|Hi}} would put "Hi" in both tab 3 and 5).
  • The parser function's nth parameter must contain something other than just whitespace. Recursive references won't work, so {{#tab:|Hi|$1|$2}} will put "Hi" in tabs 1 and 2, and the literal text "$1" in tab 3.

Toggle box[edit]

You can create a simple collapsible box by enclosing some content between <tab> ... </tab>. All content within the tags will be displayed within the toggle box.

Dropdown menus[edit]

Dropdown menus are made by simply defining the dropdown attribute on a toggle box. They can be opened by either hovering over the label, or by clicking on the label to keep it opened even after moving away the cursor. Dropdown menus have an opening delay of 0.2 seconds built in to prevent accidental opening when hovering over the label, and to prevent accidental closing when accidentally moving the cursor off the dropdown. This delay is enough to prevent accidents like those, but is not enough to be bothersome.

Dropdown menus are heavily based on the code for toggle boxes, so will also resemble them in many ways. There are a couple of quite distinct differences though.

Since dropdown menus use the <menu> tag for their content, it is permitted to use <li> tags directly within the dropdown menu's contents. Any other content is also allowed.

Dropdown menus will convert all list items and links placed within to specially styled list items. The only exception is that links show as they normally do when placed within unordered lists (any line starting with *). This is also the only difference between ordered and unordered lists.

Any nested lists will be rendered as sub-menus in the dropdown menu. Nested lists are created by starting a line with multiple * or # characters. There is one limitation with this however: Individual nested lists can not alternate between ordered and unordered lists. Seperate levels can, however. For example, this is not allowed:

*Menu item 1
*Menu item 2
**Sub-menu item 1
*#Sub-menu item 2

But this is:

*Menu item 1
#Menu item 2
#*Sub-menu item 1
#*Sub-menu item 2
#*#Sub-sub-menu item 1
*Menu item 3
**Sub-menu item 1
**#Sub-sub-menu item 1

Combining tags[edit]

In most cases, it is possible to put multiple of these boxes inside each other. For this to work however, the #tag:tabs, #tag:tab or #tab: parser functions will have to be used whenever two of the same tags are used anywhere within each other. This is required because otherwise the wikicode parser will recognise the closing tag for the nested tag as the closing tag for the outer tag, and skip the rest of the content, which could cause problems.

For the #tag: parser function, even boolean attributes (such as dropdown or inline) need to have a value defined for them, otherwise they are not recognised as attributes. For example, {{#tag:tab|Dropdown contents|dropdown}} will not work (it will show a toggle box instead of a dropdown), while {{#tag:tab|Dropdown contents|dropdown=true}} will work to show a dropdown box.

All combinations of nesting multiple tags will work, except for nesting any tab menus inside other tab menus.