Skip to content

Commit

Permalink
Add doc input Range::class. (#315)
Browse files Browse the repository at this point in the history
  • Loading branch information
@terabytesoftw
terabytesoftw committed Feb 19, 2024
1 parent 6d62c42 commit 48f954c
Show file tree
Hide file tree
Showing 5 changed files with 225 additions and 40 deletions.
1 change: 1 addition & 0 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,7 @@ This is particularly useful for creating forms and other interactive elements on
- [password](/docs/form/input/Password.md)
- [radio](/docs/form/input/Radio.md)
- [radio-list](/docs/form/input/RadioList.md)
- [range](/docs/form/input/Range.md)
- [text](/docs/form/input/Text.md)
- [time](/docs/form/input/Time.md)
- [url](/docs/form/input/Url.md)
Expand Down
169 changes: 169 additions & 0 deletions docs/form/input/Range.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,169 @@
# Range

The input element with a type attribute whose value is `range` represents an imprecise control for setting the element’s
value to a string representing a number.

## Basic Usage

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

```php
$range = Range::widget();
```

## Generate field id and name

The `generateField` method is used to generate the field id and name for the `HTML` output.

Allowed arguments are:

- `modelName` - The name of the model.
- `fieldName` - The name of the field.
- `arrayable` - Whether the field is an array. For default, it is `false`.

```php
// generate field id and name
$range->generateField('model', 'field');
```

## Setting Attributes

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

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

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

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

## Adding value

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

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

## Rendering

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

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

Or, use the magic `__toString` method.

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

## Common use cases

Below are examples of common use cases:

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

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

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

## Prefix and Suffix

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

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

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

## Attributes

Refer to the [Attribute Tests](https://github.com/php-forge/html/blob/main/tests/Input/Range/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/Range/CustomMethodTest.php)
for comprehensive examples.

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

| Method | Description |
| ---------------------------- | ------------------------------------------------------------------------------------- |
| `generateField()` | Generate the field id and name for the `HTML` output. |
| `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 `Range::class`. |

## Validate methods

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

| Method | Description |
| ------- | ---------------------------------------------------------------------------------------------------------- |
| `max()` | Set the `max` attribute. |
| `min()` | Set the `min` attribute. |
| `step()`| Set the `step` attribute. |
40 changes: 0 additions & 40 deletions tests/Input/Range/AttributeTest.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -153,26 +153,6 @@ public function testLang(): void
);
}

public function testMax(): void
{
Assert::equalsWithoutLE(
<<<HTML
<input id="range-6582f2d099e8b" type="range" max="value">
HTML,
Range::widget()->id('range-6582f2d099e8b')->max('value')->render()
);
}

public function testMin(): void
{
Assert::equalsWithoutLE(
<<<HTML
<input id="range-6582f2d099e8b" type="range" min="value">
HTML,
Range::widget()->id('range-6582f2d099e8b')->min('value')->render()
);
}

public function testName(): void
{
Assert::equalsWithoutLE(
Expand All @@ -193,26 +173,6 @@ public function testReadonly(): void
);
}

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

public function testStep(): void
{
Assert::equalsWithoutLE(
<<<HTML
<input id="range-6582f2d099e8b" type="range" step="1">
HTML,
Range::widget()->id('range-6582f2d099e8b')->step(1)->render()
);
}

public function testStyle(): void
{
Assert::equalsWithoutLE(
Expand Down
10 changes: 10 additions & 0 deletions tests/Input/Range/CustomMethodTest.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,16 @@ public function testPrefixContainerTag(): void
);
}

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

public function testSuffix(): void
{
Assert::equalsWithoutLE(
Expand Down
45 changes: 45 additions & 0 deletions tests/Input/Range/ValidatorTest.php
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
<?php

declare(strict_types=1);

namespace PHPForge\Html\Tests\Input\Range;

use PHPForge\Html\Input\Range;
use PHPForge\Support\Assert;
use PHPUnit\Framework\TestCase;

/**
* @psalm-suppress PropertyNotSetInConstructor
*/
final class ValidatorTest extends TestCase
{
public function testMax(): void
{
Assert::equalsWithoutLE(
<<<HTML
<input id="range-6582f2d099e8b" type="range" max="value">
HTML,
Range::widget()->id('range-6582f2d099e8b')->max('value')->render()
);
}

public function testMin(): void
{
Assert::equalsWithoutLE(
<<<HTML
<input id="range-6582f2d099e8b" type="range" min="value">
HTML,
Range::widget()->id('range-6582f2d099e8b')->min('value')->render()
);
}

public function testStep(): void
{
Assert::equalsWithoutLE(
<<<HTML
<input id="range-6582f2d099e8b" type="range" step="1">
HTML,
Range::widget()->id('range-6582f2d099e8b')->step(1)->render()
);
}
}

0 comments on commit 48f954c

Please sign in to comment.