Skip to content
Documentation › Charitable_Donation_Field

Charitable_Donation_Field

The Charitable_Donation_Field class allows you to create new donation fields or edit existing ones.

Table of Contents

Usage

Create a new donation field

If you want to add a new donation field, you will first need to create a new Charitable_Donation_Field instance, and then register it in the Donation Fields Registry. 

add_action( 'init', function() {

    /* Create the Donation Field instance. */
    $field = new Charitable_Donation_Field(
        'my_custom_field',
        array(
            'label'          => __( 'My Custom Field' ),
            'data_type'      => 'meta', 
            'value_callback' => false,
            'donation_form'  => array(
                'type'       => 'text',
                'required'   => false,
                'show_after' => 'phone',
            ), 
            'admin_form'     => true,
            'show_in_meta'   => true,
            'show_in_export' => true,
            'email_tag'      => array(
                'description' => __( 'The custom field value' ),
            ),
        )
    );

    /* Register it. */
    charitable()->donation_fields()->register_field( $field );
} );

Get an existing donation field

If you want to edit or change an existing donation field, the best way to do this is by getting the registered donation field object.

You can then use set() or the magic setter to update the field definition, or use the magic getter to get information about the field.

/* Get the Donation Fields Registry. */
$fields = charitable()->donation_fields();

/* Get the Phone field. */
$field = $fields->get_field( 'phone' );

/* Change the label (magic setter). */
$field->label = 'Mobile No.';

/* Change the field to be required. */
$field->set( 'donation_form', 'required', true );

/* Print out the field's label (magic getter). */
echo $field->label;

Properties

field (string)

The field’s key, or identifier. Every field must have a unique key.

label (string)

The field’s label. This is a description of the field. This is what will be used in the donation form (unless you specifically override it in the donation_form argument), in the admin donation details area and in the donations export as the column header.

data_type (string)

The type of data that this field represents. There are two main options, with a third used mostly for internal Charitable purposes:

  • user: This is information that is specific to the donor, and will generally remain true for the donor in subsequent donations. Examples of this would include their name, phone number, etc.
  • meta: This is information that is specific to the donation. An example of this would be the payment gateway used for the donation, or whether the donor would like this donation to be made anonymously.
  • core: This is used primarily for internal purposes and should not be used in most cases. If you do use it, you will need to make sure you write additional code for storing the field value, as well as for getting it back from the database.

value_callback (false|callable)

How the field’s value will be retrieved. If you leave this out or set it to false, the default callback will be used based the field’s data type:

  • For a meta field, the default value callback is charitable_get_donor_meta_value.
  • For a user field, the default value callback is charitable_get_donation_meta_value.

You can specify your own value callback by passing your own function’s name, an array representing an object method [$class_name, $method_name], or an anonymous function.

donation_form (false|array)

How/whether the field will be included in the donation form. If this is left out or set to false, the field will not be included in the donation form at all. When passing an array, the following arguments are available:

  • label (string)
    The label shown in the donation form. If this is left out, the field’s label property will be used.
  • type (string)
    The type of field. Options include:
    • text
    • email
    • password
    • date
    • datepicker
    • checkbox
    • multi-checkbox
    • select
    • radio
    • file
    • fieldset
    • editor (uses the classic WordPress Editor)
    • textarea
    • number
    • picture
    • url
    • hidden
  • required (boolean)
    Whether this is a required field.
  • options (array)
    Provide a set of options. This is required when type is one of select, radio or multi-checkbox. These should be provided in a simple value => label array, where the label is what people see when they select an option, and value is what gets stored in the database.
  • default (mixed)
    The default value for this field.
  • placeholder (string)
    A placeholder shown in the field when it’s empty.
  • min (int)
    Set the minimum allowed number. Only applicable if type is number.
  • max (int)
    Set the maximum allowed number. Only applicable if type is number.
  • attrs (array)
    An array of arbitrary attributes to be added to the input field.
  • section (string)
    The section of the donation form this should appear in. There are two sections by default: user and meta. If this is not set, the section will be based on the field’s data type.
  • show_before (string)
    Sets where the field should be added in the donation form by specifying the field it should appear before.
  • show_after (string)
    Sets where the field should be added in the donation form by specifying the field it should appear after.
  • priority (int)
    Set the position of the field within the form. This is used unless show_after or show_before are set for the field. If priority, show_after and show_before are not set, the field will be shown after the most recently registered form field.
  • value_callback (false|callable)
    A callback function to retrieve the value of the field for a donation. This will override the value_callback setting for the field.

admin_form (boolean|array)

Sets whether the field should be shown in the admin donation form.

  • If this is set to false, the field will not be shown in the admin donation form (not even as a hidden input).
  • If this is set to true, the form field will inherit arguments from the donation_form (if provided), or use default arguments.
  • Alternatively, you can pass an array of values to fine-tune how this field is shown in the admin form (all the same arguments are accepted as for donation_form above).

show_in_meta (boolean)

Whether to include this in the “Donation Details” section of a single donation details admin page.

show_in_export (boolean)

Whether to include this in the Donations export available from Charitable > Donations.

email_tag (boolean|array)

Whether to create an email tag for this field.

  • If this is false, no email tag will be created.
  • If this is true, an email tag will be created, using the field label as the description. No preview value will be set.
  • Alternatively, pass an array for finer control over the email tag details:
    • description (string)
      The description shown for the email tag. If no description is set, the field’s label will be used.
    • tag (string)
      The email tag. If this is not provided, the field key will be used.
    • preview (mixed)
      A value to use in email previews for this field.

Methods

__construct( $field, $args )

Added in version 1.5.0

Create a new Donation Field instance.

Arguments

  • $field (string)

    The field’s unique key.

  • $args (array)

    An array containing any of the properties shown above, except for $field.

Usage

$field = new Charitable_Donation_Field(
    'my_custom_field',
    array(
        'label'          => __( 'My Custom Field' ),
        'data_type'      => 'meta', 
        'value_callback' => false,
        'donation_form'  => array(
            'type'       => 'text',
            'required'   => false,
            'show_after' => 'phone',
        ), 
        'admin_form'     => true,
        'show_in_meta'   => true,
        'show_in_export' => true,
        'email_tag'      => array(
            'description' => __( 'The custom field value' ),
        ),
    )
);

set( $key, $setting, $value )

Added in version 1.6.0

Change a field argument.

Arguments

  • key (string)

    The field argument to change. This can be any of the properties outlined above, except for $field: label, data_type, value_callback, donation_form, admin_form, show_in_meta, show_in_export, email_tag.

  • setting (string)

    This identifies a specific array element within one of the array-compatible arguments: donation_form, admin_form, email_tag. Note: If $key is not one of those three, leave this as an empty string.

  • $value (mixed)

    The new value for this field argument.

Usage

/* Get the State field. */
$field = charitable()->donation_fields()->get_field( 'state' );

/* Change the label to Province. */
$field->set( 'label', '', 'Province' );

/* Change the field to be required. */
$field->set( 'donation_form', 'required', true );

__set( $key, $value )

Added in version 1.5.0

Change the field’s parameters. Unlike the set() method described above, this does not allow you to update a single element within an array-like argument (you can’t use it to easily change whether a field is required in the donation form, for example).

It’s the equivalent of calling set() with the $setting argument left as an empty string.

Note: __set() is a magic method in PHP. It is called implicitly when you try to set one of the class properties, other than $field.

Arguments

  • $key (string)

    The field argument to change. This can be any of the properties outlined above, except for $field: label, data_type, value_callback, donation_form, admin_form, show_in_meta, show_in_export, email_tag.

  • $value (mixed)

    The new value for this field argument.

Usage

/* Get the State field. */
$field = charitable()->donation_fields()->get_field( 'state' );

/* Change the label to Province. */
$field->label = 'Province';

__get( $key )

Added in version 1.5.0

Get the field’s value for a particular argument.

Note: __get() is a magic method in PHP. It is called implicitly when you try to access a class property.

Arguments

  • $key (string)

    The field argument to retrieve.

Usage

/* Get the State field. */
$field = charitable()->donation_fields()->get_field( 'state' );

/* Print/echo the current label. */
echo $field->label;

Categories