Advanced Settings for Ratings and Satisfaction

Similarly to the core KB Support plugin, and its extensions, Ratings and Satisfaction can be customised beyond the options that are available within settings.

This document, aimed at our more advanced user base, will detail some of the advanced customisation’s that can be achieved. As always, we highly recommend that any changes are implemented within your child theme to avoid being overwritten during future updates.

Adding Content to the Rating Forms

Whilst the options within settings allow you to choose your own labels for headings etc. you may also want to add additional content to your rating forms. For example to tell customers why you want them to provide their feedback.

This gives you the opportunity to further encourage customers to provide the feedback and it is much more likely they will do so if they understand why it is you’re asking for it.

You can insert your content easily using a number of hooks. The hooks available are:

• kbs_before_article_rating_heading
  By Hooking here you can add content to the rating form before the form heading, which in the above example is “Was this article helpful?”.
  To use this hook on the ticket rating form, use the hook kbs_before_ticket_rating_heading
• kbs_before_article_rating_stars
  Hooking here allows you to add content before the rating stars. In the image above, this hook is being used to insert the content between “Was this article helpful?” and the stars.
  To use this hook on the ticket rating form, use the hook kbs_before_ticket_rating_stars
• kbs_before_ticket_rating_comments
  This hook allows for content to be added between the rating stars and the comment field on the ticket rating form
• kbs_before_ticket_rating_submit
  This hook allows for content to be added between the rating stars and the submit button on the ticket rating form
• kbs_after_article_rating
  Hooking here you can add content after the rating form.
  To use this hook on the ticket rating form, use the hook kbs_after_ticket_rating

Example

In order to add the paragraph within the image above, the following was used…

function kbs_mh_article_rating_intro()	{
	ob_start(); ?>
	<p>We're working hard to ensure we provide you with useful and relevant documentation to help you get the most out of KB Support.</p>
    <p>Please take a moment to let us know if you found this article helpful.</p>
	<?php echo ob_get_clean();
} // kbs_mh_article_rating_intro
add_action( 'kbs_before_article_rating_stars', 'kbs_mh_article_rating_intro' );

Enabling Ticket Rating for Statuses other than Closed

By default, the ticket rate form will only be displayed to customers whilst their ticket is within the closed status (and they have not already rated). If you need to display the form whilst a ticket is in another status, perhaps because you have created a custom status using the Custom Ticket Status extension, you can do so by hooking into the kbs_rs_ticket_rate_statuses filter.

Example

Let’s say you have created a custom ticket status of Parked and you want to display the rating form for tickets in this status.

The following example would achieve this.

/**
 * Allow tickets within the Parked status to be rated.
 *
 * @param	array	$statuses	An array of statuses for which the rating form should be displayed
 * @return	arrray	Filtered array of statuses for which the rating form should be displayed
 */
function mh_kbs_rate_parked_tickets( $statuses )	{
	// To display the form for tickets that are closed or parked
	$statuses[] = 'parked'; // This needs to be the status 'slug'

	// To display the form only for parked tickets
	$statuses = array( 'parked' );

	return $statuses; // Don't forget to return $statuses
}
add_filter( 'kbs_rs_ticket_rate_statuses', 'mh_kbs_rate_parked_tickets' );

Changing the Rating Forms

As with the majority of pages, content and shortcodes that are output by KB Support, the rating forms are generated by template pages which are located within the kbs-ratings-satisfaction\templates folder together with the CSS stylesheets. The files are named as follows:

• kbs-rs.css – This is the CSS file responsible for styling the form and its elements
• kbs-rs.min.css – This is the minified CSS file responsible for styling the form and its elements. KB Support will always load a .min.css file in preference to a .css file if it exists so it is important that you update both css files
• ratings-article.php – This is the file responsible for the output of the article rating form
• ratings-ticket.php – This is the file responsible for the output of the ticket rating form

Before making changes to these files, copy them to the kbs_templates directory within your child theme. You will need to create this directory if you have not done so previously.

Once you have copied the files, make changes to the copies and not the originals. Any changes to the original files will be overwritten during future plugin updates.

It is recommended that you edit the file between the EDIT BELOW THIS POINT ONLY and NO FURTHER EDITS AFTER HERE commented markers only. Edits outside these comments may result in the form no longer working.

You should also retain the element names and classes as changing these may stop the form from working.