README

Installation

Via Composer

$ composer require spindogs/laravel-spin-forms

Upon install/update, it is recommended to clear the view cache. If there are new components in here, then they will need to either be manually copied over from the spin-forms.php config file, or republish the service provider with the --force flag. NB: using the --force command will overwrite your config file, so if you have any custom controllers or views, plase change them again

php artisan view:clear

Some components require additional javascript to be used in conjunction with the FE Baseline, these are generated by the components, but you will need to add code to your layout page to display it.

@stack('scripts')

Components

• Form
• Form Wrap
• Form Fieldset
• Form Group (Deprecated)
• Error List
• Button
• Label
• Input
• Textarea
• Checkbox
• Radio
• Select
• Date Picker
• Time Picker
• Date/Time Picker
• Help

Modification

You can modify/override any of the templates, by changing the view and class keys in the config file. To do this, you need to publish the vendor file.

php artisan vendor:publish --provider="Spindogs\LaravelSpinForms\SpinFormsServiceProvider"

return [
    'components' => [
        'form' => [
            'view'  => 'spin-forms::components.form', // DEFAULT
            'view'  => 'components.spin-forms.form', // OVERRIDE
            'class' => \Spindogs\LaravelSpinForms\View\Components\Form::class
        ],
    ]
]

Examples

Form

Options

• method - string - DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT (Default: POST)
• files - boolean (Default: false)

DELETE, PATCH, PUT; will trigger the Laravel @method command to then spoof the verb.

The files variable, will add the enctype/multipart to the form tag. This needs to be sent as a boolean value, so needs to be in the component as :files="true"

<x-form method="POST" :files="true">
</x-form>

Error List

Displays all form errors in list.

<x-form-error-list />

Button

Options

• type - string - Expected input: button/reset/submit (Default: submit)

This takes a slot as the entry for the button content.

<x-form-button type="submit">
Submit Form
</x-form-button>

Form Wrap

Options

• field-identifier - string - Type of form element that is going to be present (null)

This is utilised by all elements as a div wrapper around all of the form element controls. This will display the content inside of it. Field Identifier is generally automatically generated.

<x-form-wrap field-identifier="__text">
    ...
</x-form-wrap>

Form Fieldset

This element is used to house checkboxes / radio buttons. Fieldset should be used over Group for accessibility. But we are not removing Group for backwards compatability. These elements are identical except for: HTML output, Title is required.

Options

• name - string - Name of inputs to be displayed inside the group, this is needed to correctly style the error (required)
• type - string - Either checkbox, or radio, needed to correctly generate the field identifier of the Form Wrap component. (required)
• title - string - Title for group of elements in the group (required)
• required - boolean - Adds asterisk next to title (Default: false)
• show-error - boolean - Defines whether or not to display error text under element (Default: false)

<x-form-fieldset name="some-name-for-input" type="radio" title="This is the title of the elements" :required="true">
    ...
</x-form-fieldset>

Form Group (Deprecated)

This element is deprecated, but will still be available for backwards compataibility. This is almost identical to Form Fieldset.

Options

• name - string - Name of inputs to be displayed inside the group, this is needed to correctly style the error (required)
• type - string - Either checkbox, or radio, needed to correctly generate the field identifier of the Form Wrap component. (required)
• title - string - Title for group of elements in the group (Default: null)
• required - boolean - Adds asterisk next to title (Default: false)
• field-wrap - boolean - Wraps the input inside the field wrap div/class (Default: true)
• show-error - boolean - Defines whether or not to display error text under element (Default: false)

<x-form-group name="some-name-for-input" type="radio" title="This is the title of the elements" :required="true">
    ...
</x-form-group>

Input

Options

• name - string - Name of input (required)
• id - string - ID of input, if not given, randomly generated (Default: null)
• label - string - Label for input (Default: null)
• type - string - Any applicable types available for input, although not recomended for checkbox/radio (Default: text)
• value - string - This is the default value of the element on the page (Default: null)
• required - boolean - Adds asterisk next to label, and required tag to input (Default: false)
• readonly - boolean - Adds readonly attribute to input (Default: false)
• field-wrap - boolean - Wraps the input inside the field wrap div/class (Default: true)
• show-error - boolean - Defines whether or not to display error text under element (Default: true)

Also takes all attributes and merges across, like min, max, step etc.

<x-form-input type="text" label="Text Input" name="text-input" value="Default text input" />
<x-form-input type="number" label="Number Input" name="number-input" value="Default number input" min="1" max="10" />

Textarea

Options

• name - string - Name of textarea (required)
• id - string - ID of textarea, if not given, randomly generated (Default: null)
• label - string - Label for textarea (Default: null)
• value - string - This is the default value of the element on the page (Default: null)
• required - boolean - Adds asterisk next to label, and required tag to input (Default: false)
• readonly - boolean - Adds readonly attribute to input (Default: false)
• field-wrap - boolean - Wraps the input inside the field wrap div/class (Default: true)
• show-error - boolean - Defines whether or not to display error text under element (Default: true)

Also takes all attributes and merges across.

<x-form-textarea label="Textarea" name="textarea-input" value="Lorem Ipsum" />

Checkbox

Options

• name - string - Name of input (required)
• id - string - ID of checkbox, if not given, randomly generated (Default: null)
• label - string - Label for checkbox, if left as null, this is represented by a   (Default: null)
• value - string - Value for this checkbox to when selected (Default: 1)
• selected - boolean - Denotes whether the checkbox should be checked as default (Default: false)
• required - boolean - Adds asterisk next to label (Default: false)
• readonly - boolean - Adds readonly attribute to input (Default: false)
• field-wrap - boolean - Wraps the input inside the field wrap div/class (Default: true)
• show-error - boolean - Defines whether or not to display error text under element (Default: false)

It is higly recommended to utilise the Form Group element when using Checkboxes.

<x-form-group name="sign-up" type="checkbox">
    <x-form-checkbox name="sign-up" label="Sign up to the Newsletter!" />
</x-form-group>

<x-form-group name="checkbox-items" type="checkbox" title="Select some items!">
    <x-form-checkbox name="checkbox-items[item-1]" label="Item 1" :selected="true" />
    <x-form-checkbox name="checkbox-items[item-2]" label="Item 2" />
    <x-form-checkbox name="checkbox-items[item-3]" label="Item 3" />
    <x-form-checkbox name="checkbox-items[item-4]" label="Item 4" />
</x-form-group>

Radio

Options

• name - string - Name of input (required)
• id - string - ID of radio button, if not given, randomly generated (Default: null)
• label - string - Label for checkbox, if left as null, this is represented by a   (Default: null)
• value - string - Value for this checkbox to when selected (Default: null)
• selected - boolean - Denotes whether the checkbox should be checked as default (Default: false)
• readonly - boolean - Adds readonly attribute to input (Default: false)
• field-wrap - boolean - Wraps the input inside the field wrap div/class (Default: true)
• show-error - boolean - Defines whether or not to display error text under element (Default: false)

It is higly recommended to utilise the Form Group element when using Radio Buttons.

<x-form-group name="favourite-team" type="radio" title="Select Your Favourite Team!" :required="true">
    <x-form-radio name="favourite-team" label="Arsenal" :selected="true" />
    <x-form-radio name="favourite-team" label="Chelsea" />
    <x-form-radio name="favourite-team" label="Liverpool" />
    <x-form-radio name="favourite-team" label="Man United" />
</x-form-group>

Select

Options

• name - string - Name of select (required)
• id - string - ID of select, if not given, randomly generated (Default: null)
• label - string - Label for the select (Default: null)
• options - array - Key => Array [name, image] array of options for each select. (Default: [])
• selected - string/array - List of keys / single key for default selection on page view. (Default: null)
• required - boolean - Adds asterisk next to title (Default: false)
• readonly - boolean - Adds readonly attribute to input (Default: false)
• field-wrap - boolean - Wraps the input inside the field wrap div/class (Default: true)
• multiple - boolean - Allow multiple selection (Default: false)
• images - boolean - Adds images to each option, must be in array to work correctly (Default: false)
• search - boolean - Allow searching of dropdown (Default: true)
• show-error - boolean - Defines whether or not to display error text under element (Default: true)
• placeholder - string - Adds placeholder row to select, add the content for it (Default: null, does not work with images)

Currently does not work with optgroup.

Example of $options and $selected

$options = [
    'arsenal' => ['name' => 'Arsenal', 'image' => '/images/badge/arsenal.png'],
    'chelsea' => ['name' => 'Chelsea', 'image' => '/images/badge/chelsea.png'],
    'liverpool' => ['name' => 'Liverpool', 'image' => '/images/badge/liverpool.png'],
    'man-united' => ['name' => 'Manchester United', 'image' => '/images/badge/man-united.png']
];

$selected_singular = 'arsenal';

$selected_multiple = ['arsenal', 'liverpool'];

<x-form-select label="Select" name="select1" :options="$options" :required="true" :selected="$selected" placeholder="Select a Team" />

<x-form-select label="Select - no search" name="select2" :options="$options" :required="true" :selected="$selected" :search="false" placeholder="Select a Team"  />

<x-form-select label="Select - images" name="select3" :options="$options" :required="true" :selected="$selected" :images="true" />

<x-form-select label="Select - multiselect" name="select4[]" :options="$options" placeholder="Select a Team" :multiple="true"/>

<x-form-select label="Select - multiselect" name="select5[]" :options="$options" :required="true" :selected="$selected_multiple" :multiple="true" :images="true" placeholder="Select a Team" />

Date Picker

Options

• name - string - Name of input (required)
• id - string - ID of input, if not given, randomly generated (Default: null)
• label - string - Label for input (Default: null)
• value - string - This is the default value of the element on the page. Must be in format Y-m-d, otherwise will not render the default date (Default: null)
• required - boolean - Adds asterisk next to title (Default: false)
• field-wrap - boolean - Wraps the input inside the field wrap div/class (Default: true)
• show-error - boolean - Defines whether or not to display error text under element (Default: true)

<x-form-date-picker label="Date Picker" name="date-picker" default="2020-12-01" />

Date and Time Picker

Options

• name - string - Name of input (required)
• id - string - ID of input, if not given, randomly generated (Default: null)
• label - string - Label for input (Default: null)
• value - string - This is the default value of the element on the page. Must be in format Y-m-d H:i, otherwise will not render the default date/time (Default: null)
• required - boolean - Adds asterisk next to title (Default: false)
• field-wrap - boolean - Wraps the input inside the field wrap div/class (Default: true)
• show-error - boolean - Defines whether or not to display error text under element (Default: true)

<x-form-date-time-picker label="Date/Time Picker" name="date-time-picker" default="2020-12-01 13:44" />

Time Picker

Options

• name - string - Name of input (required)
• id - string - ID of input, if not given, randomly generated (Default: null)
• label - string - Label for input (Default: null)
• value - string - This is the default value of the element on the page. Must be in format H:i, otherwise will not render the default time. Regex to verify (Default: null)
• required - boolean - Adds asterisk next to title (Default: false)
• field-wrap - boolean - Wraps the input inside the field wrap div/class (Default: true)
• show-error - boolean - Defines whether or not to display error text under element (Default: true)

<x-form-time-picker label="Time Picker" name="time-picker" value="12:34" />

Help

You can also add help text, beofre and/or after the input elemtn with the use of the slots pre_help and post_help

<x-form-input type="text" id="adam" name="text-input">
    @slot('pre_help')
        Some help text before the form element
    @endslot
    @slot('post_help')
        Some help text after the form element
    @endslot
</x-form-input>

Change log

Please see the changelog for more information on what has changed recently.

Contributing

Please see contributing.md for details and a todolist.

Security

If you discover any security related issues, please email achapman@spindogs.com instead of using the issue tracker.

Credits

• Adam Chapman
• All Contributors

License

MIT. Please see the license file for more information.

Supported Versions

Versions will be supported for a limited amount of time.