Directory

Part of the IP4CMS portal. ← All module guides

What it's for — The Directory is a member-facing list of important numbers, services, and organisations (emergency contacts, municipal departments, security, clinics, utilities, and so on). You build and maintain the list of entries here in the portal; published entries are then served to your member portal/app as a grouped contact directory. Each entry can carry a title, a heading, a description, an email, a primary number, and an additional number, and can be grouped under a category.

Where to find it — Main navigation: Directory (route /app/directory). The landing screen is the Directory items grid. Categories are managed separately under Settings → Directory → Directory categories (route /app/settings/directory-categories).

Before you start

• The Directory licence module must be enabled for your tenant. If it isn't, the Directory nav item does not appear.
• You need directory permissions on your role (see Permissions & access). At minimum you need a read permission to open the module; you need create/update to add or edit entries, publish to expose entries to members, and directory:manage:categories to manage categories.
• Decide your category structure first (e.g. "Emergency", "Municipal", "Security", "Health") if you want entries grouped in the member view — it's easier to assign categories as you add entries than to retro-fit them.

Key tasks

Add a directory entry

1. Go to Directory.
2. Click Add item (top right). A dialog opens with the entry form.
3. Complete the fields:

• Title (required) — the name of the contact/service/organisation. This is the only mandatory field.
• Heading (optional) — a short label/sub-heading shown with the entry.
• Description (optional) — free rich text (formatted via the editor). Max ~2000 characters.
• Email (optional) — contact email address.
• Number (optional) — the primary phone number.
• Additional number (optional) — a secondary number (e.g. after-hours line).
• Category (optional) — choose an existing category, or leave as None. Entries with no category appear ungrouped in the member view.

1. Click Create. The entry is saved and the grid refreshes.

Note: entries created through this form are saved as PUBLISHED by default (the form defaults the status to Published). See Draft vs publish for how status controls member visibility.

Edit a directory entry

1. On the Directory items grid, find the entry (use the search box — it searches title, heading, description, email and both numbers — or the Category filter).
2. Click Edit on that row. The same form opens pre-filled.
3. Change any fields and click Update.

Delete a directory entry

1. Find the entry on the grid and click Delete.
2. Confirm in the prompt. The entry is removed from the grid and from the member view. (Deletion is a soft delete — the record is retired but kept for audit history, so it stops appearing everywhere but isn't physically destroyed.)

Add and manage categories

Categories group entries in the member-facing directory.

1. Go to Settings → Directory → Directory categories (/app/settings/directory-categories).
2. Click Add category, enter a Name, and save. New categories are appended to the end of the order.
3. To rename a category, click Edit, change the name, and save.
4. To reorder categories, use the Up / Down controls. Category order determines the order groups appear in the member view.
5. To remove a category, click Delete and confirm.

Managing categories requires the directory:manage:categories permission. The Categories path under the Directory module redirects to this Settings screen.

Order entries within the list

Entries have a manual order that drives both the admin grid (default sort) and the member view (order within each category).

1. On the Directory items grid, use the Up / Down buttons on each row to move an entry one position.
2. The grid re-sorts to order and reloads after each move.

How ordering works: the system keeps entries in a single ordered sequence and swaps an entry's position with its nearest neighbour when you move it. Gaps or duplicate order values are automatically re-sequenced before a move, so ordering stays consistent even after deletions.

Draft vs publish (the status workflow)

Every entry has a status: DRAFT, READY, or PUBLISHED. Only PUBLISHED entries are visible to members.

• Create as draft, publish later — entries can be created in a draft state and only exposed to members once published. (Note: the standard Add form defaults new entries to Published; entries set to a non-published status via the API/import stay hidden from members until published.)
• Publishing an entry sets its status to PUBLISHED, stamps the publish time, and records which user published it. Publishing requires the directory:publish (or directory:update) permission.
• Until an entry is published, it does not appear in the member portal/app directory.
• Readers with only published-level access (directory:read:published) cannot see or open draft/ready entries — those are visible only to staff with full directory access.

Search and filter the grid

• Search — type into the search box and press Enter. Matches title, heading, description, email, number, and additional number.
• Category filter — use the toolbar Category filter (or Add filter → Category) to show only entries in a chosen category.
• Sort — click the Title or Created column to sort; the default sort is by manual order.
• Rows per page — 10, 20, 50, or 100.
• Clear — removes active filters and search.

See the member/public view

Members see the published directory through the member portal/app, not through this admin screen. The member view is grouped by category: categories appear in category order (then alphabetically), with each category's entries shown in their manual order. Entries with no category are grouped together as uncategorised. Only published entries appear, and member-facing readers never see staff-only metadata (status, publish details). To preview what members will see, publish your entries and check the member portal/app directory.

How the data connects

What you enter → where it's stored

• Each directory entry is stored as an important number record (table important_number) on your tenant, with fields: title, heading, description, email, number, additional number, order, status, category link, plus publish metadata (published-at / published-by) and audit timestamps.
• Each category is stored as a directory category record (table directory_category) with a name and an order value. An entry links to at most one category.

What it feeds

• The admin grid (GET /directory) shows all entries to staff with full access, joined to their category name, with search/filter/sort and pagination.
• The member view (GET /directory/member) returns only published entries, grouped by category in display order, for the member portal/app. This is the public/member-facing directory.
• Create, update, delete, and publish actions write audit history (entity type important_number) capturing the actor and field-level changes (e.g. title, heading, status).

Status gate: the single lever between "what you maintain" and "what members see" is the entry's status. Draft/Ready entries live only in the admin grid; Published entries flow through to the member directory.

Permissions & access

Access is governed by the Directory licence module plus role permissions:

Notes:

• admin:full:access grants full directory access.
• The Add item button shows for operators with create or update. Edit requires update; Delete requires delete. The Up/Down reorder controls and publishing require update (or publish).
• Member visibility: members only ever see published entries, served through the member view. They do not access this admin module, and they never see draft entries, status, or publish details.
• The Directory nav entry only appears when the directory module is licensed for the tenant and the operator holds a directory read permission.

Tips & gotchas

• New entries are published by default. The standard Add-item form sets status to Published, so an entry you create here goes live to members on save. If you need to stage content before members see it, treat publishing as deliberate and confirm status before saving (or build the entry first and review before exposing it).
• Title is the only required field. Everything else (heading, description, email, both numbers, category) is optional — but an entry with no number/email gives members nothing to act on, so fill in at least one contact detail.
• Uncategorised entries still show. Leaving Category as None doesn't hide an entry; it appears in an ungrouped section of the member view. Assign a category if you want it grouped.
• Order is global, then grouped. Reordering on the admin grid sets a single global order across all entries; in the member view that order is applied within each category. So an entry's neighbours in the admin grid may differ from its neighbours in the member view once categories are involved.
• Category order matters for members. The sequence of category groups in the member directory follows the category order you set in Settings (then alphabetical). Reorder categories there, not on the entries grid.
• Deleting a category doesn't delete its entries — those entries simply become uncategorised. Re-assign them if you want them grouped elsewhere.
• Export is a placeholder. The Export button on the grid currently shows an informational message only; there is no CSV/Excel download yet.
• Two numbers per entry. Use Number for the primary line and Additional number for a secondary/after-hours line — both are plain text, so you can format them however members expect to dial them.
• Categories live under Settings. They're not on the Directory grid screen — manage them at Settings → Directory → Directory categories (the in-module Categories link redirects there).