Download the PHP package jakesutherland/nomad-forms without Composer

Nomad Forms

A WordPress PHP Composer Package that provides you with an easy way to display and process forms, render and validate fields, and display error/success messages.

Installation

You can install Nomad Forms in your project by using composer.

Dependencies

Nomad Forms depends on the following packages:

• Nomad Helpers for various functions, constants, and utilities.
• Nomad Validate for validating form submissions and generating error messages.

If for some reason you didn't install Nomad Forms via Composer as a required package in your project, you will still need to run composer install to install it's dependencies as they are not included in the repository.

Documentation

Nomad Forms is a full-featured form generator for processing, validating and displaying forms on your website. You can use Nomad Forms on the front-end or in the admin.

Example Usage

The nomad_form() function is used to get your form configured and set up.

The first parameter is your form ID. In our example below, my_form_id is used as a unique identifer for this form.

The second parameter is your form arguments. This is where you can configure your form and define your form fields.

Alternatively, you can use the nomad_fields() function if you want to output just form fields (and still utilize Nomad Forms Theme styles). Basically is a helper function that sets various form arguments to what would be needed in order to just output form fields. See below:

When using this by itself, you would be expected to handle all form processing and validation manually.

Common use case would be adding custom fields to a post type in the WordPress admin and then processing those fields on save_post.

Available Form Arguments

You can customize how a form behaves with many different form arguments available.

Note: The only required form argument is fields. All other form arguments are optional and have defaults set.

action

Type: string

Default: null

Sets the form action if you want the form to be submitted to a specific URL.

This is not recommended unless you plan on handling the form submission yourself. Note that the variable you assign nomad_form() to is only available on the page it is defined, so the other functions likely won't be available somewhere else in your codebase. It is highly recommended that you handle everything on the same page that the form is being displayed on.

allow_modifications

Type: boolean

Default: true

Whether or not you want to allow the potential for other plugins or pieces of code to modify the form.

When set to true, the form can be modified through various hooks, filters and fields added through injections. If set to false, the majority of hooks and filters won't be triggered and form injections will not add any fields.

automate_validation

Type: boolean

Default: true

Whether or not you want to allow automatic validation of form fields.

When set to true, automatically validates values for "choice" type fields (such as button groups, checkboxes, radios, selects, etc) and makes sure that only the options that were available can be used, email fields are valid emails, and numeric fields only contain numbers.

If you already specify any of these rule keys in your field validation, automatic validation will not override them.

callback

Type: callable

Default: null

The function to be called to process the form when it is successful. Must be a valid callback function.

cancel_button

Type: boolean

Default: false

Whether or not to display a "Cancel" button at the bottom of the form.

cancel_href

Type: string

Default: home_url( '/' ); (your WordPress installs homepage)

The URL to go to when the Cancel button is clicked.

cancel_text

Type: string

Default: Cancel

The Cancel button text.

error_message

Type: string

Default: Sorry, there was a problem submitting your form:

When the form is submitted and there is an error, this is the text to be displayed above the list of error messages.

fields

Type: array

Required

The list of form fields to be displayed, submitted validated, and processed.

form_tag

Type: boolean

Default: true

Whether or not the form fields should be rendered inside a <form>...</form> tag. If set to false, the form fields will be rendered inside a <div>...</div> instead.

labels_alignment

Type: string

Default: left

Possible Values: left center right

Determines the text alignment of the field labels.

labels_position

Type: string

Default: top

Possible Values: inline top

Determines where the field labels are displayed in relation to its field.

method

Type: string

Default: POST

Possible Values: POST GET

Determines the form method that is used when the fields are submitted.

nonce

Type: boolean

Default: true

Whether or not to create and use a nomad_form_nonce to make sure that the form being processed is the one that was just submitted.

nonce_message

Type: string

Default: Invalid form submission. Please try again.

The text to be displayed if the nonce verification fails and the form submission was invalid.

reset_button

Type: boolean

Default: false

Whether or not to display a "Reset" button at the bottom of the form.

reset_text

Type: string

Default: Reset

The Reset button text.

submit_button

Type: boolean

Default: true

Whether or not to display a "Submit" button at the bottom of the form.

submit_text

Type: string

Default: Submit

The Submit button text.

success_message

Type: string

Default: Success! Your form has been submitted.

When the form is submitted and there is an error, this is the text to be displayed above the list of error messages.

Available Fields

Each field is defined as a constant in the Nomad_Form_Fields class. Below is a list of all available fields and an example of how it would be registered.

Alternatively, you can take a look at example.php to test out a Nomad Form that contains one of every field type available.

AM PM Field

Usage: Nomad_Form_Fields::AM_PM

Select dropdown menu with AM and PM options.

Button Group Field

Usage: Nomad_Form_Fields::BUTTON_GROUP

Styled radio buttons. If the multiple argument is provided and set to true then the styled buttons will behave like checkboxes.

Checkbox Field

Usage: Nomad_Form_Fields::CHECKBOX

A single checkbox.

Checkboxes Field

Usage: Nomad_Form_Fields::CHECKBOXES

Multiple checkboxes.

Country Field

Usage: Nomad_Form_Fields::COUNTRY

Select dropdown menu with list of all countries as options.

Date Field

Usage: Nomad_Form_Fields::DATE

Date input field.

Day Field

Usage: Nomad_Form_Fields::DAY

Select dropdown menu with days of the month (01-31) as options.

Email Field

Usage: Nomad_Form_Fields::EMAIL

Email input field.

Enable/Disable Button Group

Usage: Nomad_Form_Fields::ENABLE_DISABLE_BUTTON_GROUP

Button group with predefined Enable and Disable options.

Enabled/Disabled Button Group

Usage: Nomad_Form_Fields::ENABLED_DISABLED_BUTTON_GROUP

Button group with predefined Enabled and Disabled options.

Hidden Field

Usage: Nomad_Form_Fields::HIDDEN

Hidden input field.

Hour Field

Usage: Nomad_Form_Fields::HOUR

Select dropdown menu with hours of the day as options. You can specify format with 12 or 24 to have 1-12 or 0-23 hour format options. Default is 12 hour format.

Minute Field

Usage: Nomad_Form_Fields::MINUTE

Select dropdown menu with 00-60 minute options.

Month Field

Usage: Nomad_Form_Fields::MONTH

Select dropdown menu with months of the year as options. You can specify format with full (January-December), short (Jan-Dec), or number (1-12) format options. Default format: number.

Number Field

Usage: Nomad_Form_Fields::NUMBER

Number input field.

On/Off Button Group

Usage: Nomad_Form_Fields::ON_OFF_BUTTON_GROUP

Button group with predefined On and Off options.

Password Field

Usage: Nomad_Form_Fields::PASSWORD

Password input field.

Percentage Field

Usage: Nomad_Form_Fields::PERCENTAGE

Number input field with a minimum value of 0 and maximum value of 100.

Phone Field

Usage: Nomad_Form_Fields::PHONE

Phone input field.

Radio Field

Usage: Nomad_Form_Fields::RADIO

A single radio button.

Radios Field

Usage: Nomad_Form_Fields::RADIOS

Multiple radio buttons.

Select Field

Usage: Nomad_Form_Fields::SELECT

Select dropdown menu.

State Field

Usage: Nomad_Form_Fields::STATE

Select dropdown menu with US States as options. You can specify format with full (Alabama-Wyoming) or short (AL-WY) format options. Default format: short.

Text Field

Usage: Nomad_Form_Fields::TEXT

Text input field

Textarea Field

Usage: Nomad_Form_Fields::TEXTAREA

Textarea field.

Time Field

Usage: Nomad_Form_Fields::TIME

Time input field.

Toggle Field

Usage: Nomad_Form_Fields::TOGGLE

Styled checkbox toggle switch field.

Toggles Field

Usage: Nomad_Form_Fields::TOGGLES

Styled checkboxes toggle switch fields.

Upload Field

Usage: Nomad_Form_Fields::UPLOAD

File input field.

URL Field

Usage: Nomad_Form_Fields::URL

URL input field.

Weekday Field

Usage: Nomad_Form_Fields::WEEKDAY

Select dropdown menu with days of the week as options. You can specify format with full (Monday-Sunday), short (Mon-Sun), or lower (monday-sunday) format options. Default format: lower.

Year Field

Usage: Nomad_Form_Fields::YEAR

Select dropdown menu with the years 1900-current as options. You can specify the min and max to determine what years are available as options.

Yes/No Button Group

Usage: Nomad_Form_Fields::YES_NO_BUTTON_GROUP

Button group with predefined Yes and No options.

Reserved Field Names

The field name nomad_form_id is reserved because it is used to determine the form that is being submitted. This is how multiple Nomad Forms are allowed to be used on the same page and be able to distinguish between which one was submitted.

Available Hooks and Filters

nomad/forms/init

nomad/forms/{$this->form_id()}/init

nomad/forms/{$this->form_id()}/args

nomad/forms/{$this->form_id()}/fields

nomad/forms/{$this->form_id()}/injections

nomad/forms/before_form_open

nomad/forms/{$this->form_id()}/before_form_open

nomad/forms/form_open

nomad/forms/{$this->form_id()}/form_open

nomad/forms/{$this->form_id()}/after_open

nomad/forms/after_open

nomad/forms/hidden_fields

nomad/forms/{$this->form_id()}/hidden_fields

nomad/forms/before_fields_container

nomad/forms/{$this->form_id()}/before_fields_container

nomad/forms/before_fields

nomad/forms/{$this->form_id()}/before_fields

nomad/forms/{$this->form_id()}/field/{$field['name']}/args

nomad/forms/{$this->form_id()}/field/before

nomad/forms/{$this->form_id()}/field/{$field['name']}/before

nomad/forms/{$this->form_id()}/field/{$field['name']}/after

nomad/forms/{$this->form_id()}/field/after

nomad/forms/{$this->form_id()}/after_fields

nomad/forms/after_fields

nomad/forms/{$this->form_id()}/after_fields_container

nomad/forms/after_fields_container

nomad/forms/before_form_actions

nomad/forms/{$this->form_id()}/before_form_actions

nomad/forms/submit_attributes

nomad/forms/{$this->form_id()}/submit_attributes

nomad/forms/before_submit_button

nomad/forms/{$this->form_id()}/before_submit_button

nomad/forms/{$this->form_id()}/after_submit_button

nomad/forms/after_submit_button

nomad/forms/{$this->form_id()}/after_form_actions

nomad/forms/after_form_actions

nomad/forms/reset_attributes

nomad/forms/{$this->form_id()}/reset_attributes

nomad/forms/cancel_attributes

nomad/forms/{$this->form_id()}/cancel_attributes

nomad/forms/form_close

nomad/forms/{$this->form_id()}/form_close

nomad/forms/{$this->form_id()}/before_form_close

nomad/forms/before_form_close

nomad/forms/{$this->form_id()}/after_form_close

nomad/forms/after_form_close

nomad/forms/{$this->form_id()}/is_valid

nomad/forms/{$this->form_id()}/success

nomad/forms/{$this->form_id()}/error

nomad/forms/process

nomad/forms/{$this->form_id()}/process

nomad/forms/{$this->form_id()}/success_message

nomad/forms/{$this->form_id()}/error_message

nomad/forms/{$this->form_id()}/error_messages

Changelog

v1.0.0

• Initial Release

License

The MIT License (MIT). Please see License File for more information.

Copyright

Copyright (c) 2021 Jake Sutherland