(0)

Documentation: Awesome Support Core: Customization

Awesome Support Core: Customization

Dated: 04 Sep 2016

Adding Conditional Logic

Conditional Logic allows you to configure your Ticket Submission form to show/hide fields,  or even the submit button based on user selections. This allows you to make the looks more compact than it really is, and also provide a better user experience for your WordPress users.

Demo video

Still confused? Have a look at our video (Ad blockers or privacy mode in browsers can prevent the video from displaying):

Please bear in mind that Conditional Logic is not built-in (there’s not GUI to create conditional logic). To manually customize the Ticket Submission form, you need to have some basic PHP & jQuery knowledge.

The code

Please check out the code below or download the example plugin. This example demonstrates how to do conditional logic with Select dropdown, Checkbox and Radio.

https://gist.github.com/SiamKreative/735845931f04a9a44f6b

Ticket Details Page Template

While the submission page and the tickets list page can easily use custom templates by selecting them in the edit view, ticket details pages can’t.

The reason for that is simple: ticket details page is a “post type single view”. This means that WordPress automatically selects the template to use without letting you choose a custom one.

By default, WordPress will use your theme’s single.php, page.php or index.php template.

If you want to use a different template, it is still possible. You will need to manually customize it. Don’t worry, it’s easier that it sounds.

First of all, open your theme’s directory (eg. wp-content/themes/mytheme).

From here, locate the template file that you want to use. Let’s imagine your theme has a template with a sidebar that’s called template-sidebar.php. Copy and paste this template in the theme directory and rename it single-ticket.php.

Now, open the newly created file single-ticket.php and find the line that contains the function the_content() (most themes should have it in their templates).

Page Template

Replace the_content() by wpas_single_ticket(). That’s it. Your ticket details pages will now use the template you just customized.

At this point you can modify the look of the template – add/remove side bars, “pretify” it etc.  Only the ticket details page will be affected with any changes you make.

If you change your mind and decide you want to use the default template, simpleydelete the single-ticket.php file

How to disable agent auto-assignment?

If you need to disable the auto-assignment function and hence have all new tickets assigned to the default agent (set in the plugin general settings), you can add this constant in your theme’s functions.php file:

define( 'WPAS_DISABLE_AUTO_ASSIGN', true );

Note that this will only disable auto-assignment in the core WordPress plugin. It will NOT disable auto-assignment in the Smart Agent extensions/add-on. To disable it there, simply deactivate the extension in the WordPress Plugins screen.

Templating

If you want to change the ticket details page template, please follow this guide: Ticket Details Page Template

The plugin comes with a theme for the front-end part that should be compatible with most themes. However, if you want / need to customize it so that it fits your theme better, there is a way to achieve it.

First of all, the theme is located in awesome-support/themes/default. A theme for Awesome Support contains a minimum of four files:

  • details.php : The ticket details view. This is where users can read the ticket and reply to it
  • list.php : The list of all tickets created. This is where the user can find the complete list of tickets he opened
  • registration.php : The registration form
  • submission.php : The ticket submission form

All those templates can be customized, but you don’t need to customize them all in your custom themes.

Be careful when editing the template files. You will see a number of hooks throughout the code. Do not remove those as it will break some of the plugin’s features.

Customizing a Theme

The first thing you need to do is create the theme directory. It must be located inside your active WordPress theme’s directory and named awesome-support.

Then, you have to copy the template file(s) that you want to customize in this new directory.

Once this is done, you can customize the template code as much as you want to achieve the result you like, but keep in mind that it is important to keep all the hooks in the templates (the do_action() and apply_filters() functions).

Stylesheet

If you need to add custom style to your theme you can add a new stylesheet. It will be loaded automatically if you place it inside a /css directory and name it style.css.

Example

Let’s imagine I’m using the WordPress theme TwentyFifteen and I want to customize the Awesome Support theme. I will save all the customized files in

wp-content/themes/twentyfifteen/awesome-support

The architecture of this directory will look like this (if I want to customize everything):

/
- details.php
- list.php
- registration.php
- submission.php
/css
- style.css

Custom Fields

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' ) ) );

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' ) ) );
}

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' ) );
	}
}

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
    • 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)
  • $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
  • $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
  • $desc (string): Description shown in the ticket edit screen (admin)
  • $html5_pattern (string): Surprisingly, 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):  coming soon in version 3.3.5 in mid-2017 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 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):  coming soon version in 3.3.5 in mid-2017 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.

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' ) ) );

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

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

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

Example

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

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

Translations

The core plugin and each add-on ships with a standard POT file.  The file can then be used by many popular translation tools to create your own .PO and .MO files that render the text in the language of your choice.

The core plugin has been translated into a number of languages by volunteers.  Most popular languages have had 100% of the strings translated.  The add-ons, however, do not have as many languages readily available but you can translate them using the included .POT files at any time.

Sharing Your Language Skills

If you would like contribute to the translation effort, you can join the projects on www.poeditor.com.  By performing your translations on this site you can share your language skills with other users and, in turn, they will share their language skills with you!

The first step is to access the translations project page and register a new account on www.poeditor.com.  Then, you should contact us to have us add a slot for the language you need – contact us using our contact page or by opening a support ticket.

Once we have approved your account and added your language you can proceed to translate the strings.

POEDITOR.com Project Pages

Here are the poeditor.com links for each of the projects:

Core: https://poeditor.com/join/project/P6HgfPnBt4

Auto Close: https://poeditor.com/join/project/3GOG3r1ynk

Canned Responses: https://poeditor.com/join/project/oAKLCKNIOx

Custom Status: https://poeditor.com/join/project/Lw4R8QZzJ1

Easy Digital Downloads: https://poeditor.com/join/project/VD5AFeXNOP

Email Support: https://poeditor.com/join/project/kGJCtexJrZ

Envato Validation: https://poeditor.com/join/project/ilPmG1SE4y

FAQs: https://poeditor.com/join/project/NYvmBIwogM

Filestack: https://poeditor.com/join/project/eSyjpJDmjJ

Guest Tickets: https://poeditor.com/join/project/TxzFeMbQ5C

Mailchimp: https://poeditor.com/join/project/7O3FNckF2l

Notifications: https://poeditor.com/join/project/bfc2HRKlOX

Private Credentials: https://poeditor.com/join/project/2GQMfwnlM7

Private Notes: https://poeditor.com/join/project/zv24CYQdFc

Satisfaction Survey: https://poeditor.com/join/project/sPQnSxVtz0

WooCommerce: https://poeditor.com/join/project/BHLbDoPTn9

Suggest Edit