/
Editing a template

Editing a template

Introduction

All UltraCart storefront themes are now Visual Builder enabled. This means the majority of content edits should be performed within the UltraCart Visual Builder interface rather than directly within template files.

Editing templates is primarily reserved for developers who need to declare attributes, define or adjust Velocity Template Language (VTL) directives, or comment in/out portions of the template. Direct edits should be done cautiously, as they may introduce conflicts during theme upgrades.

Warning: Modifying theme templates can cause conflicts when upgrading your storefront theme to newer versions. Only make direct edits when necessary, and document your changes for future reference.

Prerequisites

  • Access to the UltraCart back office.

  • A storefront using any current Visual Builder theme.

  • Familiarity with Velocity Template Language (VTL).

The StoreFront theme is wide open for you to edit.  Before you do, please consider the following warning:  By modifying theme files, you risk conflicts when upgrading your theme to subsequent versions.   This warning doesn't mean you should never modify your templates!  It just means you should be sure you have a good reason to do so.  You may need some help handling merge conflicts when you perform your next theme upgrade.

If you feel your edits might be beneficial to others, contact the theme developers and ask them to make the change in the official theme. Not only will it help others, it will give you the feature you need without the hassle of upgrade conflicts in the future. At the very least, talking through the change with the theme developers might provide advice on the best way to go about your change if it's a substantial one.

Steps

  1. Where are the templates located

    image-20250924-191636.png

  2. Select a template to edit. You can edit the templates by directly navigating to the templates:

    image-20250924-192000.png

    1. Editing via the Visual Builder
      Editing via the Visual Builder
      You can initiate template editing through the "Developers" toolbar while viewing a storefront page, provided you are logged into the UltraCart back-end. This sets a cookie in your browser, indicating that you are a merchant, not a regular customer. This method helps you understand which template(s) affect a specific page view in your storefront.

  3. View of the template opened in the template editor:

  4. Editing a template:

  5. Save the template

  6. View the change:

Troubleshooting Velocity Coding Errors

When editing the velocity snippets within the templates, you may inadvertently create a error.
If a error occurs in the rendering of the velocity of your template, you'll see a visual indicator of this in
the "Developer Tools" tab when viewing the page. 

  1. Example of Developer Alert when viewing a storefront page:

     

  2. To investigate the velocity error, mouse-over "Developers Tools" in the admin toolbar, 
    then click on "Server Logs" which is also highlighted in red to indicate an error requiring 
    your attention/correction:

     
     

  3. Clicking on the Server Log button will display a dialog window that explicitly references the lines in the template that contain the error:

     

    Here we see that the server logs displays which template and also the specific portion of the source (providing both line and column numbers where the error exists. 
     

  4. Click directly on the portion of the highlighted error that is highlighted with blue background, which will take us to line 48, column 5 of source code:

     
     

  5. Here we are taken to the template editor and the line containing the error is highlighted in pink:

     

  6. Removing the  problematic velocity code and saving the changes eliminates the issue.