Template:Clickable button/doc: Difference between revisions

From Official Kodi Wiki
Jump to navigation Jump to search
(Write documentation for new Clickable button template)
 
(Little tweaks and such to documentation content and inline CSS)
Line 1: Line 1:
<div style="font-size: 1.19em; font-weight: 800;">[[Template:Clickable button|This template]], <code><nowiki>{{Clickable button}}</nowiki></code>, provides a uniform way to create clickable buttons on pages.</div><br />
<div style="font-size: 1.19em; font-weight: 700; margin-bottom: 1.33em;">[[Template:Clickable button|This template]], named {{Clickable button|target=Template:Clickable button|text='''Clickable button'''|iconPrimary=ui-icon-link|iconSecondary=ui-icon-extlink|class=ui-button-green}}, provides a uniform way to create clickable buttons on pages which behave like plain-text hyperlinks but offer much greater visial differentiation from the standard content.</div>


<div style="font-size: 1.09em; font-style: italic; font-weight: 600;">* For the purposes of Kodi Wiki and this documentation, the term 'clickable' shall be defined as BOTH<br />
<div style="font-size: 1.09em; font-style: italic; font-weight: 500;">* For the purposes of Kodi Wiki and this documentation, the term 'clickable' shall be defined as BOTH<br />
:1) reacting to mouse-over hovering and keyboard selection as the active page element with visual cues, AND<br />
:1) reacting to mouse-over hovering and keyboard selection as the active page element with visual cues, AND<br />
:2) performing a valid HTML 5.0 page action such as behaving like an <a> tag, triggering the loading of another web page.</div>
:2) performing a valid HTML 5.0 page action such as behaving like an <a> tag, triggering the loading of another web page.</div>
Line 13: Line 13:
When used in the block style instead, it appears as:
When used in the block style instead, it appears as:


<div style="font-family: monospace; font-size: 1.10em; font-weight: 700; margin-left: 4em;"><code>{{Clickable button<br />&nbsp;|&nbsp;target&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#61;<br />&nbsp;|&nbsp;text&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#61;<br />&nbsp;|&nbsp;external&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#61;<br />&nbsp;|&nbsp;iconPrimary&nbsp;&nbsp;&nbsp;&#61;<br />&nbsp;|&nbsp;iconSecondary&nbsp;&#61;<br />&nbsp;|&nbsp;class&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#61;<br />&nbsp;|&nbsp;id&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#61;<br />}}</code></div>
<pre style="font-size: 1.10em; font-weight: 700; margin: 1em 11.5em 2.5em 4em;">{{Clickable button
| target       =
| text         =
| external     =
| iconPrimary   =
| iconSecondary =
| class         =
| id           =
}}</pre>


=== Template parameters ===
== Template parameters ==
{|class="wikitable"
{|class="wikitable"
  |+ Parameter listing for Template:Clickable_button
  |+ Parameter listing for Template:Clickable_button
Line 22: Line 30:
  |-
  |-
  ! <code>target&nbsp;&#61;</code><br /><code>1&nbsp;&#61;</code>
  ! <code>target&nbsp;&#61;</code><br /><code>1&nbsp;&#61;</code>
  | The target page of the button's underlying hyperlink, if also on Kodi Wiki simply the page name or prepended with the page's namespace. If the target is located on a different web site, then the value must be a URI with a fully-qualified domain name (FQDN), and directory path/page (if needed), optionally prepended with the protocol. It is strongly advisable in the case of external targets to use the named parameter <code>target&nbsp;&#61;</code> in the event such a link uses the equals sign '=' character which confuses/breaks the template parser.
  | The target page of the button's underlying hyperlink, if also on Kodi Wiki simply the page name or prepended with the page's namespace. If the target is located on a different web site, then the value must be a URI with an authority (fully-qualified domain name or FQDN) and also a resource path (if needed), optionally prepended with the protocol scheme. It is strenuously advised when defining external targets to use the named parameter <code>target&nbsp;&#61;</code> rather than the unnamed/positional one, in the event such a link uses the equals sign '=' character which confuses/breaks the template parser.
  | Undefined<br /><span style="font-size: 0.92em; font-style: italic;">(User must provide)</span>
  | Undefined<br /><span style="font-size: 0.92em; font-style: italic;">(User must provide)</span>
  | <u>Required</u>
  | <u>Required</u>
Line 82: Line 90:


== Dependencies ==
== Dependencies ==
This template relies on being able to load [https://gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=tree;f=resources/jquery.ui jquery.ui.button].
This template relies on being able to load [https://github.com/wikimedia/mediawiki/raw/master/resources/lib/jquery.ui/jquery.ui.button.js jquery.ui.button.js].


== Test suite/Unit tests ==
== Test suite/Unit tests ==
Line 93: Line 101:


<includeonly>
<includeonly>
<!-- Interwikis go on Wikidata, please add only Categories here -->
<!-- Please add only Categories here, in alphabetical order -->
[[Category:Formatting templates]]
[[Category:Formatting templates]]
</includeonly>
</includeonly>

Revision as of 02:55, 16 August 2021

This template, named Clickable button , provides a uniform way to create clickable buttons on pages which behave like plain-text hyperlinks but offer much greater visial differentiation from the standard content.
* For the purposes of Kodi Wiki and this documentation, the term 'clickable' shall be defined as BOTH
1) reacting to mouse-over hovering and keyboard selection as the active page element with visual cues, AND
2) performing a valid HTML 5.0 page action such as behaving like an <a> tag, triggering the loading of another web page.

Usage

The template, with its full complement of parameters (but no values, making this well-suited to the copy/paste maneuver into the Wikitext of the page you wish to using it in) looks like this using the inline template style:

{{Clickable button|target=|text=|external=|iconPrimary=|iconSecondary=|class=|id=}}


When used in the block style instead, it appears as:

{{Clickable button
 | target        =
 | text          =
 | external      =
 | iconPrimary   =
 | iconSecondary =
 | class         =
 | id            =
}}

Template parameters

Parameter listing for Template:Clickable_button
Parameter Description Default Status
target =
1 =
The target page of the button's underlying hyperlink, if also on Kodi Wiki simply the page name or prepended with the page's namespace. If the target is located on a different web site, then the value must be a URI with an authority (fully-qualified domain name or FQDN) and also a resource path (if needed), optionally prepended with the protocol scheme. It is strenuously advised when defining external targets to use the named parameter target = rather than the unnamed/positional one, in the event such a link uses the equals sign '=' character which confuses/breaks the template parser. Undefined
(User must provide)
Required
text =
2 =
Text label that appears on the button. If you choose not to set a value for this parameter, the iconPrimary parameter's status changes to Required. Undefined Suggested
external =
3 =
Accepts a boolean value for whether or not the target is an external link. If it is, set to 'yes', 'true', or '1'. For links to other Kodi Wiki pages if can be left undefined, or set as the logical inverse of the values just described. Undefined Optional
iconPrimary =
4 =
A JQuery.UI icon class for the primary icon (preceding the label/name text, depends on direction the language is written in), e.g. ui-icon-gear. Undefined Suggested
iconSecondary =
5 =
A JQuery.UI icon class for the secondary icon (following the label/name text or the iconPrimary), e.g. ui-icon-triangle-1-s. Undefined Optional
class = Add CSS classes like ui-button-green ui-button-large, shorthand for sets of predefined configurations that manipulate the appearance of a web element like a button. Typically includes things such as colors, fonts, and "thickness." Undefined Optional
id = Unique 'ID' attribute to be set for the button. Mostly used for JavaScript bindings and CSS styling in tandem with the preceding class parameter. Undefined Optional

Examples

{{Clickable button|FAQ|Frequently asked questions}}
Frequently asked questions

{{Clickable button|target={{fullurl:{{FULLPAGENAME}}|withJS=MediaWiki:VisualFileChange.js}}|text=This page with '''VisualFileChange'''|external=true}}
This page with VisualFileChange

{{Clickable button|:w:Wikipedia:Manual of Style/Layout|'''Wikipedia's Manual of Style'''|class=ui-button-green ui-button-large}}
Wikipedia's Manual of Style

{{Clickable button|:w:Wikipedia:Twinkle/Preferences|Twinkle Preferences|iconPrimary=ui-icon-wrench|class=ui-button-blue ui-button-large}}
Twinkle Preferences

{{Clickable button|target={{fullurl:Special:Random/User talk|action=edit&section=new&preloadtitle=I+love+your+work}}|text=Do something nice for a random editor|iconSecondary=ui-icon-heart|external=true|class=ui-button-red}}
Do something nice for a random editor

Dependencies

This template relies on being able to load jquery.ui.button.js.

Test suite/Unit tests

Icon only Parameter 'text' is empty Parameter 'text' is empty Parameter 'text' is empty
Icon text Abc Abc Abc
Text only, links Abc Abc [Main Page Abc ]
Colors Abc Abc Abc