@dotcms/uve
Version:
Official JavaScript library for interacting with Universal Visual Editor (UVE)
222 lines (221 loc) • 8.75 kB
TypeScript
import { DotCMSBasicContentlet, DotCMSColumnContainer, DotCMSPageAsset, DotPageAssetLayoutColumn, EditableContainerData } from '@dotcms/types';
import { DotCMSContainerBound, DotCMSContentletBound, DotContainerAttributes, DotContentletAttributes } from '@dotcms/types/internal';
/**
* Calculates the bounding information for each page element within the given containers.
*
* @export
* @param {HTMLDivElement[]} containers - An array of HTMLDivElement representing the containers.
* @return {DotCMSContainerBound[]} An array of objects containing the bounding information for each page element.
* @example
* ```ts
* const containers = document.querySelectorAll('.container');
* const bounds = getDotCMSPageBounds(containers);
* console.log(bounds);
* ```
*/
export declare function getDotCMSPageBounds(containers: HTMLDivElement[]): DotCMSContainerBound[];
/**
* Calculates the bounding information for each contentlet inside a container.
*
* @export
* @param {DOMRect} containerRect - The bounding rectangle of the container.
* @param {HTMLDivElement[]} contentlets - An array of HTMLDivElement representing the contentlets.
* @return {DotCMSContentletBound[]} An array of objects containing the bounding information for each contentlet.
* @example
* ```ts
* const containerRect = container.getBoundingClientRect();
* const contentlets = container.querySelectorAll('.contentlet');
* const bounds = getDotCMSContentletsBound(containerRect, contentlets);
* console.log(bounds); // Element bounds within the container
* ```
*/
export declare function getDotCMSContentletsBound(containerRect: DOMRect, contentlets: HTMLDivElement[]): DotCMSContentletBound[];
/**
* Get container data from VTLS.
*
* @export
* @param {HTMLElement} container - The container element.
* @return {object} An object containing the container data.
* @example
* ```ts
* const container = document.querySelector('.container');
* const data = getContainerData(container);
* console.log(data);
* ```
*/
export declare function getDotCMSContainerData(container: HTMLElement): {
acceptTypes: string;
identifier: string;
maxContentlets: string;
uuid: string;
};
/**
* Get the closest container data from the contentlet.
*
* @export
* @param {Element} element - The contentlet element.
* @return {object | null} An object containing the closest container data or null if no container is found.
* @example
* ```ts
* const contentlet = document.querySelector('.contentlet');
* const data = getClosestDotCMSContainerData(contentlet);
* console.log(data);
* ```
*/
export declare function getClosestDotCMSContainerData(element: Element): {
acceptTypes: string;
identifier: string;
maxContentlets: string;
uuid: string;
} | null;
/**
* Find the closest contentlet element based on HTMLElement.
*
* @export
* @param {HTMLElement | null} element - The starting element.
* @return {HTMLElement | null} The closest contentlet element or null if not found.
* @example
* const element = document.querySelector('.some-element');
* const contentlet = findDotCMSElement(element);
* console.log(contentlet);
*/
export declare function findDotCMSElement(element: HTMLElement | null): HTMLElement | null;
/**
* Find VTL data within a target element.
*
* @export
* @param {HTMLElement} target - The target element to search within.
* @return {Array<{ inode: string, name: string }> | null} An array of objects containing VTL data or null if none found.
* @example
* ```ts
* const target = document.querySelector('.target-element');
* const vtlData = findDotCMSVTLData(target);
* console.log(vtlData);
* ```
*/
export declare function findDotCMSVTLData(target: HTMLElement): {
inode: string | undefined;
name: string | undefined;
}[] | null;
/**
* Check if the scroll position is at the bottom of the page.
*
* @export
* @return {boolean} True if the scroll position is at the bottom, otherwise false.
* @example
* ```ts
* if (dotCMSScrollIsInBottom()) {
* console.log('Scrolled to the bottom');
* }
* ```
*/
export declare function computeScrollIsInBottom(): boolean;
/**
*
*
* Combine classes into a single string.
*
* @param {string[]} classes
* @returns {string} Combined classes
*/
export declare const combineClasses: (classes: string[]) => string;
/**
*
*
* Calculates and returns the CSS Grid positioning classes for a column based on its configuration.
* Uses a 12-column grid system where columns are positioned using grid-column-start and grid-column-end.
*
* @example
* ```typescript
* const classes = getColumnPositionClasses({
* leftOffset: 1, // Starts at the first column
* width: 6 // Spans 6 columns
* });
* // Returns: { startClass: 'col-start-1', endClass: 'col-end-7' }
* ```
*
* @param {DotPageAssetLayoutColumn} column - Column configuration object
* @param {number} column.leftOffset - Starting position (0-based) in the grid
* @param {number} column.width - Number of columns to span
* @returns {{ startClass: string, endClass: string }} Object containing CSS class names for grid positioning
*/
export declare const getColumnPositionClasses: (column: DotPageAssetLayoutColumn) => {
startClass: string;
endClass: string;
};
/**
*
*
* Helper function that returns an object containing the dotCMS data attributes.
* @param {DotCMSBasicContentlet} contentlet - The contentlet to get the attributes for
* @param {string} container - The container to get the attributes for
* @returns {DotContentletAttributes} The dotCMS data attributes
*/
export declare function getDotContentletAttributes(contentlet: DotCMSBasicContentlet, container: string): DotContentletAttributes;
/**
*
*
* Retrieves container data from a DotCMS page asset using the container reference.
* This function processes the container information and returns a standardized format
* for container editing.
*
* @param {DotCMSPageAsset} dotCMSPageAsset - The page asset containing all containers data
* @param {DotCMSColumnContainer} columContainer - The container reference from the layout
* @throws {Error} When page asset is invalid or container is not found
* @returns {EditableContainerData} Formatted container data for editing
*
* @example
* const containerData = getContainersData(pageAsset, containerRef);
* // Returns: { uuid: '123', identifier: 'cont1', acceptTypes: 'type1,type2', maxContentlets: 5 }
*/
export declare const getContainersData: (dotCMSPageAsset: DotCMSPageAsset, columContainer: DotCMSColumnContainer) => EditableContainerData | null;
/**
*
*
* Retrieves the contentlets (content items) associated with a specific container.
* Handles different UUID formats and provides warning for missing contentlets.
*
* @param {DotCMSPageAsset} dotCMSPageAsset - The page asset containing all containers data
* @param {DotCMSColumnContainer} columContainer - The container reference from the layout
* @returns {DotCMSBasicContentlet[]} Array of contentlets in the container
*
* @example
* const contentlets = getContentletsInContainer(pageAsset, containerRef);
* // Returns: [{ identifier: 'cont1', ... }, { identifier: 'cont2', ... }]
*/
export declare const getContentletsInContainer: (dotCMSPageAsset: DotCMSPageAsset, columContainer: DotCMSColumnContainer) => DotCMSBasicContentlet[];
/**
*
*
* Generates the required DotCMS data attributes for a container element.
* These attributes are used by DotCMS for container identification and functionality.
*
* @param {EditableContainerData} params - Container data including uuid, identifier, acceptTypes, and maxContentlets
* @returns {DotContainerAttributes} Object containing all necessary data attributes
*
* @example
* const attributes = getDotContainerAttributes({
* uuid: '123',
* identifier: 'cont1',
* acceptTypes: 'type1,type2',
* maxContentlets: 5
* });
* // Returns: { 'data-dot-object': 'container', 'data-dot-identifier': 'cont1', ... }
*/
export declare function getDotContainerAttributes({ uuid, identifier, acceptTypes, maxContentlets }: EditableContainerData): DotContainerAttributes;
/**
* Read a contentlet's dataset attributes off a DOM element and return a
* normalized contentlet object. Mirrors the shape consumed by the editor's
* SET_BOUNDS and CONTENTLET_CLICKED events. Optionally parses the
* `dotStyleProperties` JSON when present.
*/
export declare function readContentletDataset(element: HTMLElement): {
dotStyleProperties?: any;
identifier: string | undefined;
title: string | undefined;
inode: string | undefined;
contentType: string | undefined;
baseType: string | undefined;
widgetTitle: string | undefined;
onNumberOfPages: string | undefined;
};