01 Getting Started - ecellar/remote-widgets GitHub Wiki

Overview

The eCellar Designer Widget system is comprised of:

1. A javascript-based Single Page Application (SPA). It takes a few lines of javascript to initialize the SPA. No advanced javascript skills are required.

2. An HTML template system. The SPA uses templates to render everything it displays. Templates are loaded on-demand as your user interacts with the SPA. You may fully customize any HTML template.

3. A CSS theme to style the HTML templates. The theme inherits the styling of your site. You may override any style or completely replace the theme.

What You Need

To get started, you will need to obtain an API Key to use for your client’s site.

You will also need certain permissions to modify your web site. If you are using a CMS, like Squarespace or WordPress, you will need admin access. If you are working with a 100% custom site, you will need rights to add and modify files.

To Add Designer Widgets

1. Create a page that you will use for the SPA. Ideally, this should be either:

a) A page on a development version of your site (preferred).

or

b) A hidden (not publicly linked to) page on your production site.

Your page should include the typical trimmings of your site: page header, footer, any sidebars that you use, etc. You are going to be adding some things to the <head> and <body> sections of the page.

2. In the head area of your page:

Add a link to our default CSS theme:

<link rel="stylesheet" type="text/css" href="https://cdn.ecellar-rw.com/1/css/ecp-theme.css"/>

Add a script tag containing Initialization Options for loading the SPA. We recommend starting with the options shown below. You can use other options after things are up and running.

<script>
  epubOptions = {
    APIKey: '<provided by eCellar>',
    initQueryString: true,
    pathRoot: '/<url path for your page>/'
  }
</script>

For pathRoot, if your page is at /store/index.html, use ‘/store/index.html’. If your page works at ‘/store/’ without a filename after it, you can use ‘/store/’.

3. In the body of your page:

Add a div where you want the “Mini Cart” to appear. Usually this goes somewhere in the header area of a site’s page template. It will display “always present” cart information (number of items in cart, cart item subtotal):

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

Add a div where you want the main SPA content to appear. Typically this is where the “main content area” is in a site’s page template.

<div data-ecp-wrapper="true" class="ecp-wrapper"></div>

4. At the end of the body section of your page:

Add a script tag with the path to our SPA loader file:

<script src="https://cdn.ecellar-rw.com/js/loader.js"></script>

Save your changes.

Test Your Page

Let’s say that your page url is:

https://<www.yoursite.com>/store/index.html

and your epubOptions look like this:

initQueryString: true,
pathRoot: '/store/index.html'

Try loading your page using the page url plus a query string parameter to tell the SPA to load the “signup” view. For example:

https://<www.yoursite.com>/store/index.html?view=signup

If that works, try loading another view:

https://<www.yoursite.com>/store/index.html?view=joinlist

If that works, great! You now have the SPA initialized and are able to use the query string to dynamically load individual views.

Note: if your site does not need to include the file name in the url your test urls should look like this:

https://<www.yoursite.com>/store/?view=signup
https://<www.yoursite.com>/store/?view=joinlist

If you are using WordPress or Squarespace and are not sure how to do all of this, we have additional information available for you:

Using WordPress
Using Squarespace

Update the Cache Prevention Value to see your custom template changes

We use a cache prevention value when loading templates to ensure new templates are loaded after a deployment. You can append your own string to this to force your custom templates to load fresh after making changes to them.

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

Documentation for custom templates can be found here: 09 Custom Templates

Use Deep Linking

As shown above, you can create one instance of the SPA and then use query string parameters to load specific views on-demand. You will probably want to use SPA deep links somewhere in your site’s navigation menus, footer, etc.

Doing so is straight-forward, nothing fancy. All you need to do is create menu items or links using the deep links for different SPA views.

For example, you may have a main menu with items like this:

Wines —> /store/?view=products&slug=current-releases
White Wines —> /store/?view=categorieslist&slug=white-wines
Wine Clubs —> /store/?view=joinclub
Reservations —> /store/?view=reservationlist
Mailing List —> /store/?view=joinlist
Cart —> /store/?view=cart
Checkout —> /store/?view=checkout
Account —> /store/?view=account

Note: if you use the Mini Cart, you may not want to have a separate Cart link in your main menu, because the Mini Cart can be clicked on to view cart contents.

These values can be used with the view parameter:

Value Description
account Displays the customer Account dashboard. Prompts user to login if not already logged in.
allocation Displays a customer’s current allocation, if any. Prompts user to login if not already logged in.
cart Displays the cart editor.
categories Displays a list of product categories, with links to drill down to subcategories or products. A category slug parameter must also be used in the query string. For example: ?view=categories&slug=red-wines
categorieslist Displays a list of product categories and the products in them. A category slug parameter must also be used in the query string. For example: ?view=categorieslist&slug=white-wines
checkout Displays the first step of the checkout process. Prompts user to login if not already logged in.
forgotpassword Displays a form for requesting a password reset email.
giftcardsearch Displays a form for checking gift card balance.
joinclub Displays the first step (intro page) of the Join Club workflow. Club tiers that are marked “Public” in the ACP will be available for selecting in step 2 (the tier list).

If you would like to create a deep link to bypass steps 1 and 2 for joining a specific club, you may do so by using this URL format: https://<www.yoursite.com>/store/?view=joinclub&club_tier_name=<slug>, where <slug> is the tier’s Slug from the ACP (case-sensitive).
joinlist Displays a form for joining the mailing list.
product Displays data for a single product. A product slug parameter must also be used in the query string. For example: ?view=product&slug=2015-cabernet
products Displays a list of products in a category. A category slug parameter must also be used in the query string. For example: ?view=products&slug=current-releases
reservationlist Displays a list of available reservation types.
reservationsearch Displays a form to search for available reservation types.
reservationtimes Displays one reservation type with fields to search for available times. A reservation type slug must also be used in the query string. For example: ?view=reservationtimes&slug=premiere_tasting
signout Displays a form to confirm signing out of a customer account.
signup Displays a form for creating a new customer account.

View Aliases

You may use the SPA’s viewAliases initialization option to create aliases for any of these values.

For example, to use home instead of account:

viewAliases: { "account": {alias: 'home'} }

See the Initialization Options page for more information.

URL Rewrites

Some web hosting systems provide a way to create “rewrite rules” for URLs. If your host allows rewrite rules, you may use them instead of query string parameters to create deep links into the SPA.

For example, rather than this:

/store/?view=products&slug=current-releases

You would be able to do this:

/store/products/current-releases/

To learn more, visit our URL Rewrites page.

Next Steps

Every Designer Widgets installation requires coordination between the web site administrator, the winery and an eCellar support rep.

Some of this work may have already been completed for you.

See our 02 Prepare Data page to learn more.

You May Also Be Interested In

08 HTML Templates
09 Custom Templates
12 Template Directory
10 Content
11 Custom Messages
07 Themes
Initialization Options
Reporting Analytical Statistics

View the 00 Table of Contents.

View our 99 Updates page to learn about recent releases.

⚠️ **GitHub.com Fallback** ⚠️