Why doesn't my Squarespace code work until I refresh the page?

I've answered many questions on this subject. Each asks why a particular piece of code isn't working properly and it usually mentions that it only works after the page is refreshed or reloaded. Usually, the question refers to code that was found on one of the forums (usually Squarespace Answers) but it can also refer to scripts or ‘widgets’ that companies have produced to add features to a website.

So why is this happening? Ajax.

If you're using one of the newer Squarespace templates you’ll find that it uses a great technique called Ajax (Asynchronous JavaScript And XML). This allows your Squarespace site to change content dynamically without the need to reload the entire page. This makes your website faster because when a different page is selected in the navigation, only the canvas content is loaded. The header and footer are already in place and don’t reload unless header content has changed. Neither does any of the script content (including your code!) and this makes the page load faster.

The technique also enables features like ‘lazy loading’ where a few images or blog posts are loaded initially, and then, as the user scrolls down the page, more images or posts appear just in time. It also allows sites to show a ‘quick view’ panel for products.

The downside is that if you’ve obtained some code that hasn’t been written to work with the Squarespace-specific Ajax, it won’t work. Many code samples run when the page loads, but if Ajax is enabled, the code only loads for the initial page. After that, the content is updated using Ajax so the page never needs to load again.

So what can you do?

Rewrite the Code

If your code is behaving as I’ve described then it is not Ajax compatible. It was probably written prior to 2016 when Squarespace started adding Ajax to their templates. If you obtained the code when you purchased an add-on for Squarespace then it’s best to contact the supplier and ask them to update their code. Squarespace started adding Ajax to their templates in 2016 so it’s about time companies updated their ‘widgets’ to work with it.

If you found the code on an internet forum then you may not be so lucky. You could try to contact the author or you could post a new question on a forum, but you aren’t guaranteed an answer. Alternatively you could hire a developer to code an Ajax-compatible solution for you.

Disable Ajax

If you don’t want the Ajax features that improve your website, a quick workaround is to disable Ajax on your site. To disable Ajax:

Go to Design > Site Styles.

Scroll down to SITE: LOADING.

Uncheck Enable Ajax Loading.

When you save your changes, this workaround will get your code working but bear in mind that all the great Ajax features that improve your website’s performance are now disabled. Visitors love sites that load quickly and so do search engines, so whilst this may be a quick fix, it will have long term consequences for your website.

Coding Advice

Injection

On Squarespace sites with Ajax disabled, you can insert JavaScript into any of these locations and it will run every time the page loads:

  • Site Header

  • Site Footer

  • Page Header

  • Code Block

  • Markdown Block

Squarespace sites with Ajax enabled, JavaScript will only run the FIRST time a page is loaded when a visitor arrives on your site.

So for example, if someone sees you listed on Google, and clicks on the result to open your site, JavaScript in any of the locations listed above will run. Once. But never again. When the visitor clicks on other links on your site, they will be taken to the new content but the JavaScript will never run again. Ever.

So how do we deal with this? Surely we need the JavaScript to load? Well actually no, we don’t want all that code to load again becuase it slows things down, but it does require us to think differently.

If you want your code to run the next time a page is opened, you need to make the SAME code run AGAIN. We do this by using something called Mercury.

Document Ready

When Ajax is enabled on your site, Squarespace’s Mercury loader takes care of loading page data instead of the standard one that triggers the usual DOM loading event triggers in JavaScript and jQuery. We call these Ajax-enabled or Mercury sites.

If your code is using $(document).ready or Y.on('domready', or window.onload then you’ll need to replace this with something that fires when either of two events happens:

  • The DOM has loaded (because of a refresh or because the visitor has just arrived on the site)

  • The Mercury Loader has just loaded the page (because the visitor clicked a link on another page of this site)

There are a number of ways to do this.

One is to use window.Squarespace.onInitialize instead. This will call a function on either of these events.

Another is to add an Event Listener to DOMContentLoaded (as you would on a non-Mercury site) and add another Event Listener to mercury:load. Both should call the same function so that it triggers on either event.

SF DigitalAjax, Refresh, JavaScript