# Widget System

## Table of Contents

* [Overview](#overview)
* [Getting Started](#getting-started)
* [Understanding Widgets](#understanding-widgets)
  * [Widget Types](#widget-types)
  * [Widget Groups](#widget-groups)
  * [Widget Codes](#widget-codes)
* [Viewing Widget Content](#viewing-widget-content)
* [Content Administration](#content-administration)
  * [The Content Administration Panel](#the-content-administration-panel)
  * [Home Page Tab](#home-page-tab)
  * [Public Home Page Tab](#public-home-page-tab)
  * [Content Pages Tab](#content-pages-tab)
* [Managing Widgets](#managing-widgets)
  * [Adding a Content Page](#adding-a-content-page)
  * [Editing a Widget](#editing-a-widget)
  * [Deleting a Widget](#deleting-a-widget)
  * [Editing Content with the HTML Editor](#editing-content-with-the-html-editor)
* [Managing Widget Groups](#managing-widget-groups)
* [Managing Widget Types](#managing-widget-types)
* [Common Scenarios](#common-scenarios)
* [Troubleshooting](#troubleshooting)

## Overview

The Widget System is the content management layer of OtisEd.Nimble. It lets administrators create and maintain blocks of content — called widgets — that appear on portal pages such as the home page, the public landing page, and standalone content pages. Each widget holds a piece of content that can range from a short text snippet to a full HTML page layout.

Widgets are organized by type (which controls how the content is rendered) and by group (which controls where the widget appears in the portal). Administrators can update portal content directly through the Content Administration panel without needing developer assistance.

## Getting Started

Access to the Widget System depends on the permissions granted to your account:

* To view widget content pages: no special permissions are required. Content is displayed automatically on the appropriate portal pages.
* To administer widgets (create, edit, delete content): your account needs the Widgets administration permissions.
* To manage widget groups: your account needs the Widget Groups administration permissions.
* To manage widget types: your account needs the Widget Types administration permissions.

To reach the Content Administration panel, navigate to the Content Administration section from the main portal navigation. You must be logged in with an account that has the appropriate administrative permissions.

If you expect to have access to the Content Administration panel but cannot see it, contact your system administrator to verify your account permissions.

## Understanding Widgets

A widget is a named, reusable block of content identified by a unique code. Each widget belongs to exactly one group (which determines its placement context) and one type (which determines how its content is rendered).

### Widget Types

Widget types define the format of a widget's content. The following types are supported:

* **Text (TXT):** Plain text content displayed as-is, without any HTML formatting applied.
* **HTML Content (HTM):** Rich content that supports full HTML markup. Administrators can author HTML content either in a plain text editor (for those comfortable writing HTML directly) or through a visual HTML editor that provides formatting tools.
* **File (FIL):** Content linked to an uploaded file.

When creating a new widget through the Content Pages tab, the system defaults to the HTML Content type.

### Widget Groups

Widget groups are named collections that control where widgets are used. Each group has a name and a code. The code is used internally to associate widgets with the correct page or section. Key built-in groups include:

* **HOMEPAGE:** Contains widgets displayed on the authenticated user home page, including the main content area and footer sections.
* **HOMEPAGE-PUBLIC:** Contains widgets displayed on the public-facing (pre-login) home page, with its own content area and footer sections.
* **WIDGETPAGE:** Contains standalone content pages that are accessible via a direct link using the widget's code.

Administrators can add additional groups to extend the system to new placement contexts.

### Widget Codes

Every widget has a unique code that identifies it within its group. For standalone content pages, the code is used in the URL to load the correct widget (for example, `/widget?id=MY-CODE`). For home page and public home page widgets, specific reserved codes control which section each widget populates:

| Code             | Location                              |
| ---------------- | ------------------------------------- |
| `CONTENT`        | Home page main content area           |
| `FOOTER1`        | Home page left footer section         |
| `FOOTER2`        | Home page right footer section        |
| `CONTENT-PUBLIC` | Public home page main content area    |
| `FOOTER1-PUBLIC` | Public home page left footer section  |
| `FOOTER2-PUBLIC` | Public home page right footer section |

## Viewing Widget Content

End users do not interact with widgets directly. Widget content is rendered automatically in the appropriate location — on the home page, the public landing page, or a dedicated content page.

To view a standalone content page widget, navigate to `/widget?id=CODE`, replacing `CODE` with the widget's code. If no widget with that code exists in the WIDGETPAGE group, a "Widget Not Found" message is displayed instead. The page title and breadcrumb are automatically set to the widget's name.

## Content Administration

### The Content Administration Panel

The Content Administration panel is the primary interface for managing portal content. It is divided into three tabs:

* **Home Page** — Edit the content shown on the authenticated user home page.
* **Public Home Page** — Edit the content shown on the public (pre-login) landing page.
* **Content Pages** — Manage standalone content pages accessible by widget code.

Each tab loads the widgets belonging to its associated group and presents them in an editable layout.

### Home Page Tab

The Home Page tab displays a live preview of the home page content sections. Three sections are shown:

* **Main Content** (code: `CONTENT`) — The primary body content at the top of the home page.
* **Left Footer** (code: `FOOTER1`) — A wider footer section occupying roughly two-thirds of the page width.
* **Right Footer** (code: `FOOTER2`) — A narrower footer column occupying roughly one-third of the page width.

Each section shows an edit icon in its header. Clicking the edit icon opens the widget editor for that section. After saving, the tab reloads the updated content.

### Public Home Page Tab

The Public Home Page tab works identically to the Home Page tab, but manages the content shown to users who have not yet logged in. The three sections mirror the home page layout:

* **Main Content** (code: `CONTENT-PUBLIC`)
* **Left Footer** (code: `FOOTER1-PUBLIC`)
* **Right Footer** (code: `FOOTER2-PUBLIC`)

Changes saved here are immediately visible on the public landing page.

### Content Pages Tab

The Content Pages tab manages standalone content pages that users access directly by URL. The tab shows a table listing all content pages with the following columns:

| Column | Description                                                 |
| ------ | ----------------------------------------------------------- |
| Name   | The display name of the content page                        |
| Code   | The unique identifier used in the page URL                  |
| Path   | A direct link to view the content page (opens in a new tab) |

Action buttons on each row allow you to edit or delete a page. An Add New Content Page button above the table opens the widget editor to create a new page.

## Managing Widgets

### Adding a Content Page

1. Navigate to Content Administration and select the **Content Pages** tab.
2. Click **Add New Content Page**.
3. In the widget editor, enter a **Name** for the page — this appears as the page title and breadcrumb.
4. Enter a **Code** — this is the identifier used in the page URL. Use uppercase letters and hyphens, for example `SCHOOL-OVERVIEW`. Codes must be unique within the group.
5. Enter or paste the **Content** for the page. For HTML content, choose whether to use the HTML editor toggle or author directly in the text area.
6. Click **Save**. The new page appears in the content pages table and is immediately accessible at `/widget?id=YOUR-CODE`.

### Editing a Widget

For home page and public home page widgets:

1. Open the **Home Page** or **Public Home Page** tab in Content Administration.
2. Locate the section you want to edit and click its edit icon.
3. Update the Name, Code, or Content fields as needed.
4. Click **Save** to apply the changes. The updated content is displayed immediately.

For standalone content pages:

1. Open the **Content Pages** tab.
2. Find the content page in the table and click its edit icon.
3. Update the fields as needed and click **Save**.

### Deleting a Widget

1. Open the **Content Pages** tab.
2. Find the content page and click its delete icon.
3. A confirmation dialog will display the page name and code and ask you to confirm the deletion.
4. Click **OK** to permanently delete the page. This action cannot be undone.

Widgets used on the home page and public home page cannot be deleted through the Content Administration panel.

### Editing Content with the HTML Editor

When a widget uses the HTML Content type, the editor form includes a **Use HTML Editor** toggle. By default, the toggle is off and the content field is a plain text area where you can type or paste HTML directly.

Switching the toggle on opens a visual rich-text editor with formatting controls, allowing you to style content, add headings, insert links, and format lists without writing HTML by hand.

You can switch between the two editing modes at any time within an editing session. The content is preserved when toggling between modes.

## Managing Widget Groups

Widget groups are the organizational containers that connect widgets to portal locations. Administrators with Widget Groups permissions can create, edit, and delete groups.

To manage widget groups, navigate to the Widget Groups administration screen. The list shows all groups with their name and code. Each group entry can be edited to update its name or code, or deleted if it has no widgets associated with it.

When creating a new group:

* Provide a meaningful **Name** that describes the placement context.
* Provide a **Code** in uppercase letters. This code is referenced in the portal to load widgets for a given location.

Changes to group codes may affect how widgets are loaded in the portal. Coordinate with a developer before changing the code of an existing group.

## Managing Widget Types

Widget types define the rendering behavior for widget content. Administrators with Widget Types permissions can view and manage the list of types.

The built-in types are Text (TXT), HTML Content (HTM), and File (FIL). Adding a new widget type requires a corresponding update to the frontend rendering logic and should be coordinated with a developer.

To view the widget types list, navigate to the Widget Types administration screen.

## Common Scenarios

**Updating the portal home page message after a policy change**

1. Go to Content Administration and select the **Home Page** tab.
2. Click the edit icon on the Main Content section.
3. Update the text in the Content field.
4. Click **Save**. The change takes effect immediately for all logged-in users.

**Creating a new informational page about a program**

1. Go to Content Administration and select the **Content Pages** tab.
2. Click **Add New Content Page**.
3. Enter the program name as the Name and a short uppercase code such as `PROGRAM-INFO`.
4. Write the page content using the HTML editor for formatted text.
5. Click **Save**.
6. Share the link `/widget?id=PROGRAM-INFO` with the intended audience.

**Updating the public landing page for a new school year**

1. Go to Content Administration and select the **Public Home Page** tab.
2. Edit the Main Content section to reflect the new school year welcome message.
3. Update the footer sections as needed with new dates or contact information.
4. Click **Save** on each section after editing.

## Troubleshooting

**"Widget Not Found" is displayed when visiting a content page**

The code in the URL does not match any widget in the WIDGETPAGE group. Check the URL and confirm it matches the Code field of the intended widget in the Content Pages tab. Codes are case-sensitive.

**Changes to the home page are not visible after saving**

Try a hard refresh in your browser (Ctrl+Shift+R or Cmd+Shift+R). If changes still do not appear, confirm the widget was saved successfully and that you edited the correct section (Home Page versus Public Home Page).

**The Add New Content Page button or edit icons are not visible**

Your account does not have the Widgets Create or Widgets Edit permission. Contact your administrator to request the appropriate access.

**A content page is not displaying formatted content correctly**

Check that the widget type is set to HTML Content (HTM) and not Text (TXT). Plain text widgets do not render HTML markup. If the type needs to be changed, an administrator with edit permissions must update the widget record.

**The HTML editor is not available when editing a widget**

The HTML editor toggle only appears for widgets with the HTML Content type. If the widget uses the Text type, only a plain text input is shown. Contact your administrator if the widget type needs to be updated.


---

# 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/widget-system.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.