New to Liquid? You may want to check out our Crash Course on Liquid article before learning about the Liquid Editor.
If you’re using Liquid or HTML in your Apps, your tool belt should include our Liquid Editor. The editor functions as a testing ground where you can use your App’s transaction and user data as test cases to:
- Validate Liquid Scripts: If you’re writing Liquid for a UI Action or Condition, for example, you can preview the output of your script in the Liquid Editor to ensure that it returns the data you expect.
- Validate HTML Formatting: When writing HTML for some element of your App, such as an email notification or transaction widget, you can format and preview what it will look like in the editor.
While the Liquid Editor has a few gotchas that you’ll need to be aware of, it’s ultimately an excellent tool for taking the guesswork out of your App configuration.
In this tutorial, we’ll first cover using the Liquid Editor with a few examples. Then, we’ll explain how to open the editor and get started.
Using the Liquid Editor
Let’s take a quick tour of the Liquid Editor, which contains three panes:
- Editing Pane: This is where you’ll do your editing. It contains a couple of different modes, which we’ll go into detail on below.
- Preview Pane: This is where you can see the output of your work. For Liquid, the result/output of your Liquid expression will appear here. Similarly, this where your HTML will be rendered and displayed.
- Data Source Pane: In this pane, you can select the data that you want to test against. For example, if you want to test that {{customer_name}} will output a value correctly, you can select various transactions in the Data Source Pane. The specific customer name that will appear in the Preview Pane will depend on which transaction you have selected in the Data Source Pane.
Using WYSIWYG Mode vs. Source Code Mode
You can use the Editing Pane in two different modes: WYSIWYG or Source Code.
-
WYSIWYG: WYSIWYG stands for “What You See Is What You Get.” This mode allows you to use the HTML toolbar at top to format text. It makes creating HTML code easier as you can manipulate the formatting of content without needing to know or write HTML. By default, the Liquid Editor opens in WYSIWYG mode.
In the example below, we’ve used the WYSIWYG mode to format some text in bold and add a hyperlink:
- Source Code: In this mode you can either write HTML code (including CSS) or Liquid, or a mix of the two.
We strongly recommend using the Source Code mode whenever you’re writing or validating a Liquid script. This will prevent your Liquid code from inadvertently being converted into HTML with special characters (e.g., % becoming %), which can break your Liquid. (Even pasting Liquid into the editor's WYSIWYG mode can break your scripts.)
After editing any of the content in your Editing Pane, you’ll need to select the Update Preview button to update the output in the Preview Pane.
Using the Data Source Selector
If you’re validating Liquid, you’ll need a transaction or user to apply that Liquid to so that you can preview an example of its output.
In the Data Source Selector, choose which transaction (or user data set) that your Liquid should be previewed against.
In the example below, we’re using the Editing Pane to request the {{name}} of a Record be outputted. From the Data Source Selector, we’ve selected one of our app’s preexisting transactions, whose name field value is Contract 204.
You can also toggle between transaction data and user data sets by selecting Switch Data Source.
User data includes domain-level information about a given user (e.g., a user’s email, his/her unique ID, the last date he/she signed in, etc.).
Warning: Toggling between data sources will refresh the Liquid Editor, causing any unsaved content to be discarded.
Accessing a List of Variables
Select Variables (in the Preview Pane) to see a list of variables that you can reference within a Liquid script.
An arrow icon to the left of a variable indicates that it is a hash or array. Select the arrow icon to expand the variable’s associated properties.
Need help using hashes or arrays? See the Hashes/Arrays section in our Crash Course on Liquid tutorial.
Opening the Liquid Editor
Now that you understand how to use the Liquid Editor, let’s discuss how it can be opened. There are two ways:
-
While configuring a specific element in the Advanced Designer: Properties of elements that accept Liquid, (e.g., Actions, Conditions, UI Actions, etc.), will have an Editor button in their top-right corner. Clicking this button will open a Liquid Editor that is specific to that element. Changes made here will be inserted back into the element and used when the element runs.
For example, if we wanted to edit the Body of a Send Notification Action, we could open its associated Liquid Editor by selecting the property's Editor button, as pictured below:
Once the Liquid Editor opens, we can build and test out our Liquid (against the app’s existing transactions). When we’re ready to save our changes, we can click OK.
Any changes that you’ve made in the editor won’t stick unless you select OK when you’re finished.
- Via the sidebar on an App’s main Advanced Designer page. As opposed to opening the editor to create Liquid/HTML for a specific element (e.g., an Action or Condition), you can instead just open the editor in “playground” mode. To do so, browse to your app’s Advanced Designer, scroll to the bottom of the panel on the left, and select Liquid Editor.
This has the same look and feel as the editor shown above, but there’s no way to save your changes. If you end up building Liquid or HTML in this mode that you want to use in your app, you’ll need copy and paste the text into the appropriate location.
And that’s it! You’re now fully equipped to use the Liquid Editor. Give it a shot!
On a related note, have you checked out our Liquid Examples article? You may have fun testing some of those scripts out in the Liquid Editor against your Apps' transactions.