Coralite Library

The Coralite library is used for processing and rendering HTML documents with custom elements, components, and plugins. It provides a structured way to manage document metadata, component paths, plugin configurations, and ignored attributes during rendering.

Table of Contents #

Coralite Constructor
Initialise Method
Build Method
Save Method
Render Method
Get Page Paths Using Custom Element
Add Render Queue
Create Component

Coralite Constructor #

Initializes a Coralite instance using the await createCoralite factory with configuration options for components, pages, plugins, and ignore attributes.

Parameters #

Name	Type	Attribute	Description
options	`Object`	Required	Configuration options for the `Coralite` constructor.
options.components	`string`	Required	The absolute or relative path to the directory containing Coralite components.
options.pages	`string`	Required	The absolute or relative path to the directory containing pages to be rendered with the provided components.
options.plugins	`CoralitePluginInstance[]`	Optional	An array of plugin instances that extend Coralite's functionality.
options.ignoreByAttribute	`IgnoreByAttribute[]` \| `string[]`	Optional	An array of strings or objects specifying attribute name-value pairs to ignore during document processing. Objects must have a name and value property.
options.skipRenderByAttribute	`IgnoreByAttribute[]` \| `string[]`	Optional	An array of strings or objects specifying attribute name-value pairs to skip rendering.
options.onError	`CoraliteOnError`	Optional	A callback function for handling errors, warnings, and logs from the framework. The `Coralite` instance uses an internal `handleError` method to wrap and manage this callback. If not provided, level `'ERR'` will throw by default.

Example Usage #

  const coralite = await createCoralite({
    components: './src/components',
    pages: './src/pages',
    plugins: [myCustomPlugin],
    ignoreByAttribute: [
      { name: 'data-ignore', value: 'true' },
      { name: 'aria-hidden', value: 'true' }
    ],
    skipRenderByAttribute: [
      'data-client-only'
    ]
  });

Initialise Method #

Initialises the Coralite instance by loading components and setting up collections for pages and custom elements.

  /**
   * Initialises the Coralite instance.
   * @returns {Promise*void*}
   */
  
      <coralite-heading level="h3" text="Returns"></coralite-heading>
      <p>A promise that resolves when the initialization is complete.</p>
  
      <coralite-heading level="h2" text="Build Method" id="build-method"></coralite-heading>
      <p>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.</p>
  
      <coralite-code-highlight language="JavaScript">/**
   * 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.
   * @param {CoraliteBuildOptions} [options] - Build configuration options.
   * @param {function} [callback] - Optional callback to transform each page result.
   * @return {Promise<coraliteresult[]>}
   */
  coralite.build(path, options, callback)</coraliteresult[]></coralite-code-highlight>
  
      <coralite-heading level="h3" text="Parameters"></coralite-heading>
      <div class="table-responsive">
        <table class="table">
          <thead>
            <tr>
              <th scope="col">Name</th>
              <th scope="col">Type</th>
              <th scope="col">Attribute</th>
              <th scope="col">Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <th scope="row">path</th>
              <td><code>string</code> | <code>string[]</code></td>
              <td>Optional</td>
              <td>The path or array of paths to the HTML files relative to the project&apos;s <code>pages</code> directory. If omitted, compiles all <code>pages</code> in the pages directory.</td>
            </tr>
            <tr>
              <th scope="row">options</th>
              <td><code><a href="/docs/reference/types.html#coralitebuildoptions">CoraliteBuildOptions</a></code></td>
              <td>Optional</td>
              <td>Configuration options for the build process.</td>
            </tr>
            <tr>
              <th scope="row">callback</th>
              <td><code>function</code></td>
              <td>Optional</td>
              <td>A function invoked for each page to transform the result.</td>
            </tr>
          </tbody>
        </table>
      </div>
  
      <coralite-heading level="h3" text="Example Usage"></coralite-heading>
      <p>Build a single page by providing its file path:</p>
      <coralite-code-highlight language="JavaScript">coralite.build(&apos;pages/home/index.html&apos;)
    .then(documents =&gt; {
      console.log(&apos;Build result:&apos;, documents);
    })
    .catch(error =&gt; {
      console.error(&apos;Error during build:&apos;, error);
    });</coralite-code-highlight>
  
      <p>Building multiple pages using an array of paths:</p>
      <coralite-code-highlight language="JavaScript">coralite.build([&apos;pages/home/index.html&apos;, &apos;pages/about/index.html&apos;])
    .then(documents =&gt; {
      documents.forEach((document, index) =&gt; {
        console.log(`Result for page &#x24;{index + 1}:`, document);
      });
    })
    .catch(error =&gt; {
      console.error(&apos;Error during build:&apos;, error);
    });</coralite-code-highlight>
  
      <p>Building all pages by omitting the path parameter:</p>
      <coralite-code-highlight language="JavaScript">coralite.build()
    .then(documents =&gt; {
      console.log(&apos;All built documents:&apos;, documents)
    })
    .catch(error =&gt; {
      console.error(&apos;Error building all pages:&apos;, error)
    });</coralite-code-highlight>
  
      <coralite-heading level="h2" text="Save Method" id="save-method"></coralite-heading>
      <p>Saves processed pages and assets to the output directory configured in the Coralite instance.</p>
  
      <coralite-code-highlight language="JavaScript">/**
   * Compiles and saves pages to disk.
   *
   * @param {string | string[]} [path] - Optional page path(s) to build.
   * @param {CoraliteBuildOptions} [options] - Build configuration options.
   * @returns {Promise&lt;{ path: string, duration: number }[]&gt;} Array of saved file paths.
   */
  coralite.save(path, options)</coralite-code-highlight>
  
      <coralite-heading level="h3" text="Parameters"></coralite-heading>
      <div class="table-responsive">
        <table class="table">
          <thead>
            <tr>
              <th scope="col">Name</th>
              <th scope="col">Type</th>
              <th scope="col">Attribute</th>
              <th scope="col">Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <th scope="row">path</th>
              <td><code>string | string[]</code></td>
              <td>Optional</td>
              <td>Optional page path(s) to build.</td>
            </tr>
            <tr>
              <th scope="row">options</th>
              <td><code><a href="/docs/reference/types.html#coralitebuildoptions">CoraliteBuildOptions</a></code></td>
              <td>Optional</td>
              <td>Build configuration options.</td>
            </tr>
          </tbody>
        </table>
      </div>
  
      <coralite-heading level="h3" text="Example Usage"></coralite-heading>
      <coralite-code-highlight language="JavaScript">coralite.build()
    .then(async (documents) =&gt; {
      // save documents to disk
      await coralite.save()
    })
    .catch(error =&gt; {
      console.error(&apos;Error building all pages:&apos;, error)
    })</coralite-code-highlight>
  
      <coralite-heading level="h2" text="Render Method"></coralite-heading>
      <p>Renders the provided node or array of nodes using the render function. This method serves as an internal utility to handle the rendering process.</p>
  
      <coralite-code-highlight language="JavaScript">/**
   * 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 {CoraliteComponentRoot | CoraliteAnyNode | CoraliteAnyNode[]} root - The node(s) to be rendered.
   * @returns {string} returns raw HTML
   */
  coralite._render(root)</coralite-code-highlight>
  
      <coralite-heading level="h3" text="Parameters"></coralite-heading>
      <div class="table-responsive">
        <table class="table">
          <thead>
            <tr>
              <th scope="col">Name</th>
              <th scope="col">Type</th>
              <th scope="col">Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <th scope="row">root</th>
              <td><code>CoraliteComponentRoot | CoraliteAnyNode | CoraliteAnyNode[]</code></td>
              <td>The node(s) to be rendered.</td>
            </tr>
          </tbody>
        </table>
      </div>
  
      <coralite-heading level="h3" text="Returns"></coralite-heading>
      <p>Raw HTML string from the rendering process.</p>
  
      <coralite-heading level="h2" text="Get Page Paths Using Custom Element"></coralite-heading>
      <p>Retrieves page paths associated with a custom element component.</p>
  
      <coralite-code-highlight language="JavaScript">/**
   * Retrieves page paths associated with a custom element component.
   *
   * @param {string} path - The original path potentially prefixed with the components directory.
   * @returns {string[]} An array of page paths linked to the custom element component.
   */
  coralite.getPagePathsUsingCustomElement(path)</coralite-code-highlight>
  
      <coralite-heading level="h3" text="Parameters"></coralite-heading>
      <div class="table-responsive">
        <table class="table">
          <thead>
            <tr>
              <th scope="col">Name</th>
              <th scope="col">Type</th>
              <th scope="col">Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <th scope="row">path</th>
              <td><code>string</code></td>
              <td>The original path potentially prefixed with the components directory.</td>
            </tr>
          </tbody>
        </table>
      </div>
  
      <coralite-heading level="h3" text="Returns"></coralite-heading>
      <p>An array of page paths linked to the custom element component.</p>
  
      <coralite-heading level="h2" text="Add Render Queue"></coralite-heading>
      <p>Adds a page to the current render queue.</p>
  
      <coralite-code-highlight language="JavaScript">/**
   * 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.addRenderQueue(value)</coralite-code-highlight>
  
      <coralite-heading level="h3" text="Parameters"></coralite-heading>
      <div class="table-responsive">
        <table class="table">
          <thead>
            <tr>
              <th scope="col">Name</th>
              <th scope="col">Type</th>
              <th scope="col">Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <th scope="row">value</th>
              <td><code>string | CoraliteCollectionItem</code></td>
              <td>The path to a page or a CoraliteCollectionItem to add to the render queue.</td>
            </tr>
          </tbody>
        </table>
      </div>
  
      <coralite-heading level="h2" text="Create Component"></coralite-heading>
      <p>Creates a component by processing the provided parameters and returning a rendered HTML element.</p>
  
      <coralite-code-highlight language="JavaScript">/**
   * @param {Object} options
   * @param {string} options.id - id - Unique identifier for the component
   * @param {Object} [options.state={}] - Initial state available for replacement
   * @param {CoraliteElement} [options.element] - Mapping of component IDs to their module definitions
   * @param {CoraliteComponent} 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&amp;lt;CoraliteElement | void&amp;gt;}
   *
   * @example
   * // example usage:
   * const component = await coralite.createComponentElement({
   *   id: &apos;my-component&apos;,
   *   state: {
   *     &apos;some-value&apos;: &apos;value-for-component&apos;
   *   },
   *   element: customElement,
   *   document: documentInstance,
   *   contextId: &apos;unique-context-id&apos;,
   *   index: 0
   * })
   */
  coralite.createComponentElement(options)</coralite-code-highlight>
  
      <coralite-heading level="h3" text="Parameters"></coralite-heading>
      <div class="table-responsive">
        <table class="table">
          <thead>
            <tr>
              <th scope="col">Parameter</th>
              <th scope="col">Type</th>
              <th scope="col">Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <th scope="row">options.id</th>
              <td><code>string</code></td>
              <td>Unique identifier for the component</td>
            </tr>
            <tr>
              <th scope="row">options.state</th>
              <td><code>Object</code></td>
              <td>Initial state available for replacement (default: {})</td>
            </tr>
            <tr>
              <th scope="row">options.element</th>
              <td><code>CoraliteElement</code></td>
              <td>Mapping of component IDs to their module definitions (optional)</td>
            </tr>
            <tr>
              <th scope="row">options.document</th>
              <td><code>CoraliteComponent</code></td>
              <td>Current document being processed</td>
            </tr>
            <tr>
              <th scope="row">options.contextId</th>
              <td><code>string</code></td>
              <td>Context Id (optional)</td>
            </tr>
            <tr>
              <th scope="row">options.index</th>
              <td><code>number</code></td>
              <td>Context index (optional)</td>
            </tr>
          </tbody>
        </table>
      </div>
  
      <coralite-heading level="h3" text="Returns"></coralite-heading>
      <p>A promise that resolves to a rendered HTML element or void.</p>

Coralite Library

Start Building with Coralite!