Description
OmniDirectory is one flexible directory engine for searchable WordPress directories: staff, members, professionals, businesses, organizations and more. Every entry has a name, a photo, relabelable directory fields, Phone, Email, Bio, Website, a Directory Category and a profile page, shown in your choice of search and profile layouts. You adapt it to your use case by relabeling fields — no code required.
Add a directory to any page with the [omnidirectory_search] shortcode or with four Gutenberg blocks: Directory Search, Directory Category List, Directory Listings and Member Card.
Use it as a staff, employee, team, member, professional, medical, business, school, church, nonprofit, multilingual or Arabic/RTL directory. These are uses of the same engine, not separate modes with industry-specific fields.
Search
Add the [omnidirectory_search] shortcode, or the Directory Search block, to any page for live AJAX search as visitors type. Search matches the entry’s name and Directory Category (developers can extend it with filters). Only published entries that are not password-protected are listed. Results are cached briefly, refreshed as soon as an entry changes, capped to a configurable limit, and protected by basic rate limiting.
Gutenberg blocks
Four blocks in the “OmniDirectory” block category. They need WordPress 6.0 or later.
- Directory Search — the live search of
[omnidirectory_search], with the same search box and results. - Directory Category List — your directory categories as links to each category’s page, as a list or a grid.
- Directory Listings — a paginated list of published members in your result layouts.
- Member Card — one published member’s photo, name, first two profile fields, categories and a link to the full profile. Phone and email are never shown on the card.
Live search (the shortcode and the Directory Search block), Directory Listings and Member Card show only published members that are not password-protected. Search filters added by other plugins use their own queries and are not covered. Each block’s settings are described under “Using the blocks” below.
Each Directory Listings block pages on its own: moving one list to page 2 keeps every other list on the page where it is. This also applies to lists inside synced patterns in your posts and pages, and to lists in template parts and block widgets. Page links are plain links (they work without JavaScript), and each combination of pages has its own URL, so it can be bookmarked. See the FAQ for bookmarks, synced patterns and page caching.
The shortcode is still supported
The [omnidirectory_search] shortcode keeps working as before, with the same output and attributes, so existing pages need no change. You can keep using it, use the blocks, or use both on the same site.
On a single page, the combination that has been tested is several Directory Search blocks together with an [omnidirectory_search] shortcode: each of them searches on its own. Other blocks on the same page as the shortcode have not been specifically tested.
Arabic, multilingual and RTL
Search normalizes common Arabic letter variants (forms of Alef, ta marbuta / ha, and similar), and every layout uses the correct dir="rtl" or dir="ltr". Directory entries and categories are registered as translatable for Polylang and WPML (wpml-config.xml included).
With Polylang, the Directory Category List, Directory Listings and Member Card blocks show the categories and members of the page’s language; Directory Search searches exactly as the shortcode does. The blocks have not been tested with WPML.
Layouts and fields
- Eight search-result layouts: Modern Grid Cards (default), Horizontal List Row, Avatar Badge Compact, Structured Table View, Masonry Grid, Horizontal Directory List, Compact Table Matrix, Interactive Hover Flip Cards.
- Eight profile layouts: Modern Centered Card (default), Two-Column Sidebar, Hero Banner Top, Tabbed Profile View, Minimalist Clean, Split Screen Cover, Interactive Dashboard, Floating Card Overlay.
- Field labels are relabeled from Settings (e.g. Specialty / Location / Phone, or Department / Office / Phone). Relabeling does not add new fields.
- Documents (PDF, DOC, DOCX, XLS, XLSX, TXT) can be attached to profiles with custom labels; the real file type is checked on upload. A gallery field stores and renders a shortcode you provide.
- Optional Click-to-Reveal masks a profile’s phone and email until clicked (the profile markup holds them only base64-encoded). A light deterrent against simple bots, not privacy or access control: a published entry’s contact details stay public, and its JSON-LD still lists them.
- Profiles include Schema.org
PersonJSON-LD (name, URL, photo, phone, email, website, bio, job title). Theomnidirectory_structured_datafilter ($schema, $post_id) can unsettelephone/email, or return an empty array for none.
CSV import and export
Export downloads every entry as CSV. A cell that a spreadsheet could read as a formula (starting with = + – @, a tab, carriage return or line feed, or their full-width forms = + - @, also after spaces) gets a leading apostrophe, which import removes again. Phone numbers such as +46 70 123 45 67 and plain numbers are left as they are. Spreadsheets may show the apostrophe, and a file edited and saved again in a spreadsheet may lose it. Import replaces the whole directory with the file’s content; it doesn’t edit entries in place.
- The whole file is validated first (header, every row, at most 1,000 rows); an invalid file changes nothing. Headers are matched automatically, including variants such as “Title” or “Phone Number”; unknown columns are ignored and new categories are created.
- New entries are staged privately in the background, then swapped in only when all are ready. Previous published entries, and draft, pending or private entries whose name matches a row, go to Trash, where they can be restored until WordPress empties it. If Trash is turned off on the site (EMPTY_TRASH_DAYS is 0), they are permanently deleted and cannot be restored. The upload must be confirmed. The confirmation states that up to a given number of published entries, and every draft, pending or private entry whose name matches a row, will be replaced, and, when Trash is turned off, that they will be permanently deleted. With Trash turned off, the import then stops before it changes the directory and lists the entries it would delete permanently, in parts of at most 10,000; it deletes only entries on a list an administrator approved, unchanged since then, contents included, and stops to ask again before any other. If Trash is turned off after the upload, the import pauses before it deletes any previous entry permanently, and continues only after an administrator confirms the permanent deletion or Trash is turned on again. Before it finishes, it checks again and goes back if entries were published, renamed or changed while it was finishing, up to three times; then it stops and asks whether to continue or to finish, and lists the entries it did not replace. Entries added or changed after its final check are kept; unpublished entries that are not in the file, and scheduled entries, are kept. If a new entry cannot be given its status, it stays private and the entry it replaces is kept unchanged, together with all of that entry’s Polylang translations; this is listed with a warning. “Resume Import” continues a stalled import.
- Draft, pending and private entries keep their status, and password-protected entries keep their protection (passwords are never exported). A row whose status or protection cannot be kept safely is not imported and is listed with the reason. Files from 4.3.32 or earlier have no Status column: their rows keep the status of the existing entry with the same name, so re-export from this version before moving a directory to another site.
- Featured images are downloaded afterwards in the background (WordPress safe HTTP, limited retries); a failed image never fails the import.
- The uploaded file is stored in
uploads/omnidirectory-imports/under a random name. It is deleted as soon as its rows are staged, or when the import fails or is cancelled (“Cancel Import”). An import still staging that has made no progress for 24 hours is ended, and its file deleted, the next time WP-Cron runs or an administrator opens the Import page or uploads a file. On a site with little traffic or without WP-Cron, this can be later. While the file exists, the web server must block that folder. PHP cannot do this on Nginx, and the plugin cannot stop Nginx from listing or serving the folder without a deny rule. The file’s name is kept out of error messages and logs. Tested: Apache 2.4 withAllowOverride All, which honours the plugin’s.htaccess; Nginx 1.24 withlocation ^~ /wp-content/uploads/omnidirectory-imports/ { deny all; return 404; }. Other servers were not tested.
Polylang: each entry is imported in the language from its Language Code column, and entries sharing a Translation Group value (last export column) are linked again as translations — only when the whole group was imported, one entry per language; otherwise a warning is shown. A file with a Language Code that is not a language of the site is refused before anything changes. Files without a Translation Group column are never linked automatically, not even by name. Translation Group values change after each import (entries are new posts).
Without Polylang (including WPML): a file with any Language Code or Translation Group value is refused before anything changes; empty columns import as before. WPML is not supported for these two columns.
Installation
- Install from Plugins → Add New (search “OmniDirectory”), or upload the zip under Plugins → Add New → Upload Plugin, then activate.
- Go to Directory Members → Directory Settings to set field labels, layouts and colors.
- Add entries under Directory Members → Add New, or import them under Directory Members → Import / Export.
- Show the directory on a page: add the
[omnidirectory_search]shortcode, or open the page in the block editor, click + and add a block from the “OmniDirectory” category (or search for “Directory”).
Using the blocks
Select a block to see its settings in the editor’s sidebar. The setting names below are the ones shown there.
Directory Search
- Show title: shows or hides the title above the search box.
- Title: leave empty to use the title from Directory Settings.
- Placeholder: the text in the empty search box; leave empty to use the placeholder from Directory Settings.
- Results per page: how many results the live search shows at once, 1–50; clear it to use the number from Directory Settings.
The block shows the same search box and results as [omnidirectory_search].
Directory Category List
- Layout: list or grid.
- Order by: name, or number of members.
- Show sub-categories nested: nested under their parent, or one flat list.
- Show number of members; Hide empty categories.
- Maximum top-level categories: up to 100; clear it to show all. In a flat list, every category counts as top-level.
- Parent category ID: show only the sub-categories of this category; 0 shows all.
Each category links to that category’s page. Searching the block inserter for “Directory Categories” also finds this block. On WordPress 6.5 and later the inserter also lists WordPress’s own block named “Directory Categories”, which shows the current post’s categories instead.
Directory Listings
- Title: an optional heading above the members.
- Layout: any of the eight result layouts, or the site default from Directory Settings.
- Members per page: 1–50; clear it to use the Directory Settings value.
- Order: Name (A–Z) or Newest first.
- Category: type to search your categories; the list includes the category’s sub-categories. All categories shows all members.
- Show pagination: on or off.
A page number beyond the last page shows the last page. Feeds and embeds show the first page, without page links. You can place several Directory Listings blocks on one page; each keeps its own page. In the editor, the block shows a preview of the first page; page links work on the published page.
Member Card
- Member: type to search your published members and choose one.
- Layout: Vertical or Horizontal.
- Show photo (an initial is shown when there is no photo), Show profile fields (the first two, with their labels), Show categories, Show “View profile” link.
The card never shows phone or email. With Polylang, it shows the member’s published translation in the page’s language when there is one.
FAQ
Which kinds of directory can I build?
Staff, member, employee, professional, medical, business, school or other directories of people or listings, by relabeling the built-in fields and choosing layouts. There are no industry-specific fields (for example for courses or departments).
Does it support Polylang and WPML?
Polylang can translate entries and categories. For WPML, the included wpml-config.xml registers them as translatable; WPML itself has not been tested with this release. CSV import keeps languages and translation links with Polylang only; see “CSV import and export” for WPML.
The blocks were tested with Polylang: Directory Category List, Directory Listings and Member Card show the page’s language, and Directory Search searches as the shortcode does. The blocks have not been tested with WPML.
Can I add unlimited custom fields?
No. You can relabel the existing fields, but this plugin does not add new ones.
Does CSV import update existing entries?
No. It replaces the directory with the file’s content; previous published entries, and draft, pending or private entries whose name matches a row, go to Trash, or are permanently deleted if Trash is turned off (other unpublished entries not in the file and scheduled entries are kept).
Are there Gutenberg blocks?
Yes, four: Directory Search, Directory Category List, Directory Listings and Member Card. See “Gutenberg blocks” and “Using the blocks”.
Do I have to replace the shortcode with blocks?
No. [omnidirectory_search] is still supported and works as before, so existing pages need no change. The Directory Search block shows the same search box and results as the shortcode.
You can use the blocks and the shortcode on the same site. On a single page, several Directory Search blocks together with an [omnidirectory_search] shortcode have been tested, and each searches on its own. Other blocks on the same page as the shortcode have not been specifically tested.
How does pagination work with several lists on one page?
Each Directory Listings block reads its page from its own address parameter (for example ?omni-page-<id>=2). Moving one list to another page keeps every other list where it is. This also applies to lists inside synced patterns in your posts and pages, and to lists in template parts and block widgets. Page links keep the pages of the other lists and drop unrelated query parameters. The links are plain links, so they also work without JavaScript.
Do Directory Listings pages work with page caching?
Each page of a list has its own URL. A cache that stores every URL, including its query string, as a separate page should keep the list pages apart, and a cache that does not cache URLs with a query string should pass them through. Do not configure a cache to ignore query strings and serve one copy for all of them: list pages beyond the first would then show page 1.
In our tests on WordPress 7.1, with several lists on one page, for visitors and logged-in users, each list kept its own page with WP Super Cache 3.1.5 and W3 Total Cache 2.11.0 (with their default settings, and with caching of URLs with query strings turned on), and with Cache Enabler 1.8.16 and LiteSpeed Cache 7.9.2 on OpenLiteSpeed 1.9.4 (with their default settings). Cache Enabler set to cache URLs with query strings showed page 1 for every list page, because it stores one copy per address without its query string; keep its default (URLs with query strings are not cached) on sites with Directory Listings.
After you add, edit or remove a member, a page cache can keep showing the old details on other pages with lists until that cache is purged or expires. In our tests, W3 Total Cache refreshed only the edited member’s page and the home page, and LiteSpeed Cache with its default purge rules refreshed all pages and the home page but not posts that contain lists. With W3 Total Cache, pages listed under Performance → Page Cache → Purge Policy → “Additional pages” are refreshed too; for LiteSpeed Cache, see Cache → Purge → “Auto Purge Rules For Publish/Update”. Otherwise, purge the page cache after editing members. CDNs and LiteSpeed Enterprise have not been tested.
Does it work with AMP?
In our tests with the AMP plugin 2.5.5 on WordPress 6.7, AMP pages showed the blocks, and Directory Listings page links worked and stayed on the AMP version. Live search needs JavaScript, which AMP does not allow, so on AMP pages the search box is replaced by a link to the regular version of the page, where live search works. In AMP Standard mode, where every page is an AMP page, a short notice is shown instead. With AMP’s default settings, member profile pages were not AMP pages. In our tests with AMP 2.5.5 on WordPress 7.1.3, result cards kept their photo fallback attribute (onerror), which predates 4.4.0; the AMP plugin removed it from AMP pages and reported it as a validation error (DISALLOWED_ATTR). Member profiles are not fully supported as AMP pages: when we added them to AMP’s supported content types (same tests), AMP removed OmniDirectory’s profile scripts and their jQuery dependencies, as well as WordPress core’s speculation-rules script, and reported them as validation errors. Profile features that need these scripts were not tested there. Other AMP versions, and Reader mode with other reader themes, have not been tested.
How do lists in synced patterns work?
Each use of a synced pattern that contains a Directory Listings block pages on its own. To keep its pages apart from the pattern’s other uses, each use gets its own identity, which is stored in your post or page the next time you save it in the block editor. OmniDirectory does not change the pattern’s shared content.
Until that identity is stored, the list’s page links use a temporary address. Usually this lasts only until the next save. In our tests on WordPress 6.9, 7.0 and 7.1, the editor loads a synced pattern’s content in the background, and a save made before it has loaded waits up to 8 seconds for it. If the content arrives later, or cannot be loaded, the save goes ahead and the identity is stored at the next save.
This applies to synced patterns in the content of a post or page. Synced patterns placed in block widgets, template parts or templates have not been tested.
Do editor actions such as Undo change a list’s page links?
Not in our tests, which used synced patterns in post content. Once a use’s identity had been stored, reordering or moving that reference by cutting and pasting, and using Undo or Redo, kept its identity, so its page links stayed the same. Copying or duplicating a reference creates a new identity for the new use; the original keeps its identity.
Do bookmarked list pages keep working?
Yes, in most cases. In our tests, a bookmarked page of a Directory Listings block kept opening the same page of that list after the post was edited and saved again, or after its lists were reordered. The members shown on that page can change as your directory changes.
This also holds for a list in a synced pattern that is used once in the post, even if the page was bookmarked while its links still used a temporary address (see “How do lists in synced patterns work?”): after the identity is stored, the bookmark keeps opening the same page.
When the same synced pattern is used more than once in a post, bookmarks made while the links used temporary addresses behave as follows:
- If the post still uses the pattern more than once when the identities are stored, these bookmarks open page 1 from then on.
- If the first of two uses is deleted before the identities are stored, the deleted use’s bookmark opens the remaining use, at the bookmarked page. The remaining use’s own earlier bookmark opens page 1.
- If the second of two uses is deleted before the identities are stored, the first use’s bookmark keeps working, and the deleted use’s bookmark opens page 1.
- If the two uses are swapped and the post is saved before the identities are stored, each use’s earlier bookmark opens the other use until the identities are stored. From then on, both open page 1.
In our tests, such a bookmark opened at most another use of the same pattern, which shows the same members; no other list on the page was affected, and every list’s own page links kept working. Bookmarks made after the identities are stored are not affected by any of this.
Bookmarks for synced patterns in block widgets, template parts or templates have not been tested.
Is the console error in the WordPress 6.0 editor preview a known issue?
Yes. On WordPress 6.0, the block editor logs a JavaScript console error (“Cannot destructure property ‘frameElement'”) when the editor preview is switched from Mobile back to Desktop. In our tests it appeared on pages containing an OmniDirectory block, and the same error was reproduced with WordPress’s own Latest Posts block while OmniDirectory was deactivated. It did not occur in our WordPress 6.2 tests.
What is it not designed for?
Membership management (registration, logins, gated content), marketplaces or e-commerce, bookings, reviews/ratings and affiliate features.
My site is behind a reverse proxy or CDN. Does rate limiting still work?
Limits use REMOTE_ADDR. Behind a proxy, return the real visitor IP with the omnidirectory_client_ip filter (only from a header your proxy sets). Limits can be changed with omnidirectory_rate_limits.
Can other plugins add CSV export columns?
Yes, with the omnidirectory_csv_export_columns and omnidirectory_csv_export_value filters. Extra columns come after this plugin’s columns and cannot change them.
Screenshots
Changelog
4.4.0
- New: four Gutenberg blocks in the “OmniDirectory” category — Directory Search, Directory Category List, Directory Listings and Member Card (WordPress 6.0 or later).
- New: each Directory Listings block pages on its own, with plain links that work without JavaScript and a URL per page that can be bookmarked — also for lists inside synced patterns and in template parts and block widgets.
- The
[omnidirectory_search]shortcode is still supported, with the same output and attributes; settings and existing pages are unchanged. - Accessibility: the search box’s category filter and search field have accessible names, also without placeholder text; photos in result cards and Member Cards are no longer announced besides the member’s name; darker green profile Call buttons; visible keyboard focus rings on Call buttons, result cards and the Member Card link (checked on Twenty Twenty-One, -Two and -Five); Member Card labels are no longer faded; on block themes that show the post title as the main heading, the profile’s member name is a level-2 heading.
- Fix: members without a photo show their initial placeholder in result cards and profiles; previously an empty image was shown.
- Fix: a photo file that cannot be loaded is replaced by the initial placeholder on the Member Card and the profile (not on AMP pages; with Polylang, not after every language switch).
- Fix: Flip Cards result layout: cards were shown collapsed; they now have their full size and turn over on hover and on keyboard focus. The back of the card uses black text when the Primary Accent Color is too light for white text.
- Fix: renaming or deleting a Directory Category takes effect in live search immediately.
- AMP: on AMP pages the search box is replaced by a link to the regular version of the page (a short notice in AMP Standard mode). Known AMP limits, including member profiles set up as AMP pages: see the FAQ.
- Tested caching plugins and their limits: see the FAQ on page caching. Not tested: the blocks with WPML; CDNs.
- Security: live search no longer lists password-protected members, like Directory Listings and Member Card.
- Security: CSV export also protects cells that start with a line feed or with the full-width = + - @, or with spaces before a formula character.
- Privacy: the stored import file has a random name, kept out of error messages and logs, and is deleted as soon as its rows are staged. An import still staging can be cancelled; one with no progress for 24 hours is ended the next time WP-Cron runs or the Import page is used.
- Import: “Upload and Replace Directory” asks for an explicit confirmation that up to a given number of published members, and draft, pending or private members whose name matches a row, will be replaced; with Trash turned off, a separate warning and confirmation say they will be permanently deleted, and the import shows the exact list for approval before it deletes any of them. If Trash is turned off during an import, it pauses before it deletes any previous member permanently.
- Settings: the Click-to-Reveal option is described as a light anti-spam deterrent; it does not make contact details private.
- Tested in Chromium on Linux with WordPress 6.0 to 7.1 on PHP 7.4 and 8.3. Firefox, Safari and Google Chrome were not tested. Accessibility was checked with automated tests (axe) and keyboard navigation, not with screen readers; this is not a statement of WCAG conformance.
- Known limits: only the back of Flip Cards switches to black text; other elements in the Primary Accent Color keep white text, so choose a color dark enough for it. The Member Card link’s hover contrast is about 4.35:1 with the default color. More in
changelog.txt. - Developers: new functions and hooks for add-ons that extend the blocks (see
changelog.txt). - Full details, including bookmark notes for synced patterns: see
changelog.txt.
4.3.34
- Fix (Polylang): profile URLs in a non-default language (e.g.
/ar/omni-directory/…) no longer stay broken after OmniDirectory or Polylang is activated or reactivated. Rewrite rules are now rebuilt once Polylang has added its language rules; sites already affected are repaired once after updating. - Fix: CSV files not saved as UTF-8 (e.g. Windows-1252 or UTF-16) are refused before anything changes, with the affected line named, instead of importing members with empty names.
- Fix: an import whose progress cannot be saved no longer repeats the same batch; it stops or pauses safely and can be resumed. Long non-Latin names in import warnings no longer stall an import.
- Full details: see
changelog.txt.
Older versions and full details: see changelog.txt.




