Manual mode

Out of the box, Locksmith automatically protects all content between the header and footer, for everything covered by your locks.

Sometimes this can be too aggressive - you might want to allow visitors to preview your products without being able to see pricing, for example. Or, you might want to protect just the checkout button of your cart.

Locksmith comes with an advanced manual mode that allows for this sort of thing. It disables Locksmith's full-page protection, stepping aside so that some custom code in your theme can take responsibility for hiding part of your content.

Two important notes:

  • If a particular piece of content has multiple locks in play (for example, if the customer is viewing a product that is a part of several locked collections), manual lock will only work if all applicable locks have manual mode enabled.
  • Server keys require a special initialization step, when working with manual mode. For more on this, see the Interactions with server keys section, later in this article.

Purpose-specific guides

General guide

Because each theme is a bit different, manual locking does require manual coding. If you install a new theme down the road, these changes will need to be re-applied.

Enabling manual mode

Before proceeding, make sure that your theme is set up for manual locking. Use the next sections of this guide to get the necessary changes in place.

  1. Open Locksmith (available in your store's Apps list), then click on the lock for which you'd like to use manual mode.
  2. Click on "Advanced" in the lock Settings section and tick the checkbox for "Enable manual locking". Then, hit save.

That's it! Locksmith will hold off on its full-page protection with this enabled, and allow your custom code to enforce protection.

Updating your theme for manual locking

Manual locking leverages Liquid variables to empower you to render content however you'd like, based on Locksmith's permissions.

Locksmith's variables are loaded via the locksmith-variables snippet. It can be included two ways, depending on context:

Using {% render %}

This usage supports "exporting" a single variable at a time, by informing the snippet of the object you're interested in (e.g. a specific product), capturing the rendered result, and performing any post-processing of the captured value necessary.

These variables are available:

  • "locked" – Can be "true" or "false", depending on whether or not the resource has any active locks that apply to it.
  • "initialized" – Only relevant when server keys are in play; is "true" or "false", depending on whether or not Locksmith has had an opportunity to initialize the visitor's session; access decisions cannot be made until initialization is complete. If "initialized" is "false", trigger a refresh of the page to allow Locksmith to finish initializing.
  • "scope" – A string describing the type of resource being analyzed. Can be values like "product", "collection", "article", etc.
  • "access_granted" – Can be "true" or "false", depending on whether or not Locksmith has determined that the current visitor may view the content.
  • "access_denied" – Can be "true" or "false"; the opposite of "access_granted".
  • "manual_lock" – Can be "true" or "false", depending on whether or not all applicable locks have manual mode engaged.
  • "server_lock" – Can be "true" or "false", depending on whether or not a server key must be evaluated for Locksmith to complete the visitor's authorization.
  • "hide_resource" – Can be "true" or "false", depending on whether or not the visitor is permitted to see the resource when it occurs in a list (e.g. search results, or product lists shown in a collection).
  • "hide_links_to_resource" – Can be "true" or "false", depending on whether or not the visitor is permitted to see navigation links to the resource, in the store's navigation menus.
  • "lock_ids" – A comma-delimited list of IDs, indicating the set of locks that apply to the given resource.
  • "opened_lock_ids" – A comma-delimited list of IDs, indicating the subset of locks that are currently considered "open" for the current visitor.
  • "key_ids" – A comma-delimited list of IDs, indicating the keys involved in opening the locks listed in "opened_lock_ids".

To access any single value from this list, use this approach:

{% capture var %}{% render 'locksmith-variables', variable: 'access_granted', scope: 'subject', subject: product %}{% endcapture %}
{% if var == 'true' %}
  {% assign locksmith_access_granted = true %}
{% else %}
  {% assign locksmith_access_granted = false %}
{% endif %}

For variants, one additional argument is required for the render tag: subject_parent, defining the product that contains the variant you're checking in on.

{% render 'locksmith-variables', variable: 'access_granted', scope: 'subject', subject_parent: product, subject: variant %}

Feel free to adjust this code to taste. Only the capture and render tags need to be used exactly as written; process the rendered value string in whatever way you need to. Use the support button in the corner if you've got any questions. :)

Using {% include %}

The include tag has been deprecated by Shopify. Locksmith still uses this variable itself, in situations where overriding variables is important. You shouldn't need to use this on a regular basis, but we document it here for completeness.

  1. {% include 'locksmith-variables' %} – In this mode, Locksmith will autodetect the applicable locks for the current url, and set up its access variables accordingly.
  2. {% include 'locksmith-variables', locksmith_scope: foobar %} – In this mode, you specify the exact object that Locksmith should base its access decisions upon. Use this if you need to load up Locksmith's variables based on the cart, or a certain product, or some other Liquid variable, regardless of what url the user is on

For the code following this tag, all of the variables available in the {% render %} usage are now automatically available, their names being prefixed with "locksmith_". For example, you may now use "locksmith_locked", "locksmith_access_granted", and "locksmith_manual_lock". The values differ in that all booleans are real booleans (not strings), and the values in "locksmith_lock_ids", "locksmith_opened_lock_ids", and "locksmith_key_ids" are exported as arrays of strings (in which each string is an ID value), instead of as comma-delimited strings.

After loading the Locksmith variables, wrap the code you'd like to conditionally hide like this:

{% if locksmith_access_granted %}
  You've got access!
{% endif %}

Interactions with server keys

In most usages, server keys don't require any theme configuration. Locksmith will render a loading screen, with a spinner animation; once it's finished initializing, it'll reload the page automatically, and your storefront's normal content will be displayed.

When using manual mode, Locksmith will show your storefront content immediately by design. Manual mode leaves you with the responsibility of updating your theme's code to show or hide content based on Locksmith's decisions. Without server keys, this is a simple boolean: either access is granted, or denied. When combined with server keys, we add a third state: either access is granted, or denied,  or Locksmith hasn't finished initializing and the page should be refreshed.

To explain by example: in cases like price hiding, this means that there are three possibilities for the content you should display: either you should display the price (and add-to-cart form), or you should hide it, or you should display a "please wait" message, coupled with some JavaScript that reloads the page when Locksmith has finished initializing in the background.

To accomplish this, adapt this code for your own purposes:

{% if locksmith_access_granted %}
  <!-- the original add-to-cart button code -->
{% elsif locksmith_initialized %}
  <p>No access for you!</p>
{% else %}
  <p>Please wait&hellip;</p>
    Locksmith.on('initialize', function () { window.location.reload(); });
{% endif %}

The code above assumes that you've already exported the locksmith_access_granted and locksmith_initialized variables. Use one of these options to export those variables, making sure to do so before making any content decisions:

{% capture var %}{% render 'locksmith-variables', variable: 'access_granted', scope: 'subject', subject: product %}{% endcapture %}
{% if var == 'true' %}
  {% assign locksmith_access_granted = true %}
{% else %}
  {% assign locksmith_access_granted = false %}
{% endif %}

{% capture var %}{% render 'locksmith-variables', variable: 'initialized', scope: 'subject', subject: product %}{% endcapture %}
{% if var == 'true' %}
  {% assign locksmith_initialized = true %}
{% else %}
  {% assign locksmith_initialized = false %}
{% endif %}
{% include 'locksmith-variables' %}
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.