Building a directory

Three blocks turn a template project into a working directory over anything your site already models: a listings post type, a staff page, your member roll. Members can browse it, open one entry, edit their own, and delete them.

This page is about wiring the three together. What each one draws is covered in Blocks.

Your site needs Advanced Custom Fields, because the fields these blocks show are the ones you set up there. You do not define fields in the builder.

The three screens

A directory is normally three screens in one template project.

Screen	What is on it
Browse	One Entry List block
Detail	Entry Field blocks, laid out with headings, images and sections
Edit	One Entry Form block, set to edit

Only the browse screen goes into your navigation. The other two are opened by the list, and the builder places them for you.

Wiring it up

Make the three screens in one project. Name them so you can tell them apart in a dropdown later.
On the browse screen, add an Entry List. Set Entries are to a post type or to Members, then pick the Field group ACF attached to it. If the dropdown is empty, choose one of your apps above the canvas so the builder can read that site.
For a Members list, tick its Roles. The list shows members in those roles and nobody else. Tick at least one: the screen will not save without it.
On the detail screen, add Entry Field blocks. Each one shows either an ACF field or a part of the entry itself: title, summary, body, featured image, author or date. Arrange them with the ordinary blocks. This is a canvas like any other, so headings, spacers, dividers and sections all work.
On the edit screen, add an Entry Form and set This form to Edits the entry on screen. Give it the same post type and field group as the list.
Back on the Entry List, point the actions at those screens. View opens takes the detail screen, Edit opens takes the edit screen.

That last step is the chain. Until a screen is named, the matching action is hidden rather than drawn doing nothing.

In the app, the detail and edit screens open inside the tab the list is in: a back bar titled with the entry, and your bottom navigation still underneath. Back returns to the list, and a Button set to Back on the detail screen does the same. Tapping another tab leaves them.

Per page sets how many entries load at a time. There are no page buttons: the next page loads as the member scrolls to the end of the list.

The chain places screens for you

When you place the browse screen in navigation, the builder adds the screens it opens to the Background zone automatically. Background features are not in any navigation bar. They exist so a screen that is only ever reached by tapping something still has settings of its own.

You do not have to place them, and you should not place them in a visible zone unless you want a member to reach the detail screen without going through the directory.

The chain follows links as far as they go, so a detail screen that itself holds a directory brings its own detail screen along too.

Two things are worth knowing about it:

It only ever adds. Repointing an action leaves the old screen in the Background zone rather than deleting it, because a background feature carries appearance settings and losing those to a dropdown change would be worse than a spare row. Delete it yourself when you mean to.
It is about the builder, not the app. A linked screen is included in a build whether or not it appears in the Background zone. Placing it is what lets you see it and style it.

What members are allowed to do

Every action obeys your site, checked one entry at a time.

Edit and Delete appear only on entries WordPress says that member may change. A member browsing a shared directory sees them on their own entries and not on anyone else’s.
A member who cannot publish gets Pending review instead of published, the same downgrade wp-admin makes for a contributor.
Delete uses the trash, so a mistake is recoverable from wp-admin. Sites that have turned the trash off delete immediately, because there is nowhere for the entry to go.

Turn on Only their own entries for a directory that is each member’s own list rather than a shared one. It also lets them see their own drafts, which a shared directory never shows.

New members are not created here. Entries are: Members can edit a member’s fields, but accounts come through registration, which runs your sign-up checks and sends your welcome email.

Members lists

Your site holds a Members list to the roles you ticked, not only the app. The builder sends those roles to your site when you save the template or the app, and your site answers with members in those roles whatever the app asks for.

A member cannot open anyone outside those roles, even by editing the request. Your site answers as if that member did not exist.
Accounts that are pending review, rejected or inactive never appear, and neither does anyone who ticked Hide my profile from directory. The viewer’s Ultimate Member role settings for which roles they may view apply as well.
The search box matches names. It never matches email addresses or usernames.
A member’s own account is always open to them. Someone who can list users in wp-admin is not held to the ticked roles, though the list still shows them only those roles.

A worked example: a member-run listings directory

Say you sell listings and each member manages their own.

Browse screen. An Entry List on the listing post type, Only their own entries on, one column, with a search box and a range filter on your Price field. All three actions on.
Detail screen. An Entry Field showing the featured image, one showing the title as a heading, then fields for price, location and description.
Edit screen. An Entry Form set to edit, same post type and field group.
Add screen. A fourth screen with an Entry Form set to Adds a new entry, and After saving, open pointing at the detail screen so a member sees what they just created. Reach it with a Button on the browse screen.

Place the browse screen in your bottom navigation. The other three arrive in the Background zone on their own.

When it does not work

Symptom	Cause	Fix
The field group dropdown is empty	No app is chosen above the canvas, or ACF has no group on that post type	Pick one of your apps, or attach a group in ACF
View or Edit never appears	No screen is named for that action	Set View opens or Edit opens
Edit and Delete never appear	The site says this member may not change those entries	Check the role, or turn on Only their own entries
The detail screen is blank	The Entry Field blocks name fields from a different group	Give the detail screen’s fields the same group the list uses
An edit form is empty	Its This form is set to add rather than edit	Set it to Edits the entry on screen
The list is empty on a site with entries	Nothing is published, or Only their own entries is on and this member has none	Publish an entry, or turn the setting off
A dropdown filter has no choices	The field is not a choice field	Use a text box for text, or a range for numbers
The screen will not save: “Choose at least one role for a Members list.”	A Members list has no role ticked	Tick at least one role under Roles
A Members list is empty	No member in the ticked roles is approved and visible	Tick a role that has one, or approve the account in wp-admin
A Members list went empty after an update	It was saved before roles existed, so your site allows none	Tick its roles and save
A member you expect is missing	Their account is pending, rejected or hidden from the directory, or the viewer’s Ultimate Member role may not view that role	Approve the account, or change the viewer’s role settings
No more entries load at the end of the list	Every page has loaded	Nothing to fix

Blocks covers every setting on the three Entry blocks.