05 Initialization Examples - ecellar/remote-widgets GitHub Wiki

The eCellar Designer Widgets system offers a number of Initialization Options that you can use to load one or more instances of the SPA in your site.

Below are some examples showing different combinations of the most commonly used options.

Please see our 01 Getting Started page if this is all new to you.

Basic

This is the minimal set of required and recommended options for initializing the SPA. When used like this, all SPA operations happen at a single root url, specified by the pathRoot option.

epubOptions = {
  APIKey: '<provided by eCellar>',
  pathRoot: '/shop/'
}

Basic with cache prevention value

By default, the browser and some servers cache certain requests, such as html templates, to speed up the performance of the internet. You may find it necessary to force new templates to load instead of cached versions. You can do so by using the @cpv option to append a string to our existing cpv value which updates with each deployment.

epubOptions = {
  APIKey: '<provided by eCellar>',
  pathRoot: '/shop/',
  cpv: 'v1'
}

Basic with URL Rewrites

If you are able to configure URL-Rewrites on your server, the SPA is capable of parsing and presenting itself using paths appended to the pathRoot instead of query string variables. You can do so by using the initLocationPath option which overrides any initQueryString option.

epubOptions = {
  APIKey: '<provided by eCellar>',
  pathRoot: '/shop/',
  initLocationPath: true
}

Global Cart Presence

If you would like to include the “Mini Cart” container on all of the pages of your site (outside of your main SPA pathRoot), you can place the markup for it in any page and set your SPA options globally.

For example, place the markup in any page template:

<div data-ecp-minicart></div>

And then include something like this in your template’s HTML head area:

epubOptions = {
  APIKey: '<provided by eCellar>',
  pathRoot: '/shop/',
  initQueryString: false, // note that this is false
  viewAliases: {
    account: { forcePageLoad: 'viewchange' },
    cart: { forcePageLoad: 'viewchange' }
  }
};

Followed by something like this if you are using the initQueryString option:

if (window.location.pathname.indexOf('/shop/') === 0) {
  epubOptions.initQueryString = true;
}

Or something like this if you are using the initLocationPath option:

if (window.location.pathname.indexOf('/shop/') === 0) {
  epubOptions.initLocationPath = true;
}

Global with a few content overrides

This example shows how to use the addMessages option to add some content message overrides. This is handy when you only have a few messages to override.

Visit the 11 Custom Messages page for more info.

epubOptions = {
  APIKey: '<provided by eCellar>',
  pathRoot: '/shop/',
  addMessages: [
    {
      "en": {
        "epub": {
          "account": {
            "Dashboard": {
              "Summary": "Welcome!  Please select from the options below."
            }
          },
          "products": {
            "CategoryWithProducts": {
              "Status": {
                "RestrictedWineClub": "Wine Club Member Exclusive"
              }
            },
            "ProductDetail": {
              "Status": {
                "RestrictedWineClub": "Wine Club Member Exclusive"
              }
            }
          }
        }
      }
    }
  ]
};

Global with a JSON file for content overrides

If you have a number of content message overrides, you may put them in a file and use the addMessages option to load the file (or multiple files):

epubOptions = {
  APIKey: '<provided by eCellar>',
  pathRoot: '/shop/',
  addMessages: [
    'https://<www.yoursite.com>/files/custom-messages.json'
  ]
};

Global with custom HTML templates

If you want to use any 09 Custom Templates, use the addTemplates option to load them.

epubOptions = {
  APIKey: '<provided by eCellar>',
  pathRoot: '/shop/',
  addTemplates: [
    { 
      "cart": {
        "en": {
          "MiniCart": {
            "url": "https://<www.yoursite.com>/wp-content/uploads/2018/11/MiniCart__Custom.html"
          }
        }
      },
      "products": {
        "en": {
          "CategoryWithProducts__Product": {
            "url": "https://<www.yoursite.com>/wp-content/uploads/2018/11/CategoryWithProducts__Product.html"
          }
        }
      }
    }
  ]
};

Global with multiple SPA instances

If you would like to enclose specific SPA views in different page wrappers on your site (for example, all club-related views in one wrapper and all shop related views in another), you may do so.

First, you must create a page in your site for each instance of the SPA. For example, if you are using WordPress, you might create two pages:

One at /shop/ designed for displaying SPA views that are related to product and product category display.
One at /ecellar/ designed for displaying the rest of the SPA views (joinlist, cart, checkout, etc).

You would then use a combination of the global examples above, with some additional javascript to designate which pages should handle which SPA views. Using the two pages described above, an example would look something like this:

epubOptions = {
  APIKey: '<provided by eCellar>',
  pathRoot: '/shop/',
  viewAliases: {
    account: { forcePageLoad: 'viewChange', pathRoot: '/ecellar/' },
    allocation: { forcePageLoad: 'viewChange', pathRoot: '/shop/' },
    cart: { forcePageLoad: 'viewChange', pathRoot: '/ecellar/' },
    categories: { forcePageLoad: 'viewChange', pathRoot: '/shop/' },
    categorieslist: { forcePageLoad: 'viewChange', pathRoot: '/shop/' },
    checkout: { forcePageLoad: 'viewChange', pathRoot: '/ecellar/' },
    joinclub: { forcePageLoad: 'viewChange', pathRoot: '/ecellar/' },
    joinlist: { forcePageLoad: 'viewChange', pathRoot: '/ecellar/' },
    passwordreset: { forcePageLoad: 'viewChange', pathRoot: '/ecellar/' },
    product: { forcePageLoad: 'viewChange', pathRoot: '/shop/' },
    products: { forcePageLoad: 'viewChange', pathRoot: '/shop/' },
    reservationlist: { forcePageLoad: 'viewChange', pathRoot: '/ecellar/' },
    reservationsearch: { forcePageLoad: 'viewChange', pathRoot: '/ecellar/' },
    reservationtimes: { forcePageLoad: 'viewChange', pathRoot: '/ecellar/' },
    signup: { forcePageLoad: 'viewChange', pathRoot: '/ecellar/' }
  }
};

Followed by something like this if you are using the initQueryString option:

if (window.location.pathname.indexOf('/shop/') === 0) {
  epubOptions.initQueryString = true;
  epubOptions.pathRoot = '/shop/';
}
else if (window.location.pathname.indexOf('/ecellar/') === 0) {
  epubOptions.initQueryString = true;
  epubOptions.pathRoot = '/ecellar/';
}

Or something like this if you are using the initLocationPath option:

if (window.location.pathname.indexOf('/shop/') === 0) {
  epubOptions.initLocationPath = true;
  epubOptions.pathRoot = '/shop/';
}
else if (window.location.pathname.indexOf('/ecellar/') === 0) {
  epubOptions.initLocationPath = true;
  epubOptions.pathRoot = '/ecellar/';
}

You can use this approach to create custom page wrappers for any set of SPA views.

For more information about the view names used in the viewAliases section of the example above, see the Deep Linking section of our Getting Started page.

For more help

Visit our Designer Widgets Community Forum