Skip to content

Commit 3438545

Browse files
athphaneathphane
committed
docs: optimize existing docs
1 parent ea1e0b4 commit 3438545

File tree

5 files changed

+327
-149
lines changed

5 files changed

+327
-149
lines changed

‎docs/basic-usage/inputs-and-textarea.md‎

Lines changed: 75 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -3,63 +3,98 @@ title: Input and textarea elements
33
sidebar_position: 1
44
---
55

6-
The minimum requirement for an `input` or `textarea` is the `name` attribute.
6+
7+
The `input` and `textarea` components are the workhorses of form creation. They handle labels, values, validation errors, and layout automatically.
8+
9+
## Basic Usage
10+
11+
The minimum requirement is the `name` attribute.
712

813
```html
914
<x-forms::input name="company_name" />
1015
```
1116

12-
Optionally you can add a `label` attribute, which can be computed as well.
17+
## Labels & Layout
1318

14-
```html
15-
<x-forms::input name="company_name" label="Company name" />
16-
<x-forms::input name="company_name" :label="__('Company name')" />
17-
```
19+
You have full control over how labels are rendered.
20+
21+
### Standard Labels
1822

19-
You can also choose to use a `placeholder` instead of a label, and of course you can change the `type` of the element.
23+
You can provide a label directly or let the value be computed from the name (e.g., `company_name` -> "Company Name").
2024

2125
```html
22-
<x-forms::input type="email" name="current_email" placeholder="Current email address" />
26+
<!-- Explicit Label -->
27+
<x-forms::input name="company_name" label="Company Name" />
28+
29+
<!-- Translated Label -->
30+
<x-forms::input name="company_name" :label="__('Company Name')" />
2331
```
2432

25-
By default, every element shows validation errors, but you can hide them if you want.
33+
### Floating & Inline Labels
34+
35+
Support for different form layouts is built-in.
36+
37+
:::info
38+
The column widths for `inline` labels are defined in your `forms.php` config file under `frameworks`.
39+
:::
2640

2741
```html
28-
<x-forms::textarea name="description" :show-errors="false" />
42+
<!-- Floating Label (Material Style) -->
43+
<x-forms::input name="company_name" label="Company Name" floating />
44+
45+
<!-- Inline Label (Horizontal Form) -->
46+
<x-forms::input name="company_name" label="Company Name" inline />
2947
```
3048

31-
By default, the input will be rendered inside a form group.
32-
You can display the `label` either inline or as a floating label using the `inline` and `floating` attributes.
49+
### No Label
50+
51+
If you need the input without the wrapping `form-group` or label:
3352

3453
```html
35-
<x-forms::input name="company_name" label="Company name" inline />
36-
<x-forms::input name="company_name" label="Company name" floating />
54+
<x-forms::input name="search" placeholder="Search..." :show-label="false" />
3755
```
3856

39-
If you want to hide the label and not wrap the input inside a form group, you can hide the label:
57+
## Validation & Required Fields
58+
59+
Validation errors are shown automatically directly below the input if they exist in the `$errors` bag.
60+
61+
### Required Indicator
62+
63+
Adding the `required` attribute automatically appends an asterisk `*` to the label to indicate the field is mandatory.
4064

4165
```html
42-
<x-forms::textarea name="description" :show-label="false" />
66+
<x-forms::input name="email" required />
4367
```
4468

45-
You can mark an input as required using the `required` attribute.
46-
This will also add an `*` to the input label.
69+
You can customize the text (removing the `*` or changing it to `(Required)`) by publishing the translations.
70+
71+
### Hiding Errors
72+
73+
To suppress validation messages for a specific field:
4774

4875
```html
49-
<x-forms::input name="company_name" label="Company name" required />
76+
<x-forms::input name="username" :show-errors="false" />
5077
```
5178

52-
To change the `*` to some other text such as `(Required)`, you can publish the package translations and edit the `strings.php` language file.
79+
## Available Options
5380

54-
```php
55-
...
56-
'required_text' => '(Required)',
57-
...
58-
```
81+
| Prop | Type | Default | Description |
82+
|---|---|---|---|
83+
| `name` | `string` | **Required** | The name of the input field. Used for id, name, and error bag lookup. |
84+
| `label` | `string` | `null` | The text for the label. If omitted, a title-cased version of `name` is tried. |
85+
| `value` | `mixed` | `null` | The default value. If a model is bound to the form, that takes precedence. |
86+
| `type` | `string` | `'text'` | The HTML input type (e.g., `text`, `email`, `password`). |
87+
| `placeholder` | `string` | `null` | The placeholder text. |
88+
| `required` | `bool` | `false` | If true, adds `required` attribute and appends `*` to label. |
89+
| `inline` | `bool` | `false` | Renders the label and input side-by-side (horizontal layout). |
90+
| `floating` | `bool` | `false` | Renders a floating label. |
91+
| `show-label` | `bool` | `true` | Set to `false` to render only the input tag. |
92+
| `show-errors` | `bool` | `true` | Set to `false` to hide validation errors. |
93+
| `help` | `string` | `null` | Helper text to display below the input. |
94+
95+
## Available Components
5996

60-
The `input` element will default to `text` input.
61-
For convenience, components for other HTML5 input types are also included which are just extensions of the `input` component.
62-
The included input types are given below.
97+
For convenience, we provide aliases for common input types. These are all wrappers around the core `input` component.
6398

6499
```html
65100
<x-forms::text name="text" />
@@ -69,6 +104,16 @@ The included input types are given below.
69104
<x-forms::email name="email" />
70105
<x-forms::url name="url" />
71106
<x-forms::tel name="tel" />
72-
<x-forms::latitude name="latitude" /> <!-- Number field with range -90 to 90 -->
73-
<x-forms::longitude name="longitude" /> <!-- Number field with range -180 to 180 -->
107+
```
108+
109+
### Special Inputs
110+
111+
Some inputs have extra logic:
112+
113+
* **`<x-forms::latitude />`**: A number input restricted to `-90` to `90`.
114+
* **`<x-forms::longitude />`**: A number input restricted to `-180` to `180`.
115+
116+
```html
117+
<x-forms::latitude name="lat" step="0.000001" />
118+
<x-forms::longitude name="lng" step="0.000001" />
74119
```

‎docs/basic-usage/model-binding.md‎

Lines changed: 54 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -3,40 +3,55 @@ title: Model Binding and Default Values
33
sidebar_position: 2
44
---
55

6-
You can use the `default` attribute to specify the default value of the element.
6+
7+
Model binding allows you to populate your forms with data from Eloquent models or other objects automatically.
8+
9+
## Precedence Order
10+
11+
It is important to understand how the component decides which value to show. The priority list is as follows (highest to lowest):
12+
13+
1. **Old Input**: If a validation error occurred or the form was just submitted, `old('name')` takes top priority.
14+
2. **Explicit Value**: A hardcoded `:value="..."` attribute.
15+
3. **Model Binding**: Value derived from a bound Model or Object (e.g., `$user->name`).
16+
4. **Default Attribute**: The `default="..."` attribute passed to the component.
17+
5. **Null**: Empty string.
18+
19+
## Binding Methods
20+
21+
### 1. Simple Default Values
22+
23+
For simple use cases where you just want a fallback value:
724

825
```html
926
<x-forms::textarea name="motivation" default="I want to use this package because..." />
1027
```
1128

12-
# Binding a target
29+
### 2. Binding (Single Component)
1330

14-
Instead of setting a default value, you can also pass in a target, like an Eloquent model. Now the component will get the value from the target by the `name`.
31+
You can bind a specific model to a single component.
1532

1633
```html
17-
<x-forms::textarea name="description" :model="$video" />
34+
<x-forms::input name="title" :model="$post" />
1835
```
36+
*This renders value of `$post->title`.*
1937

20-
In the example above, where `$video` is an Eloquent model, the default value will be `$video->description`.
21-
22-
# Binding a form
38+
### 3. Binding (Whole Form)
2339

24-
Instead of binding individual elements, you can bind a whole form.
40+
Commonly, you'll want to bind an entire form to a model.
2541

2642
```html
2743
<x-forms::form :model="$video">
44+
<!-- Populates with $video->title -->
2845
<x-forms::input name="title" />
46+
47+
<!-- Populates with $video->description -->
2948
<x-forms::textarea name="description" />
3049
</x-forms::form>
3150
```
3251

33-
In the example above, the elements inside the form will be bound to the `$video` Eloquent model.
34-
The default value of the `title` text input will be `$video->title` and the default value of the `description` textarea will be `$video->description`.
35-
36-
# Binding a target to multiple elements
37-
38-
You can also bind a target by using the `@model` directive. This will bind the target to all elements until the `@endmodel` directive.
52+
### 4. The `@model` Directive
3953

54+
If you aren't using the `x-forms::form` component but still want binding scope, use the blade directive.
4055

4156
```html
4257
<div>
@@ -47,33 +62,40 @@ You can also bind a target by using the `@model` directive. This will bind the t
4762
</div>
4863
```
4964

50-
You can even mix targets!
65+
## Advanced & Nested Binding
5166

52-
```html
53-
<x-forms::form>
54-
@model($user)
55-
<x-forms::input name="full_name" label="Full name" />
67+
You can nest bindings or override them for specific fields.
68+
69+
### Nested Models
5670

57-
@model($userProfile)
58-
<x-forms::textarea name="biography" label="Biography" />
59-
@endmodel
71+
Useful when a form handles relations (e.g., User and UserProfile).
6072

61-
<x-forms::input name="email" label="Email address" />
73+
```html
74+
<x-forms::form :model="$user">
75+
<x-forms::input name="full_name" />
76+
77+
<!-- Switch context to profile -->
78+
@model($user->profile)
79+
<x-forms::textarea name="biography" />
6280
@endmodel
81+
82+
<!-- Back to $user context -->
83+
<x-forms::input name="email" />
6384
</x-forms::form>
6485
```
6586

66-
# Override or remove a binding
87+
### Breaking the Binding
6788

68-
You can override the `@model` directive by passing a target directly to the element using the `:model` attribute.
69-
If you want to remove a binding for a specific element, pass in false.
89+
You can opt-out of binding for a specific field by setting `:model="false"` or providing a specific bound object.
7090

7191
```html
72-
<x-forms::form>
73-
@model($video)
74-
<x-forms::input name="title" label="Title" />
75-
<x-forms::input :model="$videoDetails" name="subtitle" label="Subtitle" />
76-
<x-forms::textarea :model="false" name="description" label="Description" />
77-
@endmodel
92+
<x-forms::form :model="$video">
93+
<x-forms::input name="title" />
94+
95+
<!-- Use a different model -->
96+
<x-forms::input name="category_name" :model="$category" />
97+
98+
<!-- No binding at all -->
99+
<x-forms::textarea name="comments" :model="false" />
78100
</x-forms::form>
79101
```

0 commit comments

Comments
 (0)