Skip to content

Commit

Permalink
Add docs input Button::class. (#297)
Browse files Browse the repository at this point in the history
  • Loading branch information
@terabytesoftw
terabytesoftw committed Feb 16, 2024
1 parent 94015c5 commit ec1762f
Show file tree
Hide file tree
Showing 4 changed files with 175 additions and 12 deletions.
1 change: 1 addition & 0 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ In addition to basic `HTML` tags, the repository also supports the generation of

This is particularly useful for creating forms and other interactive elements on a webpage.

- [button](/docs/form/input/Button.md)
- [date](/docs/form/input/Date.md)
- [datetime-local](/docs/form/input/DatetimeLocal.md)
- [datetime](/docs/form/input/Datetime.md)
Expand Down
162 changes: 162 additions & 0 deletions docs/form/input/Button.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,162 @@
# Button

The input element with a type attribute whose value is `button` represents a button with no more semantics.

## Basic Usage

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

```php
$button = Button::widget();
```

## Setting Attributes

Use the provided methods to set specific attributes for the a element.

```php
// setting class attribute
$button->class('container');
```

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

```php
$button->attributes(['class' => 'container', 'style' => 'background-color: #eee;']);
```

## Adding value

If you want to include value in the `button` element, use the `value` method.

```php
$button->value('MyValue');
```

## Rendering

Generate the `HTML` output using the `render` method, for simple instantiation.

```php
$html = $button->render();
```

Or, use the magic `__toString` method.

```php
$html = (string) $button;
```

## Common use cases

Below are examples of common use cases:

```php
// adding multiple attributes
$button->class('external')->value('Myvalue');

// using data attributes
$button->dataAttributes(['analytics' => 'trackClick']);
```

Explore additional methods for setting various attributes such as `lang`, `name`, `style`, `title`, etc.

## Prefix and Suffix

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

```php
// adding a prefix
$html = $button->value('MyValue')->prefix('MyPrefix')->render();

// adding a suffix
$html = $button->value('MyValue')->suffix('MySuffix')->render();
```

## Template

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

The following template tags are available:

| Tag | Description |
| ---------- | ---------------- |
| `{prefix}` | The prefix text. |
| `{tag}` | The a element. |
| `{suffix}` | The suffix text. |

```php
// using a custom template
$button->template('<div>{tag}</div>');
```

## Attributes

Refer to the [Attribute Tests](https://github.com/php-forge/html/blob/main/tests/Input/Button/AttributeTest.php)
for comprehensive examples.

The following methods are available for setting attributes:

| Method | Description |
| ------------------ | ----------------------------------------------------------------------------------------------- |
| `ariaDescribedBy()`| Set the `aria-describedby` attribute. |
| `ariaLabel()` | Set the `aria-label` attribute. |
| `attributes()` | Set multiple `attributes` at once. |
| `autofocus()` | Set the `autofocus` attribute. |
| `class()` | Set the `class` attribute. |
| `dataAttributes()` | Set multiple `data-attributes` at once. |
| `disabled()` | Set the `disabled` attribute. |
| `form()` | Set the `form` attribute. |
| `hidden()` | Set the `hidden` attribute. |
| `id()` | Set the `id` attribute. |
| `lang()` | Set the `lang` attribute. |
| `name()` | Set the `name` attribute. |
| `readOnly()` | Set the `readonly` attribute. |
| `step()` | Set the `step` attribute. |
| `style()` | Set the `style` attribute. |
| `tabIndex()` | Set the `tabindex` attribute. |
| `title()` | Set the `title` attribute. |
| `type()` | Set the `type` attribute. |
| `value()` | Set the `value` attribute. |

## Custom methods

Refer to the [Custom Methods Tests](https://github.com/php-forge/html/blob/main/tests/Input/Button/CustomMethodTest.php)
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 `textarea` element. |
| `prefixContainer()` | Set enabled or disabled for the `prefix-container` element. |
| `prefixContainerAttributes()`| Set `attributes` for the `prefix-container` element. |
| `prefixContainerClass()` | Set the `class` attribute for the `prefix-container` element. |
| `prefixContainerTag()` | Set the `tag` for the `prefix-container` element. |
| `render()` | Generates the `HTML` output. |
| `suffix()` | Add text after the `label` element. |
| `suffixContainer()` | Set enabled or disabled for the `suffix-container` element. |
| `suffixContainerAttributes()`| Set `attributes` for the `suffix-container` element. |
| `suffixContainerClass()` | Set the `class` attribute for the `suffix-container` element. |
| `suffixContainerTag()` | Set the `tag` for the `suffix-container` element. |
| `template()` | Set the template for the `HTML` output. |
| `widget()` | Instantiates the `Button::class`. |
|
## Label methods

Refer to the [Label Tests](https://github.com/php-forge/html/blob/main/tests/Input/Button/LabelTest.php) for
comprehensive examples.

The following methods are available for customizing the `HTML` output:

| Method | Description |
| ------------------ | ----------------------------------------------------------------------------------------------- |
| `labelAttributes()`| Set `attributes` for the `label` element. |
| `labelClass()` | Set the `class` attribute for the `label` element. |
| `labelContent()` | Set the `content` within the `label` element. |
| `labelFor()` | Set the `for` attribute for the `label` element. |
° `notLabel()` | Set disabled for the `label` element. |
12 changes: 0 additions & 12 deletions tests/Input/Button/AttributeTest.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -203,18 +203,6 @@ public function testReadonly(): void
);
}

public function testRender(): void
{
Assert::equalsWithoutLE(
<<<HTML
<div>
<input id="button-6582f2d099e8b" type="button">
</div>
HTML,
Button::widget()->id('button-6582f2d099e8b')->render()
);
}

public function style(): void
{
Assert::equalsWithoutLE(
Expand Down
12 changes: 12 additions & 0 deletions tests/Input/Button/CustomMethodTest.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -133,6 +133,18 @@ public function testPrefixContainerTag(): void
);
}

public function testRender(): void
{
Assert::equalsWithoutLE(
<<<HTML
<div>
<input id="button-6582f2d099e8b" type="button">
</div>
HTML,
Button::widget()->id('button-6582f2d099e8b')->render()
);
}

public function testSuffix(): void
{
Assert::equalsWithoutLE(
Expand Down

0 comments on commit ec1762f

Please sign in to comment.