Using the Build Command

As the next step, we want to use a build command in the app/lib/commands/contacts/create/build.liquid file.

The build command is an essential part of the data processing workflow. It allows you to normalize and prepare data before it is stored or used further in your application. By defining a build command, you can manipulate incoming data, perform validations, and ensure the data meets your application's requirements. This is especially useful for tasks like cleaning up user input, setting default values, and enforcing data consistency.

Build commands are defined in Liquid templates and typically involve transforming and returning JSON objects. This process ensures that your data is well-structured and ready for subsequent operations or storage.

Set up a Build Command

To set up a build command, you don’t need to write the code from scratch. Let’s use the dummy build command from the core module documentation.

Here's the dummy build command from the core module documentation:

{% liquid
  assign title = object.title | downcase
  assign data = { "title": title, "uuid": object.uuid, "c__score": 0 }

  if data['uuid'] == blank
    assign data["uuid"] = '' | uuid | json
  endif

  return data
%}

Copy this code into your app/lib/commands/contacts/create/build.liquid file.

Customize the Build Command

Now, we will modify the build command to suit our needs. In the build phase, you normalize the parameters, ensuring you only take what's relevant and perform any necessary transformations. The goal is to clean up and prepare the contact data (email and body) before further processing.

For example, you want to ensure that the email is always in lowercase:

app/lib/commands/contacts/create/build.liquid

{% liquid
  assign email = object.email | downcase
  assign contact = { "email": email, "body": object.body }

  return contact
%}

We create a contact object using the assign tag with a hash literal. The email is pre-processed to lowercase before being included in the hash.

Every function needs to return an object. In this case, the function takes user parameters, processes them (downcasing the email), and returns an object with the email and body properties.

Invoking the function

To process the contact data using the build command, we need to invoke the function inside the /app/lib/commands/contacts/create.liquid file:

Here's the code snippet for invoking the function:

app/lib/commands/contacts/create.liquid

{% function contact = 'commands/contacts/create/build', object: object %}

This line of code will call the build command, passing the object containing the email and body parameters to it. The build command will then process these parameters and return a normalized contact object.

We used the function tag to specify the path to the build command partial. Remember, you can use LSP to autocomplete paths, so you don’t need to type them manually. In our example, the path leads to the app/lib/commands/contacts/create/build.liquid file.

You also need to pass the object that you defined earlier in your /app/views/pages/contacts/create.liquid file, which is object.

You might notice that LSP complains that the contact variable is never used. This is true for now, and we will address it in later steps.