Guide recipe: Requesting feedback for article downvotes

The standard Copenhagen theme lets end users vote on help center articles. In this recipe, you'll edit the theme's code to display a follow-up message when a user downvotes an article.

The downvote message includes a link to a New Request page that contains a ticket form. A user can fill out the ticket form to leave feedback for the article. The form uses a custom ticket field to capture the article's URL. When submitted, the form creates a ticket in Zendesk Support.

About this recipe

You must be a Zendesk Support admin to complete this recipe. The recipe involves the following tasks:

• Task 1: Enabling anonymous voting
• Task 2: Creating a custom ticket field for the article URL
• Task 3: Adding custom CSS
• Task 4: Updating the Article Page template
• Task 5: Adding custom JavaScript
• Task 6: Testing your changes

The recipe assumes you're editing the standard Copenhagen theme. If you want to edit another theme or make similar changes to a customized Copenhagen theme, you may need to change the code examples.

The recipe also uses a pre-filled ticket form. Pre-filled ticket forms require a theme using Templating API version 2. To check your theme's version, see About Guide templating versions.

Note: This recipe requires editing CSS, page templates, and JavaScript. When you edit a standard theme, it is saved as a custom theme. Custom themes are not supported by Zendesk and are not automatically updated when new features are released. See About standard themes and custom themes in your help center.

Task 1: Enabling anonymous voting

If your help center is visible to anonymous visitors, you can enable anonymous voting as an optional step. Anonymous voting lets end users vote on help center articles without signing in.

To enable anonymous voting, follow the instructions in Enabling users to vote on knowledge base articles without signing in. Then return to this article.

Task 2: Creating a custom ticket field for the article URL

To start, create a custom ticket field to capture help center article URLs.

To create a custom ticket field for the article URL

1. In Admin Center, click Objects and rules in the sidebar, then select Tickets > Fields.
2. Click Add field.
3. Select the Text field type.

   

4. Enter Help Article URL as the Display name.
5. Under Permissions, select Customers can edit.
6. Under Customers, enter Help Article URL as the Title shown to customers.

   

7. Click Save.

   If your account uses a single ticket form, the new field automatically appears in your ticket form. If you use multiple ticket forms, you have to manually add the field to any ticket forms you'd like to include it in.

8. On the Fields page, copy the Field ID for the Help Article URL field. You'll use the ID later in this recipe.

Task 3: Adding custom CSS

Next, add custom CSS for the downvote message to your theme.

To add the custom CSS to the theme

1. In Guide, open the code editor for the theme. For instructions, see Editing your Help Center theme.
2. Click style.css.
3. Paste the following at the bottom of the file:

   /* ---- Downvote message ----------- */
   .downvote-message {
     display: none;
     border: 1px solid #ddd;
     border-radius: 4px;
     text-align: center;
   }

   The code adds CSS rules for a .downvote-message class. You'll use the class to hide the downvote message until a user downvotes an article. The class also styles the message when it's displayed.

4. If you're updating your help center's live theme, click Publish. Otherwise, click Save.

Task 4: Updating the Article Page template

Next, add HTML for the downvote message to the theme's Article Page template.

To update the Article Page template

1. In Guide, open the code editor for the theme.
2. Click article_page.hbs.
3. Add the following HTML snippet before the closing tag of <div class="article-votes"> :

   <div class="downvote-message">
     <p>We're sorry to hear that.</p>
     <p><a href="{{page_path 'new_request'}}?tf_CUSTOM_FIELD_ID=HTTPS://SUBDOMAIN.ZENDESK.COM{{url}}">Please tell us
         why.</a></p>
   </div>

   In the snippet, replace:

   • CUSTOM_FIELD_ID with the Field ID for the Help Article URL field you created in Creating a custom ticket field for the article URL
   • HTTPS://SUBDOMAIN.ZENDESK.COM with the base URL for your help center
   The HTML adds a downvote message below the voting buttons of each article. The message's parent div uses the downvote-message class you added in Creating a custom ticket field for the article URL. This class's CSS hides the message from all users. Later in the recipe, you'll add custom JavaScript to display the message when a user leaves a negative vote.

   The message contains a link to a New Request page containing a ticket form. This link uses a URL parameter to pre-fill the form's Help Article URL field with the current article URL. To learn more about pre-filling ticket forms, see Creating pre-filled ticket forms.

4. If your account uses a single ticket form, skip to the next step. If your account has multiple ticket forms, add the &ticket_form_id=FORM_ID URL parameter to the end of the HTML snippet's href value. In the parameter, replace FORM_ID with your ticket form's ID. Example:

   <div class="downvote-message">
     <p>We're sorry to hear that.</p>
     <p><a href="{{page_path 'new_request'}}?tf_12345=https://example.zendesk.com{{url}}&ticket_form_id=67890">Please tell us
         why.</a></p>
   </div>

   The ticket form must be visible to end users. To check or change a ticket form's visibility, see Creating multiple ticket forms to support different request types.

5. Review your template's <div class="article-votes"> element. It should look similar to this:

   <div class="article-votes">
     <span class="article-votes-question" id="article-votes-label">{{t 'was_this_article_helpful'}}</span>
     <div class="article-votes-controls" role="group" aria-labelledby="article-votes-label">
       {{vote 'up' role='radio' class='button article-vote article-vote-up' selected_class="button-primary"}}
       {{vote 'down' role='radio' class='button article-vote article-vote-down' selected_class="button-primary"}}
     </div>
     <small class="article-votes-count">
       {{vote 'label' class='article-vote-label'}}
     </small>
     <div class="downvote-message">
       <p>We're sorry to hear that.</p>
       <p><a href="{{page_path 'new_request'}}?tf_67890=https://example.zendesk.com{{url}}">Please tell us
           why.</a></p>
     </div>
   </div>

6. If you're updating your help center's live theme, click Publish. Otherwise, click Save.

Task 5: Adding custom JavaScript

Add some JavaScript to display the downvote message when a user downvotes an article.

To add the custom JavaScript to the theme

1. In Guide, open the code editor for the theme.
2. Click script.js.
3. Paste the following at the bottom of the file:

   // Display message for article downvotes
   document.addEventListener("DOMContentLoaded", () => {
     if (document.querySelector(".article-votes-controls")) {
       const voteButtons = document.querySelectorAll(".article-vote");
       const voteMessage = document.querySelector(".downvote-message");
   
       voteButtons.forEach((button) => {
         button.addEventListener("click", () => {
           let isDownButton = button.matches(".article-vote-down");
           let isPressed = button.matches(".button-primary");
   
           if (isDownButton && !isPressed) {
             voteMessage.style.display = "block";
           } else {
             voteMessage.style.display = "none";
           }
         });
       });
     }
   });
   

   When a user clicks the No vote button, the JavaScript displays the downvote message you added in Updating the article page template. If the user resets their vote or changes their vote to Yes, the JavaScript hides the message again.

4. If you're updating your help center's live theme, click Publish. Otherwise, click Save.

Task 6: Testing your changes

Test out your new voting functionality to ensure it works as intended.

To test your changes

1. In Guide, open the code editor for the theme.
2. Click Preview.
3. In the Preview window, select a Preview role of End user.
4. Navigate to an article in your help center. At the bottom of the article, click the No vote button under Was this article helpful?.

   A short message containing a Please tell us why link should appear.

   

5. Click the Please tell us why link.

   The link should open a New Request page containing the ticket form. The ticket form's Help Article URL field should contain the URL for the related help center article.

   

   If wanted, you can submit the form to create a test ticket.

6. Navigate to another article in your help center and click the No vote button.
7. After the downvote message appears, click the Yes vote button. The downvote message should disappear.
8. If you didn't make the changes to your help center's live theme and are ready to launch them, you can set the customized theme as your live theme. See Changing the live theme of your help center.