My previous post about Give was an intro to building a payment gateway for the plugin. If you’ve built extensions for Give or are starting to then you’ve probably run into the settings fields API for adding a variety of inputs. The options are limited and there are often times a need for custom fields.
How Give’s Settings Fields Work
In the class file class-admin-settings.php located in give/includes/admin/ the function output_fields handles displaying different types of fields registered. If you are here you probably know the standard format for adding a settings field in your code:
settings[] = [ 'name' => __( 'Select an Option', 'my-text-domain' ), 'desc' => '', 'id' => 'select_box_1', 'type' => 'select', 'options' => [ 'op1' => 'Option 1', 'op2' => 'Option 2' ], ]
That adds a select field with a couple options.
As you add settings to an array they will be displayed in the same order in a Give formatted html table. It appears they were using CMB2 but have since deprecated it. I’m not 100% sure but there are remnants of it in the plugin.
Creating A Custom Field
Within the output_fields function I mentioned above there is a switch statement on the field type. This goes through all the type options default in Give and outputs the field content based on type. After all the case type options the default is a sweet do_action( ‘give_admin_field_’ . $value[‘type’], $value, $option_value ); This is how you do what you want to do with a custom field.
One thing I really needed when building an extension was a way to have inter-woven sub headers for form options. I could not find a way to just output a title. The type field title that’s default to Give outputs the top of a table with it as it’s meant to be, that’s right, at the top lol.
Let’s start with an example of creating a simple sub title output.
https://gist.github.com/ChrisFlannagan/a2f89eef7b65f18bddd0de5987db61b0
Remember, the form settings fields are all in a table so you need to use a table row to output your field. Now we can add this subtitle between fields by using:
$settings[] = [ 'id' => 'my_settings_subheader_one', 'name' => 'Custom Sub Header Section', 'type' => 'my_custom_subtitle', ];
Voila! We have a custom field in Give settings. The type is set to what comes after give_admin_field_ in the add_action of our sample.
Saving Custom Field Data
Saving is pretty straight forward as well. The example below is kind of pointless as Give already has a text box type but it shows how you’d go about saving your data in a custom field.
The key is figuring out how to structure your action’s name. Give uses the settings page followed by _save_ followed by the tab you are on. Here’s their documentation on it followed by an example.
/** * Trigger Action. * * Note: action dynamically fire on basis of setting page slug and current tab. * For example: if you register a setting page with give-settings menu slug and general current tab name * then action will be give-settings_save_general * * @since 1.8 */ do_action( self::$setting_filter_prefix . '_save_' . $current_tab );
https://gist.github.com/ChrisFlannagan/36e235224bb135019424fc1eed2504db