Skip to content

Latest commit

 

History

History
165 lines (123 loc) · 8.33 KB

Button.md

File metadata and controls

165 lines (123 loc) · 8.33 KB

Button

The <button> HTML element is an interactive element activated by a user with a mouse, keyboard, finger, voice command, or other assistive technology. Once activated, it then performs an action, such as submitting a form or opening a dialog.

Basic Usage

Instantiate the Button class using Button::widget().

$button = Button::widget();

Setting Attributes

Use the provided methods to set specific attribute for the button element.

// setting the title attribute
$button->title('MyTitle');

Or, use the attributes method to set multiple attributes at once.

$button->attributes(['title' => 'MyTitle', 'class' => 'btn btn-primary']);

Adding Content

If you want to include content within the button tag, use the content method.

$button->content('MyContent');

Rendering

Generate the HTML output using the render method.

$html = $button->render();

Or, use the magic __toString method.

$html = (string) $button;

Common Use Cases

Below are examples of common use cases:

// adding multiple attributes
$button->class('external')->content('MyContent')->title('Mytitle');

// using data attributes
$button->dataAttributes(['bs-toggle' => 'modal', 'bs-target' => '#exampleModal', 'analytics' => 'trackClick']);

Explore additional methods for setting various attributes such as ariaControls, tabIndex, role, etc.

Container

Use the container() method to add a container around the button tag.

// adding a container
$button->content('MyContent')->container()->render();

Prefix and Suffix

Use prefix and suffix methods to add text before and after the button tag, respectively.

// adding a prefix
$button = $button->content('MyContent')->prefix('MyPrefix')->render();

// adding a suffix
$button = $button->content('MyContent')->suffix('MySuffix')->render();

Template

The template method allows you to customize the HTML output of the button element.

The following template tags are available:

Tag Description
{prefix} The prefix text.
{tag} The button element.
{suffix} The suffix text. 
// using a custom template
$button->template('<span>{tag}</span>');

Attributes

Refer to the Attribute Tests for comprehensive examples.

The following methods are available for setting attributes:

Method Description
ariaControls() Set the aria-controls attribute.
ariaDescribedby() Set the aria-describedby attribute.
ariaDisabled() Set the aria-disabled attribute.
ariaExpanded() Set the aria-expanded attribute.
ariaLabel() Set the aria-label attribute.
attributes() Set multiple attributes at once.
autofocus() Set the autofocus attribute.
class() Set the class attribute.
content() Set the content within the button element.
dataAttributes() Set multiple data-attributes at once.
formaction() Set the formaction attribute.
formenctype() Set the formenctype attribute.
formmethod() Set the formmethod attribute.
formnovalidate() Set the formnovalidate attribute.
formtarget() Set the formtarget attribute.
id() Set the id attribute.
lang() Set the lang attribute.
name() Set the name attribute.
role() Set the role attribute.
style() Set the style attribute.
tabindex() Set the tabindex attribute.
title() Set the title attribute.
type() Set the type attribute.
Allowed values: button, submit, reset.

Custom methods

Refer to the Custom Method Test for comprehensive examples.

The following methods are available for customizing the HTML output:

Method Description
container() Set enabled or disabled for the container element.
containerAttributes() Set attributes for the container element.
containerClass() Set the class attribute for the container element.
containerTag() Set the tag for the container element.
prefix() Add text before the tag element. If empty, the prefix tag will be disabled.
prefixAttributes() Set attributes for the prefix element.
prefixClass() Set the class attribute for the prefix element.
prefixTag() Set the tag for the prefix element.
If false the prefix tag will be disabled.
render() Generates the HTML output.
suffix() Add text after the tag element. If empty, the suffix tag will be disabled.
suffixAttributes() Set attributes for the suffix element.
suffixClass() Set the class attribute for the suffix element.
suffixTag() Set the tag for the suffix-container element.
If false the suffix tag will be disabled.
tagName() Set the tag for the button element.
Allowed values: a, button.
template() Set the template for the button element.
widget() Instantiates the Button::class.