If you've configured Tickler PLUS to use a progress field and would like to display it to end-users in Guide (i.e., Help Center), you'll need to add some JavaScript code to your template. This converts the text to HTML and applies some basic formatting. The steps below will help you accomplish this.
Note: The JavaScript code was designed to work a relatively "stock" Guide template. If you're using a heavily modified template or you've make changes to the "request_page" file, you may need to modify our code to work on your site. You can find a link to the unminified code towards the end of this document.
Step 1 - Log in as a Guide Admin
Log into Zendesk as a user with Guide Manager privileges. If you're in the agent interface, you'll need to switch to Guide. To do that, click the icon on the top right that looks like four squares and choose Guide.
Once in Guide, click "Guide admin" on the right side of the toolbar.
If you don't see the link, log out and then back in. If the link still isn't there, you may not have Guide Manager privileges. Consult the following document for more information on Guide privileges and how to configure them:
https://support.zendesk.com/hc/en-us/articles/218113638-Understanding-Guide-roles-and-setting-permissions
Step 2 - Backup your Template
In "Guide admin", click "Customize Design" on the left (the icon that looks like an eye). This will show you the templates you've installed to Guide. Unless you've a lot of customization to your guide, there'll probably only be one or two templates.
For the template you'd like to modify, move your mouse over the template name, on the bottom part of the thumbnail. A button that looks like a gear will appear, click it and select Duplicate on the menu. Another copy of the template will appear.
Click on the check icon to make it available for use. Now, if you need to rollback your changes, all you need to do is click on the gear icon for this copy and select "Set as live theme".
Step 3 - Open the Template Editor Interface
Next, click on preview part of the template thumbnail in you'd like to modify. This will take you to the Template Editor. Once there, click on the button near the top with the three dots and select "Edit Code" on the menu.
Step 4 - Add the Custom JavaScript to Guide
4.1 Add jQuery
If your site already uses jQuery, you can skip the following.
In the left column with the files, look for "document_head.hbs" and click on it. Add the following code near the bottom and click Publish:
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script>
Note: This will add jQuery to all pages in Guide. If you'd like to limit it to only the page where we're using it, add it to "request_page.hbs" instead.
4.2 Add JavaScript to Format Progress Field
Scroll down until you see "script.js". Click on it to open it in the editor. This file may or may not be empty. If it isn't empty, add the following code after everything else and click Publish.
Note: Again, this will add the code to all Guide pages. If you'd like to limit it to only the page it's needed, add it to "request_page.hbs" instead wrap it in a script tag. i.e., "<script type="text/javascript">... code below ...</script>".
// Converts plain text progress field to HTML $(document).ready(function(){if(($("h1 span.request-id").length||$("#request_comment_body").length)&&$("dl.request-details").length){var t=".tickler-text-output ul { margin-left: 0 }";t+=".tickler-text-output ul li { list-style: none; overflow: auto; positon: relative; } ",t+=".tickler-text-output ul li span { display: block; height: 100%; } ",t+=".tickler-text-output ul li span.item-status { position: absolute; } ",t+=".tickler-text-output ul li span.item-status span.inner-status { width: 12px; text-align: center; display: inline-block; } ",t+=".tickler-text-output ul li span.item-text { margin-left: 27px; } ",t+=".tickler-text-output ul li.status-pending span.item-text { font-style: italic; } ",t+=".tickler-text-output ul li.status-skipped span.item-text { font-style: italic; text-decoration: line-through; opacity: 0.7; } ",t+=".tickler-text-output ul li.status-done span.item-text { text-decoration: line-through; } ",t="<style>"+t+"</style>",$("dl.request-details dd span").each(function(e){var n=$(this).text().trim(),i=[{symbol:" ",slug:"not-started",label:"Not Started"},{symbol:"…",slug:"pending",label:"Pending"},{symbol:"✗",slug:"skipped",label:"Skipped"},{symbol:"✓",slug:"done",label:"Done"}],l=!1;if(""!==n&&"—"!==n&&(i.forEach(function(t){l||0!=n.indexOf("[ "+t.symbol+" ]")||(l=!0)}),l)){var s=n.split("\n");s=s.filter(function(t){return""==t.trim()?!1:!0}),s=s.map(function(t){if(0==t.indexOf("Legend:"))return t;var e="",n="",l="";return i.forEach(function(i){""!==i&&0==t.indexOf("[ "+i.symbol+" ]")&&(e=i.symbol,n=i.slug)}),l=t.replace("[ "+e+" ]","").trim(),l="<span class='item-text'>"+l+"</span>",l="<span class='item-status'>[<span class='inner-status'>"+(""==e.trim()?" ":e)+"</span>]</span>"+l,l="<li class='status-"+n+"'>"+l+"</li>"});var a=s.pop();a=a.replace("Legend:","Legend:<br> "),a=a.replace("[ ]","[ ]"),a=a.replace("Pending,","Pending,<br> "),s=s.join("\n"),$(this).parent().addClass("tickler-text-output"),$(this).html("<ul>"+s+"</ul><p>"+a+"</p>"+t)}return l?!1:void 0})}$(".zd-comment").each(function(t){$(this).text().indexOf("✗")>-1&&$(this).text().indexOf("✓")>-1&&$(this).find("table").length>0&&($(this).find("table tr td").eq(0).prop("nowrap",!0),$(this).find("table tr td").eq(1).attr("width","100%"))})});
If you'd like to customize the code, you can find an unminified version here:
https://cdn.cloudmetro.com/public/tickler/app.js
Step 5 - Verify the code is working
If all went, the field should look something like the following image. If the text is all jumbled together, follow the troubleshooting steps below.
Troubleshooting
Adding the code broke my site
If added properly, the code shouldn't interfere with your site. Use your backup to revert your changes. Make another backup and start the process again. This time, after each step check your Guide to make sure nothing has broken.
Neither the field nor the heading for the field are being displayed.
Make sure "Visible" is checked for end-users in the custom ticket field settings.
The progress field heading is visible, but there's no checklist
This means there's nothing saved to the field for this ticket. Open the ticket in the agent part of Zendesk, make some changes to your checklist and save the ticket. You should now see text when viewing the ticket from Guide. If the text is jumbled, see below.
The text is jumbled for the progress field
Did you remember to click "Publish" after adding the code? If so, that's a common mistake. Go back to the template editor and re-add the code if necessary.
The text is still jumbled and there's a JavaScript error
Many browsers hide JavaScript errors by default, so you may need to manually open the JavaScript console to check for errors. There are instructions on how to to that for popular browsers here: https://code-maven.com/open-javascript-console Reload the browser page after opening the JavaScript console.
If you see an error in the JavaScript console, what is the message? If it mentions jQuery or '$', it's possible there's a conflict of some kind with jQuery. If you added it in step 4.1, try removing it. If you didn't add it, then try adding it. If the error goes away, congrats! You just found and fixed the problem and there's nothing else you need to do.
I'm still getting a JavaScript error and adding/removing jQuery didn't help
It could caused by the script in step 4.2. To test this, try removing the code and see if the error goes away. If so, try using the un-minified code instead. You can find it here:
https://cdn.cloudmetro.com/public/tickler/app.js
The text is jumbled, but there's no error
If the field is displayed, but the text is all jumbled together, it's likely that the script is having trouble finding the field or there's a problem with the script. See the section below for opening a ticket.
Nothing so far has helped
If you have access to a web developer or someone familiar with JavaScript, consult them first. It's quite easy to make a small mistake that could prevent the code from running properly.If you don't have access to someone like that, feel free to open a support ticket with us.
Submitting a Ticket
If nothing so far has worked, please feel free to open a ticket. In order to help, we'll need the following:
- The results of the troubleshooting steps above. If you haven't gone through them yet, this is the first thing we'll ask you to do.
- We'll need an end-user account with a ticket that displays the progress field. If possible, please also provide a second user account with admin privileges in Guide. This will allow us to diagnose the problem much quicker. Once we've diagnosed the problem, you can remove these users.
Comments