A directory lets Portal visitors search your contacts or organizations. If you allow it, visitors can open an entry’s details or send a message. This article explains how to create and configure a directory from Setup. To place a directory on a Portal page after you create it, see Add Directories to Portal Pages.
Prerequisites
- You need access to your account’s Contacts or Organizations setup, specifically Directories.
- Review the fields in your Contacts or Organizations query before you choose searchable and display fields, because directory fields come from that same field list.
Where to Find It
For a contact directory, go to Setup › Contacts › Directories, then select Create Contact Directory. For an organization directory, go to Setup › Organizations › Directories, then select Create Organization Directory. Each page lists every directory of that kind in your Rhythm account, with options to edit or delete it.
Basic Information
Every directory needs a Name. When you create the directory, Rhythm suggests an identifier based on the name, and you can change it before you save for the first time. After you save, you cannot change the identifier. Two directories can have the same name because Rhythm does not check for duplicate names, but each identifier must be unique among directories of the same kind.
A new directory includes a practical set of default search and display fields, so you start with a working setup instead of a blank form. Those defaults apply only when you create a new directory, not when you edit an existing one.
The Settings
| Setting | Effect |
|---|---|
| Searchable Fields | Choose the fields visitors can use to search the directory. You can reorder fields with the arrows, add a group name to visually group a searchable field with the fields after it, and override the label visitors see for any field. |
| Additional Fields | Choose extra fields to display in your custom result template. Searchable fields are always available for display too. |
| Directory Messaging | Let visitors send a message to a contact while they view that contact’s directory entry. This setting works only for contact directories; organization directories cannot relay messages. |
| Radius/Distance Search | Let visitors search within a distance of a location, using the postal code field you choose and the radius options you set, in miles. |
| Rule-Based Directory Constraints | Add filters that limit who appears in the directory based on attributes of the contact, organization, parent organization, or membership. |
| Expression-Based Directory Constraints | Add an advanced expression-based filter for cases the rule-based filters cannot cover. |
| Custom Sorting | Change the order in which directory results appear. |
| Custom Search Results Template, Directory Entry | Replace the built-in result and entry designs with your own HTML and CSS. Rhythm uses your HTML only when Use Custom Template is selected. |
Tip
Members who have opted out of directories are always excluded automatically, no matter what filtering expression you write under Expression-Based Directory Constraints.
The searchable fields and additional fields you choose become merge fields when you write a custom result or entry template. Contact directory templates can also use merge fields from the contact’s organization, the organization’s parent organization, and the contact’s membership. Organization directory templates can use the organization’s own fields, its parent organization’s fields, and its contacts’ fields. The available variables differ by template type: a search result template mostly uses the searchable and additional field names themselves, while an entry template exposes those same details under objects such as contact.* or organization.*, for example contact.image_url and contact.full_name instead of plain field names.
Choosing Fields
Searchable and additional fields come from the same field list your account’s Contacts query or Organizations query offers, including your custom fields. A custom field must already be created under Setup and associated to the relevant form before it can capture data. After that, it becomes available in the query, and then you can add it to a directory. If a field is not available in that query yet, such as a custom field you just created, it will not appear here until it is available there.
Tip
Whether a visitor who is not signed in can see a contact’s photo in a public directory depends on where the photo file is stored. Photos uploaded directly through the console or Portal are stored where anonymous visitors can see them. Photos brought in through an import may be stored where only signed-in visitors can see them, though a signed-in visitor can see a contact’s photo either way. If an imported photo does not display for a visitor who is not signed in, re-uploading it directly through the console or Portal and updating the contact’s image address typically restores it.
Dependencies and Precedence
- An existing saved query cannot be attached to a directory as its data source. If you already have a saved query that finds the people or organizations you want, use it only as a reference for the fields and criteria to recreate. You still build the equivalent filtering with the directory’s own Rule-Based or Expression-Based Directory Constraints.
- Rule-based constraints only limit who is found by a search. They do not prevent someone from opening or messaging a specific entry directly if they already have its identifier, so a rule-based filter does not hide a record’s details from someone with the link.
- A directory's default entry layout comes from Rhythm's own defaults unless you turn on a custom template. Changing Rhythm’s default design later requires a Rhythm release; a directory using the default is not automatically updated by anything you configure yourself.
- The searchable-fields list also decides what a save-time refresh rebuilds. When you save a directory, Rhythm clears its cached search results so the next search reflects the current configuration and data.
Change Impact and How to Revert
When you edit a directory’s fields, filters, or layouts, visitors see the change as soon as you save. There is no separate publish step. Deleting a directory from the setup pages is permanent, and there is no restore option. If you delete a directory while a Portal page still names it, that page’s directory block stops working. Remove or reconfigure the block on the affected page too.
Warning
Your account can hold only a limited number of directories in total, with a very large ceiling that ordinary use is unlikely to reach. If you are consolidating directories, delete the ones you no longer use instead of leaving them inactive. A directory has no separate active or inactive state; it either exists or it does not.
Permissions
Setting up and changing directories requires access to your account’s Contacts or Organizations setup, specifically Directories. Portal members cannot create, change, or delete directories; the Portal only searches and reads them.
Validation and Errors
| Message contains | Cause | Fix |
|---|---|---|
| A record already exists with this name | The identifier you are creating already matches one in use. Rhythm checks this when you create a directory, not when you edit one. | Choose a different name or identifier. |
| The save is refused naming the name | The Name field is empty. | Enter a name. |
A directory’s identifier accepts only the characters Rhythm allows, and Rhythm refuses disallowed characters when you save. Because you cannot change the identifier after the first save, review it carefully on the create form before you save for the first time.
If an organization directory’s search results appear normally but an individual entry page stays stuck loading, check that directory’s custom Directory Entry template first. A template issue there is a practical place to start.