Admin Template Rules

Addon admin screens provide inner content. The Admin layer owns the page frame, navigation, identity, and shell.

Rule

Do not render a second full admin shell from an addon. Render the feature content for the current screen and let the Admin shell place it.

List Screen Pattern

A governed addon list screen should include:

• permission check before rendering
• search/filter inputs when the addon owns real filters
• sortable headers for sortable columns
• stable pagination
• row actions scoped to the record
• empty state when no records match
• no business queries inside the shared Admin template layer

Expected permission split:

• `admin.access`: may enter Admin
• `{addon}.view`: may view the list
• `{addon}.manage`: may create/edit/archive records

Create/Edit Form Pattern

Create and edit screens should:

• use one canonical screen parameter, such as `screen=create` or `screen=edit`
• use one record identifier, such as `note_uuid`
• include a CSRF token on every POST form
• validate permissions before saving
• validate input before writing
• redirect after successful POST
• show a concise notice after redirect

Minimal Save Flow

if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    if (!amv_core_csrf_validate((string) ($_POST['_token'] ?? ''))) {
        return ['notice' => 'Security token invalid.', 'redirect' => ''];
    }
    if (!amv_core_permission_has($authContext, 'example_notes.manage')) {
        return ['notice' => 'Permission denied.', 'redirect' => ''];
    }

    $result = amv_example_notes_save($pdo, $_POST);
    if ($result['ok'] ?? false) {
        return [
            'notice' => 'Note saved.',
            'redirect' => '/admin/index.php?view=example_notes&screen=edit&note_uuid=' . rawurlencode($result['note_uuid']),
        ];
    }
}

Use the exact CSRF/permission helper names available in the target code path. Do not invent a helper when the addon already has a local wrapper.

Notices And Redirects

• Use notices for user-facing success/failure state.
• Redirect after successful POST to avoid repeat submissions.
• Keep failure notices on the same screen when the user needs to fix input.
• Do not leak raw SQL or stack traces into notices.

Shared Helper Boundary

If a change improves every addon list, it belongs in the shared Admin helper/template layer. If it changes feature data, workflow, permissions, labels, or save behavior, it belongs in the addon.

Related: Addon Development/Admin Routes, Addon Development/Build Your First Addon.

Copyable Runtime Sample

Use Reference Samples/Admin Runtime Sample for a fuller `admin_runtime.php` skeleton that shows list, create, edit, CSRF validation, permission checks, notices, and redirect-after-POST behavior.