Add a Custom Form Field to Your Form

matador_docs_add_custom_field_application.php

<?php
/**
 * Example: Add a Custom Field to Your Default Form
 *
 * Adding a custom field to your form in Matador requires 2 steps, as well as an optional 3rd.
 *
 * 1. Registering the Field
 * 2. Adding it to a form, either via the shortcode, function, or adding it to defaults
 * 3. Choosing to make it required.
 *
 * Note: This example uses PHP 5.6+ array declarations, or single brackets `[]`. Matador 3.0+ requires PHP 5.6, Matador
 *       3.5+ requires PHP 7.0+, and WordPress 5.2+ requires PHP 5.6, so we feel safe using this. By all means, you may
 *       continue to declare arrays with `array()`.
 */

/**
 * Step 1: Register Custom Field
 *
 * Example below adds the custom field "Why Are You Awesome" to the list of possible form fields in your Matador
 * application. All fields must be registered, or Matador will ignore the input from a form.
 *
 * @copyright 2019, Matador Software, LLC
 * @author Jeremy Scott, Matador Software LLC
 * @link https://matadorjobs.com/
 *
 * @param $fields
 *
 * @return array
 */
function matador_docs_matador_application_fields_structure( $fields ) {

	//
	// This demonstrates the structure. It is unnecessarily verbose. The true example new field is after this.
	// Delete this when you don't need it.
	//

	$fields['structure'] = [
		'type'     => 'text', // Type can be 'text', 'textarea', 'select', 'checkbox', 'radio', 'password', 'file'
		'label'    => 'Structure Example', // The form label
		'sublabel' => '', // Optional. Describe the label in more detail.
		'description' => '', // Optional. Descriptions are after the form input.
		'default'     => '', // Optional. Pre-fill the field. Not the same as a placeholder.
		'options'     => '', // Optional. Array. Use to create select, checkbox, or radio options.
		'attributes'  => [
			'minlength' => 2,
		],
		// Attributes are Optional. Add attributes to the input tag. Key/Value Array, where key is the rule and value
		// is the value. Use HTML 5 form validators here. Like example.
		'class'       => [], // Optional. Pass classes for the form field wrapper.
		'sanitize'    => null,
		// Sanitize is Optional. Pass a function name for a custom sanitizer callback. Logical defaults are used
		// otherwise. IE: sanitize_text_field() for 'type' = 'text'.
	];

	//
	// Now lets actually add the "Why Am I Awesome" field!
	//

	$fields['why_awesome'] = [
		'type'        => 'text',
		'label'       => 'Why Am I Awesome?',
		'description' => 'Tell why you are awesome. We hire awesome people.',
		'attributes'  => [
			'minlength' => 2,
		],
	];

	return $fields;
}

add_filter( 'matador_application_fields_structure', 'matador_docs_matador_application_fields_structure' );

/**
 * Step 2.A : Add Custom Field to Default Application Fields
 *
 * Example below adds the custom field "Why Are You Awesome" to the default application form.
 *
 * @copyright 2019, Matador Software, LLC
 * @author Jeremy Scott, Matador Software LLC
 * @link https://matadorjobs.com/
 *
 * @param $fields
 *
 * @return array
 */
function matador_docs_matador_application_fields( $fields ) {
	$fields = array(
		'name',
		'email',
		'phone',
		'resume',
		'why_awesome',
	);

	return $fields;
}

add_action( 'matador_application_fields_defaults', 'matador_docs_matador_application_fields' );

/**
 * Step 2.B: Use Custom Field In Shortcode
 *
 * Example below uses the custom field "Why Are You Awesome" in a shortcode-included application form.
 *
 * @copyright 2019, Matador Software, LLC
 * @author Jeremy Scott, Matador Software LLC
 * @link https://matadorjobs.com/
 */

?>
[matador_application fields='name,email,phone,resume,why_awesome']
<?php

/**
 * Step 2.C: Use Custom Field In Function
 *
 * Example below uses the custom field "Why Are You Awesome" in a function-included application form.
 *
 * @copyright 2019, Matador Software, LLC
 * @author Jeremy Scott, Matador Software LLC
 * @link https://matadorjobs.com/
 */

matador_application( [ 'fields' => [ 'name', 'email', 'phone', 'resume', 'why_awesome' ] ] );

/**
 * Step 3.A : Require Custom Field in Default Application Fields
 *
 * Example below requires the custom field "Why Are You Awesome" in the default application form.
 *
 * @copyright 2019, Matador Software, LLC
 * @author Jeremy Scott, Matador Software LLC
 * @link https://matadorjobs.com/
 *
 * @param $fields
 *
 * @return array
 */
function matador_docs_matador_default_required_fields( $fields ) {
	$fields = array(
		'name',
		'email',
		'why_awesome',
	);

	return $fields;
}

add_action( 'matador_application_fields_defaults', 'matador_docs_matador_default_required_fields' );

/**
 * Step 3.B: Require Custom Field In Shortcode
 *
 * Example below requires the custom field "Why Are You Awesome" in a shortcode-included application form.
 *
 * @copyright 2019, Matador Software, LLC
 * @author Jeremy Scott, Matador Software LLC
 * @link https://matadorjobs.com/
 */
?>
[matador_application fields='name,email,phone,resume,why_awesome' require='name,email,why_awesome']
<?php

/**
 * Step 2.C: Require Custom Field In Function
 *
 * Example below requires the custom field "Why Are You Awesome" in a function-included application form.
 *
 * @copyright 2019, Matador Software, LLC
 * @author Jeremy Scott, Matador Software LLC
 * @link https://matadorjobs.com/
 */

matador_application( [ 'fields' => [ 'name', 'email', 'phone', 'resume', 'why_awesome' ], 'require' => [ 'name', 'email', 'why_awesome' ] );