Storefront

Learn more about the possibilities of Storefront, how to work with it and how to develop it further.

Filter

As described in the chapter Filter to the Makaira Backend, there is an option to also select the "Appearance" when creating or editing a filter. In order for a filter to be displayed with the selected display type, a corresponding React component must be assigned to it in the storefront.

The storefront has a number of prefabricated filter components for multi-select and range filters. These components can be customized or used as a basis for further development. 

 

Adding a new filter component

Experience shows that filters are displayed differently on mobile devices than on devices where more space is available. To meet this requirement, the storefront offers the possibility to implement separate filter components for the different views.

The "display type" mapping in the Makaira backend described above causes the storefront to get a corresponding type from the Makaira API for each filter, for example list_multiselect or list_multiselect_custom_2.

In the storefront, the corresponding React components are assigned to these types:

// patterns/core/ProductListFilter/DesktopFilter/index.js

const filterComponents = {
  list_multiselect: MultiSelectFilter,
  list_multiselect_custom_1: MultiSelectFilterGrid,
  list_multiselect_custom_2: MultiSelectFilter,
  range_slider: RangeFilter,
  range_slider_custom_1: RangeFilter,
  range_slider_custom_2: RangeFilter,
  range_slider_price: RangeFilter,
}

as well as

// patterns/core/ProductListFilter/MobileFilter/MobileFilterList.js

const filterComponents = {
  list_multiselect: MultiSelectFilter,
  list_multiselect_custom_1: MultiSelectFilter,
  list_multiselect_custom_2: MultiSelectFilter,
  range_slider: RangeFilter,
  range_slider_custom_1: RangeFilter,
  range_slider_custom_2: RangeFilter,
  range_slider_price: RangeFilter,
}

If, for example, a new type of multi-select filter is to be implemented, the mapping shown above must be adapted to the newly implemented React component and the configuration in the Makaira backend for this filter must be made accordingly.

Customise your NGINX configuration

With our Service Storefront as a Service offering, you can also customise the NGINX configuration for your specific needs. You can find the NGINX configuration here:

config/nginx.erb

This file contains a template, that also supports the usage of environment variables. By default the following values are available:

Name Vaule (Example)
MAKAIRA_API_INSTANCE stage
MAKAIRA_API_URL https://shop.makaira.io
MAKAIRA_ASSET_URL https://storefront-preview.s3.eu-central-1.amazonaws.com
NODE_ENV production
PRODUCTS_PER_PAGE 50
RUNS_ON_HEROKU true
SHOP_DOMAIN https://shop.makaira.cloud
SHOP_ID 1

In order to use an environment variable inside the template, you'll need to use the following syntax:

listen <%= ENV["PORT"] %>;

Additionally you can also use all common features of NGINX. You can find the documentation of NGINX directly on their website: NGINX Documentation

 

Basic Auth

Your new Storefront is protected by a login. You can find all authorised users in the config/.htpasswd file. If you want to add a new user to your list, you can do so by running:

htpasswd -B config/.htpasswd USER_NAME

If you have htpasswd not installed, please follow one of these guides: Install htpasswd on Ubuntu/DebianUse htpasswd on Windows or Use htpasswd on macOS

 

Configuration Examples

Pre Go Live Routing

The following configuration is useful if you want to forward the whole traffic to your shop system. You can do that before you go live with your new storefront and have already switched your DNS record to the new storefront.

http {
  ...

  location / {
    # Redirect all traffic to HTTPS
    if ($http_x_forwarded_proto != "https") {
      return 301 https://$host$request_uri;
    }

    proxy_pass            http://example.com; # Please put the url of your shop system here
    proxy_read_timeout    120s;
    proxy_connect_timeout 15s;
    proxy_send_timeout    90s;
    proxy_set_header      Host "SHOP.makria.io"; # Please put the address of this storefront here
    proxy_set_header      X-Real-IP $http_x_real_ip;
    proxy_set_header      X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header      X-Forwarded-Proto $http_x_forwarded_proto;
    proxy_set_header      HTTPS $http_https;
  }
}
Failover

Use this configuration, if you want to forward requests to shop system, that cannot be served by storefront and are throwing an error.

http {
  ...
  # Enable this part if you want to use error page failover
  proxy_busy_buffers_size   512k;
  proxy_buffers   			4 512k;
  proxy_buffer_size   		256k;
  proxy_intercept_errors 	on;
  recursive_error_pages 	on;

  location / {
    # Redirect all traffic to HTTPS
    if ($http_x_forwarded_proto != "https") {
      return 301 https://$host$request_uri;
    }

    # Enable password protection
    auth_basic           "Access Restricted";
    auth_basic_user_file /app/config/.htpasswd;

    # Enable error_page if you want to use error page failover
    error_page 404 500 501 502 503 504 505 506 507 508 510 511 = @failover_target;

    proxy_set_header      Host $http_host;
    proxy_set_header      X-Real-IP $http_x_real_ip;
    proxy_set_header      X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header      X-Forwarded-Proto $http_x_forwarded_proto;
    proxy_set_header      HTTPS $http_https;
    proxy_set_header      Accept-Encoding "gzip,deflate";
    proxy_set_header      Connection "";
    proxy_set_header      Proxy "";
    proxy_set_header      X-Country-Code $http_x_country_code;

    proxy_redirect 			off;
    proxy_pass 				http://app_server;
  }

  # Failover target
  location @failover_target {
    proxy_pass            http://example.com; # Please put the url of your shop system here
    proxy_read_timeout    120s;
    proxy_connect_timeout 15s;
    proxy_send_timeout    90s;
    proxy_set_header      Host "SHOP.makria.io"; # Please put the address of this storefront here
    proxy_set_header      X-Real-IP $http_x_real_ip;
    proxy_set_header      X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header      X-Forwarded-Proto $http_x_forwarded_proto;
    proxy_set_header      HTTPS $http_https;
  }
}
Forward specific routes to your shop system

If you want to forward the whole traffic for specific routes to your shop system directly, you can use the following configuration. For the configuration of the route you can use regular expressions. For more information about configuring locations in NGINX, please go and visit this blog post by DigitalOcean: Understanding Nginx Server and Location Block Selection Algorithms

http {
  ...
  location / {
    ...
  }

  # Custom location with direct failover
  location ~* ^(/api/) {
    try_files /dev/null @failover_target;
  }

  # Failover target
  location @failover_target {
    proxy_pass            http://example.com; # Please put the url of your shop system here
    proxy_read_timeout    120s;
    proxy_connect_timeout 15s;
    proxy_send_timeout    90s;
    proxy_set_header      Host "SHOP.makria.io"; # Please put the address of this storefront here
    proxy_set_header      X-Real-IP $http_x_real_ip;
    proxy_set_header      X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header      X-Forwarded-Proto $http_x_forwarded_proto;
    proxy_set_header      HTTPS $http_https;
  }
}

Smart Bundles

Depending on your storefront some prerequisites have to be fulfilled to use the smart bundles.

  1. Usage with Makaira Storefront
  2. Usage with the API for other frontends
  3. Storing the bundle configuration
  4. Integration into cart systems

1. Usage with Makaira Storefront

The Makaira Storefront ships with components and utils to be able to represent the Smart Bundles. In case you are already working with the storefront you need to migrate manually from the Storefront template. 

Bundle components/utils:

Component Path Type
BundlePage /frontend/BundlePage New
BundleSelection /patterns/core/BundleSelection New
ProductList /patterns/core/ProductList Change
RequestBuilder /utils/core/RequestBuilder Change
redirectToBundle /utils/core/redirectToBundle New
collectBundleFormData /utils/core/collectBundleFormData New
fetchPageData /utils/core/fetchPageData Change

To be able to use the Bundle form you need to register the BundlePage.

2. Usage with the API for other frontends

Please use the endpoint <YOUR_MAKAIRA_URL>/enterprise/page with the configured bundle URL to retrieve more data regarding the bundles.

Retrieve a bundle
Passing a bundle URL will respond with all data which are needed to render the bundle page, If the type is a bundle you get data like the number of slots, assigned products, text, images of the bundle.

{
  ...
  url: '<BUNDLE-URL>',  
  ...
}

In the case of a bundle URL, the response contains information like amount of slots, assigned products, text, images to render the bundle. 

Modify a bundle
Bundles can be modified by passing the IDs of bundles, slots and products.

{
  ...
  url: 'BUNDLE_URL',
  bundles: {
    <BUNDLE_ID>: {
    	<SLOT_ID_1>: <PRODUCT_ID_FOR_SLOT_1>,
        <SLOT_ID_2>: <PRODUCT_ID_FOR_SLOT_2>
        ...
    },
    ...
  }
  ...
}

Retrieving a specific slot
To guide the customer through the configuration you can request specific slots.

{
  ...
  url: '<BUNDLE-URL>',  
  slot: <SLOT_ID>
  ...
}

3. Storing the bundle configuration

The configuration of a bundle is stored by in a client and serverside cookie named bundle.  Updates of the serverside are handeled by the RequestBuilder.

4. Integration into cart systems

The add to cart functionality is not implemented into the Storefront as it is independant from any cart system. Depending on your cart system you can either add all bundle items with one call or one by one. If you're planing to have features on top of bundles like discounts we reccomend to implement your own API.

To prevent missconfigurations you are able to validate the configured bundle by <YOUR_MAKAIRA_URL>/smart-bundle​/validate.

More information