Chapter 9. Liquids: Developer Portal

This section contains information about Liquid formatting tags and how they work in the 3scale system, including the different elements of the markup, the connections between them, and short examples of how to use them in your Developer Portal.

To learn the basics about Liquids, see the Liquid reference.

9.1. Using Liquids in the Developer Portal

This section explains how to enable liquid markup processing in layouts and pages.

9.1.1. Enabling Liquids

Liquid markup processing is enabled by default for all partials and email templates. Enabling them on layouts is done by ticking the checkbox right under the system_name input field. However, to enable them on pages, you will have to go to the advanced options section of the page.

developer portal configuration liquids enable

Just expand the Advanced options section and mark the Liquid enabled checkbox. From now on, all the liquid markup will be processed by the internal engine, and the Developer Portal built-in editor will also add code highlighting for liquid.

9.1.2. Different use on pages, partials, and layouts

The use of liquids usually differs slightly between pages, partials and layouts. Within pages, liquids are single-use elements; while liquids with partials and layouts are the reusable elements of the Developer Portal. This means that instead of applying multiple layouts or partials with small changes to different pages, you can add some logic liquid tags, and alter the layout depending on the page the user is on.

<!-- if we are inside '/documentation' URL -->
<li class="{% if request.request_uri contains "/documentation" %}active{% endif %}"><!-- add the active class to the menu item -->
  <a href="/documentation">Documentation</a>
</li>

9.1.3. Use with CSS/JS

Liquid markup does not just work with HTML, you can easily combine it with CSS and/or JavaScript code for even more control. To enable liquid in a stylesheet or JS, create them as a page and follow the same steps as if you were enabling it for a normal page. Having done that, you’ll be able to add some conditional markup in CSS or use the server-side data in JavaScript. Just remember to set the content type of the page as CSS or JS.

9.2. Usage of liquids in email templates

This section explains how you can use liquid tags to customize email templates.

9.2.1. Differences from Developer Portal

As previously mentioned, liquid tags can also be used to customize the email templates sent to your users. All the general rules for writing liquid mentioned before also apply to the email templates, with some exceptions:

  • There is no commonly shared list of variables that are available on every template. Instead, you will have to do some testing using the previously mentioned {% debug:help %} tag.
  • Since emails are by nature different from web pages, you will have limited or no access to some tags. For example, {{ request.request_uri }} will not make sense, as an email does not have a URL.

9.3. Troubleshooting

This troubleshooting section will help you debug and fix typical errors that might occur.

9.3.1. Debugging

If something is not working as intended, but is saved correctly, check the following:

  • All the tags are closed correctly
  • You are referring to variables available on the current page
  • You are not trying to access an array – for example current_account.applications is an array of applications
  • The logic is correct

9.3.2. Typical errors and ways to solve them

  • If the document cannot be saved due to a liquid error, it is usually because some tags or drops were not closed correctly. Check that all your {% %} and {{ }} tags were properly closed and that the logic expressions, for example, if, for and so on, are terminated correctly with endif, enfor. Normally if this is the case, an error will be displayed at the top of the page above the editor with a descriptive error message.
  • If everything saved correctly and you do not see any effect, check that you are not referring to an empty element and you are not using a logic tag to display content. {% %} will never render any content, besides usage in tags which is already an alias of a more complex set of tags and drops.
  • If only a # symbol is displayed, it means that you have tried to display an element that is an array. Check the section on the liquid hierarchy.

9.3.3. Contacting support

If you still have a problem, you can open a new case via the Red Hat Customer Portal.