resknow / form
Form - A toolkit for building and managing forms in Boilerplate
Installs: 2
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 2
Forks: 0
Open Issues: 0
Type:boilerplate-plugin
Requires
- catfan/medoo: 1.4
- phpmailer/phpmailer: 6.0
- resknow/boilerplate: ^4.0.0
- wixel/gump: 1.5.7
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!
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.