Breaking Changes - System pages

System pages are a set of recommend pages that required less setup to get up and running. You could simply define a template such as the product or category and the page would work without configuration. However, this also meant that you could not customize the page as much as you would like including adding controls and customizing the schema.

We decided to change this behavior and allow the developers to have more control with these types of pages. This change will require you to define your own schemas and properties for these pages as you would with any other page.

Migration path

If your theme uses any of the following pages, you must take action by adding the corresponding site data to your page with the corresponding schemas. We have included the properties and schemas that were previously defined for you in our platform here to help with migration.

These code snippets are only needed if you want to preserve the original behavior, you should adjust them to your specific needs and are no way required to have your definitions look like this.

To preserve the previous behavior, you will need to do the following:

1. Create the respective page file in the site/pages directory.
2. Define the respective schema on the page in the theme/store directory.
3. (Optional) If you were using the provided items, please see the Items migration section for more information.

Shop all page

site/pages/shop.json

{
    "route": "s/shop",
    "template": "templates/store/shop",
    "props": {
        "categories": {
            "filters": []
        },
        "category_hierarchy": {
            "filters": []
        }
    }
}

theme/templates/store/shop.html.twig

{% schema %}
{
    "categories": {
        "type": "category-list"
    },
    "category_hierarchy": {
        "type": "category-hierarchy"
    }
}
{% endschema %}

Note: If you previously relied on the platform generated items you will need to implement your own filtering. For any more advanced use cases, see the Items migration for more information about how we migrated the Brisk theme.

Product detail page

site/pages/item.json

{
    "route": "product/:name*/:id",
    "template": "templates/store/item",
    "props": {
        "item": {
            "filters": {
                "id": "request_data(path.id)",
                "square_online_id": true
            }
        }
    }
}

theme/templates/store/item.html.twig

{% schema %}
{
    "item": {
        "type": "item"
    }
}
{% endschema %}

Category detail page

site/pages/category.json

{
    "route": "shop/:name*/:id",
    "template": "templates/store/category",
    "props": {
        "category": {
            "filters": {
                "id": "request_data(path.id)",
                "square_online_id": true
            }
        },
        "categories": {
            "filters": []
        }
    }
}

theme/templates/store/category.html.twig

{% set items = item_list({ category_id: category.id, square_online_id: true }) %}

{% schema %}
{
    "category": {
        "type": "category"
    },
    "categories": {
        "type": "category-list"
    }
}
{% endschema %}

Note: If you previously relied on the platform generated items you will need to implement your own filtering.

The most simple way to migrate is to use the item_list resource function and pass in the appropriate filters to have it dynamically apply as seen above.

Search page

site/pages/search.json

{
    "route": "s/search",
    "template": "templates/store/search",
    "props": {
        "search_term": "request_data(query.q)"
    }
}

theme/templates/store/search.html.twig

{% set items = item_list({ searchTerm: search_term }) %}

{% schema %}
{
    "search_term": {
        "type": "string"
    }
}
{% endschema %}

Note: If you previously relied on the platform generated items you will need to implement your own filtering.

The most simple way to migrate is to use the item_list resource function and pass in the appropriate filters to have it dynamically apply as seen above.

Order online page

site/pages/order.json

{
    "route": "s/order",
    "template": "templates/store/order",
    "props": {
        "categories": {
            "filters": []
        }
    }
}

site/store/order.html.twig

{% schema %}
{
    "categories": {
        "type": "category-list"
    }
}
{% endschema %}

Customer account page

site/pages/customer.json

{
    "route": "s/customer-accounts",
    "template": "templates/store/customer",
    "props": {}
}

theme/templates/store/customer.html.twig

{% schema %}
{
    "customer": {
        "type": "customer-account"
    }
}
{% endschema %}

Store locations page

site/pages/locations.json

{
    "route": "s/store-locator",
    "template": "templates/store/locations",
    "props": {
        "locations": []
    }
}

theme/templates/store/locations.html.twig

{% schema %}
{
    "locations": {
        "type": "location-list"
    }
}
{% endschema %}

Items migration

Previously the platform would provide some item filtering for you, this is no longer the case. You will need to implement your own filtering within your template file.

For instance, we used to include items in the schema on the shop, category, and search pages but this has been removed. You can achieve similar behavior within your template by using the item_list resource function and passing in the appropriate filters to have it dynamically apply.

The following example is used in Brisk to deal with item filtering via the query string:

{# Item list filtering #}
{# Pluck item filters from query #}
{% set queryFilters = ['price_min', 'price_max', 'location_id', 'has_discounts'] %}
{% for filter in queryFilters %}
    {% if request.query[filter] %}
        {% set items_options = items_options|merge({ (filter): request.query[filter] }) %}
    {% endif %}
{% endfor %}

{# Pluck comma separated item filters from query and convert to array #}
{% set commaQueryFilters = ['fulfillments', 'category_ids', 'item_status', 'option_choices'] %}
{% for filter in commaQueryFilters %}
    {% if request.query[filter] %}
        {% set value = request.query[filter]|split(',') %}
        {% set items_options = items_options|merge({ (filter): value }) %}

        {% if filter == 'category_ids' %}
            {% set items_options = items_options|merge({ square_online_id: true }) %}
        {% endif %}
    {% endif %}
{% endfor %}

{# Item pagination #}
{% if request.query.limit %}
    {% set pageSize = 0 + request.query.limit %} {# Convert string to number #}
    {% set items_options = items_options|merge({ pagination: { page_query_param: 'page', page_size: pageSize } }) %}
{% endif %}

{# Item sorting #}
{% if (request.query.sort_by or request.query.sort_order) %}
    {% set sortConfig = items_options.sort|default({}) %}
    {% if request.query.sort_by %}
        {% set sortConfig = sortConfig|merge({ by: request.query.sort_by }) %}
    {% endif %}
    {% if request.query.sort_order %}
        {% set sortConfig = sortConfig|merge({ order: request.query.sort_order }) %}
    {% endif %}

    {% set items_options = items_options|merge({ sort: sortConfig }) %}
{% endif %}

{% set items = item_list(items_options) %}