From f14b577168a904dc9a57ace9195707ded8c2a815 Mon Sep 17 00:00:00 2001 From: TinaH Date: Tue, 28 Jul 2020 18:43:31 +0200 Subject: [PATCH] wip readme --- readme.md | 70 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 58 insertions(+), 12 deletions(-) diff --git a/readme.md b/readme.md index d53ac0b..77e50e2 100644 --- a/readme.md +++ b/readme.md @@ -17,28 +17,30 @@ The package is in development, it is being used in a live project without issues # Help wanted If you like this package, please help me with the documentation and tests. Send me a PM. -### Requirements +# Requirements - Make sure you've [installed Laravel Livewire](https://laravel-livewire.com/docs/installation/). - Install [Tailwind UI](https://tailwindui.com/) or [Tailwind CSS](https://tailwindcss.com/) + [Form plugin](https://tailwindcss-custom-forms.netlify.app/) - This package also uses [Blade UI kit - blade-icons](https://github.com/blade-ui-kit/blade-icons). Follow the package installation instructions. -## Looking for a Bootstrap CSS version?: +# Looking for a Bootstrap CSS version?: If you want to use Bootstrap CSS you can use the package made by kdion4891, which this package is based on. - [https://github.com/kdion4891/laravel-livewire-forms](https://github.com/kdion4891/laravel-livewire-forms) -## Credits +# Credits - [kdion4891](https://github.com/kdion4891) # Installation Installing this package via composer: +``` composer require tanthammar/tall-forms - +``` You'll need to add `@stack('scripts')`, `@livewireScripts`, and `@livewireStyles` blade directives to your `resources/views/layouts/app.blade.php` file: +```blade @livewireStyles @@ -50,18 +52,21 @@ You'll need to add `@stack('scripts')`, `@livewireScripts`, and `@livewireStyles @livewireScripts @stack('scripts') - +``` # Making Form Components Using the `make` command: +``` - php artisan make:tall-form UserCreateForm --model=User --path=App/ +php artisan make:tall-form UserCreateForm --model=User --path=App/ +``` That command would create a new form component in `app/Http/Livewire/App` folder. After making a component, you may want to edit the `fields`, `success`, `saveAndStayResponse` and `saveAndGoBackResponse` methods: +```php class UserCreateForm extends FormComponent { @@ -87,6 +92,7 @@ After making a component, you may want to edit the `fields`, `success`, `saveAnd return back(); } } +``` You don't have to use the `render()` method in your form component or worry about a component view, because the package handles that automatically. @@ -96,7 +102,9 @@ You don't have to use the `render()` method in your form component or worry abou You use form components in views just like any other Livewire component: - @livewire('user-create-form') +``` + @livewire('user-create-form') +``` Now all you have to do is update your form component class! @@ -108,13 +116,14 @@ Doing so, you can skip the step to create a laravel blade view. **No render meth ### For this feature to work; - Livewire assumes you have a layout stored in `resources/views/layouts/app.blade.php` that yields a "content" section `@yield('content')` - A laravel 7 Blade component: `pages/default.php` with a default `{$slot}`. It will be used as ``. + ``` // Route Route::livewire('/users/edit/{$user}', 'users.edit'); ``` Users/Edit.php -``` +```php use App\User; //override the tall-form components mount method @@ -132,8 +141,10 @@ use App\User; ``` + ### "SPA" mode without route Simply setting the property `spaMode` to true will wrap your form with ``. Don't forget to create the blade component. + ``` $this->spaMode = true; ``` @@ -148,16 +159,21 @@ Publish the config file and set the path and name for the array field icons (use Optional [Eloquent](https://laravel.com/docs/master/eloquent) model instance attached to the form component. This is passed in via the `@livewire` blade directive. Example: +```php @livewire('user-edit-form', ['model' => $user]) +``` + Example of using the model in the component `success` method: +```php public function success() { $this->model->update($this->form_data); } - +``` + ### `$form_data` An array of the current data present in the form. This data is keyed with each field name. @@ -184,12 +200,16 @@ Or, via `.env` to apply globally: A static property which sets the path to use for file uploads. Defaults to `uploads`. Example: +```php private static $storage_path = 'avatars'; - +``` + Or, via `.env` to apply globally: +``` FORM_STORAGE_PATH="avatars" +``` ### Inline or Stacked form layout ```php @@ -262,17 +282,20 @@ Declaring `Field`s is similar to declaring Laravel Nova fields. [Jump to the fie This method is used to set rules to ignore during realtime validation. Example: +```php public function rulesIgnoreRealtime() { return ['confirmed', new MyCustomRule]; } - +``` + ### `success()` This method defines what actions should take place when the form is successfully submitted and validation has passed. Example: +```php public function success() { @@ -281,27 +304,35 @@ Example: User::create($this->form_data); } +``` + ### `saveAndStayResponse()` This method defines the response after successful submission via the `Save` button. Example: +```php public function saveAndStayResponse() { return redirect()->route('users.edit', $this->model->id); } +``` + ### `saveAndGoBackResponse()` This method defines the response after successful submission via the `Save & Go Back` button. By default it uses a version of `redirect()->back()`. See the source code. Example: +```php public function saveAndGoBackResponse() { return redirect()->route('users.index'); } +``` + ### `mount($model = null)` @@ -312,6 +343,7 @@ This method sets the initial form properties. If you have to override it, be sur The model instance passed to the form component. Example: +```php public function mount($model = null) { @@ -319,12 +351,15 @@ Example: // my custom code } +``` + ### `render()` This method renders the form component view. If you have to override it, be sure to `return $this->formView()`. Example: +```php public function render() { @@ -332,11 +367,15 @@ Example: return $this->formView(); } +``` + # Form Field Declaration The `Field` class is used to declare your form fields. +```php + public function fields() { $brand_options = Brand::orderBy('name')->get()->pluck('id', 'name')->all(); @@ -357,6 +396,8 @@ The `Field` class is used to declare your form fields. ]; } +``` + ### `make($label, $name = null)` ##### `$label` @@ -368,16 +409,20 @@ The label to use for the form field, e.g. `First Name`. The name to use for the form field. If null, it will use a snake cased `$label`. Basic field example: +```php Field::make('First Name')->input()->rules('required|min:2'), +``` Relationship field example: +```php $brand_options = Brand::orderBy('name')->get()->pluck('id', 'name')->all(); return [ Field::make('Brand', 'brand_id')->select($brand_options)->rules(['required', Rule::exists('brands', 'id')]), ... +``` ### `input($type = 'text')` @@ -388,8 +433,9 @@ Sets the field to be an `input` element. Defaults to `text`. Optional HTML5 input type to use for the input. Example: - +```php Field::make('Email Address')->input('email'), +``` ### `file()`