Awesome Support Documentation

Custom Fields

Introduction

Awesome Support’s ticket submission form can be customized with custom fields. Those custom fields can be defined manually by using the wrapper functions available.

Note:  you can also use our Custom Fields Add-on that provides a nice visual interface for creating custom fields with no programming necessary.  Or you can create a completely custom ticket form with our Gravity Forms add-on ( also no programming required – but, of course, the Gravity Forms plugin is required.)

The rest of this documentation is for users who are comfortable writing code for WordPress.

Please be aware that a basic knowledge of PHP functions, arrays and variable types is required to add custom fields manually as described in this documentation.

Where To Start?

First of all, where should you add all the code that’s necessary to add the custom fields you need?

The classic is to use your theme’s functions.php file. However, this is a pretty bad idea because if you ever decide to change your theme, all the customization will be lost.

The preferred solution is to use a dedicated plugin that will hold all of your code. Don’t worry, it’s easier than you think ;)

We have prepared a starter kit for you. It’s available on Gist. What you need to do is download the file from Gist and save it in your plugin’s directory (typically /wp-content/plugins/awesome-support-custom-fields.php).

Once you have this file saved in your plugin’s directory you can get started on creating your first custom field.

Creating a Custom Field

Creating a custom field is straightforward because it can be done by using just one function. However, there are quite a lot of parameters (most of them are optional) for each field.

Available Field Types

You can see all the available field types (and even ask for more!) here: https://github.com/ThemeAvenue/Awesome-Support/issues/196

Registering the Custom Field

The action of registering a custom field is dead simple. You only need to use one function that will handle all the heavy lifting for you. The function is wpas_add_custom_field( $name, $args ).

This function takes 2 parameters:

  • $name (string): A text string identifying your custom field. It must be unique, lowercase and without spaces. For instance my_custom_field
  • $args (array): The parameters used to define the custom field (more on this in Custom Fields Parameter)

Both these parameters are mandatory and a custom field will not be registered if one (or both) is missing. A correct way to register a custom field would look like this:

wpas_add_custom_field( 'my_custom_field',  array( 'title' => __( 'My Custom Field', 'wpas' ), 'order' => 1 ) );

When using wpas_add_custom_field() or wpas_add_custom_taxonomy(), please make sure to wrap them inside a function_exists() check.

if ( function_exists( 'wpas_add_custom_field' ) ) {
    wpas_add_custom_field( 'my_custom_field',  array( 'title' => __( 'My Custom Field', 'awesome-support' ), 'order' => 1 ) );
}

Ideally, the code ends up looking like this:

/**
 * Register all custom fields after the plugin is safely loaded.
 */
add_action( 'plugins_loaded', 'wpas_user_custom_fields' );
function wpas_user_custom_fields() {
	if ( function_exists( 'wpas_add_custom_field' ) ) {
		wpas_add_custom_taxonomy( 'my_custom_services', array( 'title' => 'My Custom Services', 'label' => 'Service', 'label_plural' => 'Services', 'order' => 1 ) );
	}
}

Custom Field Parameters

Mandatory fields are identified next to their name by the (mandatory) tag. For all non-mandatory fields, if you don’t understand what it is and what it does, please do not use it. The parameters shown in the Basic Field Parameters should be relatively easy to understand, but the ones shown in Advanced Field Parameters are oriented to developers. Just skip it if you don’t understand it – you will still be able to create your custom fields.

Basic Field Parameters

  • $title (mandatory) (string): The “human readable” name of your custom field. That’s the name that’ll be shown in the submission form.
  • $field_type (mandatory) (string): The type of field that you want to register. It can be a custom function (for developers). For inexperienced users, use the field types available in core:
    • text: A standard text input
    • url: A text input with URL validation (won’t submit if the input is not a URL)
    • checkbox
    • date-field
    • email: Basically a text field but with e-mail validation on front-end
    • number
    • password
    • radio
    • select: A select dropdown
    • textarea
    • upload
    • wysiwyg: The WordPress TinyMCE text editor. Note: if the “Use editor in front-end” option is disabled in the plugin settings, the WYSIWYG editor will fallback to a simple textarea
    • taxonomy: For dynamic dropdowns (see Dynamic Dropdowns below)
  • $order (int): The order in which the field should appear on the screen
  • $placeholder (string): An optional placeholder to use with input fields
  • $default (mixed): The (optional) default value for your custom field
  • $required (boolean): Whether or not this field is required for submission. If set to false a ticket can be submitted even if this field is not filled-in
  • $log (boolean): Whether or not to log the changes of values to this field. The log is shown in the ticket history in the back-end (seen by admins and agents)

Advanced Field Parameters

  • $show_column (boolean): Whether or not to show the field’s value in the tickets list screen.  Cannot be used with fields that store multiple values (eg: checkbox fields).
  • $column_attributes (array): Added in version 3.3. Defines custom colums attributes in the front-end tickets list table. More on this in the “Columns Attributes” section hereafter.
  • $sortable_column (boolean): Whether or not to make the column sortable (not compatible with taxonomy fields)
  • $filterable (boolean): Whether or not to add a filter based on the field (for taxonomies only)
  • $capability (string): Required capability for editing the field value in the admin. If current user doesn’t have the required capability the field will be “read-only”
  • $sanitize (string): A custom sanitization callback (default to sanitize_text_field)
  • $save_callback (string): A custom function used to save the custom field’s content. If a custom save callback is used the plugin will not process this field at all.
  • $column_callback (string): Purpose and use will be updated in future versions of this documentation.
  • $desc (string): Description shown in the ticket edit screen (admin) as well as under the field when user is filling out a new ticket.
  • $html5_pattern (string): This allows you to declare an HTML5 validation pattern
  • $select2 (bool): Added in version 3.3. Make any select or taxonomy field searchable using jQuery select2. To enable select2 for the products dropdown see this FAQ article.
  • $hide_front_end (bool):  Added in version 4.0.0. Hide field on the front-end form and allow the developer to write their own back-end display logic? If you set this flag to TRUE and you want to use and see this field on the back-end you MUST write your own back-end (wp-admin) display functions.  Obviously this is only for use by experienced WordPress developers.
  • $backend_only (bool): Added in version 4.0.0. Show field only on the back-end (wp-admin)?.  For most users this is better than using $hide_front_end since no custom back-end display logic is necessary.
  • $readonly (bool): Added in version 4.0.0. Make the field read-only – neither the user nor agent can edit a field where this value is set to TRUE.
  • $show_frontend_list (bool): Added in version 4.1.0. Should the field be shown on the front-end to the user in their ticket list (default is TRUE)
  • $show_frontend_detail (bool): Added in version 4.1.0. Should the field be shown on the front-end to the user when viewing an individual ticket form (default is TRUE)
  • $extra_wrapper_css_classes (string): Added in version 4.3.0. Any custom CSS classes that you would like added to the markup that wraps the custom field on the front-end form
  • $extra_field_css_classes (string): Added in version 4.3.0. Any custom CSS classes that you would like added to the markup for the custom field control on the front-end form
  • $extra_wrapper_css_classes_be (string): Added in version 4.3.0. Any custom CSS classes that you would like added to the markup that wraps the custom field on the back-end (wp-admin)
  • $extra_field_css_classes_be (string): Added in version 4.3.0. Any custom CSS classes that you would like added to the markup for the custom field control on the back-end (wp-admin)
  • $boot_strap_row_fe_start (bool): Added in version 4.3.0. Set to TRUE if a new BootStrap 4.0 row should be started with this field on the front-end form (default is FALSE).  This setting basically wraps the field in a div that has a classname of ROW.
  • $boot_strap_row_fe_end (bool): Added in version 4.3.0. Set to TRUE if an existing BootStrap 4.0 row should be terminated with this field on the front-end form (default is FALSE)
  • $boot_strap_column_fe (bool): Added in version 4.3.0. Set to TRUE if this field is to be placed in a BootStrap 4.0 column (default is FALSE). This only works properly if an existing BootStrap row has already been set up.

Checkbox, Radio and Select-Only Parameters

  • $options (array): An array of options. The array must be or the form array( 'option_id' => 'Option Label' )
Example
wpas_add_custom_field( 'my_field_with_options', array( 'title' => 'My Options', 'options' => array( 'option1' => 'First Option', 'option2' => 'Second Option' ), 'order' => 1 ) );

Textarea-Only Parameters

  • $cols (int): Number of columns
  • $rows (int): Number of rows

Upload-Only Parameters

  • $multiple (bool): Whether or not to allow multiple files in the upload field

WYSIWYG-Only Parameters

  • $editor (array): Additional editor parameters, same as the $settings parameter in wp_editor()

Dynamic Dropdown (AKA Taxonomy)

As explained above, you can create dropdown selects using custom fields. However, this means that your dropdown options will be hardcoded in your custom fields plugin.

Sometimes this is just fine, but sometimes you might want to be able to edit the options on a regular basis.

In this case, there is a very specific type of custom field that we call dynamic dropdown, or taxonomy for more experienced users.

What this custom field type does is create a specific kind of option that we call a taxonomy. Once registered, you will see a new menu item appear under Tickets in your admin. This will take you to a page that lets you edit the dropdown options.

Declaring a Dynamic Dropdown

There is a dedicated function for declaring a dynamic dropdown. This function is wpas_add_custom_taxonomy().

This function takes exactly the same parameters as wpas_add_custom_field() (explained above), except that is has a couple of extra parameters available.

Specific Parameters for Dynamic Dropdowns

Just like above, if you don’t understand what some of there parameters are for, just skip it.

  • $taxo_std (boolean): Whether or not this taxonomy should act as a standard WordPress taxonomy. If set to false it will be used as a “fake” taxonomy and displayed as a basic select input. Please note that if it is set to false and you want to display the values in the tickets list screen you need to set $show_column to true
  • $label (string): Taxonomy singular name
  • $label_plural (string): Taxonomy plural name
  • $taxo_hierarchical (boolean): Whether or not this taxonomy should be hierarchical
  • $update_count_callback (string): Custom taxonomy count callback. Default to wpas_update_ticket_tag_terms_count
  • $taxo_manage_terms (string): Added in version 4.0.0. Capability required to manage taxonomy if the custom field is a taxonomy field.  Default is ‘create_ticket’.
  • $taxo_edit_terms (string): Added in version 4.0.0. Capability required to edit taxonomy terms if the custom field is a taxonomy field. Default is ‘settings_tickets’.
  • $taxo_delete_terms (string): Added in version 4.0.0. Capability required to delete taxonomy terms if the custom field is a taxonomy field. Default is ‘settings_tickets’.
  • $taxo_assign_terms (string): Added in version 4.0.0. Capability required to assign taxonomy terms if the custom field is a taxonomy field. Default is ‘create_ticket’.

Example

wpas_add_custom_taxonomy( 'my_custom_services', array( 'title' => 'My Custom Services', 'label' => 'Service', 'label_plural' => 'Services', 'order' => 1  ) );

Column Attributes

This parameter requires $show_column being set to true. It will not work otherwise.

Since version 3.3 it is possible to add custom column attributes. Those attributes are data attributes that are added to the column head and/or body of the front-end tickets list table (where the user can find the list of his tickets).

The column_attributes parameter is quite flexible. It allows you to add attributes to both the table head and the table body. It also allows the use of custom callbacks.

This parameter is a multidimensional array. Its basic form defines attributes for the table head and body.

See code example here: http://pastebin.com/RL3539m3

In the most basic use, you just pass the attribute name and its value.

NOTE: Column attributes are in fact data-attributes. However, you don’t need to add the data- prefix as it is automatically added if missing.

Using Callback Functions

If you need to add more advanced attributes with dynamic values, you can do so very easily. What you need to do it pass a function name as the attribute value. The plugin will automatically try to find an existing function and use it.

See code example here: http://pastebin.com/7msMDk1E

This also means another thing: if you’re just passing plain values, those values must not be a function name.

If you’re using a custom callback function, you can also pass parameters to it. In this case, the attribute value must be an array with the first value being the function name, and then your parameters come after that. Your parameters will be passed as an array to the callback function.

See code example here: http://pastebin.com/ayj3ZsvS

Populate Custom Fields With URL Variables

You can pre-populate custom fields with URL variables. For all fields, including custom fields, you need to pass a URL variable where the key is the field ID (as declared in your custom fields, first parameter of  wpas_add_custom_field()) prefixed with wpas_

For instance, if you have a custom field declared as follows:

wpas_add_custom_field( 'my_field', $args );

You can pre-populate it by browsing:

http://yoursite.com/submit-ticket/?wpas_my_field=value

An Example Using A Custom Upload Field

Here is an example showing how to add a new file upload field to your front end ticket screen.

add_action( 'wpas_submission_form_inside_after_subject', 'my_upload_field_frontend', 1 );
function my_upload_field_frontend( ) {
$image_array_args = array(
'title' => 'Front Of Check',
'field_type' => 'upload',
'capability' => 'edit_ticket',
'multiple' => false,
'label' => 'Upload an image of the front of your check',
'log' => true,
'order' => 1
);
wpas_add_custom_field( 'front_of_check', $image_array_args );
}

Here is an example of how to do the same thing in the back-end admin area only.

add_action( 'wpas_mb_details_before_custom_fields', 'my_upload_field_backend' );
function my_upload_field_backend( ) {
$imagem_do_registro_args = array(
'title' => 'Imagem do Registro',
'field_type' => 'upload',
'capability' => 'edit_ticket',
'multiple' => false,
'label' => 'Insira aqui a imagem do protocolo',
'log' => true,
'order' => 1
);
wpas_add_custom_field( 'imagem_do_registro', $imagem_do_registro_args );
}

More About Custom Upload Fields

Custom upload fields will allow you to upload a file but you will have to add hooks to DO SOMETHING with the file. Otherwise the file isn’t attached to anything. For example, you might want to add a function to take the file and send it to a SaaS service (such as Microsoft Azure or Google Or Amazon AWS) to check for objectionable images or to extract data. Here is an example of how to move a file and make it an attachment to the ticket. Notice that in this case we are actually extending a built-in Awesome Support class to do something with the files that are uploaded.

//load main class if not exists
if ( ! class_exists( 'WPAS_File_Upload' ) ) {
    if ( defined( WPAS_PATH ) && file_exists( WPAS_PATH . 'includes/file-uploader/class-file-uploader.php' ) ) {
        require( WPAS_PATH . 'includes/file-uploader/class-file-uploader.php' );
    } else {
        exit();
    }
}

if ( ! class_exists( 'ASCF_My_File_Upload' ) ) {
    class ASCF_My_File_Upload extends WPAS_File_Upload {
        protected $index;

        public function __construct( $field_name ) {
            $this->setup_index( $field_name );
            if ( is_admin() ) {
                add_action( 'wpas_add_reply_admin_after', array( $this, 'new_reply_backend_attachment' ), 10, 2 );
            } else {
                add_action( 'wpas_open_ticket_after', array( $this, 'new_ticket_attachment' ), 10, 2 );
            }
        }

        protected function setup_index( $field_name ) {
            $this->index = $field_name;
        }
    }
}

new ASCF_My_File_Upload( 'front_of_check' );

add_action( 'wpas_submission_form_inside_after_subject', 'my_upload_field_frontend', 1 );
function my_upload_field_frontend() {
    $image_array_args = array(
        'title'      => 'Front Of Check',
        'field_type' => 'upload',
        'capability' => 'edit_ticket',
        'multiple'   => false,
        'label'      => 'Upload an image of the front of your check',
        'log'        => true,
        'order'      => 1
    );
    wpas_add_custom_field( 'front_of_check', $image_array_args );
}