Designing Custom Forms in HelpSpot

HelpSpot has many different channels to receive new requests. Email, API Request, Widgets and Forms on the support portal. Email is a great way to quickly collect requests. However, sometimes you would like customers to included more detailed information about their requests. This can be achieved through customizing forms on your support portal.

Portal Form Setup Options

HelpSpot has many different options for formatting and collecting extra information through forms. We’ll be looking at the settings that are available in the forms administration area. To navigate to these settings click on Admin > Settings > Portal.

The first option on this page is the Portal Request Form Format. This is the simplest way to change how you gather information in the support portal. Two options are available, Simple Format or Detailed Format. Simple format is selected by default and provides a single text box for customers to describe their problem. The Detailed format asks three
structured prompts that are ideal for troubleshooting technical issues: This is what I DID, This is what I EXPECTED to happen, This is what ACTUALLY happened. For some cases this may work perfectly but it isn’t the most flexible option. We’ll cover a more flexible options using custom fields in a little bit.

The next setting that will affect how customers interact with your support form is the Allow Attachments setting. This setting also has an associated setting Forbidden Attachment Extensions. This setting allows you to filter out certain attachment types while still accepting attachments. If you regularly request files from your customers this can be a great item to turn on.

The final setting on this screen that will affect your forms is the Captcha Type option. Captcha tools are a category of tools that allow you to filter out bots and spam requests. You can run Helpspot with no CAPTCHA tool enabled, a simple internal CAPTCHA filter or use Google’s reCaptcha service. If you opt for the last option you will be directed to generate an API key with Google and then enter that key into the settings area. It is good to note that your HelpSpot server will need access to the public internet in order to use the Google options. The simple CAPTCHA filter will work without any external access.

Public Categories

Public categories are the next way to customize your HelpSpot forms. Categories are the most general field available for organizing requests. By default, requests come into the inbox
without a category attached to them. Requests must then be categorized before updates are made.

You can allow your customers to categorize their requests through the portal forms by switching some or all categories to public view. This setting can be changed in the Admin > Categories area. Each category has a public/private switch. Since this setting is per Category you can choose to keep some categories for internal use only and have others be public facing.

Custom Fields

Related to public categories, custom fields can also be made public. You may already have custom fields set up in your system that you want make available on your forms. If you don’t, now is a great time to think about what other structured data you usually need from your customers. Here’s a few things to keep in mind about custom fields:

Custom fields are enabled and disabled per category so a custom field does not need to apply to all types of requests and customers.
There are 11 types of custom fields:
- Predefined List
- Drill Down List
- Text Field
- Large Text Field
- Date Field
- Date and Time Field
- Regular Expression Field
- AJAX Selection Field
- Checkbox, Numeric Field
- Decimal Field.
Each field can be marked as required or optional based on your needs.

Custom fields have all sorts of uses. For example, you could use a Regular Expression Field to gather zip codes or order numbers in a strict format to perform automatic lookups. Or, you could use a dropdown list to have customers select their country or state to route requests to the right departments. Remember, once you have gathered custom field data you can have triggers and automations perform a wide array of tasks automatically for you.

Integrating Custom Fields Into Forms

Once you have your custom fields defined. You will need to make them public. To accomplish this, go to the custom fields settings and then look for the private / public toggle button. Note, custom field visibility can be overridden at the category level. If the category is private making a custom field that is attached to the category public will have no effect.

At this point any custom fields that you have made public should be visible as you fill out the request portal form. Any fields that you have defined as required will also be required on the portal form.

Secondary Portals

If you are utilizing secondary portals you can select which custom fields you want to display in that particular portal. This feature is found in the secondary portal setup options. Being able to turn off certain custom fields per portal allows you to display only the relevant fields to the visitors on each of your portals.

Deeper Customizations

All of the customizations that we have demonstrated so far are accomplished through various settings in the admin area of HelpSpot. We can take these customizations even further by editing the request template directly. HelpSpot includes an easy way to make these edits. Simple navigate to Admin > Customize > Portal Templates and then edit request.tpl.php. This file controls the display and operation of the request page in the HelpSpot portal.

Removing the Urgent Option

Do you have customer’s that think every issue is urgent? At times you may want to use the urgent marker in helpspot internally and not allow customers to self select urgent requests. You can remove the urgent option by commenting out a few lines in request.tpl.php.

First find this section of code:

<p>
<label for="fUrgent" class="data label">
<?php echo lg_portal_req_urgent ?>
</label>
<br />
<select name="fUrgent">
    <option value="0" <?php if($this->request_fUrgent == 0) echo 'selected' ?>><?php echo lg_portal_req_no ?></option>
    <option value="1" <?php if($this->request_fUrgent == 1) echo 'selected' ?>><?php echo lg_portal_req_yes ?></option>
</select>
</p>

After you have found this section of code, use the html comment tags  to comment out this section. Your final code should look like this:

<!--<p>
<label for="fUrgent" class="data label">
<?php echo lg_portal_req_urgent ?>
</label>
<br />
<select name="fUrgent">
    <option value="0" <?php if($this->request_fUrgent == 0) echo 'selected' ?>><?php echo lg_portal_req_no ?></option>
    <option value="1" <?php if($this->request_fUrgent == 1) echo 'selected' ?>><?php echo lg_portal_req_yes ?></option>
</select>
</p>-->

Separate First and Last Name Fields

By default HelpSpot containts a single name field that it parses into first and last names. If you would rather use individual first name and last name fields you can do this very easily using some commented code in the portal template.

First search for these lines in request.tpl.php:

<?php
/*
If you would rather use individual first name and last name fields then uncomment these fields
and comment out the fullname field above. You also need to remove the 'fullname' item from the
hidden field 'required' above.

<p><label for="sFirstName" class="datalabel"><?php echo lg_portal_req_firstname ?></label><br />
    <?php echo $this->helper->showError('sFirstName','<br />') ?>
    <input type="text" name="sFirstName" size="40" maxlength="100" value="<?php echo $this->request_sFirstName ?>" />
</p>

<p><label for="sLastName" class="datalabel"><?php echo lg_portal_req_lastname ?></label><br />
    <?php echo $this->helper->showError('sLastName','<br />') ?>
    <input type="text" name="sLastName" size="40" maxlength="100" value="<?php echo $this->request_sLastName ?>" />
</p>
*/
?>

Next, remove the /* from the beginning and end of the code. Your final code block should looking like this:

<?php
/*
If you would rather use individual first name and last name fields then uncomment these fields
and comment out the fullname field above. You also need to remove the 'fullname' item from the
hidden field 'required' above.*/

<p><label for="sFirstName" class="datalabel"><?php echo lg_portal_req_firstname ?></label><br />
    <?php echo $this->helper->showError('sFirstName','<br />') ?>
    <input type="text" name="sFirstName" size="40" maxlength="100" value="<?php echo $this->request_sFirstName ?>" />
</p>

<p><label for="sLastName" class="datalabel"><?php echo lg_portal_req_lastname ?></label><br />
    <?php echo $this->helper->showError('sLastName','<br />') ?>
    <input type="text" name="sLastName" size="40" maxlength="100" value="<?php echo $this->request_sLastName ?>" />
</p>

?>

Now we need to hide the old, single field. Find this code block:

<?php /* HelpSpot will automatically parse the name into first name and last name */?>
<p><label for="fullname" class="datalabel required"><?php echo lg_portal_req_name ?></label><br />
    <?php echo $this->helper->showError('fullname','<br />') ?>
    <input type="text" name="fullname" size="40" maxlength="100" value="<?php echo $this->request_fullname ?>" />
</p>

Move the php end tag and comment down to comment out this whole section:

<?php /* HelpSpot will automatically parse the name into first name and last name 
<p><label for="fullname" class="datalabel required"><?php echo lg_portal_req_name ?></label><br />
    <?php echo $this->helper->showError('fullname','<br />') ?>
    <input type="text" name="fullname" size="40" maxlength="100" value="<?php echo $this->request_fullname ?>" />
</p>
*/?>

Next we also need to remove the ‘fullname’ item from the hidden field ‘required’ and add sFirstName and sLastName. Find this line:

<input name="required" type="hidden" value="sEmail,fullname" />

Modify the code to look like this:

<input name="required" type="hidden" value="sEmail,sFirstName,sLastName" />

Integrating with Other Systems

If you have poked around in the request.tpl.php file, you probably noticed comments about passing information into fields and adding hidden fields into the request form. While this is beyond the scope of this article, take a look at the comments in this file to get ideas on ways that you can pass preexisting data into your request forms to make the submission process even easier for your customers.

Making Everyone’s Job Easier

As you customize your portal forms remember to think about everyone involved in a support interaction. Too many options can leave a customer frustrated and confused as they fill out a form. Too few, can cause unnecessary communication between your team and your customers clarifying information that could have easily been collected. Designing great forms isn’t easy. But, HelpSpot’s tools make it easier to find the right balance and design to create great interactions with your customers.