URL Encoding Dynamic Values in Handlebars Templates on My Account Pages
Overview
UltraCart's My Account pages, including the customer portal's order history section, combine server-side Velocity templating with client-side Handlebars rendering for dynamic tables like recent orders. Velocity processes first on the server, followed by Handlebars in the browser.
This execution order means Velocity tools (such as $formatHelper.urlEncode) cannot directly encode values used inside Handlebars expressions. Attempting to nest them often fails because Velocity evaluates before Handlebars populates the data.
This tutorial explains the template execution order and shows how to safely URL encode dynamic values (e.g., customer emails from custom fields) in links within Handlebars-rendered sections. It provides a reliable client-side solution using a custom Handlebars helper with JavaScript's encodeURIComponent, along with multiple variations and examples across different My Account pages.
Note: This approach works in contexts where order details, custom fields, or other customer data are available as Handlebars variables (e.g., {{orderId}}, {{customField6}}, {{email}}).
[Image Placeholder: Screenshot of the My Account dashboard with recent order history table and a custom "Renew Now" link]
What You'll Need
Editor access to My Account templates (located in Home ➜ Configuration ➜ Themes & Templates ➜ My Account).
Basic familiarity with Velocity, Handlebars, and JavaScript.
Prerequisite: Ensure any custom fields or data you reference are configured and populated on relevant orders or customer profiles. See the Customer Profile Custom Fields guide for setup.
Steps
Locate the Handlebars template section Open the relevant My Account .vm file. Dynamic tables (e.g., recent orders, full order history) are rendered client-side using Handlebars templates embedded in <script type="text/x-handlebars-template"> blocks.
[Image Placeholder: Screenshot highlighting a Handlebars script block in a My Account template]
Register a custom Handlebars helper for URL encoding Add the following JavaScript in the .vm file (before any Handlebars templates that need it):
JavaScript
<script type="text/javascript"> Handlebars.registerHelper('urlEncode', function(value) { if (value == null) { return ''; } if (typeof value === 'string') { return encodeURIComponent(value.trim()); } return value; // Return unchanged if not a string }); </script>Tip: This robust version handles null/undefined, trims whitespace, and safely processes non-strings.
Use the helper in your Handlebars template Call the helper inside {{ }} for any value that needs encoding.
Save and test Save the template, clear browser cache (or use incognito mode), and log into a test customer account to verify encoding and link behavior.
Expected Outcome
Dynamic values are correctly URL-encoded at browser render time, producing valid query parameters and preventing broken links.
Additional Code Examples
Robust Helper with SafeString
To prevent potential double-escaping:
JavaScript
<script type="text/javascript">
Handlebars.registerHelper('urlEncode', function(value) {
if (value == null) return '';
return new Handlebars.SafeString(encodeURIComponent(value.toString().trim()));
});
</script>Complex Link with Multiple Encoded Parameters
handlebars
<a href="https://secure.ultracart.com/renew?
order={{orderId}}
&email={{urlEncode email}}
&eu_email={{urlEncode customField6}}
&name={{urlEncode customerName}}
&license={{urlEncode customField1}}">
Renew License
</a>Conditional Fallback Encoding
handlebars
<a href="/support?ticket={{orderId}}&contact={{urlEncode (or customField6 email 'no-reply@example.com')}}">
Contact Support
</a>Examples for Other My Account Pages
Client-side Handlebars templating is used on several My Account pages for dynamic lists and tables. The same helper registration and usage pattern applies to all of them.
Add the helper script once per .vm file (typically near the top or just before the first Handlebars template block). Since each page is a separate template, duplicate the script where needed.
Common pages that use Handlebars include:
Full Order History – myaccount_orders.vm
Recurring Orders / Subscriptions – myaccount_autoorders.vm
Digital Items – myaccount_digitalitems.vm
Full Order History (myaccount_orders.vm)
The order history table renders rows via Handlebars. Use the helper for custom action links.
Example: Custom "Reorder" link with encoded email
handlebars
<td>
<a href="/cart?restoreOrder={{orderId}}&customerEmail={{urlEncode email}}">
Reorder
</a>
</td>[Image Placeholder: Screenshot of full order history table with custom "Reorder" link]
Recurring Orders / Subscriptions (myaccount_autoorders.vm)
Subscription rows are rendered with Handlebars. Encode parameters for management or renewal links.
Example: Custom "Manage Subscription" link
handlebars
<td>
<a href="https://secure.ultracart.com/manage-sub?
code={{autoOrderCode}}
&email={{urlEncode email}}
&nextItem={{urlEncode nextItem}}">
Manage Subscription
</a>
</td>[Image Placeholder: Screenshot of recurring orders table with custom management link]
Digital Items (myaccount_digitalitems.vm)
Digital delivery items are listed via Handlebars. Encode any custom parameters for download or access links.
Example: Custom "Access Resource" link with encoded identifiers
handlebars
<td>
<a href="https://secure.ultracart.com/access?
item={{itemId}}
&key={{urlEncode accessKey}}
&customer={{urlEncode email}}">
Access File
</a>
</td>Note: Exact variable names (e.g., autoOrderCode, nextItem, accessKey) depend on the data context provided to Handlebars on each page. Use browser developer tools (inspect the compiled template or console-log the data object) on a live customer account to confirm available variables.
Alternative: Server-Side Encoding (When Possible)
If a value is available during Velocity processing (outside Handlebars blocks):
velocity
#set($encodedEmail = $formatHelper.urlEncode($customer.email)) <a href="https://secure.ultracart.com/example?email=${encodedEmail}">Link</a>
Troubleshooting
Helper not found → Ensure the registration script loads before Handlebars compilation.
Undefined variables → Verify field names match the page's data context exactly (case-sensitive).
Encoding issues with special characters → Test with +, spaces, or international characters.
Auto-escaping → The explicit helper bypasses Handlebars escaping behavior.
If issues persist, contact UltraCart Support with details of the template and page.