From c37d6a45594d67aac21bc13c3d04dcb1cecfade9 Mon Sep 17 00:00:00 2001 From: Giorgio Balduzzi Date: Tue, 16 Jul 2024 17:31:20 +0200 Subject: [PATCH] Completed readme documentation --- README.md | 339 +++++++++++++++++++++++- resources/views/search-select.blade.php | 5 +- src/BsBladeFormsServiceProvider.php | 2 +- 3 files changed, 329 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index ea36add..e464a76 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,41 @@ -# Very short description of the package +# Blade Form Components Library [![Latest Version on Packagist](https://img.shields.io/packagist/v/tiknil/bs-blade-forms.svg?style=flat-square)](https://packagist.org/packages/tiknil/bs-blade-forms) [![Total Downloads](https://img.shields.io/packagist/dt/tiknil/bs-blade-forms.svg?style=flat-square)](https://packagist.org/packages/tiknil/bs-blade-forms) -This is where your description should go. Try and limit it to a paragraph or two, and maybe throw in a mention of what PSRs you support to avoid any confusion with users and contributors. +Opinionated library designed to streamline the process of building forms in Laravel applications by leveraging Blade +components and Boostrap utilities. -## Installation + +- [Key Features](#key-features) +- [Installation](#installation) +- [Usage](#usage) +- [Examples](#examples) +- [Components](#components) + - [SearchSelect](#searchselect) + - [MultiSelect](#multiselect) + - [Select](#select) + - [Input](#input) + - [Textarea](#textarea) + - [Checkbox](#checkbox) + - [Radio](#radio) + + +### Key Features + +- **Reduced boilerplate**: Minimize repetitive code and simplify the form-building process +- **Advanced Select Components**: Utilize `SearchSelect` and `MultiSelect` for enhanced and complex selection input + needs, providing a better user experience. +- **Automatic Old Input Handling**: Automatically + manage [old input](https://laravel.com/docs/validation#repopulating-forms) based on the field name, ensuring form + repopulation is seamless. +- **Livewire Support**: Fully integrate with Livewire by forwarding tags (e.g., `wire:model`) to the underlying + input/select + elements. + + + +### Installation You can install the package via composer: @@ -13,18 +43,303 @@ You can install the package via composer: composer require tiknil/bs-blade-forms ``` -## Usage +JS/CSS assets should be automatically published alongside the default laravel libraries assets. Alternatively, publish +them using: + +```bash +php artisan vendor:publish --tag=bs-blade-forms:assets +``` + +> [!NOTE] +> Boostrap is not imported automatically by the library. We assume you are already using it on your page and it is +> already available + +### Usage + +The advanced select elements (SearchSelect / MultiSelect) requires some additional assets to be included. Add this +between your page `head` tag: ```php -// Usage description here + + ... + {{ BsBladeForms::assets() }} + ``` -### Testing +In your blade templates, use the provided components: -```bash -composer test +```bladehtml + + + + + + +``` + +#### Examples + +Go from: + +```html + + + + + + +
+ newsletter) === '1') /> + +
+``` + +To: + +```bladehtml + + + + + +newsletter) +/> +``` + +## Components + +#### SearchSelect + +Renders a single selection element with a research bar for filtering the options. + +```bladehtml + + +``` + +> [!IMPORTANT] +> Include `{{ BsBladeForms::assets() }}` in the page head for this component to work + +| Attribute | Type | Description | +|--------------------|-------------------|--------------------------------------------------------------------------------| +| name | string | *Required*. Name of the select element | +| options | array, Collection | The options to display on the select. | +| value | string, int | The initial selected value | | +| required | bool | Set the select element as required (form can't be submitted without selection) | | +| placeholder | string | Element placeholder when no option is selected | +| label | string | If present, renders a `Label` above the element | +| icon | string | If present, renders an `IconGroup` around the element | +| allow-clear | bool | Allows the user to clear the selected option | +| empty-value | string | The value to submit when no option is selected | +| search-placeholder | string | The placeholder of the search input | +| * | | Additional attributes will be forwarded to the underlying element. | + +#### MultiSelect + +Renders a multiple selection element with a research bar for filtering the options. + +```bladehtml + + ``` +> [!IMPORTANT] +> Include `{{ BsBladeForms::assets() }}` in the page head for this component to work + +| Attribute | Type | Description | +|--------------------|-------------------|--------------------------------------------------------------------------------| +| name | string | *Required*. Name of the select element | +| options | array, Collection | The options to display on the select. | +| value | array | The initial selected values | | +| required | bool | Set the select element as required (form can't be submitted without selection) | | +| placeholder | string | Element placeholder when no option is selected | +| label | string | If present, renders a `Label` above the element | +| icon | string | If present, renders an `IconGroup` around the element | +| search-placeholder | string | The placeholder of the search input | +| * | | Additional attributes will be forwarded to the underlying element. | + +#### Select + +```bladehtml + + +``` + +| Attribute | Type | Description | +|--------------|-------------------|-----------------------------------------------------------------------------------------| +| name | string | *Required*. Name of the select element | +| options | array, Collection | The options to display on the select. | +| value | string | The initial selected values | | +| required | bool | Set the select element as required (form can't be submitted without selection) | | +| label | string | If present, renders a `Label` above the element | +| icon | string | If present, renders an `IconGroup` around the element | +| empty-option | string | When present, an additional option with empty string as value is added with this label. | +| * | | Additional attributes will be forwarded to the underlying element. | + + +#### Input + +```bladehtml + + +``` + +| Attribute | Type | Description | +|-----------|--------|--------------------------------------------------------------------| +| name | string | *Required*. Name of the input element | +| value | string | The initial value | +| label | string | If present, renders a `Label` above the element | +| icon | string | If present, renders an `IconGroup` around the element | +| type | string | Type of the input (`text` by default) | +| * | | Additional attributes will be forwarded to the underlying element. | + + +#### Textarea + +```bladehtml + + +``` + +| Attribute | Type | Description | +|-----------|--------|--------------------------------------------------------------------| +| name | string | *Required*. Name of the textarea element | +| value | string | The initial value | | +| label | string | If present, renders a `Label` above the element | +| * | | Additional attributes will be forwarded to the underlying element. | + + +#### Checkbox + +```bladehtml + +enabled) +/> +``` + +> [!NOTE] +> When the form is submitted, a parameter is submitted even when the checkbox is not checked! +> The parameter submitted has value `1` when the checkbox is checked, `0` otherwise + + +| Attribute | Type | Description | +|------------------|--------|------------------------------------------------------------------------| +| name | string | *Required*. Name of the element | +| label | string | If present, renders a `Label` aside the input checkbox | +| checked | bool | Initial checked value (default `false`) | +| value | string | The value submitted when the checkbox is checked (default `1`) | +| false-value | string | The value submitted when the checkbox is not checked (default `0`) | +| send-false-value | bool | Send the false value when the checkbox is not checked (default `true`) | +| * | | Additional attributes will be forwarded to the underlying element. | + + +#### Radio + +```bladehtml + +contact_choice === 'email') +/> +``` + +| Attribute | Type | Description | +|------------------|--------|-------------------------------------------------------------------------| +| name | string | *Required*. Name of the element | +| label | string | If present, renders a `Label` aside the input radio | +| checked | bool | Initial checked value (default `false`) | +| value | string | The value submitted when the checkbox is checked | +| * | | Additional attributes will be forwarded to the underlying element. | + + +#### Label + +All form components automatically include the `Label` component when the `label` attribute is present, but it can be used independently: + + +```bladehtml + + + User email + +``` + + ### Changelog Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently. @@ -35,12 +350,8 @@ Please see [CONTRIBUTING](CONTRIBUTING.md) for details. ### Security -If you discover any security related issues, please email [balduzzi.giorgio@tiknil.com](mailto:balduzzi.giorgio@tiknil.com) instead of using the issue tracker. - -## Credits - -- [Giorgio Balduzzi](https://github.com/tiknil) -- [All Contributors](../../contributors) +If you discover any security related issues, please +email [balduzzi.giorgio@tiknil.com](mailto:balduzzi.giorgio@tiknil.com) instead of using the issue tracker. ## License diff --git a/resources/views/search-select.blade.php b/resources/views/search-select.blade.php index b6000bf..ffa6c3d 100644 --- a/resources/views/search-select.blade.php +++ b/resources/views/search-select.blade.php @@ -50,10 +50,11 @@ class="form-select ss-box"   @else {{ $placeholder }} - @endif + @endif + - + {{-- Option dropdown --}}