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
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 simply checking the checkbox right under the system_name input field. However, to enable them on pages, you’ll have to go to the advanced options section of the page.
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, which are single-use elements and partials/layouts, which are the reusable elements of your portal. This means that instead of using multiple layouts or partials with small changes for use on different pages, you can add some logic liquid tags inside 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 doesn’t 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
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’ll 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 anymore, as an email does not have a URL.<!--samples-->
9.3. Troubleshooting
9.3.1. Debugging
If something is not working as intended (but saved correctly) check that:
- All the tags are closed correctly
- You’re referring to variables available on the current page
- You’re 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’s usually because some tags or drops were not closed correctly. Check that all your
{% %}
and{{ }}
tags were properly closed and that the logic expressions (if, for, etc.) are terminated correctly (with endif, enfor, etc.) 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 don’t see any effect, check that you’re not referring to an empty element and you’re 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 instead of what you wanted to see only a # is displayed, it means that you’ve tried to display an element that is an array. Check the section on the liquid hierarchy in this article (link).
9.3.3. Answers on the forum
If you still have a problem, try looking for an answer on our forum or ask a question yourself.