# Pages and Page Cards

Pages and Page Cards give administrators a structured way to compose portal content. A page is a named container with a defined type; page cards are the individual content blocks placed onto that page. Each card has a type, a position in the grid, and its own configuration that controls what it displays and how it looks.

## Table of Contents

* [Overview](#overview)
* [Key Concepts](#key-concepts)
  * [Pages](#pages)
  * [Cards](#cards)
  * [Page Cards](#page-cards)
* [Managing Pages](#managing-pages)
  * [Viewing the Page List](#viewing-the-page-list)
  * [Adding a Page](#adding-a-page)
  * [Editing a Page](#editing-a-page)
  * [Deleting a Page](#deleting-a-page)
* [Managing Cards](#managing-cards)
  * [Viewing the Card Library](#viewing-the-card-library)
  * [Adding a Card](#adding-a-card)
  * [Card Types and Configuration](#card-types-and-configuration)
  * [Editing a Card](#editing-a-card)
  * [Deleting a Card](#deleting-a-card)
* [Composing a Page Layout](#composing-a-page-layout)
  * [Adding Cards to a Page](#adding-cards-to-a-page)
  * [Positioning Cards on the Grid](#positioning-cards-on-the-grid)
  * [Configuring an Individual Card on a Page](#configuring-an-individual-card-on-a-page)
  * [Removing a Card from a Page](#removing-a-card-from-a-page)
  * [Saving the Layout](#saving-the-layout)
* [Relationship to the Container Designer](#relationship-to-the-container-designer)
* [Permissions](#permissions)
* [Troubleshooting](#troubleshooting)

***

## Overview

The Pages and Page Cards system is the foundation for how content is organized and displayed in the portal. Administrators create pages, then populate them with cards. Each card represents a discrete piece of content — a data table, a chart, a KPI metric, a map, or a block of formatted HTML. Cards placed on a page are called page cards, and each one has a position in a responsive grid layout as well as its own type-specific configuration.

This system is separate from the Container Designer, which provides a more advanced visual composition tool for dashboards. Pages and Page Cards offer a direct administrative interface for setting up the fundamental building blocks.

***

## Key Concepts

### Pages

A page is the top-level organizational unit. It has three properties:

* **Title** — A human-readable label used to identify the page throughout the admin interface.
* **Page Type** — A short code (between 2 and 10 characters) that the portal uses to look up and route to the page. This is the technical identifier for the page, so it should be concise and consistent with any naming conventions used in your environment.
* **Description** — A longer explanation of the page's purpose. Required, and may be up to 2,000 characters.

### Cards

A card is a reusable content component that can be placed onto one or more pages. Cards are defined in the card library and have three base properties:

* **Name** — The card's display label.
* **Type** — Determines what kind of content the card renders (see card types below).
* **Description** — An optional explanation of what the card shows, up to 4,000 characters.

In addition to these base properties, each card has a **Configuration** section whose fields depend on the card type.

### Page Cards

A page card is the link between a page and a card. It records which card appears on a page, where it appears (position), and whether any page-specific configuration overrides the card's default settings. When a page card is saved, that card slot becomes part of the page's layout.

***

## Managing Pages

### Viewing the Page List

The page list is available in the Administration section of the portal. It displays a table of all existing pages with columns for Page Type, Title, Description, and modification metadata. The list supports sorting by any column and pagination when there are more than 25 pages.

### Adding a Page

1. Open the page list in the Administration section.
2. Select **Add New Page** in the toolbar.
3. Complete the required fields in the dialog that opens:
   * **Page Type** — Enter a short code (2–10 characters). This is case-sensitive and must be unique.
   * **Title** — Enter a descriptive title (2–250 characters).
   * **Description** — Enter a description of the page (2–2,000 characters).
4. The card layout grid appears in the same dialog. You may add cards to the page immediately or save the page first and edit it later.
5. Select **Save** to create the page.

### Editing a Page

1. In the page list, select the edit icon next to the page, or select the page type link in the Page Type column.
2. The same dialog as Add opens, pre-populated with the current values.
3. Modify the fields or the card layout as needed.
4. Select **Save** to apply changes.

Editing a page and its card layout is done in a single dialog. Any changes to the grid — cards added, repositioned, or removed — are saved at the same time as the page's title, type, and description.

### Deleting a Page

1. In the page list, select the delete icon next to the page.
2. A confirmation dialog appears showing the page title. Confirm to proceed.

The delete action is only available for pages that have no child records. If the delete icon does not appear for a page, the page has associated data that must be addressed before deletion is possible.

***

## Managing Cards

### Viewing the Card Library

The card library lists all available card definitions. It shows the card name, type, description, and modification metadata. Cards listed here are the templates that can be placed onto any page.

### Adding a Card

1. Open the card library in the Administration section.
2. Select **Add New Card** in the toolbar.
3. Complete the required fields:
   * **Name** — A descriptive label for the card (2–500 characters).
   * **Card Type** — Select one of the available card types from the dropdown.
   * **Description** — An explanation of the card's content (optional, up to 4,000 characters).
4. A Configuration section appears below, with fields specific to the selected card type.
5. Fill in the configuration fields as appropriate for the card type.
6. Select **Save** to create the card.

### Card Types and Configuration

The following card types are available when creating or editing a card:

**Table** Displays tabular data. The configuration controls the visual styling of the table header and body rows.

| Configuration field | Description                   |
| ------------------- | ----------------------------- |
| Font Color (Header) | Text color for column headers |
| Font Size (Header)  | Text size for column headers  |
| Font Color (Body)   | Text color for data rows      |
| Font Size (Body)    | Text size for data rows       |

**KPI** Displays a single key performance indicator with a title and a value. The configuration controls the styling of the title and the value separately.

| Configuration field | Description                  |
| ------------------- | ---------------------------- |
| Font Color (Title)  | Text color for the KPI label |
| Font Size (Title)   | Text size for the KPI label  |
| Font Color (Body)   | Text color for the KPI value |
| Font Size (Body)    | Text size for the KPI value  |

**Line Chart** Displays data as a line chart. The configuration controls title and legend visibility and position.

| Configuration field | Default | Description                                    |
| ------------------- | ------- | ---------------------------------------------- |
| Show Title          | On      | Show or hide the chart title                   |
| Title Position      | Top     | Position the title above or below the chart    |
| Show Legend         | On      | Show or hide the legend                        |
| Legend Position     | Bottom  | Position the legend (left, right, top, bottom) |

**Donut Chart** Displays data as a donut (ring) chart. Configuration options mirror the Line Chart type, with the legend defaulting to the right side.

| Configuration field | Default | Description                                    |
| ------------------- | ------- | ---------------------------------------------- |
| Show Title          | On      | Show or hide the chart title                   |
| Title Position      | Top     | Position the title above or below the chart    |
| Show Legend         | On      | Show or hide the legend                        |
| Legend Position     | Right   | Position the legend (left, right, top, bottom) |

**Map** Displays data on a geographic map. The configuration controls text styling.

| Configuration field | Description               |
| ------------------- | ------------------------- |
| Font Color          | Text color for map labels |
| Font Size           | Text size for map labels  |

**HTML Block** Displays free-form HTML content. This card type is used for informational text, formatted announcements, instructions, or any custom HTML the portal should render on a page.

| Configuration field | Description                                                   |
| ------------------- | ------------------------------------------------------------- |
| Content             | A rich text editor for entering the HTML content of the block |

### Editing a Card

1. In the card library, select the edit icon next to the card, or select the card name link in the Name column.
2. Modify the name, type, description, or configuration as needed.
3. Select **Save** to apply changes.

Changing a card's type resets the configuration to the default values for the new type.

### Deleting a Card

1. In the card library, select the delete icon next to the card.
2. Confirm the deletion in the dialog that appears.

Cards that are in use as page cards cannot be deleted until they are removed from their pages. If the delete icon is not present for a card, that card has child records preventing deletion.

***

## Composing a Page Layout

The page layout editor is embedded in the page edit dialog. It presents a responsive grid where cards can be added, moved, and configured. The grid adapts to different screen widths using breakpoints (extra-large, large, medium, small, extra-small), so a layout set up at full width will reflow appropriately on smaller screens.

### Adding Cards to a Page

1. Open the page edit dialog (either when adding a new page or editing an existing one).
2. Scroll down past the Title, Page Type, and Description fields to the layout grid section.
3. Select **Add Card** to insert a new card slot into the grid. The new slot appears at the bottom of the grid.
4. A new card slot starts with an empty name and no type assigned. Give the card a name by typing in the name field at the top of the card slot.
5. Use the card slot's settings menu to configure the card's type and options (see below).

### Positioning Cards on the Grid

Each card slot on the grid can be repositioned:

* **Drag to move** — Click and drag the card slot to a new position within the grid.
* **Move Left / Move Right** — Use the card slot menu to shift the card one column left or right.
* **Resize** — Drag the resize handle at the bottom-right corner of a card slot to change its width and height on the grid. Grid columns are 12-wide at full breakpoint, with each unit representing one column.

Card positions are recorded as grid coordinates (column, row, width, height). When the page is saved, these coordinates are stored along with each page card's configuration.

### Configuring an Individual Card on a Page

Each card slot on the layout grid has a context menu accessed through the layout icon in the top-right corner of the slot. The menu options are:

* **Move Left** — Shift one column to the left.
* **Move Right** — Shift one column to the right.
* **Remove** — Remove this card slot from the page layout.
* **Settings** — Open the card configuration dialog for this slot.

Selecting **Settings** opens a modal where you can:

1. Set or change the card's **Name**.
2. Select the card's **Type** (Table, Donut Chart, Line Chart, Map, HTML Block, or KPI).
3. Optionally add a **Description**.
4. Configure the type-specific settings that control the card's appearance.

Changes made in this dialog apply only to this card's placement on this page. The card definition in the card library is not affected.

### Removing a Card from a Page

Select **Remove** from a card slot's context menu. The slot is removed from the grid immediately. The change takes effect when the page is saved.

### Saving the Layout

Select **Save** in the page edit dialog. The system saves the page's metadata (title, type, description) and then saves all card slots in a single bulk operation. New card slots are created, existing slots are updated with their current positions and configurations, and any slots that were removed are deleted.

***

## Relationship to the Container Designer

Pages and Page Cards provide the direct administrative interface for composing page layouts. The Container Designer is a more advanced visual tool for building dashboard-style layouts with richer card types and event-driven interactions between cards.

Both systems use the card concept, but they serve different use cases:

* Use the **Pages and Page Cards** admin interface when you want to set up a structured page with a defined type identifier, place standard content cards in a grid, and manage those pages centrally in the Administration section.
* Use the **Container Designer** when you need advanced dashboard composition — dynamic data connections, cross-card filtering, interactive drilldowns, or access to the full range of card visualization types including Power BI embeds.

For more information on the Container Designer, see the Container Designer documentation.

***

## Permissions

Access to Pages and Page Cards is controlled by the following permission groups:

**Pages**

| Permission      | What it allows                               |
| --------------- | -------------------------------------------- |
| Pages (default) | View the page list and read page data        |
| Pages.Create    | Add new pages                                |
| Pages.Edit      | Modify existing pages and their card layouts |
| Pages.Delete    | Delete pages that have no child records      |

**Page Cards**

| Permission          | What it allows                                            |
| ------------------- | --------------------------------------------------------- |
| PageCards (default) | View page card data                                       |
| PageCards.Create    | Add new card slots to pages (also required for bulk save) |
| PageCards.Edit      | Update existing card slots (also required for bulk save)  |
| PageCards.Delete    | Remove individual card slots from pages                   |

An administrator assigns these permissions through the role management screen. Users without the Pages default permission cannot access the page list at all.

***

## Troubleshooting

**The delete icon is missing for a page or card.**

The delete action is suppressed when a record has child records. For pages, this means the page has page cards assigned to it. Remove all card slots from the page layout and save before attempting to delete the page. For cards in the library, this typically means the card is referenced by one or more page cards. Remove those references first.

**A page cannot be saved — validation errors appear on Title, Page Type, or Description.**

All three fields are required. Page Type must be between 2 and 10 characters. Title must be between 2 and 250 characters. Description must be between 2 and 2,000 characters. Correct the highlighted fields and try saving again.

**Card configuration fields are blank after changing the card type.**

Changing the card type resets the configuration to the default values for the new type. This is expected behavior. Fill in the configuration fields for the newly selected type.

**Cards do not appear on the grid after saving a page.**

Confirm that the card slots were present in the layout grid before saving. If cards were added but the grid was empty when the dialog was saved, check whether the page edit dialog was closed without saving, or whether a browser error interrupted the save. Re-open the page, add the cards again, and save.

**Changes to card positions are not reflected after saving.**

The layout is saved as a bulk operation at the time of saving the page dialog. If the page was saved while a card configuration dialog was still open (Settings modal), close the inner dialog first, then save the page.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://nimble.docs.otised.com/guides/pages-page-cards.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.