Module:Clickable button/doc: Difference between revisions

(24 intermediate revisions by one other user not shown)

Line 1:

~~<div style="background-color~~: ~~var(--background-color-neutral-subtle); width~~: ~~auto; padding~~: 0.~~2em 0~~.~~5em; margin: 4px 10%; border: 1px solid var(--border-color-disabled)">~~'''Shortcuts:''' {{mdl|module=Clickable button}}~~</div>~~

{{lua|Module:Arguments|Module:Yesno|Module:Check for unknown parameters|Module:If preview}}

{{uses templatestyles|Module:Clickable button/styles.css|Module:Clickable button/icons.css}}

{{mbox|type=message|text='''Shortcuts:'''{{nbsp}}{{mdl|module=Clickable button}}|image=none}}

'''Generates wikitext ~~to render the a~~ clickable button'''. Renders the button component from the [[wmdoc:codex/latest|Codex design system for Wikimedia]]. Includes helper functions for URL parsing and cleaning, adding tracking categories. Intended for use in templates and other modules. Implements [[Template:Clickable button]] and others. Supports legacy parameters.

'''Generates wikitext for clickable Codex button'''. Renders the [[wmdoc:codex/latest/components/demos/button.html|button component]] from the [[wmdoc:codex/latest|Codex design system for Wikimedia]]. Includes helper functions for URL parsing and cleaning, adding tracking categories. Intended for use in templates and other modules. Implements [[Template:Clickable button]] and others. Supports legacy parameters.

* Options to include an icon ~~from the list in [[Template:Clickable button/styles.css]]~~

* Options to include an icon or create an icon-only button.

* Create an icon-only ~~or a dummy~~ button ~~(no target link/URL)~~

* Target a URL or a wikilink

* Set the weight, size and state of the button (enabled or disabled).

* Dummy button creation can be disabled.

'''For more information on appropriate usage of UI buttons, see [[wmdoc:codex/latest/components/demos/button.html|the Codex documentation]].'''

<li> Inserts two CSS files. [[Module:Clickable button/styles.css]] is required and makes minor tweaks for word-wrapping if the visible label is too long, centering or aligning button left or right, and minimum widths as is needed for icon-only buttons and labels containing two characters or less.</li>

<li> The second CSS file, [[Module:Clickable button/icons.css]], is prepended to the button's HTML only if an icon is used.</li>

<li> Supports legacy parameters from previous templates.</li>

</ul>

== Usage in wikitext ==

Some arguments are case-'''in'''sensitive.

<syntaxhighlight lang=wikitext>{{#invoke:Clickable button|main

| 1 =

| 2 =

| label =

| link =

| url =

| action =

| weight =

| size =

| icon =

| disabled =

| aria-label =

| nocat =

| category =

| class =

| style =

| color =

}}</syntaxhighlight>

== Usage in other modules ==

Ensure you know what to expect from the function you call from another module.

* <syntaxhighlight inline lang=lua>function p.main(frame)</syntaxhighlight> emits TemplateStyles for the CSS files with the wikitext, and pre-processes the arguments in a <syntaxhighlight inline lang=lua>frame</syntaxhighlight> using [[Module:Arguments]], e.g. ignore blank values<code style="color: var(--color-destructive);">'<nowiki/>'</code>, and trim trailing whitespace.

* <syntaxhighlight inline lang=lua>function p._main(arguments)</syntaxhighlight> Parses the arguments such as lowercase appropriate arguments, account for use of legacy parameters and decides whether <code class="mw-highlight mw-highlight-lang-lua"><span class=nv>aria-disabled</span></code> should be <code class="mw-highlight mw-highlight-lang-lua"><span class=kc>true</span></code>.

* <syntaxhighlight inline lang=lua>function p.url(url, [label])</syntaxhighlight> is available, not for button creation, but as an adaption of [[Module:URL]] to clean and normalise a URL string and optionally generate a label.

* The module's other functions, such as <syntaxhighlight inline lang=lua>makeLinkData()</syntaxhighlight> and <syntaxhighlight inline lang=lua>renderLink()</syntaxhighlight>, are localised/local to the module and would need to be made global first to be accessible to other modules.

To call <syntaxhighlight inline lang=lua>p.main()</syntaxhighlight> for example, use:

<syntaxhighlight lang=lua>local createButton = require( 'Module:Clickable button/sandbox' )

buttonWikitext = createButton.main( {

link = 'South Africa',

label = 'Go to South Africa',

action = 'progressive'

weight = 'default',

size = 'medium',

icon = 'link-external',

} )

return buttonWikitext</syntaxhighlight>

<div style="text-align:center;">{{#invoke:Clickable button|main|link = South Africa|

label = Go to South Africa|

action = progressive|

weight = default|

size = medium|

icon = link-external}}</div>

and the value of <code class="mw-highlight mw-highlight-lang-lua"><span class="nv">buttonWikitext</span></code> would be:

<syntaxhighlight lang=wikitext><<templatestyles src="Module:Cdx-button/styles.css" /><templatestyles src="Module:Cdx-button/icons.css" /><span class="cdx-button cdx-button--fake-button cdx-button--action-progressive cdx-button--weight-quiet cdx-button--size-medium" role="button" aria-disabled="false"><span class="cdx-button__icon cdx-demo-css-icon--link-external" aria-hidden="true"></span>Go to South Africa</span></syntaxhighlight>

Function <code class="mw-highlight mw-highlight-lang-lua"><span class="nf">_main</span></code> would output:

<syntaxhighlight lang=wikitext><span class="cdx-button cdx-button--fake-button cdx-button--action-progressive cdx-button--weight-quiet cdx-button--size-medium" role="button" aria-disabled="false"><span class="cdx-button__icon cdx-demo-css-icon--link-external" aria-hidden="true"></span>Go to South Africa</span></syntaxhighlight>

As a result, unless a CSS file is added to give the appropriate class an icon, the icon will not render.

== Implementation ==

=== Length of visible label <span id="Button label length"></span> ===

See [[wmdoc:codex/latest/components/demos/button.html|the Codex button component documentation]].

</includeonly>

Admin (talk | contribs)