README

Laravel components for easy form building

Note : This package is to be used with Laravel v8 and Bootstrap v4

It also requires LaravelCollective/Html v6

Installation
Configuration
Form
Inputs
- Text
- Textarea
- Hidden
- Number
- Password
- Email
- Date
- File
- Checkbox
- Radio
- Select
- Select Range
Buttons
- Submit
- Reset
- Back
Usage
Contact
License
Copyright

Installation

Install the package via Composer:

    $ composer require regnilk/bs-form-laravel

The package service provider will be registered automatically.

Configuration

No configuration is required.

Form

Opening a form

To open a form, call the corresponding component

    <x-form-open url="{{url('/home'}}" />
    <x-form-open :url="$url" />

This component can receive various parameters :

url : where the form will be submit.
route : if you prefer, you can indicate a route name, with or without parameter(s).

    <x-form-open route="routeName" />
    <x-form-open :route="['routeName', $object->id]" />

if the url is not null, the route will be ignored.

action : it works the same way as the route parameter.

    <x-form-open route="routeName" />
    <x-form-open :route="['routeName', $object->id]" />

if the url or the route are not null, the action will be ignored.

method : You can choose the form's method among get, post, put, patch and delete.

    <x-form-open url="{{url('/user/update'}}" method="patch" />

By default, the method is set to post.

files : Indicates if the form contains file(s) field(s)

    <x-form-open url="{{url('/file/upload'}}" files="true" />

By default, this parameter is set to false.

Closing a form

    <x-form-close />

Form element

The inputs components must be surrounded by an element component.

The element component contains the label and the bootstrap structure.

    <x-form-elem name="myElem" label="myLabel">
   //Input will be placed here     
   </x-form-elem>

Here is the component's parameters list. Only the name and label are mandatory.

name : the name of the element.

Warning : It must match the name of the input to work.

label : The label text.
icon : An icon shortcut. The icons are provided by regnilk/fa-laravel. Be sure to have configured it to have your icons displayed properly.

By default, no icon is shown.

width : the width of the element. It can be from 1 to 12 because it uses the bootstrap col system.

This value is set to 12 by default.

label-width : the width of the label in px.

By default, this value is set to 150px.

Here is a full example :

     <x-form-elem name="myElem" label="myLabel" icon="ok" width="8" label-width="180">
         //Input will be placed here     
     </x-form-elem>

Inputs

Use all these input components inside a x-form-elem component.

Each of them can be customized with usual class, style, etc.

Tips :

If you need to provide a php variable as a paramater value, just change this

    <x-form-elem name="myText" label="myLabel"></x-form-elem>

to this

    <x-form-elem name="myText" :label="$label"></x-form-elem>

If you want a helping text displayed under the field. Do as follows :

    <x-form-elem name="myText" :label="$label" help="this field is required"></x-form-elem>

Text

    <x-form-elem name="myText" label="myLabel">
        <x-form-text name="myText" :value="$text"/>
    </x-form-elem>

name : the name of the field. It must match the name of the x-form-elem.
value : the value to fill the field with (optional)

Textarea

    <x-form-elem name="myTextArea" label="myLabel">
        <x-form-textarea name="myTextArea" :value="$textarea" cols="30" rows="4"/>
    </x-form-elem>

name : the name of the field. It must match the name of the x-form-elem.
value : the value to fill the field with (optional)

Tip: usual parameters of textarea element are still working

Hidden

    <x-form-text name="myHiddenField" :value="$myHiddenValue"/>

name : the name of the field. It must match the name of the x-form-elem.
value : the value to fill the field with (optional)

Note that there id no need to wrap the hidden component within a x-form-elem for it will not be displayed

Number

    <x-form-elem name="myNumber" label="myLabel">
        <x-form-number name="myNumber" :value="$number"/>
    </x-form-elem>

name : the name of the field. It must match the name of the x-form-elem.
value : the value to fill the field with (optional)

Password

    <x-form-elem name="myPassword" label="myLabel">
        <x-form-password name="myPassword" />
    </x-form-elem>

name : the name of the field. It must match the name of the x-form-elem.

Email

    <x-form-elem name="myEmail" label="myLabel">
        <x-form-email name="myEmail" :value="$email"/>
    </x-form-elem>

name : the name of the field. It must match the name of the x-form-elem.
value : the value to fill the field with (optional)

Date

    <x-form-elem name="myDate" label="myLabel">
        <x-form-date name="myDate" value="1993-05-26"/>
    </x-form-elem>

name : the name of the field. It must match the name of the x-form-elem.
value : the value to fill the field with (optional). Use the YYYY-mm-dd format.

File

    <x-form-elem name="myFile" label="myLabel">
        <x-form-file name="myFile"/>
    </x-form-elem>

name : the name of the field. It must match the name of the x-form-elem.

Checkbox

    <x-form-elem name="myFile" label="myLabel">
        <x-form-check name="check1" label="label 1" value="1" />
        <x-form-check name="check2" label="label 2" value="2" label-class="text-danger"/>
        <x-form-check name="check2" label="label 2" value="3" checked="true" />
    </x-form-elem>

name : the name of the field.
label : the label of the checkbox.
value : the value associated to the checkbox (optional).
checked : defines the checkbox as checked. By default it's set to false (optional)
label-class : classes to add to the label of the checkbox. (optional)

Radio

    <x-form-elem name="radio" label="myLabel">
       <x-form-radio name="radio" label="label 1" value="1" checked="true" />
       <x-form-radio name="radio" label="label 2" value="2" label-class="text-success"/>
       <x-form-radio name="radio" label="label 3" value="3" />
    </x-form-elem>

name : the name of the radio buttons. It must be the same for each radio button of the group and match the x-form-elem name.
label : the label of the radio button.
value : the value associated to the radio (optional).
checked : defines the radio button as checked. By default it's set to false (optional)
label-class : classes to add to the label of the radio button. (optional)

Select

    <x-form-elem name="mySelect" label="myLabel" icon="ok">
        <x-form-select name="mySelect" :options="$users" label="fullName" key="id" placeholder="choisissez" :selected="$user->id" />
    </x-form-elem>

name : the name of the select. It must match the x-form-elem name.
options : The array of options to display in the select.

It can be an array of arrays or a collection.

label : the property that will be used as text in the options.
key : the property that will be used as value in the options, "id" by default (optional).
selected : the value of the key that will be selected by default (optional)
placeholder : It will add an option at the first position with no value. (optional)

Select range

    <x-form-elem name="mySelectRange" label="myLabel" icon="ok">
        <x-form-select-range name="mySelectRange" start="0" end="20" selected="11" placeholder="select a number"/>
    </x-form-elem>

Generate a select with numeric values from "start" to "end"

name : the name of the select range. It must match the x-form-elem name.
start : the lower value of the select range.
end : the highest value of the select range.
selected : the value of the key that will be selected by default (optional)
placeholder : It will add an option at the first position with no value. (optional)

Buttons

You can generate three buttons to your form.

These buttons can contain icons. They are provided by regnilk/fa-laravel. Be sure to have configured it to have your icons displayed properly.

You have to put boostrap classes to choose the button's style. Only the 'btn' class is already present.

Submit

    <x-form-btn-submit icon="add" text="Add" class="btn-sm btn-success"/>

icon : the icon displayed in the button (optional).
text : the text of the button. 'OK' is the default text. (optional)

Reset

    <x-form-btn-reset icon="reset" text="Reset" class="btn-sm btn-secondary"/>

icon : the icon displayed in the button (optional).
text : the text of the button. 'Reset' is the default text. (optional)

Back

    <x-form-btn-back icon="back" text="Back" class="btn-sm btn-info"/>

icon : the icon displayed in the button (optional).
text : the text of the button. 'Back' is the default text. (optional)

##Usage

Working with errors

Errors can be displayed in the bootstrap style for each input. The fields can also be repopulated when an error occurs.

To have it working, you will need to do your redirection this way in your controller :

    public function store(Request $request)
    {
        $validator = Validator::make($request->all(), [
            'name' => 'required'
        ]);

        if ($validator->fails()):
            return redirect()->back()->withInput()->withErrors($validator);
        else:
            //Validator OK
        endif;
    }

regnilk / bs-form-laravel

Maintainers

Details