Events Explorer 1.0 · Install guide

A better events page, from the events you already have.

Events Explorer reads the Squarespace events page you already keep and turns it into something people can actually find their way around: a list grouped by month, a month calendar, filters for each kind of event, a search box, maps, and an Add to calendar button on every event. It takes about ten minutes to set up, and the only code you touch is one paste.

Before you start

• A Squarespace plan that runs JavaScript. On the current plans that means Core, Plus or Advanced, and on older ones Business, Commerce Basic or Commerce Advanced. The Basic and Personal plans don’t run custom scripts, so Events Explorer can’t work there.
• An events page made with Squarespace’s own Events page type. It can use the list layout or the calendar layout, and it has to be public, though it doesn’t need to be in your navigation.
• Squarespace 7.0 or 7.1. Both work.

Install

1. Find your events page’s address. Open the events page on your live site and look at the address bar. If it reads yoursite.org/events, the part you need is /events.
2. Make a page for the explorer. I’d suggest a new page called “What’s on” with your navigation pointing at it. Your events page stays where it is, because it still holds each event’s own page, which the Details buttons link to. Squarespace doesn’t let you add blocks inside an events page itself, so the explorer needs its own page anyway.
3. Add a Code block. Edit the new page, add a block and choose Code. Leave the mode on HTML and switch “Display source” off.
4. Paste. Open paste-into-code-block.html from this download in any text editor (TextEdit or Notepad are fine), copy everything and paste it into the Code block.
5. Point it at your events. Near the top of what you pasted you’ll see data-source="/events". Change /events to your events page’s address from step 1.
6. Give it room. On Squarespace 7.1, drag the Code block’s handles so it spans the full width of the section. On 7.0 it fills the column it sits in.
7. Save and look at the live page. Squarespace doesn’t run scripts inside the editor, so you’ll see an empty block while editing. Open the page in a private window, or log out, to see your events.

Setting up your events

Events Explorer uses what you already enter for each event. Nothing has to change for it to work, but a few details make every part of it richer.

Categories become the filter chips

Give each event a category in its settings, such as Youth, Community, Prayer or Services. A row of chips appears above the list as soon as your events use two or more categories, and each chip shows how many events it holds. Visitors can share a filtered view too, because the address changes to something like ?events=cat/youth.

Locations and maps

Fill in the Location section of each event: the venue name, the street address and the town. Events Explorer shows the venue and town on each event with a Map link, which opens Google Maps (or Apple Maps, if you choose that below) at the street address. With no street address it uses the pin on the event’s map instead.

A new Squarespace event starts with its map pin in New York. If you never set a location, Events Explorer recognises that pin and leaves the location off, so nobody gets sent to Manhattan for your Tuesday prayer meeting. The setup check tells you how many events are like this.

For an online event, put “Online” or “Zoom” in the venue name and leave the street address empty. It shows without a map link, and visitors in other time zones also see the time where they are.

Times and dates

Every time shows in your site’s own time zone, which you set under Settings → Language & Region. An evening service in Auckland always reads 7pm, wherever the person reading it lives. When a visitor’s computer is in a different zone, the time gets a short label such as NZDT so there’s no confusion.

Squarespace has no “all day” switch, so the usual way to mark one is to start the event at 12:00am and end it at 11:59pm. Events Explorer reads that as all day. An event that ends on a later date shows as a range, like 13–15 November, or Fri 5pm – Sun 2pm for a camp.

Images

The thumbnail image you add in each event’s settings shows beside the event in the list. Events without one show without a picture.

List or calendar layout

Squarespace’s events page has a list layout and a calendar layout. With the list layout, every event arrives in a single request, so the explorer is ready almost at once. The calendar layout only shares one month at a time, so Events Explorer loads this month and the five after it, then fetches other months as visitors move through the calendar or open past events. Both work, but if you’re choosing, the list layout is quicker.

Run the setup check

Add ?events=check to the end of your explorer page’s address, for example yoursite.org/whats-on?events=check. A panel appears above the events showing how many upcoming and past events it found, how many have a location, a map link and an image, which categories you use, which time zone it’s using, and how long it took to load. Underneath is a short list of anything worth fixing. Visitors never see this panel unless they type that address themselves.

Options

Everything is set with attributes on the <div> line. You only need the ones you want to change.

An explorer that opens on the month calendar, hides past events and uses Apple Maps looks like this:

<div data-events-explorer data-source="/events" data-start="month" data-past="off" data-map="apple"></div>

Links you can share

The address changes as people use the explorer, so any view can be bookmarked or shared: ?events=cat/youth for one category, ?events=month/2026-11 for a month, ?events=past for past events, and ?events=when/week for this week. The browser’s Back button steps back through them.

Changing the wording

Every label can be changed, which is handy for other languages or your own way of saying things. Put this in the Code block above the rest of the paste and change only the lines you want:

<script>
window.EventsExplorerStrings = {
  search: 'Search our events',
  upcoming: 'Coming up',
  past: 'Past events',
  calendar: 'Calendar',
  add: 'Add to my calendar',
  details: 'More info',
  today: 'Today',
  now: 'On now',
  noneUpcoming: 'Nothing is booked in just yet. Check back soon!'
};
</script>

Dates and month names follow your site’s language setting automatically.

Troubleshooting

The block is empty while I’m editing

That’s normal. Squarespace doesn’t run scripts in the editor. Check the live page in a private window.

“The events couldn’t be loaded”

Open the page with ?events=check on the end and the panel will tell you why. It’s nearly always one of three things: data-source doesn’t match the events page’s address exactly, the events page is password protected or members-only, or the address points at a blog or an ordinary page instead of an events page.

The times are an hour or a day out

Check your site’s time zone under Settings → Language & Region. Events Explorer shows every time in that zone. If it was set wrongly when the events were entered, the times inside Squarespace are wrong too, so fix the zone first and then check one event in the editor.

An event has no map link, or the map goes to the wrong place

The map link uses the street address in the event’s Location settings, and the pin when there’s no street address. Add the street and town, and drag the pin onto the venue if it has drifted. An event whose pin is still in New York shows without a location until you set one.

The category chips are missing

They appear once your events use two or more categories. The setup check lists the categories it found.

Add to calendar downloads a file

That’s the .ics option, which is how Apple Calendar and Outlook add events. On an iPhone, tap the file and choose Add to Calendar. On a computer, open the downloaded file and your calendar app takes it from there. The Google Calendar option opens Google Calendar in a new tab instead.

The setup check doesn’t appear on my events page

On the calendar layout, Squarespace sends visitors from your events page to its own calendar address and drops anything else from the address, including ?events=check. Put the explorer on its own page, as in the install steps, and the check works there.

The filter bar hides under my header when I scroll

The explorer looks for anything pinned to the top of the window and sits underneath it, which works on every template I’ve tested. If yours is different, email me the page address and I’ll take a look.

New events don’t appear straight away

The explorer checks for changes on every visit with one quick request, and refreshes its copy when your events page changes. If a visitor’s browser blocks storage, it loads your events fresh each time.

Squarespace 7.0 with Ajax loading

Some 7.0 templates load pages without a full refresh. The explorer listens for that, but if it only appears after a reload, turn off Ajax loading under Design → Site Styles.

Updates and help

Updates for the 1.x versions are free. When one comes out you’ll get an email with the new files, and you replace the old paste with the new one. Your settings live on the <div> line, so keep that line.

If you get stuck, email kris@singhstudio.co.nz with your page address and what you’re seeing. It helps to include a screenshot of the ?events=check panel.