Use Liquid Tags to Dynamically Fill Form Fields

ProcessKit supports the use of Liquid syntax in almost all content areas and form fields.  Liquid tags enable you to dynamically pass data from one field into another.  This article covers everything you need to know about using liquid tags in ProcessKit.

In this article:

• What is Liquid?
• How to construct Liquid objects?
• Where can you write liquid in ProcessKit?
• Liquid tags for displaying project data
  • Displaying the values of custom project fields using Liquid
• Liquid tags for displaying client data
  • Displaying the values of client attribute fields using Liquid
• Liquid tags for displaying step & task data
  • Displaying the values of fields within tasks (i.e. task blocks)
  • How to find the ID of a step or a task to use in Liquid
  • Example of working with steps & tasks & Liquid
• Constructing ProcessKit URLs using Liquid
• Advanced uses of Liquid
  • If something equals a specific value
  • If this, else that...
  • If a field is empty (or if a client is not set)
  • Formatting date outputs

What is Liquid?

Liquid is an open-source templating language developed by Shopify and used by many software tools, including ProcessKit.  For the official documentation on all of Liquid's features, click here.  The rest of this article will cover how ProcessKit makes use of Liquid template tags to enable you to dynamically store and display data throughout ProcessKit.

How to construct Liquid objects?

A basic liquid objects looks like this: {{ project.title }}

A liquid object must always begin with {{ and it must be closed with }}.  If you do not properly close a liquid object, ProcessKit will not save it.  Or, if a Liquid tag has been properly formatted, but the object doesn't exist or isn't valid, ProcessKit will display nothing.

See below for the list of Liquid objects available for you to use in ProcessKit.

Where can you write Liquid in ProcessKit?

You can place liquid objects and syntax in any of these places in ProcessKit:

• In processes:
  • In the process description
  • In step descriptions
  • In all step block fields as the pre-fill value.
• In task lists inside projects
  • In the task list description
  • In task descriptions
  • In all task block fields
  • In comments on tasks
• In projects
  • In the project notes field
  • In custom fields used in projects, including in the default value saved on custom fields
  • In comments in a project's activity
• In client attribute fields

Notes:  

• Liquid objects don't immediately refresh when data changes.  You will need to click "refresh" on your web browser to see the latest data, if it just changed during your current session.
• Liquid syntax will not work inside any titles, such as project titles, process titles, task list titles, step and task titles, and client names.
• When using Liquid inside client attribute attribute, you can only use liquid tags that display the current client's other attributes.  For example, you wouldn't be able to display, {{ project.title }} inside a client attribute field, because a client can be associated with many projects, not just one.
• When using Liquid to display the contents of a rich text field, for example {{ project.notes }}, the rich formatting (bold, italic, etc.) and any images and embedded videos will work only if the liquid tag is placed inside another rich text field.  If it is placed in a non-rich text field then the HTML will be stripped from the content.
• Liquid tags can be used inside option labels for select, radio buttons, and checkboxes.  However, they are limited to a maximum output of 50 characters.

Liquid objects for displaying project data

You can reference the current project's data using any of these liquid objects:

{{ project.title }}  --  Displays the project's title

{{ project.start }}  --  Displays the project's start date and time, shown in the current user's time zone.

{{ project.end }}  --  Displays the project's end date and time, shown in the current user's time zone.

{{ project.notes }}  --  Displays the full contents of project notes field.

{{ project.id }}  --  Displays the full contents of project notes field.

{{ client.name }}  --  Displays the name of the client that is associated with the current project.

{{ client.email }}  --  Displays the email address attribute for the client that is associated with the current project.

{{ client.id }}  --  Displays the ID of the client that is associated with the current project.

Displaying the values of custom project fields using Liquid 

• When displaying a custom field, such as a project field, spaces must be replaced with underscores.  These are case in-sensitive.  For example, a project field labeled "Favorite Color" would be displayed in a liquid object like this:  {{ project.favorite_color }}

Liquid objects for displaying client data

{{ client.name }}  -- Displays the name of the client.  When placed anywhere in a project, it will display the name of the client associated with this project, if any.

Displaying the values of client attribute fields using Liquid 

• When displaying a client attribute field, spaces must be replaced with underscores.  These are case in-sensitive.  For example, a client attribute field labeled "Company Name" would be displayed in a liquid object like this:  {{ client.company_name }}

Liquid objects for displaying process step & task data

Remember, that in ProcessKit, your processes are templates that are copied to task lists in your projects (this can happen manually or automatically).  Keep that in mind as you learn how to reference tasks (and their data), when those tasks were created as copies from steps in your process template.

When you're building your processes and the steps within your process, you can reference any step and its data using this structure:  {{ step.id.attribute }}.  For example, {{ step.123.title }}.  When the process is copied into a task list on a project, these liquid tags are automatically converted to reference the corresponding tasks, like this:  {{ task.789.title }}  (technical sidenote:  the task ID is not the same as the step ID).

These liquid blocks are available for displaying basic task data.  Note:  the "step" version is what would be used to reference a step in a process template.  The "task" version is what is used to reference a specific task within a specific project.  These are interchangeable and the "step" version gets automatically converted into the "task" version.  See the example below for more clarity on this.

{{ step.id.title }} & {{ task.id.title }}  --  Displays the title of the task

{{ step.id.start }} & {{ task.id.start }}  --  Displays the start date and time of the task, shown in the current user's time zone.

{{ step.id.start }} & {{ task.id.start }}  --  Displays the start date and time of the task, shown in the current user's time zone.

{{ task.id }}  --  This liquid tag only works when used inside a specific task's blocks.  This displays the ID of the current task.

Displaying the values of fields within tasks (i.e. task blocks)

The blocks that you build into the steps in your process (i.e. the custom fields you might place within your steps) can be individually referenced using liquid blocks as well.  These would follow this structure:  {{ step.id.field_label }}.  For example, if you have a text input on a task with a label of "Document URL", you can reference this field using a liquid block that looks something like this (the id, "123" would be different):  {{ step.123.document_url }}

How to find the ID of a step or a task to use in Liquid

When you're adding a new block to a step or task, or when you're editing the settings of a block, at the bottom of the settings panel is a field labeled "Reference this field". which gives you the liquid block for you to easily copy and use to display this field's value somewhere else.  It has the ID and label constructed for you.  Simply click the "copy" button to copy it to your clipboard.

Just want to reference a task's title or its dates?  Again, you'll need the step or task ID to construct these, like this:  {{ step.123.title }}, {{ step.123.start }}, {{ step.123.due }}.  To find that ID. simply hover over the description block (or any other block) on this step to view that block's settings.  In that block's "reference this field" space, it will display the current step or task's ID. 

Example of working with steps & tasks & Liquid:

Let's say you're using ProcessKit to manage your hiring process.  You want to have a step in your process where your team member inputs the applicant's city.  You want this city to be shown both in a future step in the process and in a field in the project's details.  Rather than having your team member enter the city in multiple places, you can have them input it once, and use Liquid to automatically display that input in all the other places.  Here's how you'd set this up:

First, build your process & a board to run this process:

1. Create a process called "Applicant evaluation"
2. Create a step called "Gather the applicant's information"
3. Within this step, add a block, a text input field, and label it "City".
   1. While you're at it, click "copy" on the "reference this field" box.  You will use this liquid block in a moment.  Let's assume that now you have {{ step.426.city }} copied to your clipboard.
4. Let's say you have another step in your process, called "Research the applicant's city".  Within this step, you might have a description where you want to inform your team member how to Google for information in the applicant's city.  In this step's description, you'd write these instructions:  
   
   Google for local tech hubs in {{ step.426.city }}.
5. After you've finished building your process template, let's create a board to run this process.  In the process settings, click "Create a Board" called "Applicants".  That's a shortcut to automatically create a new board, and automatically set this process as a preloaded process on that board.

Then you will want to create a custom field to display the applicant's city in the project details.  Here's how:

1. Go to "Boards" > "Fields" and add a new field called "City".
2. For the "pre-fill value", paste again, {{ step.426.city }}
3. Go to your "Applicants" board > "Fields" and add your "City" field to the list of pre-loaded fields on this board.  This will ensure that it always gets loaded every time you create an "Applicant" project in this board.

Now let's go ahead and create our first "Applicant" in your "Applicants" board:

1. In your "Applicants" board, create a new "Applicant" (name this Applicant whatever you want)
2. In the task, "Gather the applicant's information", you can fill in this applicant's city.  You write in: Albuquerque
3. Navigate over to the "Details" tab on this project.  As you can see, the "City" field here is automatically populated with "Albuquerque".  Nice!
4. Navigate back to the "Tasks" tab on this project.  Move onto the task, "Research the applicant's city".  Notice that the description displays:
   
   Google for local tech hubs in Albuquerque.

More info on what happened here: 
If you edit the block settings on these tasks in this project, you'll notice that they no longer show the liquid block as  {{ step.426.city }}, but rather {{ task.227.city }} (the id would be different).  This is because it was converted from a step template into a task, which also converted the liquid block to reference the specific corresponding task in this project.

Constructing ProcessKit URLs using Liquid Tags

There might be some cases where you want to output the URL of the current project, a client's profile, or even a URL that points to a specific task within a project.  Outputting URLs could be helpful when viewing things inside of ProcessKit, or when sending data out to other tools using our Zapier integration.

Construct the URL that points to the current project:

https://app.processkit.com/{{ account.id }}/projects/{{ project.id }}

Construct the URL that points to a specific task within a project
Note:  This will only work when it resides within a task block on this specific task:

https://app.processkit.com/{{ account.id }}/projects/{{ project.id }}/#task_{{ task.id }}

Construct the URL that points to a client's profile

https://app.processkit.com/{{ account.id }}/clients/{{ client.id }}

Advanced uses of Liquid

Liquid comes with lots of powerful logic built in.  You can browse all of Liquid's capabilities in its official documentation here.

One feature you may find useful will be conditional "if/else" logic, as documented here.  Here are some examples:

If something equals a specific value...

Let's say you want to show some information only if the current project is for a specific client by a specific name.  You can write it this way:

If this, else that...