UI Components & Modals (JavaScript API)

Overview

Pragma CMS leverages the native HTML5 <dialog> element combined with JavaScript Promises to create asynchronous, accessible, and blocking UI flows without the overhead of heavy UI frameworks.

`showModal()`

Creates and displays a fully customizable native <dialog> modal.

The function returns a Promise that resolves with the value of the clicked button, making asynchronous confirmation flows much cleaner than traditional callback-based modals.

Signature

JAVASCRIPT

function showModal(options = {})

Options Configuration

Property	Type	Description
`title`	`string`	Text displayed in the modal header.
`titleHtml`	`string`	Custom HTML for the header. Overrides `title`.
`icon`	`Object`	Optional icon object. Example: `{ type: 'img', src: '...' }` or `{ type: 'html', content: '...' }`.
`message`	`string`	Simple text body content.
`htmlContent`	`string`	Custom HTML body content. Overrides `message`.
`buttons`	`Array`	Array of button objects: `[{ label, value, primary, class }]`. Defaults to a single OK button.
`dismissable`	`boolean`	If `true` (default), pressing `ESC` or clicking outside closes the modal and returns `null`.
`width` / `height`	`string`	Custom CSS dimensions such as `'500px'` or `'80vh'`.
`afterRender`	`Function`	Callback executed immediately after the modal is injected into the DOM. Receives the `<dialog>` element as parameter.

Example: Confirmation Flow

JAVASCRIPT

const userChoice = await showModal({

    title: "Confirm Deletion",

    icon: {
        type: 'html',
        content: '<span class="material-symbols-outlined">warning</span>'
    },

    htmlContent: `
        <p>
            Are you sure you want to delete this item?
            This action cannot be undone.
        </p>
    `,

    buttons: [
        {
            label: "Cancel",
            value: "cancel",
            primary: false
        },
        {
            label: "Delete",
            value: "confirm",
            primary: true,
            class: "button-danger"
        }
    ],

    width: "400px"

});

if (userChoice === 'confirm') {

    // Execute deletion logic
}

`showInputModal()`

A modern asynchronous replacement for the native window.prompt() function.

Returns a Promise containing:

the entered string,
or null if the modal was cancelled.

Signature

JAVASCRIPT

async function showInputModal(
    title,
    label,
    defaultValue = '',
    placeholder = '',
    multiline = false
)

Parameters

Parameter	Type	Description
`title`	`string`	Modal title.
`label`	`string`	Input label displayed above the field.
`defaultValue`	`string`	Default input value.
`placeholder`	`string`	Placeholder text.
`multiline`	`boolean`	If `true`, renders a `<textarea>` instead of an `<input>`.

Example

JAVASCRIPT

const newFolderName = await showInputModal(
    "New Folder",
    "Enter folder name:",
    "Untitled Folder"
);

if (newFolderName) {

    console.log("Creating folder:", newFolderName);
}

`showDeleteConfirmationModal()`

A high-security confirmation modal designed for critical or irreversible actions.

The user must manually type a predefined confirmation word (for example "DELETE") before the confirm button becomes enabled.

Signature

JAVASCRIPT

async function showDeleteConfirmationModal(
    fileName,
    expectedText = "DELETE"
)

Parameters

Parameter	Type	Description
`fileName`	`string`	Name of the file or resource being deleted.
`expectedText`	`string`	Required confirmation text to unlock the delete action.

Example

JAVASCRIPT

const isConfirmed = await showDeleteConfirmationModal(
    "database_backup.sql",
    "DELETE"
);

if (isConfirmed) {

    // Execute critical deletion
}

`showLoader()`

Creates and injects a customizable spinning loader into the DOM.

The function returns the loader wrapper element so it can later be removed manually.

Signature

JAVASCRIPT

function showLoader(
    parentElement,
    classes = [],
    styles = {},
    position = 'after'
)

function showLoader( parentElement, classes = [], styles = {}, position = 'after' )

Parameters

Parameter	Type	Description
`parentElement`	`HTMLElement`	Target DOM element.
`classes`	`Array`	Additional CSS classes applied to the loader wrapper.
`styles`	`Object`	CSS variables object. Example: `{ '--size': '40px', '--thickness': '4px' }`.
`position`	`string`	Insertion position: `'prepend'`, `'append'`, `'before'`, or `'after'`.

Example

JAVASCRIPT

const form = document.getElementById('my-form');
const submitBtn = document.getElementById('submit-btn');

// 1. Attach a loader to the button
const loader = showLoader(submitBtn, [], { '--size': '24px' }, 'append');

// 2. Send the request
const response = await apiRequest('/api/settings', {
    method: 'POST',
    body: new FormData(form)
}, loader);

// 3. Handle response
if (!response) return; // Request failed and error popup is already displayed

if (response.success) {
    displaySuccessPopup(response.message);
}