resknow/form

Form - A toolkit for building and managing forms in Boilerplate

Maintainers

Details

github.com/resknow/form

Source

Issues

Installs: 2

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 2

Forks: 0

Open Issues: 0

Type:boilerplate-plugin

2.5.0 2020-03-06 11:04 UTC

This package is auto-updated.

Last update: 2022-06-12 16:46:28 UTC


README

There are a number of options when building forms, below is a breakdown of what options you have and field types that can be added.

Options

These options are required by the form plugin to setup a form for you. They belong in your .config.yml file under the forms key.

forms:
    my-form: # This is your form ID
        remote: <key> # If this form is handled by our remote API, the key goes here and the below options are configured remotely.
        name: Contact Form # This is the name of the form
        email: true # Should the result be sent in an e-mail?
        db: false # Should the result be stored in a database?
        autoresponder: true # Should the user get a thank you message?
        recipient: chris@resknow.co.uk # Where to send the form to
        subject: New message # The subject line of the e-mail
        subject_autoresponder: Thank you # The subject line of the autoresponse
        success_message: Your message has been sent # Message to display when the form is submitted successfully
        location: /thanks # URL to direct users to after successfully submitting the form
        submit: # Submit button options
            text: Submit
            classes: button positive

        honeypot: false # Set to true to add a honeypot to reduce spam submissions.

        fields:
            ...

Note: The honeypot feature creates a field with the key how, so avoid using that key for your own fields.

Fields

Fields are defined under the fields key of your form's configuration. There are a number of field types, which are listed below along with their available options.

Most field types support HTML attributes as options too.

Text field

    # Text field
    name: # This is the field key (HTML name attribute)

        ### Required ###
        label: Name # Label
        type: text # Input type

        ### Optional ###
        show_label: false # Whether to display the label above the field (defaults to true)
        validate: required # Validation rules {see: https://github.com/Wixel/GUMP#available-validators}
        filter: trim|sanitize_string # Filter rules {see: https://github.com/Wixel/GUMP#available-filters}
        classes: block pad-16 # Custom CSS classes to add to this field
        value: Chris # A default value
        placeholder: Enter your name # Placeholder text
        description: Something useful # Description to display under the field

        ### Optional HTML Attributes ###
        autocomplete: "true"
        autofocus: "true"
        min: 2
        max: 6
        pattern: /0-9/+
        step: 2
        maxlength: 100
        readonly: "true"
        disabled: "true"

Textarea field

    # Text field
    message: # This is the field key (HTML name attribute)

        ### Required ###
        label: Message # Label
        type: textarea # Input type

        ### Optional ###
        show_label: false # Whether to display the label above the field (defaults to true)
        validate: required # Validation rules {see: https://github.com/Wixel/GUMP#available-validators}
        filter: trim|sanitize_string # Filter rules {see: https://github.com/Wixel/GUMP#available-filters}
        classes: block pad-16 # Custom CSS classes to add to this field
        value: Chris # A default value
        placeholder: Enter your name # Placeholder text
        description: Something useful # Description to display under the field

        ### Optional HTML Attributes ###
        autocomplete: "true"
        autofocus: "true"
        min: 2
        max: 6
        pattern: /0-9/+
        step: 2
        maxlength: 100
        readonly: "true"
        disabled: "true"

Select field

    # Select field
    country: # This is the field key (HTML name attribute)

        ### Required ###
        label: Country # Label
        type: select # Input type
        options: # List of options (key: value)
            uk: United Kingdom
            usa: United States
            can: Canada

        ### Optional ###
        show_label: false # Whether to display the label above the field (defaults to true)
        validate: required # Validation rules {see: https://github.com/Wixel/GUMP#available-validators}
        filter: trim|sanitize_string # Filter rules {see: https://github.com/Wixel/GUMP#available-filters}
        classes: block pad-16 # Custom CSS classes to add to this field
        value: Chris # A default value
        description: Something useful # Description to display under the field

        ### Optional HTML Attributes ###
        readonly: "true"
        disabled: "true"

Datepicker field

Provides a Datepicker UI for dealing with dates.

    # Datepicker field
    date: # This is the field key (HTML name attribute)

        ### Required ###
        label: Date # Label
        type: datepicker # Input type

        ### Optional ###
        show_label: false # Whether to display the label above the field (defaults to true)
        validate: required # Validation rules {see: https://github.com/Wixel/GUMP#available-validators}
        filter: trim|sanitize_string # Filter rules {see: https://github.com/Wixel/GUMP#available-filters}
        classes: block pad-16 # Custom CSS classes to add to this field
        value: Chris # A default value
        placeholder: Enter your name # Placeholder text
        description: Something useful # Description to display under the field

        ### Optional HTML Attributes ###
        autocomplete: "true"
        autofocus: "true"
        min: 2
        max: 6
        pattern: /0-9/+
        step: 2
        maxlength: 100
        readonly: "true"
        disabled: "true"

Choice field

Provides a button based UI for small groups of choices

    # Choice field
    country: # This is the field key (HTML name attribute)

        ### Required ###
        label: Country # Label
        type: select # Input type
        options: # List of options (key: value)
            uk: United Kingdom
            usa: United States
            can: Canada

        ### Optional ###
        show_label: false # Whether to display the label above the field (defaults to true)
        validate: required # Validation rules {see: https://github.com/Wixel/GUMP#available-validators}
        filter: trim|sanitize_string # Filter rules {see: https://github.com/Wixel/GUMP#available-filters}
        classes: block pad-16 # Custom CSS classes to add to this field
        description: Something useful # Description to display under the field

        ### Optional HTML Attributes ###
        disabled: "true"

WYSIWYG field

    # Wysiwyg field
    message: # This is the field key (HTML name attribute)

        ### Required ###
        label: Message # Label
        type: wysiwyg # Input type

        ### Optional ###
        show_label: false # Whether to display the label above the field (defaults to true)
        validate: required # Validation rules {see: https://github.com/Wixel/GUMP#available-validators}
        filter: trim|sanitize_string # Filter rules {see: https://github.com/Wixel/GUMP#available-filters}
        classes: block pad-16 # Custom CSS classes to add to this field
        value: Chris # A default value
        description: Something useful # Description to display under the field

Content field

Allows you to include custom content inside your form. Note: Labels are never shown for this field type and values are not included in user input.

    # Content field
    notice: # This is the field key (HTML name attribute)

        ### Required ###
        label: ReCaptcha Notice # Label
        type: content # Input type
        callback: my_callback_function # PHP function that renders your content

Group field

Allows you to group multiple fields, it uses CSS Grid by default but you can role your own styles if you need to.

Note: Grid layouts only support up to 4 fields in a row.

    # Content field
    group: # This is the field key (HTML name attribute)

        ### Required ###
        label: Group of fields # Label
        type: group # Input type
        fields: # A list of field IDs
            name
            date

        ### Optional ###
        show_label: false # Whether to display the label above the field (defaults to true)
        classes: block pad-16 # Custom CSS classes to add to this field
        description: Something useful # Description to display under the field
        grid: false # Display items as block

Validation & Filters

Field validation and filtering is done by GUMP. Form also provides a spam filter validator, which allows you to invalidate a form if you find spam.

See inc/functions.php in the Form plugin for more details.

The validator for this is spam_filter. Add this to your validation rules to apply the spam checks.

Render a form!

Form example

Once you've created your form, to render it on your page, include the following where you'd like it to display:

Twig

{{ render_form('my-form') }}

PHP

<?php echo render_form('my-form') ?>

Switch out my-form for your actual form ID :)

Also note that the example screenshot above includes custom styling, the Form plugin tries not to give you opinionated styles, that's on you as the designer.