# Cards and Card Data ## Table of Contents * [Overview](#overview) * [Getting Started](#getting-started) * [Understanding Cards](#understanding-cards) * [What Is a Card?](#what-is-a-card) * [Card Types](#card-types) * [Card Configuration](#card-configuration) * [Managing Card Definitions](#managing-card-definitions) * [Viewing the Card List](#viewing-the-card-list) * [Creating a Card](#creating-a-card) * [Editing a Card](#editing-a-card) * [Deleting a Card](#deleting-a-card) * [Understanding Card Data](#understanding-card-data) * [What Is Card Data?](#what-is-card-data) * [School Year Scoping](#school-year-scoping) * [Entity Association](#entity-association) * [JSON Data Payloads](#json-data-payloads) * [Managing Card Data Records](#managing-card-data-records) * [Viewing Card Data](#viewing-card-data) * [Creating a Card Data Record](#creating-a-card-data-record) * [Editing a Card Data Record](#editing-a-card-data-record) * [Deleting a Card Data Record](#deleting-a-card-data-record) * [Cards in Pages and Containers](#cards-in-pages-and-containers) * [Pages and Page Cards](#pages-and-page-cards) * [Placing Cards on a Page](#placing-cards-on-a-page) * [Card Position and Layout](#card-position-and-layout) * [Relationship to Containers](#relationship-to-containers) * [Common Scenarios](#common-scenarios) * [Troubleshooting](#troubleshooting) ## Overview Cards are the reusable visual building blocks of OtisEd.Nimble dashboards and pages. A card is a self-contained component that displays a specific type of content — a data table, a chart, a key performance indicator, a map, or a block of formatted text. Administrators define cards centrally and then place them on pages, where they appear to end users. Card Data is the mechanism that associates a data payload with a specific card. When a card needs to display real data — for example, a table card showing enrollment numbers or a KPI card showing an attendance rate — a card data record provides the actual values, scoped to a school year and an organizational entity such as a district or school. This guide covers the full lifecycle of cards and card data: how to define card types, configure their appearance, attach data to them, and understand how they connect to the broader page and container system. ## Getting Started Access to Cards and Card Data is controlled by separate permissions. * To view the card list: your account needs the **Cards** permission. * To create or edit cards: your account needs the **Cards Create** or **Cards Edit** permission. * To delete cards: your account needs the **Cards Delete** permission. * To view, create, edit, or delete card data: your account needs the corresponding **Card Datas** permissions. If you expect to see Cards or Card Data sections in the administration menu but cannot find them, contact your administrator to confirm that the appropriate permissions have been granted to your role. Cards that have been placed on pages can only be deleted if they have no page card associations. The delete action is disabled for cards currently in use on one or more pages. ## Understanding Cards ### What Is a Card? A card is a named, typed, reusable visual component. You define it once and can place it on any number of pages. The card definition stores three things: * **Name** — a short label used to identify the card in administration screens (required, 2–500 characters). * **Type** — the kind of visual component the card renders, such as a table or a chart (required, 2–100 characters). * **Description** — a longer explanation of the card's purpose (required, 2–4000 characters). * **Configuration** — a JSON object that controls the card's visual appearance, stored automatically when you choose a card type and set configuration options through the form. Cards are fully audited: the system records who created each card and when, and who last modified it. ### Card Types When you create or edit a card, you choose from the following card types: | Type | Description | | ----------- | --------------------------------------------------------------------------------------------------- | | Table | Displays data in rows and columns with a configurable header and body style. | | Donut Chart | Renders a donut-style circular chart with a configurable title and legend. | | Line Chart | Renders a line graph with a configurable title and legend. | | Map | Displays a geographic map with configurable font settings. | | HTML Block | Renders free-form HTML content authored in a rich-text editor. | | KPI | Displays a single key performance indicator value with a title and body, each independently styled. | The type you choose determines which configuration fields appear in the form. If you change the card type, the configuration fields reset to the defaults for the new type. ### Card Configuration Each card type exposes a set of configuration options. These are saved as a structured JSON object alongside the card definition and control the visual presentation of the card when it renders on a page. **Table and KPI cards** expose two separate style sections: * **Header / Title** — font size and font color for the top row or title area. * **Body** — font size and font color for data rows or the KPI value. Font sizes are entered as CSS values such as `12px` or `1rem`. Font colors accept any CSS color value, such as `black`, `#333333`, or `rgb(0,0,0)`. **Map cards** expose a single set of font size and font color settings that apply globally. **Line Chart and Donut Chart cards** expose: * **Show Title** — whether the chart title is displayed. * **Title Position** — where the title appears: Top or Bottom. * **Show Legend** — whether the chart legend is displayed. * **Legend Position** — where the legend appears: Left, Right, Top, or Bottom. **HTML Block cards** expose a rich-text content editor where you author the HTML content that the card displays. This is the only card type where the content itself (rather than just styling) is part of the card configuration. ## Managing Card Definitions ### Viewing the Card List Navigate to the Card administration screen to see all defined cards. The list shows each card's name, type, and description, along with the date it was last modified and who modified it. You can sort the list by any column. If there are more than 10 cards, pagination controls appear at the bottom. ### Creating a Card 1. Click **Add New Card** in the card list. 2. In the modal that opens, enter a **Name** for the card. 3. Select a **Card Type** from the dropdown. The configuration section below updates to show the options relevant to that type. 4. Enter a **Description** for the card. 5. Fill in the configuration fields for your chosen card type. 6. Click **Save**. The new card appears in the list. All fields marked with an asterisk are required. The name must be at least 2 characters. The description must also be at least 2 characters. ### Editing a Card 1. In the card list, click the card's **Name** or click the pencil icon in its row. 2. The edit modal opens with the card's current values. 3. Make your changes and click **Save**. Changing the card type in the edit form resets the configuration to the defaults for the new type. If you want to preserve configuration values from the previous type, note them down before switching. ### Deleting a Card A card can only be deleted if it is not currently placed on any page. If the delete icon is disabled for a card, that card is in use and must be removed from all pages before it can be deleted. 1. Click the trash icon in the card's row. 2. A confirmation dialog appears: "Are you sure you want to delete the Card \[name]?" 3. Confirm to proceed. The card is permanently removed. ## Understanding Card Data ### What Is Card Data? Card data is a data record linked to a specific card definition. It provides the actual values that the card displays when it renders on a page. A card definition describes the visual structure; card data provides the content. A single card definition can have multiple card data records associated with it, each scoped to a different combination of school year and organizational entity. This allows the same card to show different data for different districts, schools, or reporting periods without requiring separate card definitions. ### School Year Scoping Each card data record includes a **School Year** field, stored as an integer (for example, `2024` for the 2023–2024 school year). When the portal renders a card on a page, it uses the school year context of the current session or the active filter to select the correct card data record. If no record exists for the active school year, the card may display empty or fall back to a default state. ### Entity Association Each card data record includes an optional **Entity ID** field. An entity represents an organizational unit — typically a district, school, or site — identified by a unique system ID. When a user views a page in the context of a specific entity (for example, a district-level dashboard), the portal selects the card data record that matches both the current school year and the current entity. This scoping mechanism allows a single card to present entity-appropriate data without creating duplicate card definitions. ### JSON Data Payloads The **JSON Data** field on a card data record is a free-form JSON string that holds the actual data values the card renders. The structure and content of this JSON depends on the card type: * For a **KPI card**, the JSON typically contains the metric value and optional label text. * For a **Table card**, the JSON typically contains an array of rows and column definitions. * For a **Chart card**, the JSON typically contains series data and category labels. * For a **Map card**, the JSON typically contains geographic data points. The exact shape of the JSON is determined by the card type's rendering implementation and any data integration configured for the card. Your administrator or implementation team can provide the expected structure for each card type in use at your organization. ## Managing Card Data Records ### Viewing Card Data Navigate to the Card Data administration screen. The list shows each record alongside the name of its associated card, the school year, and the entity ID. You can sort and filter the list. Records are displayed with full navigation properties, meaning the linked card's details are shown alongside the card data record. ### Creating a Card Data Record 1. From the Card Data list, click **Add New Card Data** (or the equivalent add action). 2. In the modal, select the **Card** this data record belongs to from the card lookup dropdown. 3. Enter the **Entity ID** — the unique identifier of the district, school, or other organizational entity this data is for. 4. Enter the **School Year** as a four-digit integer. 5. Enter the **JSON Data** payload appropriate for the selected card type. 6. Click **Save**. ### Editing a Card Data Record 1. Click the edit action in the card data record's row. 2. Update the fields as needed. You can change the linked card, entity ID, school year, or JSON data. 3. Click **Save**. ### Deleting a Card Data Record 1. Click the delete action in the card data record's row. 2. Confirm the deletion in the dialog that appears. Deleting a card data record removes the data association. The card definition and any pages that use that card are not affected, but the card will no longer have data to display for the deleted school year and entity combination. ## Cards in Pages and Containers ### Pages and Page Cards Cards are placed on pages. A **page** is an administrative grouping that has a page type, title, and description. Each page can hold one or more **page cards** — these are the individual placements of card definitions on a page, each with a position and optional per-placement configuration. The page type is a short code (2–10 characters) that the portal uses to determine how to route and display the page. The page title and description appear in the page's user interface. ### Placing Cards on a Page When you create or edit a page, a grid-based layout editor appears beneath the page's metadata fields. In this editor you can: * **Add a card placement** — click the add action to insert a new card slot in the grid. A new placeholder appears at the bottom of the layout at a default size of 2 columns wide by 2 rows tall. * **Configure a card slot** — click **Settings** in a card slot's context menu to open the card configuration modal. Select which card definition the slot displays and adjust its per-placement settings. * **Reposition a card slot** — use the **Move Left** and **Move Right** actions in a slot's context menu to shift its horizontal position within the grid. Cards are placed using a responsive 10-column grid, so each left or right move shifts the slot by one column. * **Remove a card slot** — click **Remove** in a slot's context menu to remove that card placement from the page. After making changes, save the page. The page and all its card placements are saved together in a single operation. Card placements are saved in bulk with their positions preserved. ### Card Position and Layout Each card placement on a page carries a layout configuration that records its horizontal position (`x`), vertical position (`y`), width (`w`), and height (`h`) in grid units. This layout is stored as part of the page card configuration JSON. New card placements default to a width and height of 2 grid units. Cards flow downward automatically when placed at `y: Infinity`, meaning new additions always appear at the bottom of the existing layout. ### Relationship to Containers Cards placed on pages through the page card system are distinct from the **Container Designer** card system described in the Container Designer Reference. The Container Designer is a separate visual tool for building dashboard-style pages with a more advanced card component model, event bus, and filter capabilities. The cards and pages described in this guide are a simpler, earlier system. If your organization uses the Container Designer for dashboard composition, consult the Container Designer Reference for guidance on that system. Cards defined in this guide's system and cards within containers do not share definitions or data records. ## Common Scenarios **Adding a KPI card to show current-year attendance:** 1. Create a card definition with type **KPI**, a descriptive name, and configure the title and body font settings. 2. Create a card data record linked to that card, set the school year to the current year, set the entity ID to the appropriate district or school, and enter a JSON data payload containing the attendance value. 3. Open the target page in the page editor, add a card placement, open its Settings, and select the KPI card definition. 4. Save the page. The KPI card now appears on that page and displays the attendance data. **Adding a table card with data for multiple schools:** 1. Create a single card definition with type **Table** and configure header and body styles. 2. Create one card data record per school, each with the same card ID, the same school year, and a different entity ID. Each record's JSON data contains that school's table rows. 3. When a user views the page in the context of a specific school, the portal selects the matching card data record automatically. **Creating an HTML Block card with static content:** 1. Create a card definition with type **HTML Block**. 2. In the configuration section, use the rich-text editor to author the content — for example, instructions, a disclaimer, or a heading. 3. No card data record is required for HTML Block cards because the content is stored directly in the card's configuration. 4. Place the card on any page and save. ## Troubleshooting **The delete button is disabled for a card.** The card is currently placed on one or more pages. Remove the card from all pages using the page editor before attempting to delete the card definition. **A card on a page shows no data.** Check that a card data record exists for that card, the current school year, and the relevant entity. Verify that the school year integer in the card data record matches the active school year in the portal. Confirm the entity ID is correct for the user's current context. **Changing the card type in the edit form cleared my configuration.** Switching card types resets the configuration fields to the defaults for the new type. If you need values from the previous configuration, you must re-enter them manually after selecting the new type. **The JSON Data field is not saving correctly.** Ensure the JSON you enter is valid. Malformed JSON may be rejected or saved as empty. Use a JSON validator to check your payload before submitting. **A page card placement disappeared after saving.** If no card was selected in a placement's Settings before saving, that placement may have been saved without a valid card reference. Open the page editor again, add the placement back, open its Settings to select a card, and save. **I cannot find the Card Data administration screen.** Card Data is a separate permission set from Cards. Confirm with your administrator that your role has been granted the Card Datas permission in addition to the Cards permission. --- # 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/cards-card-data.md?ask= ``` 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.