Admin UI
Overview

Admin UI Overview

ActiveQL Admin (activeql-active-admin) is a complete server-side admin UI framework integrated with ActiveQL. It provides automatic CRUD (Create, Read, Update, Delete) management interfaces for all entities defined in an ActiveQL schema.

Key Features

  • Automatic CRUD interfaces for all ActiveQL entities
  • Server-side rendering with Eta template engine
  • Dynamic interactions using HTMX
  • Authentication with JWT token support
  • Permission handling through Principal objects
  • File upload/download support
  • Customizable configuration per entity and field

Architecture

The Admin UI uses:

  • Express.js for routing
  • Eta template engine for server-side rendering
  • HTMX for dynamic form submissions
  • Bootstrap 5 + Tabler for UI components

Quick Start

import { addActiveAdmin } from 'activeql-active-admin';
import express from 'express';
 
const app = express();
 
await addActiveAdmin({
  path: '/admin',
  title: 'My Admin',
  entities: {
    // Entity configurations
  }
});

Core Components

ComponentDescription
ActiveAdminMain orchestrator class
EntityUIEntity representation with fields
FieldUIField-level abstraction
DataAccessorData retrieval and mutation

ActiveAdmin

The main entry point that manages:

  • Express middleware setup
  • Template engine configuration
  • Route registration
  • Menu system initialization
  • Authentication/token management

EntityUI

Represents a single entity with:

  • Field visibility and ordering
  • Entity-level permissions
  • Path generation
  • Content block rendering
  • Association handling (AssocTo, AssocToMany, AssocBy)

FieldUI

Abstract base with implementations for:

  • IdFieldUI: Primary key field
  • AttributeUI: Regular attributes (String, Int, Float, Date, Boolean, File, Enum)
  • CustomFieldUI: User-defined fields
  • AssocToUI: Single/many associations
  • AssocByUI: Reverse associations

DataAccessor

Handles all data operations:

  • Query/pagination/search
  • Load/save/delete items
  • Association handling
  • Permission validation

CRUD Operations

Index Page

Paginated list with:

  • Sorting
  • Searching
  • Custom actions

Show Page

Read-only detail view with:

  • Associations
  • Content blocks
  • Custom actions

Edit Page

Form with:

  • Validation
  • File uploads
  • Association selection

Delete

Single item deletion with confirmation

Supported Field Types

TypeDescription
IDPrimary key
StringText input
IntInteger input
FloatDecimal input
BooleanCheckbox
DateDate picker
DateTimeDateTime picker
FileFile upload
EnumDropdown select
AssocToSingle association
AssocToManyMultiple associations
AssocByReverse association (read-only)

UI Technologies

  • Bootstrap 5.3.3: Layout and components
  • Tabler: Extended Bootstrap components and icons
  • HTMX 1.9.10: Dynamic form submissions
  • Alpine.js 3.x: Lightweight interactivity

Integration with ActiveQL

The Admin UI integrates with:

  • Runtime: Entity definitions, attributes, associations
  • Entity: CRUD operations, permissions, validation
  • DataStore: Entity statistics
  • Principal: Permission checks, user context
  • FileHandler: Upload/download operations
  • Enums: Rendering enum dropdowns
Accessor HooksConfiguration