How to: Migrate theme to new 4.х storefront version powered by Scriban template engine

The list of known breaking changes for theme syntax and data model:

• The specialized form tag has been removed

{% form 'login' %}{% endform %}`

Replace to:

<form accept-charset="UTF-8" action="{{ '~/account/login' | absolute_url }}" method="post" id="customer_login" name="customer_login"></form>

• The paginate tag has been replaced with pipe function

{% paginate collection.products  by 5 %}{% endpaginate %}

Replace to:

{{ paginator =  collection.products  | paginate 20 }}   {% if paginator.pages > 1 %}    {% include 'pagination-custom' %}

• The special variable blank has a new behavior {{ variable != blank }} before equal to variable == null OR (IEnumerable)variable.Any(). Must be replaced to {{ variable.empty? == false }} for collections. https://github.com/lunet-io/scriban/issues/107

• Include statement doesn't longer support named parameters https://github.com/lunet-io/scriban/issues/106

{% include 'snippet' param1: aaa %}

Replace to:

{% assign param1 = aaa %}{% include 'snippet' %}

• current_tags contains tag should be replaced to current_tags[tag.value].empty? == false

• named arguments don't support for functions are called as pipe and by direct call https://github.com/lunet-io/scriban/blob/master/doc/liquid-support.md#known-issues 'localization_key' | t: param1 : 'a', param2: 'b' Replace to:

'localization_key' | t: 'a', 'b'

• Remove '-' from liquid operator brackets

{%- comment -%}

Replace to:

{% comment %}

• replaced interpolation expression for localization resources from Liqud syntax to string format {0}

en.default.json

...
 "less": "Under {{ less }}"
...

Replace to:

...
  "less": "Under {0}",
...

• else tag can't be used inside for loop block. We have to check object with .empty? before declaring for loop. Example:

{% if collection.products.empty? %}
       <div class="grid-item">
         <p>{{ 'collections.general.no_matches' | t }}</p>
       </div>
     {% else %}
         {% for product in collection.products %}
           {% include 'product-list-item' %}        
         {% endfor %}
     {% endif %}

• forloop object doesn't exist into context of the scriban for loop. We can use sciban special loop variables and custom variables with math functions. Below is a list of matches. liquid -> scriban

  • forloop.first -> for.first
  • forloop.index -> none (for.index | plus: 1)
  • forloop.index0 -> for.index
  • forloop.last -> for.last
  • forloop.length -> for.length or \<collection\>.size
  • forloop.rindex -> none (for.rindex | plus: 1)
  • forloop.rindex0 -> for.rindex

• For static content such us pages and blogs root routing does not work. For example we have to use '/pages/about_us' instead of '~/pages/about-us'. In that case page rendering is ok. To avoid this use absolute_url filter.

{% for link in linklists[settings.footer_legallinks_linklist].links %}
      <li><a href="{{ link.url | absolute_url }}">{{ link.title }}</a></li>
{% endfor %}

• current implementation of liquid "date" filter doesn't support strftime format. Need to use a standard format for the .net framework instead. https://docs.microsoft.com/en-us/dotnet/standard/base-types/custom-date-and-time-format-strings

• The WorkContext property current_page has a completely different meaning than before, instead of current page number it is represents a object of the current static page.

{% if current_page != 1 %}
      {{ 'general.meta.page' | t: current_page }}
{%endif%}

It need to be replaced with

{% if page_mumber != 1 %}
      {{ 'general.meta.page' | t: page_mumber }}
{%endif%}

• Scriban doesn't understand HTML comment as text. To avoid parsing such comments we need to wrap them by liquid comment tag. <!--<p><some_wrong_liqued_expressoin></p>--> - potentially may occur error. For example Wrapped by liquid comment tag is Ok.

<!--
{%comment%}
<p><some_wrong_liqued_expressoin></p>
{%endcomment%}
-->

• Use indexed access for access to concrete element of linklists collection instead of property name notation as before. {% for link in linklists.main-menu %} -> {% for link in linklists['main-menu'].links %}

• Add 'null' check before access to some object property See the following examples.

{%if article.excerpt contains "some string" %} - throws  exception if `article.excerpt` is `null`.

{%if article.excerpt and  article.excerpt contains "some string"" %} - join with AND logical operator is also throw an error

{%if article.excerpt%}
{% article.excerpt contains "some string"" %} - use two nested block OK