Using Squarespace - ecellar/remote-widgets GitHub Wiki

Squarespace is a proprietary system for creating and hosting web sites. Sites are managed via a user interface supplied by Squarespace.

If your site is a Squarespace site, we recommend that you read our 01 Getting Started page and then returning here for tips about integrating the SPA into your site.

Note: Adding Designer Widgets to your site requires using some javascript in Squarespace “code blocks”. Code blocks are a premium feature, available in business plans.

If you have not created a page for the SPA yet, here’s how:

1. Go to the Pages section of the admin area.
2. In the NOT LINKED area of the left nav, click the + icon.
3. In the CREATE NEW PAGE popup that opens, click Page. You should then see controls for editing your new page.
4. Enter a page title, for example “SPA”.
5. Select a layout for your page. The Designer Widgets will be going in the “main” area of whatever layout you use.
6. Click the START EDITING button.

Add a <div> placeholder for the Mini Cart view:

1. Click the + icon to add content to your page.
2. In the popup, select the “Code” item (located in the MORE section).
3. In the Code popup, leave the Display Source checkbox unchecked and select HTML in the dropdown at the right.
4. Add this markup in the large code-entry box, then click the APPLY button.

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

After clicking APPLY, you will not see anything new in the page, other than an indicator that there is a CODE block when you hover over that area of the page. That is correct. These will get content from the SPA.

Add a <div> placeholder for the main contents that will be rendered by the SPA:

In the same page, add another CODE block below the first one and put this HTML in it:

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

Below that code block, add a 3rd one with this HTML in it:

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

For that last one, when you click the APPLY button to insert the code you will see a message saying that there is an embedded script. That is correct.

Now save all of the changes that you made to the page. Your new page should now be listed in the NOT LINKED area of the left navigation. Hover over the page name and you will see a “settings” gear icon. Click that to open the page settings.

In the PAGE popup that opens, check that everything on the Basic tab is as you wish it to be. In particular, make sure that the URL Slug at the bottom is one that you want to use as the pathRoot for the SPA. By default it uses the name of the page, but you can change it to almost any word that you want (see below for a list of reserved words). For example, you could change it to /store.

While still in the PAGE popup, go to the Advanced tab. Add these to the CODE HEADER INJECTION field:

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

<script>
  epubOptions = {
    APIKey: 'Provided by eCellar',
    initQueryString: true,
    pathRoot: '/<the Squarespace URL Slug for your page>/'
  }
</script>

Click the SAVE button.

You should now be able to go to your page and load one of the views from the SPA.

For example, if your page is at https://<www.yoursite.com>/store/, add ?view=joinlist to the end of that and try loading it. Like this:

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

If that works, great! For additional information about loading different views, creating links in your site and more, please see the Test Your Page section of our Getting Started page.

Also see our 02 Prepare Data page for details about setting up data for display in your site.

We do not recommend adding any of the Designer Widget code to ALL of the pages in your site. It’s best to keep all of the SPA-related stuff in pages that are designed for their use.

You may instantiate the SPA in more than one page. A good time to do that is when you would like to have parts of the SPA appear on pages that have different overall layouts.

For more information about using more than one instance of the SPA, see the viewAliases section of the Initialization Options page.

In the setup instructions above, your new SPA page was placed in the NOT LINKED page list. If you were to link directly to the SPA page without including a query string with a view=something parameter, the SPA would not show anything in the main content area.

To link to specific views (from your site’s main menu, footer, etc), use deep linking. You can find information about that in our 01 Getting Started page.

To add a deep link to your main navigation menu:

1. Go to the Pages section of the admin area.
2. Click the + icon next to MAIN NAVIGATION.
3. In the CREATE NEW PAGE popup, click on LINK. The CONFIGURE LINK popup will appear.
4. Enter a link title (for example “Join List”).
5. Click on “Click to add URL…”
6. Select “External” (link type).
7. Enter a relative link to your SPA instance, plus a query string for the view that you want to have load when the link is clicked. For example: /store/?view=joinlist.
8. Click the SAVE button.

Now go to your site and verify that the new link appears in your main navigation and loads the correct SPA view when clicked.

We have asked Squarespace tech support if it’s possible to setup URL Rewrites in a Squarespace site. They have told us that it is not an option.

Squarespace does not allow these words to be used for Page slugs:

account
api
assets
auth
cart
checkout
commerce
config
debug
facebook
files
item
script
scripts
search
sharer
static
storage
universal

These are considered “reserved words”.

We are not currently familiar with the Squarespace Developer Mode. It’s possible that some of the things described above can be done a different way via Developer Mode. If you are familiar with that, and would like to assist us any information, please feel free to visit our Designer Widgets Forum.