Skip to content

Commit

Permalink
Add doc input Submit::class. (#318)
Browse files Browse the repository at this point in the history
  • Loading branch information
@terabytesoftw
terabytesoftw committed Feb 19, 2024
1 parent 5e46980 commit 87a1c04
Show file tree
Hide file tree
Showing 4 changed files with 173 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 @@ -68,6 +68,7 @@ This is particularly useful for creating forms and other interactive elements on
- [radio-list](/docs/form/input/RadioList.md)
- [range](/docs/form/input/Range.md)
- [reset](/docs/form/input/Reset.md)
- [submit](/docs/form/input/Submit.md)
- [text](/docs/form/input/Text.md)
- [time](/docs/form/input/Time.md)
- [url](/docs/form/input/Url.md)
Expand Down
160 changes: 160 additions & 0 deletions docs/form/input/Submit.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,160 @@
# Submit

The input element with a type attribute whose value is `submit` represents a button for submitting a form.

## Basic Usage

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

```php
$submit = Submit::widget();
```

## Setting Attributes

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

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

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

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

## Adding value

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

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

## Rendering

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

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

Or, use the magic `__toString` method.

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

## Common use cases

Below are examples of common use cases:

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

// using data attributes
$submit->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 = $submit->value('MyValue')->prefix('MyPrefix')->render();

// adding a suffix
$html = $submit->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
$submit->template('<div>{tag}</div>');
```

## Attributes

Refer to the [Attribute Tests](https://github.com/php-forge/html/blob/main/tests/Input/Submit/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. |
| `style()` | Set the `style` attribute. |
| `tabIndex()` | Set the `tabindex` attribute. |
| `title()` | Set the `title` attribute. |
| `value()` | Set the `value` attribute. |

## Custom methods

Refer to the [Custom Methods Tests](https://github.com/php-forge/html/blob/main/tests/Input/Submit/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 `Submit::class`. |
|
## Label methods

Refer to the [Label Tests](https://github.com/php-forge/html/blob/main/tests/Input/Submit/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/Submit/AttributeTest.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -207,18 +207,6 @@ public function testReadonly(): void
);
}

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

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

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

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

0 comments on commit 87a1c04

Please sign in to comment.