Coralite Type Reference

This document serves as a comprehensive reference for the type definitions used within the Coralite. It outlines the structure, properties, and relationships of core types involved in parsing, rendering, and managing HTML documents, templates, and modules. The following sections provide detailed breakdowns of each type, with tables and internal links for easy navigation.

Core Types #

HTMLData #

Represents HTML file data including path and raw content.

CoraliteFilePath #

Represents a file's path structure within the project.

CoralitePath #

Defines root directories for pages and components in a Coralite project.

CoralitePathValues #

Represents URL and file path values available during component rendering.

CoraliteValues #

Union type representing values available for token replacement in components.

CoraliteToken #

Represents a token with name and value.

CoraliteAttributeToken #

Represents an HTML attribute token linked to its parent element.

CoraliteRef #

Represents an element reference with name and element.

CoraliteTextNodeToken #

Represents a text node token with associated metadata.

CoraliteModuleValues #

A collection of module values associated with a module.

ScriptContent #

Coralite module script content.

CoraliteModuleValue #

Represents a single value that a module can store or process.

Document and Result Types #

CoraliteDocumentValues #

Holds tokenized metadata extracted from document attributes, element references and text nodes.

CoraliteDocumentResult #

Result of document processing containing extracted values and temporary elements.

CoraliteResult #

Represents a rendered output document with metadata and statistics.

CoraliteDocumentRoot #

Represents the root node of a document containing all content nodes.

CoraliteDocument #

Represents a complete Coralite document with metadata and rendering structure.

CoraliteDirective #

Represents a directive found in HTML content, like a DOCTYPE declaration.

ParseHTMLResult #

Result of parsing HTML content.

Module and Plugin Types #

CoraliteModule #

A module within the Coralite library, containing metadata and rendering logic.

CoraliteModuleSlotElement #

Defines a slot element and its configuration within a module.

CoraliteConfig #

Configuration object for Coralite instance.

CoraliteScriptContent #

Script content for Coralite instances.

CoraliteModuleScript #

Callback for module script execution.

  /**
        * @callback CoraliteModuleScript
        * @param {CoraliteValues} values - The module's current values
        * @param {CoraliteRef} refs - References template elements
        */

ClientPlugin #

Configuration for client plugins.

InstanceContext #

Context for Coralite script instances.

Content Nodes #

CoraliteElement #

Represents a standard HTML element in the Coralite content tree.

CoraliteTextNode #

Represents a text node within the Coralite content tree.

CoraliteComment #

Represents an HTML comment within the Coralite content tree.

CoraliteAnyNode #

Union type representing any content node (element, text, or comment).

CoraliteContentNode #

Union type representing nodes that can be part of a document's content hierarchy.

Plugins, Collections and Events #

IgnoreByAttribute #

An array of attribute name-value pairs to exclude from processing.

CoraliteCollectionCallbackResult #

Result value returned from event handlers.

CoraliteCollectionItem #

A document object with both HTMLData properties and result handling capabilities.

CoraliteCollectionEventResult #

Processed value from event handlers.

CoraliteCollectionEventSet #

Callback for setting an item in a collection.

  /**
        * @callback CoraliteCollectionEventSet
        * @param {CoraliteCollectionItem} value - Item to be set
        * @returns {Promise

CoraliteCollectionEventDelete #

Callback for deleting an item from a collection.

  /**
        * @callback CoraliteCollectionEventDelete
        * @param {CoraliteCollectionItem} value - Item or pathname to delete
        * @async
        */

CoraliteCollectionEventUpdate #

Callback for updating an item in a collection.

  /**
        * @callback CoraliteCollectionEventUpdate
        * @param {CoraliteCollectionItem} newValue - New item value
        * @param {CoraliteCollectionItem} oldValue - Original item value
        * @async
        */

CoralitePluginContext #

Runtime context for plugin execution.

CoralitePluginModule #

Execution function that processes content using plugin logic.

  /**
        * @template T
        * @this {ThisType

CoralitePlugin #

Definition of a Coralite plugin.

CoralitePluginResult #

Result type for Coralite plugins with generic component parameter.

CoralitePluginInstance #

A Coralite plugin with associated component data.

CoralitePluginPageSetCallback #

Async callback triggered when a page is created.

  /**
        * @this {ThisType

CoralitePluginPageUpdateCallback #

Async callback triggered when a page is updated.

  /**
        * @this {ThisType

CoralitePluginPageDeleteCallback #

Async callback triggered when a page is deleted.

  /**
        * @this {ThisType

CoralitePluginComponentCallback #

Async callback triggered for component-related events.

  /**
        * @this {ThisType

Constructor and Methods #

Constructor #

The Coralite constructor initializes a new instance with configuration options for templates, pages, plugins and ignore attributes.

  /**
  * @constructor
  * @param {Object} options
  * @param {string} options.templates - The path to the directory containing Coralite templates.
  * @param {CoralitePluginInstance[]} [options.plugins=[]]
  * @param {string} options.pages - The path to the directory containing pages that will be rendered using the
  provided templates.
  * @param {IgnoreByAttribute[]} [options.ignoreByAttribute] - Elements to ignore with attribute name value
  pair
  * @example
  * const coralite = new Coralite({
  * templates: './path/to/templates',
  * pages: './path/to/pages',
  * plugins: [myPlugin],
  * ignoreByAttribute: [{ name: 'data-ignore', value: 'true' }]
  * });
  */

Constructor Parameters #

Constructor Options Properties #

Initialise Method #

Initialises the Coralite instance.

  /**
  * Initialises the Coralite instance.
  * @returns {Promise

Returns #

A promise that resolves when the initialization is complete.

Compile Method #

Compiles specified page(s) by rendering their document content and measuring render time. Processes pages based on provided path(s), replacing custom elements with components, and returns rendered results with performance metrics.

  /**
  * Compiles specified page(s) by rendering their document content and measuring render time.
  * Processes pages based on provided path(s), replacing custom elements with components,
  * and returns rendered results with performance metrics.
  *
  * @param {string | string[]} [path] - Path to a single page or array of page paths relative to the pages
  directory. If omitted, compiles all pages.
  * @return {Promise

Parameters #

Returns #

An array of rendered results with performance metrics.

Save Method #

Saves processed documents as HTML files to the specified output directory.

  /**
  * Saves processed documents as HTML files to the specified output directory.
  * @param {Array

Parameters #

Render Method #

Renders the provided node or array of nodes using the render function. This method serves as an internal utility to handle the rendering process.

  /**
  * Renders the provided node or array of nodes using the render function.
  * This method serves as an internal utility to handle the rendering process.
  * @private
  * @param {CoraliteDocumentRoot | CoraliteAnyNode | CoraliteAnyNode[]} root - The node(s) to be rendered.
  * @returns {string} returns raw HTML
  */
  Coralite.prototype._render = function (root) {
  }

Parameters #

Returns #

Raw HTML string from the rendering process.

Get Page Paths Using Custom Element #

Retrieves page paths associated with a custom element template.

  /**
  * Retrieves page paths associated with a custom element template.
  *
  * @param {string} path - The original path potentially prefixed with the templates directory.
  * @returns {string[]} An array of page paths linked to the custom element template.
  */
  Coralite.prototype.getPagePathsUsingCustomElement = function (path) {
  }

Parameters #

Returns #

An array of page paths linked to the custom element template.

Add Render Queue #

Adds a page to the current render queue.

  /**
  * Adds a page to the current render queue.
  * @param {string|CoraliteCollectionItem} value - The path to a page or a CoraliteCollectionItem to add to
  the render queue.
  */
  Coralite.prototype.addRenderQueue = async function (value) {
  }

Parameters #

Create Component #

Creates a component by processing the provided parameters and returning a rendered HTML element.

  /**
  * @param {Object} options
  * @param {string} options.id - id - Unique identifier for the component
  * @param {CoraliteModuleValues} [options.values={}] - Token values available for replacement
  * @param {CoraliteElement} [options.element] - Mapping of component IDs to their module definitions
  * @param {CoraliteDocument} options.document - Current document being processed
  * @param {string} [options.contextId] - Context Id
  * @param {number} [options.index] - Context index
  * @param {boolean} [head=true] - Indicates if the current function call is for the head of the recursion
  * @returns {Promise

Parameters #

Returns #

A promise that resolves to a rendered HTML element or void.

Evaluate Method #

Parses a Coralite module script and compiles it into JavaScript.

  /**
  * Parses a Coralite module script and compiles it into JavaScript.
  * @private
  * @param {Object} data
  * @param {CoraliteModule} data.module - The Coralite module to parse
  * @param {CoraliteModuleValues} data.values - Replacement tokens for the component
  * @param {CoraliteElement} data.element - The Coralite module to parse
  * @param {CoraliteDocument} data.document - The document context in which the module is being processed
  * @param {string} data.contextId - Context Id
  *
  * @returns {Promise

Parameters #

Returns #

A promise that resolves to an object containing compiled JavaScript content.

Module Linker #

Links modules with their file paths for processing.

  /**
  * @param {CoraliteFilePath} path
  * @private
  */
  Coralite.prototype._moduleLinker = function (path) {
  }

Parameters #

Trigger Plugin Hook #

Executes all plugin callbacks registered under the specified hook name.

  /**
  * @template {Object} T
  * @private
  * Executes all plugin callbacks registered under the specified hook name.
  * @param
  {'onPageSet'|'onPageUpdate'|'onPageDelete'|'onComponentSet'|'onComponentUpdate'|'onComponentDelete'}
  name - The name of the hook to trigger.
  * @param {T} data - Data to pass to each callback function.
  * @return {Promise

Parameters #

Returns #

A promise that resolves to an array of results from all callbacks.

Add Plugin Hook #

Registers a callback function under the specified hook name.

  /**
  * Registers a callback function under the specified hook name.
  * @private
  * @param
  {'onPageSet'|'onPageUpdate'|'onPageDelete'|'onComponentSet'|'onComponentUpdate'|'onComponentDelete'}
  name - The name of the hook to register the callback with.
  * @param {Function} callback - The callback function to be executed when the hook is triggered.
  */
  Coralite.prototype._addPluginHook = function (name, callback) {
  }

Parameters #