shopify-collection-filter v1.0.2

✨ Grafikr® Collection Filter™

Fast & highly customizable storefront-based collection filter adapted to DEUS setups. To get a quick overview, the provided example files can be immediately imported to a project and should be functional plug & play 🤓
⚠️ When building functionality on top of the filter, never alter the main package file index.js, but instead use the event hooks provided. If you encounter bugs, or if you need additional features, that are not currently possible simply by hooking into the filter's event hooks, feel free to open an issue.

📂 Example files

💾 Data template

Before using the filter, a data template collection.data.liquid must be created. This template serves as the data endpoint for the filter. The template must use {% layout none %}, it has to be formatted in JSON and have the same structure as regular Shopify product.json endpoints, and it should paginate over the collection's products by 1000. Also there are certain data that must be included for the filter to work. The minimal data to allow for the use of all filter types is as follows:

{% layout none %}
{%- assign c = collection -%}

{%- paginate c.products by 1000 -%}
[
  {%- for p in c.products -%}
    {
      "product_type": {{ p.type | json }},
      "vendor": {{ p.vendor | json }},
      "options": [
        {%- for o in p.options_with_values -%}
          {
            "name": {{ o.name | json }},
            "values": [
              {%- for v in o.values -%}
                {{ v | json }}{% unless forloop.last %},{% endunless %}
              {%- endfor -%}
            ]
          }{% unless forloop.last %},{% endunless %}
        {%- endfor -%}
      ],
      "price": {{ p.price | json }},
      "tags": [
        {%- for t in p.tags -%}
          {{ t | json }}{% unless forloop.last %},{% endunless %}
        {%- endfor -%}
      ],
      "created_at": {{ p.created_at | json }}
    }{% unless forloop.last %},{% endunless %}
  {%- endfor -%}
]
{%- endpaginate -%}

Datasets not needed for the specific filter being built may be omitted. E.g. if the filter will not need to include product type, the product_type entry may be left out from the template and so on. Cutting down to only the necessary data may benefit the loading speed on very large collections. Aside from the required data, any additional product data may be included, and all the data will be available on the product object passed to the product render function.

🛠 Usage

The filter is created by importing the function from shopify-collection-filter and saving its return value to a variable (if you call the function without saving its return value to a variable, you will not be able to hook into the filter events afterwards), passing a config object argument. Refer to the collection.js example file to examine the actual values of each key in this example:

import CollectionFilter from 'shopify-collection-filter';

const collectionFilter = CollectionFilter({
  collection: {
    handle,
    productCount,
  },
  defaultSort,
  pagination: {
    element: moreBtn,
    pageSize,
  },
  render: {
    func: renderProduct,
    output,
  },
  filters: [
    ...filters
  ],
});

⚙️ Required config settings

⚙️ Optional config settings

🕹 Filter objects

⚙️ Required settings (all)

The following key-value pairs are required for all filter types: Key | Value | Description ---|---|--- type | string | The type of filter to be created. The allowed values are: 'sort', 'type', 'vendor', 'option', 'tag', 'tagPrefix', and 'price'. name | string | The unique name of the filter. This is used in the generated URL params, as well as internally by the filter. The value can be any string, but two filters cannot have the same name. groupEl | HTML element | The HTML element that the filter should render its individual filter items to ⚠️ This can also be an array of HTML elements ⚠️⚠️ renderFunc | function | The function to render the filter's individual filter items. The function must return an HTML string, and some element in the returned HTML must have the attributes class="${className}" and data-value="${value}". A minimal render function could look like this: const renderFunc = (val, className) => `<p class="${className}" data-value="${val}">${val}</p>`;. This can also be an array of functions ⚠️⚠️ removeFunc | function | The function used to remove the filter from the markup in case no values are found in the current collection. The remove function is passed a filter group HTML element as its sole argument. A remove function could look like: const removeFunc = (groupEl) => groupEl.remove();. This can also be an array of functions ⚠️⚠️

⚠️ NOTE: Specifically if a <select> element is used as a filter's groupEl, that filter will be listening for changes on the groupElement itself instead of on its items (as its items should be <option> elements inside the <select>). The renderFunc for a filter using a <select> as its groupEl should therefore always return an <option> element!

⚠️⚠️ NOTE: When passing an array of HTML elements for groupEl, arrays of equal length must be passed to renderFunc and removeFunc as well. For each group element in groupEl the render and remove functions of corresponding indices will be used.

⚙️ Required settings (type-specific)

⚙️ Optional settings

🪝 Event hooks

A number of events are fired by the filter during the different stages of the filter. These can be hooked into by setting collectionFilter.on(...) event listeners (where collectionFilter should be replaced with whichever variable name you have saved the return value of the collection filter function to). On these events the callback function will always be passed the filter object in its current state as its sole argument. It can be used like this: collectionFilter.on('fetchProducts', (filter) => console.log(filter));. For advanced functionality, the events can also be manually triggered by running collectionFilter.emit('eventName'), where eventName should be replaced with one of the actual event names. This should however be done with caution, as it might trigger unexpected behaviour. Below is a list of all the events: