Team Directory 1.0 · Install guide

A team page you edit like a blog.

Team Directory turns a Squarespace blog with one post per person into a staff and volunteer directory people can search, filter by team, place and language, and open to find out who someone is and how to reach them. Your team edit people in the normal Squarespace editor, and nobody has to touch the code again once it’s in. Setting it up takes about twenty minutes, most of it spent on the people themselves.

Before you start

A Squarespace plan that runs JavaScript, which means Core, Plus or Advanced on the current plans, or Business, Commerce Basic or Commerce Advanced on older ones. The Basic and Personal plans don’t run custom scripts, so the directory can’t work there.
A blog to hold your people. It can be one you make just for this and keep out of your navigation. It has to be public, but nobody needs to know it’s there.
Squarespace 7.0 or 7.1. Both work.

Install

Make a blog for your people. In Pages, add a new Blog page and call it something like “Team Members”. Drag it into Not Linked so it stays out of your menus, and in its settings under SEO you can hide it from search engines too. Delete the sample posts Squarespace adds.
Add one post per person. The next section explains which field holds what. Two or three people are enough to see it working, and you can add the rest later.
Find the blog’s address. Open the blog on your live site and look at the address bar. If it reads yoursite.org/team-members, the part you need is /team-members.
Add a Code block where the directory should go. Edit your Team or Staff page, add a block and choose Code. Leave the mode on HTML and switch “Display source” off.
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.
Point it at your blog. Near the top of what you pasted you’ll see data-source="/team-members". Change /team-members to your blog’s address from step 3 if yours is different.
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.
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 team.

If the Code block won’t saveThe paste is about 110 KB, which Squarespace normally takes without complaint. If yours refuses it, use the second file instead: paste paste-into-code-injection.html into the page’s own settings (Page settings → Advanced → Page Header Code Injection), and put only this line in the Code block: <div data-team-directory data-source="/team-members"></div>

Please don’t paste it into Design → Custom CSSThat panel runs an old style compiler that can’t read modern CSS, and it would break. The Code block (or Code Injection) is the right place.

Setting up each person

Each blog post is one person. You fill in the same fields you would for any blog post, and the directory reads them like this:

Post field	What it becomes
Title	Their name, exactly as it should appear, for example `Dr Aroha Walker`. Titles like Dr, Rev or Prof are fine, and they’re left out when sorting and on the Email button.
Thumbnail image	Their portrait (Settings → Content → Featured image). A square or upright photo with the face near the middle works best. People without one show their initials instead.
Excerpt	A short bio, two or three sentences (Settings → Content → Excerpt). If there isn’t one, the first paragraphs of the post are used instead.
Categories	Their team or department, such as `Leadership`, `Youth & Families` or `Board`. Someone in two teams gets two categories. These become the team buttons and the headings in the Teams view.
Tags	Places, skills and languages. Start a tag with `Location:`, `Language:`, `Skill:` or `Team:` to say what it is, as in `Location: Porirua` or `Language: Samoan`. Tags without a label are treated as skills, like `Youth work` or `First aid`.
Post body	Their role and contact details, as short labelled lines (see below). The first paragraph is used as the role if there’s no `Role:` line.
Source URL	Optional (Settings → Content). If the person has their own page elsewhere on your site, put its address here and the “Full profile” button goes there. Otherwise it opens their blog post.
Post date	The order. The earliest date comes first, so you can put your senior leader at the top by giving them the oldest date. Nobody sees the dates. Teams follow the same order, led by whoever has been there longest.

Labelled lines in the post body

Put each detail on its own line, starting with one of these labels. Bold labels and links are fine, and you only need the lines you want.

Youth Coordinator
Email: mere.paki@yoursite.org
Phone: 021 555 0105
Pronouns: she/her
Languages: English, te reo Māori
Location: Porirua
Ask me about: youth group, camps, mentoring

Mere grew up in Porirua and has run Friday youth since 2019…

The first line there is the role. You can write it as Role: Youth Coordinator instead, which also works when the role isn’t the first line. Based: works the same way as Location:. A labelled line in the body wins over a tag, so if you’ve tagged someone Location: Wellington and their post says Location: Porirua, Porirua is what shows.

If there’s no Email or Phone line, the directory looks for an email link or a phone link anywhere in the post and uses the first one it finds.

Anything in square brackets on a line of its own, such as [Photo coming after the shoot], is treated as a note for whoever edits the post. Visitors never see it, and a line like Email: [add an address] counts as empty.

Run the setup check

Add ?team=check to the end of your team page’s address, for example yoursite.org/our-team?team=check. A panel appears above the directory showing how many people it found and how many have a photo, a role, an email or phone, a team, a location and a language. Underneath is a short list of what to fix, naming who each one is about, such as “2 people have no role (Sam Lee and Jo Tane). Add a ‘Role:’ line or make the first paragraph the role.” Visitors never see this panel unless they type that address themselves.

What visitors can do

Search covers names, roles, teams, skills, languages and places, and it doesn’t mind macrons, so “maori” finds te reo Māori speakers. The team buttons show how many people are in each, and the location and language buttons appear once at least one person has a location or a language. A short sentence under the bar says what’s showing, like “6 people in Youth & Families based in Porirua”, and each part of it can be removed with one click. If nothing matches, visitors get a way back to everyone and, if you set one, a person to contact.

There are three layouts: a grid of portraits, a compact list with email and phone buttons, and a Teams view with everyone under their team’s heading. Opening a person shows their profile with buttons to email or call them, a button that copies their email address, and a link to their full profile.

Every state has its own address, so you can link straight to a person (?team=person/mere-paki) or a team (?team=t/youth-families) from a newsletter or another page. The browser’s Back button closes a profile.

Options

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

Attribute	What it does
`data-source`	Your people blog’s address. Required. `/team-members`
`data-view`	The layout it opens on: `grid` (default), `list` or `teams`.
`data-start`	A team to open on, for example `Board` on a governance page. Visitors can still press Everyone.
`data-photos`	Portraits are black and white until someone points at them. `colour` shows them in colour all the time.
`data-order`	`date` (default, earliest post first), `name` or `surname`.
`data-index`	`on` adds an A to Z bar for jumping to a letter, which is handy for big teams. It sorts by first name unless `data-order` says otherwise.
`data-per-page`	How many people show before a “Show more” button. Default `48`, which for most teams means everyone. `all` turns it off.
`data-hide`	Details to leave out, comma separated: `email`, `phone`, `profile`, `location`, `languages`, `pronouns`, `skills`, `ask`, `bio`. For example `data-hide="phone"`.
`data-contact-name`	Who to suggest when a search finds nobody, for example `the office`.
`data-contact-href`	Where that suggestion links to: a page, `mailto:office@yoursite.org` or `tel:045550100`.
`data-accent`	A colour for buttons and the chosen team, if you’d rather not use your site’s button colour, e.g. `#1f5560`.
`data-tags`	`auto` (default), `skills` or `places`. Some teams tag people with the areas they cover, and when most people’s tags include where they’re based, the directory notices and lists tags under “Covers” instead of “Skills”. This setting decides it for you.
`data-ignore`	Categories or tags to leave out, comma separated, e.g. `Featured, Staff only`.
`data-cache`	`off` stops the directory remembering your team between visits. Leave it on unless asked.

A list that opens on the Board, with an A to Z bar and a contact for when nothing matches, looks like this:

<div data-team-directory data-source="/team-members" data-view="list" data-start="Board" data-index="on"
     data-contact-name="the office" data-contact-href="mailto:office@yoursite.org"></div>

Changing the wording

Every label can be changed, which is handy for other languages or a different tone. Put this in the Code block above the rest of the paste and change only the lines you want:

<script>
window.TeamDirectoryStrings = {
  search: 'Search for a name, team or skill',
  everyone: 'Everyone',
  teams: 'Teams',
  anywhere: 'All campuses',
  otherPeople: 'Volunteers',
  askLabel: 'Talk to me about',
  profile: 'More about them',
  contact: 'Not sure who to ask? Get in touch with {link}.'
};
</script>

Keep anything in curly brackets, like {link}, {first} or {team}, because that’s where the name or link goes.

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 team couldn’t be loaded”

Open the page with ?team=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 blog’s address exactly, the blog is password protected or members-only, or the address points at a normal page instead of a blog.

Someone’s role is missing, or shows part of their bio

The role comes from a Role: line, or else from the first paragraph of the post when it’s short enough to be a job title. A long first paragraph is treated as the start of a bio and skipped. Adding a Role: line fixes it either way.

Someone isn’t showing

Drafts and scheduled posts aren’t public, so they don’t appear until they’re published. The setup check shows how many posts the blog has and how many were read.

A team appears twice with slightly different names

Differences in capitals, macrons and punctuation are merged for you, and so are “and”, “&” and “+”, which means “Youth & Families” and “youth and families” are one team. Different words, like “Youth” and “Youth Work”, stay separate, so pick one name and fix the other posts’ categories.

People are in the wrong order

The order follows the post dates, earliest first. Change a post’s date under Settings → Options to move them, or use data-order="name" or data-order="surname" for alphabetical.

The “Full profile” button opens a plain blog post

That’s the person’s post in your hidden blog. Put the address of their real page in the post’s Source URL, or add data-hide="profile" to remove the button.

The photos are black and white

That’s the default look, and each one turns to colour when someone points at it or opens the profile. Add data-photos="colour" if you’d rather show them in colour all the time.

The search bar hides under my header when I scroll

The directory 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.

Changes don’t appear straight away

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

Squarespace 7.0 with Ajax loading

Some 7.0 templates load pages without a full refresh. The directory 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 ?team=check panel.