Data Variables

This page describes what data variables are and how to use them in the builder.

Overview#

Data variables are synthetic values we can create and use inside a template. We can add as many as we want different data variables. There is no limitation in their quantity.

Adding/editing of data variables#

Data variables modal UI

  1. Type select.
  2. Name of the data variable.
  3. "Test query" button. Use it to quickly understand if Graph QL query works and what it returns.
  4. "Open schema explorer" button
  5. "Apply query" button. Sends request via API and updates data variables with their actual values.
  6. Query editor window.
  7. Query variables editor.
  8. Preview when testing the query.

Types of data variables#

  1. Query to DB (GraphQL)
  2. Static integer value
  3. Static float value
  4. Static string value
  5. Static boolean value
  6. Static JSON value
  7. Expression

Query to DB (GraphQL)#

Use this type of data variables for accessing data in DB. We implemented GraphQL - the modern API that makes it possible to query a different kind of data in a single request. For instance, it is possible to get the current post's title and content, also site name and any number of custom meta with only one request! Although it is not necessary to use only one request, if it helps you, then why not? :)

Graph QL syntax is not hard to learn. There are some examples of queries with an explanation of how they work.

info

All Graph QL queries start from the query root level keyword. Graph QL queries always return data in JSON format.

query {
queried_post{
post_content
}
}

This query gets the post content of the current post (which is applicant data).


query {
post: queried_post{
content: post_content
}
}

This query gets the same data as the previous one but stores it differently. This technique is called "aliasing", which means we explicitly use variable names to shape the resulting data that will look like this:

{
"post": {
"content": "..."
}
}

note

Sometimes "aliasing" is just optional. There are also cases when it is required. For instance, we have to use aliases for fetching data of the same type or same keywords in the query.

Let's review an example of the wrong syntax first:

Graph QL wrong syntax

The problem here is that we use the same type of keywords inside the query but no aliases. So Graph QL cannot create the resulting JSON object as we did not specify any keys.

The fix for that is simple - use aliases:

query{
meta: queried_post{
h1_title: meta_value(key:"h1_title")
h1_subtitle: meta_value(key:"h1_subtitle")
h2_title: meta_value(key:"h2_title")
h2_description: meta_value(key:"h2_description")
h2_form_title: meta_value(key:"h2_form_title")
}
}

This query gets several post meta at once. We used the keyword meta_value that returns post meta value (by key) inside queried_post, which means we fetch meta values for the current post (chosen applicant).

For each post meta value, we use different keys, so the resulting JSON looks like this:

{
"meta": {
"h1_title": "...",
"h1_subtitle": "...",
"h2_title": "...",
"h2_description": "...",
"h2_form_title": "..."
}
}

Using data variables#

When we see this icon DB icon next to the settings label or form field, it means the setting can use data variables as its value. Click on this icon opens the modal window of currently available data variables.

Data variables modal window

  1. An example of data variable name
  2. Hovering over the data reveals the "Copy variable" icon

Click on the "Copy variable" icon to make a copy of the path to the data. Paste this path inside the setting form field with double [[ and ]] or triple [[[ and ]]].

  • [[ and ]] are used by default; data is escaped (which means, for instance, HTML tags will be converted to character entities)
  • [[[ and ]]] are used optionally; data IS NOT escaped!
info

Use double brackets and escape data whenever possible. Using them is a safe way of data output. Use triple brackets and unescaped data when you have to output HTML, like a form or a piece of content with HTML tags inside.

The example of escaped data:

Escaped data variable

The example of unescaped data:

Unescaped data variable

Pro tip!

It is possible to mix data variables with a static text, e.g. to write heading content like this: "[[postMeta.meta.h1_title]] on SuperSite". It is also possible to use data variables without using the data variables modal window. If we know the names of data variables, let's type them directly into the setting field. It makes the process of development so easy and fast! ;)