diff options
Diffstat (limited to 'www/wiki/skins/chameleon/docs/components.md')
| -rw-r--r-- | www/wiki/skins/chameleon/docs/components.md | 949 |
1 files changed, 949 insertions, 0 deletions
diff --git a/www/wiki/skins/chameleon/docs/components.md b/www/wiki/skins/chameleon/docs/components.md new file mode 100644 index 00000000..003b589d --- /dev/null +++ b/www/wiki/skins/chameleon/docs/components.md @@ -0,0 +1,949 @@ +## Components & Modifications + +Components are the building blocks of any layout. They are the functional units +of the website, like the logo or the navigation bar. There are also four special +component types - structure, grid, row and cell - that define the general layout +of the page and assign the other components their place on the page. +Modifications can be added to most components to change their general behavior. + +The following components and modifications are available: +<!-- START doctoc generated TOC please keep comment here to allow auto update --> +<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> + + +- [`Structure`](#structure) +- [`Grid`](#grid) +- [`Row`](#row) +- [`Cell`](#cell) +- [Component `Container`](#component-container) +- [Component `FooterIcons`](#component-footericons) +- [Component `FooterInfo`](#component-footerinfo) +- [Component `FooterPlaces`](#component-footerplaces) +- [Component `Html`](#component-html) +- [Component `Logo`](#component-logo) +- [Component `MainContent`](#component-maincontent) +- [Component `Menu`](#component-menu) +- [Component `NavbarHorizontal`](#component-navbarhorizontal) +- [Component `NavMenu`](#component-navmenu) +- [Component `NewtalkNotifier`](#component-newtalknotifier) +- [Component `PageTools`](#component-pagetools) +- [Component `PageToolsAdaptable`](#component-pagetoolsadaptable) +- [Component `PersonalTools`](#component-personaltools) +- [Component `SearchBar`](#component-searchbar) +- [Component `Silent`](#component-silent) +- [Component `SiteNotice`](#component-sitenotice) +- [Component `ToolbarHorizontal`](#component-toolbarhorizontal) +- [Modification `HideFor`](#modification-hidefor) +- [Modification `ShowOnlyFor`](#modification-showonlyfor) +- [Modification `Sticky`](#modification-sticky) + +<!-- END doctoc generated TOC please keep comment here to allow auto update --> + +### `Structure` + +The root element of any layout. + +#### Example usage + +``` xml +<structure xmlns="https://github.com/cmln/chameleon/layout/1.0"> + ... +</structure> +``` + +#### Attributes: +* `xmlns`: + * Allowed values: URI of XML namespace definition + * Optional. + + Ignored by the skin itself, but may be specified to validate the layout. See + [Layouts](layouts.md). + +#### Allowed Parent Elements: +None. + +#### Allowed Child Elements: +* [Grid](#grid) +* Any component + +------------------------------------------------------------------------------- +### `Grid` + +The grid system is used for creating page layouts through a series of rows and +cells. While it is possible to place components outside of a grid it is not +recommended. + +#### Example usage + +``` xml +<grid> + ... +</grid> +``` + +#### Attributes: +* `mode`: + * Allowed values: String (`fixedwidth`|`fluid`) + * Default: `fixedwidth` + * Optional. + + Use `fixedwidth` for a responsive fixed width layout. Use `fluid` for a full + width layout, spanning the entire width of the viewport. + +#### Allowed Parent Elements: +* [Structure](#structure) + +#### Allowed Child Elements: +* [Row](#row) +* Any modification + +------------------------------------------------------------------------------- +### `Row` + +Use rows to create horizontal groups of cells. Content should be placed within +cells, and only cells may be immediate children of rows. + +#### Example usage + +``` xml +<row> + ... +</row> +``` + +#### Attributes: +None. + +#### Allowed Parent Elements: +* [Grid](#grid) + +#### Allowed Child Elements: +* [Cell](#cell) +* Any modification + +------------------------------------------------------------------------------- +### `Cell` + +Holds components. + +For each cell specify the number of columns you wish to span. + +#### Example usage + +``` xml +<cell span="12"> + ... +</cell> +``` + +#### Attributes: +* `span`: + * Allowed values: Numbers (1 ... 12) + * Default: `12` + + The number of columns this cell shall span. All cells of a row should together + span 12 columns. If more than 12 columns are placed within a single row, each + group of extra columns will, as one unit, wrap onto a new line. + +#### Allowed Parent Elements: +* [Row](#row) + +#### Allowed Child Elements: +* [Row](#row) +* Any component +* Any modification + +------------------------------------------------------------------------------- +### Component `Container` + +This component will wrap its content elements in a `<div>`. It may be used to +assign a CSS class for styling purposes. + +#### Example usage + +``` xml +<component type="container" class="foo bar"> + ... +</component> +``` + +#### Attributes: +* `class`: + * Allowed values: Any string + * Default: - + * Optional. + + The class (or classes) that should be assigned to the `<div>` element. + +#### Allowed Parent Elements: +* [Structure](#structure) +* [Cell](#cell) + +#### Allowed Child Elements: +* Any component +* Any modification + +------------------------------------------------------------------------------- +### Component `FooterIcons` + +A list containing the "powered by" icons. + +#### Example usage + +``` xml +<component type="FooterIcons"/> +``` + +#### Attributes: +* `class`: + * Allowed values: String + * Default: - + * Optional. + + The class (or classes) that should be assigned to the top-level html element + of this component. + +#### Allowed Parent Elements: +* [Structure](#structure) +* [Cell](#cell) + +#### Allowed Child Elements: +* Any modification + +------------------------------------------------------------------------------- +### Component `FooterInfo` + +A list of footer items (last modified time, view count, number of watching +users, credits, copyright). Does not include so called places (about, privacy +policy, and disclaimer links). + +#### Example usage + +``` xml +<component type="FooterInfo"/> +``` + +#### Attributes: +* `class`: + * Allowed values: String + * Default: - + * Optional. + + The class (or classes) that should be assigned to the top-level html element + of this component. + +#### Allowed Parent Elements: +* [Structure](#structure) +* [Cell](#cell) + +#### Allowed Child Elements: +* Any modification + +------------------------------------------------------------------------------- +### Component `FooterPlaces` + +A list containing links to places (about, privacy policy, and disclaimer links). + +#### Example usage + +``` xml +<component type="FooterPlaces"/> +``` + +#### Attributes: +* `class`: + * Allowed values: String + * Default: - + * Optional. + + The class (or classes) that should be assigned to the top-level html element + of this component. + +#### Allowed Parent Elements: +* [Structure](#structure) +* [Cell](#cell) + +#### Allowed Child Elements: +* Any modification + +------------------------------------------------------------------------------- +### Component `Html` + +This component allows insertion of raw HTML into the page. + +#### Example usage + + +``` xml +<component type="Html"><![CDATA[ + <b>Hello World!</b> +]]></component> +``` + +#### Attributes: +None. + +#### Allowed Parent Elements: +* [Structure](#structure) +* [Cell](#cell) + +#### Allowed Child Elements: +* Any modification + +------------------------------------------------------------------------------- +### Component `Logo` + +The Logo component displays the logo of the wiki as defined in `$wgLogo`. + +The alternative text of the image is set to the sitename of the wiki as defined +in `$wgSitename`. Depending on the `addLink` attribute the logo may link to the +main page of the wiki. The name of the main page of the wiki is defined in the +`mainpage` message and can thus be modified on the `Mediawiki:Mainpage` page of +the wiki. + +#### Example usage + +``` xml +<component type="Logo" addLink="yes" /> +``` + +#### Attributes: +* `class`: + * Allowed values: String + * Default: - + * Optional. + + The class (or classes) that should be assigned to the top-level html element + of this component. + +* `addLink`: + * Allowed values: Boolean (`yes`|`no`) + * Default: `yes` + * Optional. + +#### Allowed Parent Elements: +* [Structure](#structure) +* [Cell](#cell) +* [NavbarHorizontal](#component-navbarhorizontal) + +#### Allowed Child Elements: +* Any modification + +------------------------------------------------------------------------------- +### Component `MainContent` + +The main content of the page, the wiki article itself. + +Includes: +* Title: title of the page +* Subtitle: used for various things like the subpage hierarchy +* Tagline: usually something like "From WikiName", hidden by default, used for printing +* Undelete message +* [Page status indicators](https://www.mediawiki.org/wiki/Help:Page_status_indicators): icons that provide quick information about the status of the article +* Article text +* Data after content: Additional text block useable by extensions +* Category links + +#### Example usage + +``` xml +<component type="MainContent"/> +``` + +#### Attributes: +* `class`: + * Allowed values: String + * Default: - + * Optional. + + The class (or classes) that should be assigned to the top-level html element + of this component. + +#### Allowed Parent Elements: +* [Structure](#structure) +* [Cell](#cell) + +#### Allowed Child Elements: +* Any modification + +------------------------------------------------------------------------------- +### Component `Menu` + +An additional menu. + +The structure of the menu can be specified either in a [MediaWiki +message](https://www.mediawiki.org/wiki/Help:System_message) or directly in the +layout file. The format is the same as that of the [MediaWiki +sidebar](https://www.mediawiki.org/wiki/Manual:Interface/Sidebar). + +This component is intended to be used inside a +[NavbarHorizontal](#component-navbarhorizontal) component. It will work in other +places, but will require additional styling effort. + +#### Example usage + +Using the message _MediaWiki:Secondary-menu_: +``` xml +<component type="Menu" message="secondary-menu" /> +``` + +Using an inline description: +``` xml +<component type="Menu" > + * Foo + ** FooBar + * Test | Bar +</component> +``` + +#### Attributes: +* `message` + * Allowed values: String + * Default: - + * Optional. + + The name of the MediaWiki message that holds the menu description. + +#### Allowed Parent Elements: +* [Structure](#structure) +* [Cell](#cell) +* [NavbarHorizontal](#component-navbarhorizontal) + +#### Allowed Child Elements: +* Any modification + +------------------------------------------------------------------------------- +### Component `NavbarHorizontal` + +A horizontal navbar that takes its contents from its child elements. + +#### Example usage + +From [navhead.xml](../layouts/navhead.xml): +``` xml +<component type="NavbarHorizontal"> + <component type="Logo" position="head"/> + <component type="NavMenu" flatten="navigation" showTools="no" showLanguages="no"/> + <component type="PageTools" position="right" hideSelectedNameSpace="yes"/> + <component type="SearchBar" position="right"/> + <component type="PersonalTools" position="right"/> +</component> +``` + +#### Attributes: +* `class`: + * Allowed values: String + * Default: - + * Optional. + + The class (or classes) that should be assigned to the top-level html element + of this component. + +* `fixed`: + * **Deprecated.** Use the [Sticky](#modification-sticky) modification instead. + * Allowed values: Boolean (`yes`|`no`) + * Default: `no` + +#### Allowed Parent Elements: +* [Structure](#structure) +* [Cell](#cell) + +#### Allowed Child Elements: +* Component [`Logo`](#component-logo) +* Component [`Menu`](#component-menu) +* Component [`NavMenu`](#component-navmenu) +* Component [`PageTools`](#component-pagetools) +* Component [`PersonalTools`](#component-personaltools) +* Component [`PageToolsAdaptable`](#component-pagetoolsadaptable) +* Component [`SearchBar`](#component-searchbar) +* Any modification + +------------------------------------------------------------------------------- +### Component `NavMenu` + +A menu containing the +[sidebar](https://www.mediawiki.org/wiki/Manual:Interface/Sidebar) items. + +Does not include the search bar. Toolbox and language links can be included +optionally. + +This component is intended to be used inside a +[NavbarHorizontal](#component-navbarhorizontal) component. It will work in other +places, but will require additional styling effort. + +#### Example usage + +Using the message _MediaWiki:Secondary-menu_: +``` xml +<component type="NavMenu" flatten="navigation" showTools="no" showLanguages="no" /> +``` + +#### Attributes: +* `flatten` + * Allowed values: String + * Default: - + * Optional. + + A semicolon separated list of section names that are to be flattened, i.e. + whose menu items should appear not in a submenu, but as elements of the top + structure. + + This list may also be given in the message + _MediaWiki:skin-chameleon-navmenu-flatten_ instead. If both the message and + the attribute are used, the message takes precedence. + +* `showTools` + * Allowed values: Boolean (`yes`|`no`) + * Default: `no` + * Optional. + + If set to `yes` the toolbox will be included in the NavMenu. It is usually not + included here, but shown in a dedicated + [ToolbarHorizontal](#component-toolbarhorizontal) instead. + + The MediaWiki toolbox contains various links. Some are general links like a + link to a list of Special Pages so a user always has a way to access them. + Others are page-sensitive links like permalinks, printable links, block links, + feed links, and a link to a list of pages linking to the current page. + +* `showLanguages` + * Allowed values: Boolean (`yes`|`no`) + * Default: `no` + * Optional. + + A MediaWiki page may have links to the same page in other languages on the + wiki when inter-language links are added to the page. If the attribute is set + to `yes` the language links will be included in the NavMenu. They are usually + not included here, but shown in a dedicated + [ToolbarHorizontal](#component-toolbarhorizontal) instead. + +#### Allowed Parent Elements: +* [Structure](#structure) +* [Cell](#cell) +* [NavbarHorizontal](#component-navbarhorizontal) + +#### Allowed Child Elements: +* Any modification + +------------------------------------------------------------------------------- +### Component `NewtalkNotifier` + +A message to a user about new messages on their talkpage. Usually goes something +like "You have [a new message]() ([last change]())." + +#### Example usage + +``` xml +<component type="NewtalkNotifier"/> +``` + +#### Attributes: +* `class`: + * Allowed values: String + * Default: - + * Optional. + + The class (or classes) that should be assigned to the top-level html element + of this component. + +#### Allowed Parent Elements: +* [Structure](#structure) +* [Cell](#cell) + +#### Allowed Child Elements: +* Any modification + +------------------------------------------------------------------------------- +### Component `PageTools` + +A component containing content navigation links (Page, Discussion, Edit, +History, Move, ...) + +#### Example usage + +``` xml +<component type="PageTools"/> +``` + +#### Attributes: +* `class`: + * Allowed values: String + * Default: - + * Optional. + + The class (or classes) that should be assigned to the top-level html element + of this component. + +* `hideSelectedNameSpace` + * Allowed values: Boolean (`yes`|`no`) + * Default: `no` + * Optional. + + If set the link to the current page will not be shown among the page tools. + +#### Allowed Parent Elements: +* [Structure](#structure) +* [Cell](#cell) +* [NavbarHorizontal](#component-navbarhorizontal) + +#### Allowed Child Elements: +* Any modification + +------------------------------------------------------------------------------- +### Component `PageToolsAdaptable` + +- [Component `PageToolsAdaptable`](#component-pagetoolsadaptable) + + +Renders the same component as [Component `PageTools`](#component-pagetools), except +you can define in your structure file which actions are shown directly in the navbar +before the ... pop-down. + +#### Example usage + +``` xml +<component type="PageToolsAdaptable" show="edit,ve-edit,history"/> +``` + +#### Attributes: +Same as [Component `PageTools`](#component-pagetools). Additionally: +* `show` + * Allowed values: String + * Default: - + * Optional. + + The actions that will be shown in the navbar directly and also removed from the PageTools drop-down. + Among other, possible actions are: + + * delete + * edit + * formedit + * history + * move + * protect + * purge + * undelete + * unprotect + * unwatch + * ve-edit + * view + * watch + + Note that button for actions, that are not valid for a given page will be omitted automatically. + So in the above example, the visual-editor edit action button will only be shown for pages in a valid + visual-editor namespace. + Note also, that the valid buttons will be shown in the order you provided in the show attribute of + your structure.xml. In the example above, history would be last action right before the ellipsis. + +#### Allowed Parent Elements: +* [Structure](#structure) +* [Cell](#cell) +* [NavbarHorizontal](#component-navbarhorizontal) + +#### Allowed Child Elements: +* Any modification + +#### Integration with VisualEditor +Visual Editor has a late-executed javascript function, that replaces the content of certain page tool +action links. Unfortunately, that also concerns corresponding buttons, you indicated to show. + +The solution is to remove the corresponding tab messages from the Visual Editor configuration in your +LocalSettings.php. So for example: +```$php + wfLoadExtension( 'VisualEditor' ); + $wgVisualEditorTabMessages['editsource'] = null; + $wgVisualEditorTabMessages['createsource'] = null; +``` + +------------------------------------------------------------------------------- +### Component `PersonalTools` + +A component containing the personal tools like link to user page and user's talk +page, preferences, watchlist, etc. Also shows the new talk notifier, when +applicable. + +#### Example usage + +``` xml +<component type="PersonalTools"/> +``` + +#### Attributes: +* `class`: + * Allowed values: String + * Default: - + * Optional. + + The class (or classes) that should be assigned to the top-level html element + of this component. + +* `hideNewtalkNotifier` + * **Deprecated.** + * Allowed values: Boolean (`yes`|`no`) + * Default: `no` + * Optional. + + If set the newtalk notifier will not be shown. + + This attribute has no effect when used inside the + [NavbarHorizontal](#component-navbar-horizontal) component. + + This attribute was introduced to keep backwards compatibility. If the + PersonalTools component is used, it is recommended to always set this + attribute to *yes* and use an independent + [NewtalkNotifier](#component-newtalknotifier) component. + +#### Allowed Parent Elements: +* [Structure](#structure) +* [Cell](#cell) +* [NavbarHorizontal](#component-navbarhorizontal) + +#### Allowed Child Elements: +* Any modification + +------------------------------------------------------------------------------- +### Component `SearchBar` + +The search bar. + +#### Example usage + +``` xml +<component type="SearchBar"/> +``` + +#### Attributes: +* `class`: + * Allowed values: String + * Default: - + * Optional. + + The class (or classes) that should be assigned to the top-level html element + of this component. + +* `buttons`: + * Allowed values: String (`search`|`go`|`search go`) + * Default: `search go` + * Optional. + + The buttons that should be shown with the search bar. + +#### Allowed Parent Elements: +* [Structure](#structure) +* [Cell](#cell) +* [NavbarHorizontal](#component-navbarhorizontal) + +#### Allowed Child Elements: +* Any modification + +------------------------------------------------------------------------------- +### Component `Silent` + +This component does not output anything. It may be used as a placeholder during development. + +#### Example usage + +``` xml +<component type="Silent"/> +``` + +#### Attributes: +None. + +#### Allowed Parent Elements: +* [Structure](#structure) +* [Cell](#cell) + +#### Allowed Child Elements: +* Any modification + +------------------------------------------------------------------------------- +### Component `SiteNotice` + +The wiki's [site notice](https://www.mediawiki.org/wiki/Manual:Interface/Sitenotice). + +#### Example usage + +``` xml +<component type="SiteNotice"/> +``` + +#### Attributes: +* `class`: + * Allowed values: String + * Default: - + * Optional. + + The class (or classes) that should be assigned to the top-level html element + of this component. + +#### Allowed Parent Elements: +* [Structure](#structure) +* [Cell](#cell) + +#### Allowed Child Elements: +* Any modification + +------------------------------------------------------------------------------- +### Component `ToolbarHorizontal` + +A horizontal toolbar containing standard sidebar items (toolbox, language links). + +The MediaWiki toolbox contains various links. Some are general links like a link +to a list of Special Pages so a user always has a way to access them. Others are +page-sensitive links like permalinks, printable links, block links, feed links, +and a link to a list of pages linking to the current page. + +[Language links](https://www.mediawiki.org/wiki/Interlanguage_links) are links +to the same page in other languages on the wiki that are available when +inter-language links are added to the page. + +#### Example usage + +``` xml +<component type="ToolbarHorizontal" hideTools="no" hideLanguages="no"/> +``` + +#### Attributes: +* `class`: + * Allowed values: String + * Default: - + * Optional. + + The class (or classes) that should be assigned to the top-level html element + of this component. + +* `hideTools` + * Allowed values: Boolean (`yes`|`no`) + * Default: `no` + * Optional. + + If set to `yes` the toolbox links will be hidden. + +* `hideLanguages` + * Allowed values: Boolean (`yes`|`no`) + * Default: `no` + * Optional. + + If the attribute is set to `yes` the language links will be hidden. + +#### Allowed Parent Elements: +* [Structure](#structure) +* [Cell](#cell) + +#### Allowed Child Elements: +* Any modification + +------------------------------------------------------------------------------- +### Modification `HideFor` + +A modification that allows to hide the parent component if the condition +specified by the attributes is fulfilled. + +This is a restrictive filter. It will hide the component if _all_ of the +attributes match. However, the attributes containing lists of values will match, +if one of the values matches. + +#### Example usage + +``` xml +<modification type="HideFor" permission="edit" namespace="NS_MAIN, NS_TALK" /> +``` + +This will hide the parent component of the modification if the user has the +_edit_ right and the current page is in the 'Main' or 'Talk' namespace. + +#### Attributes + +* group + * Allowed values: String value + * Example: `group="emailconfirmed, autoconfirmed"` + + A comma-separated list of [user + groups](https://www.mediawiki.org/wiki/Manual:User_rights#List_of_groups) for + which the component should be hidden. + + It is generally not advised to use the _group_ attribute, as it + bypasses the permission system. Use _permission_ instead. + +* permission + * Allowed values: String value + * Example: `permission="createpage, createtalk"` + + A comma-separated list of [user + permissions](https://www.mediawiki.org/wiki/Manual:User_rights#List_of_permissions) + for which the component should be hidden. + +* namespace + * Allowed values: String value + * Example: `group="NS_MAIN, NS_TALK"` + + A comma-separated list of + [namespaces](https://www.mediawiki.org/wiki/Manual:Namespace_constants) for + which the component should be hidden. The namespaces may be specified as + namespace constants or as namespace index numbers. + +------------------------------------------------------------------------------- +### Modification `ShowOnlyFor` + +A modification that allows to show the parent component only if the condition +specified by the attributes is fulfilled. + +This is a permissive filter. It will show the component if _any_ of the +attributes match. + +#### Example usage + +``` xml +<modification type="ShowOnlyFor" permission="edit" namespace="NS_TALK" /> +``` + +This will show the parent component of the modification if the user has the +_edit_ right or if the current page is in the 'Talk' namespace (or both). + +#### Attributes + +* group + * Allowed values: Any string + * Example: `group="emailconfirmed, autoconfirmed"` + + A comma-separated list of [user + groups](https://www.mediawiki.org/wiki/Manual:User_rights#List_of_groups) for + which the component should be shown. + + It is generally not advised to use the _group_ attribute, as it bypasses the + permission system. Use _permission_ instead. + +* permission + * Allowed values: Any string + * Example: `permission="createpage, createtalk"` + + A comma-separated list of [user + permissions](https://www.mediawiki.org/wiki/Manual:User_rights#List_of_permissions) + for which the component should be shown. + +* namespace + * Allowed values: Any string + * Example: `group="NS_MAIN, NS_TALK"` + + A comma-separated list of + [namespaces](https://www.mediawiki.org/wiki/Manual:Namespace_constants) for + which the component should be shown. The namespaces may be specified as + namespace constants or as namespace index numbers. + +------------------------------------------------------------------------------- +### Modification `Sticky` + +A modification that will ensure that the parent component stays always visible +when the user scrolls. + +#### Example usage + +``` xml +<modification type="Sticky" /> +``` + +This will make the parent component of the modification stick to the page. + +#### Attributes +None. |