Controllers - Theme Reference - 1.1.0

Liquid Controllers

Liquid Controllers allow themes to define logic that runs either before or after page render.

They enable themes to:

Inject params into the current_request.params object
Inject variables into the liquid context for the current request
Respond to the request with content
Redirect to another page
Update custom data fields

Liquid Controllers use liquid templates that belong to a theme. They live in the controllers directory in the theme. The template path indicates which controller the template is for. For example, a template at pages/home.liquid would be the controller for the home page. See below for the full list of controllers.

Route Controllers

There are two types of controllers: before and after. The before controller runs before the page is rendered, and the after controller runs after the page is rendered. They both are defined in the same template using the before and after tags.

Theme Controller

In addition to controllers which run for a given route, there is also a theme controller which runs around the route controller actions. The theme controller is defined in the controllers/theme.liquid template.

This is the sequence of controller execution:

Theme controller before actions
Route controller before actions
Route controller after actions
Theme controller after actions

Actions

There are five actions that can be performed in a controller, each with corresponing action tags that can only be used within a controller block: params, variables, respond, redirect, and update.

The first four actions are only available in the before controller. The update action is available in both the before and after controllers.

Examples

Injecting Params

Note: params injected in the theme controller are available in the route controller.

Multiple params can be supplied at once:

{% liquid
before
  params fizz: "buzz", foo: "boo"
endbefore
%}

And they can be supplied in multiple sets:

{% liquid
before
  params foo: "bar", fizz: "buzz"
  params bing: "bang"
endbefore
%}

Params can be injected from deserialized JSON strings:

{% liquid
before
  assign hash = '{"fizz": "buzz", "foo": "boo", "items": [{"name": "item1"}, {"name": "item2"}]}' | deserialize
  params thing: hash
endbefore
%}

Injecting Variables

Note: variables injected in the theme controller are available in the route controller.

Multiple variables can be supplied at once:

{% liquid
before
  variables fizz: "buzz", foo: "boo"
endbefore
%}

Or they can be supplied one at a time:

{% liquid
before
  variables my_string: "Hello"
  variables my_number: 42
  variables my_boolean: true
endbefore
%}

Responding

Note: responding ends the request and no further before actions will be executed, nor will the underlying Rails controller.

If a controller responds, its after controller runs, but the next controller in the queue doesn’t. Eg if the theme controller responds, its after controller will run, but the page controller will not.

Responses can supply alert or notice messages:

{% liquid
before
  respond body: "some content", alert: "alert", notice: "notice"
endbefore
%}

The response can be rendered without a layout:

{% liquid
before
  respond body: "some content", layout: false
endbefore
%}

Redirecting

Note: redirecting ends the request and no further before actions will be executed, nor will the underlying Rails controller.

If a controller redirects, its after controller runs, but the next controller in the queue doesn’t. Eg if the theme controller redirects, its after controller will run, but the page controller will not.

Redirects can supply alert or notice messages:

{% liquid
before
  redirect to: "/products", alert: "some alert", notice: "some notice"
endbefore
%}

Updating Custom Data Fields

Note: only pre-defined custom data fields can be updated. This will not create new fields.

{% liquid
before
  update current_customer, field: "identity__c", value: "12345"

  # update and use the updated value
  update current_customer, field: "sample__c", value: "the sample value"
  variables sample: current_customer.data.sample__c
endbefore

after
  update current_customer, field: "identity__c", value: "12345"
endafter
%}

List of Controllers

Visit the Liquid Controller documentation to see a list of all liquid controllers.

Next up: Localisation with Theme Locales.

Back to Overview

Back to Documentation