coralite-plugin-aggregation

v0.5.4

Published

2 months ago

A Coralite plugin for dynamically collecting, filtering, sorting, and displaying content across multiple sources. Build database-free Coralite websites with automated content aggregation.

0High
0Medium
0Low

cak3

coralite plugin aggregation static site generator content management content aggregation filtering sorting pagination metadata database-free static website

Coralite Aggregation Plugin

The Coralite Aggregation Plugin is a powerful tool designed to help developers dynamically collect, filter, sort, and display content across multiple sources within a Coralite project.

Features

Content Aggregation: Gather content from multiple files or directories using path patterns (e.g., blog/, ['products/all','blog/']).
Filtering & Sorting: Use metadata-based filters and custom sort functions to refine results based on attributes like tags, categories, dates, or tokens.
Pagination Support: Easily create paginated views with customizable templates for navigation controls and visible page links.
Token Handling: Configure token aliases, defaults, and metadata mapping.

Coralite Aggregation Plugin Guide

Installation

npm install coralite-plugin-aggregation

Setup Configuration

First, enable the plugin in your coralite.config.js:

// coralite.config.js
import aggregation from 'coralite-plugin-aggregation'

export default {
  plugins: [aggregation]
}

Note: The plugin must be imported as 'coralite-plugin-aggregation' for compatibility with the core Coralite framework.

Example Implementation

Entry Point: Displaying Aggregated Results

Create a file like coralite-posts.html to define your aggregation logic and rendering template:

<!-- templates/coralite-posts.html -->
<template id="coralite-posts">
  <div>
    {{ posts }}
    <!-- Pagination controls will be injected automatically if enabled. -->
  </div>
</template>

<script type="module">
import { defineComponent, aggregation } from 'coralite/plugins'

export default defineComponent({
  tokens: {
    // Aggregation function returns an array of content items.
    posts() {
      return aggregation({
        path: ['products'],              // Source directory.
        template: 'coralite-post',       // Template ID for individual items.
        limit: 20,                       // Maximum number of results per page.
        recursive: true,                 // Include subdirectories.
        pagination: {
          token: 'post_count',           // Page size control token.
          template: 'coralite-pagination', // Template for pagination controls.
          segment: 'page',                  // Segment for paginated URLs (e.g., `page/1`).
          maxVisible: 5                     // Max number of visible page links.
        },
        filter(meta) {
          return meta.name === 'category' && meta.content === 'tech'
        },
        sort(a, b) {
          return new Date(b.date) - new Date(a.date)
        },
        tokens: {
          default: {
            author: 'Anonymous',
            category: 'uncategorized'
          },
          aliases: {
            tags: ['tech', 'news', 'tutorial']
          }
        }
      })
    }
  }
})
</script>

Aggregated Content Files

Each file to be aggregated must include metadata via <meta> elements. For example:

<!-- pages/products/product-1.html -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="title" content="Great Barrier Reef" />
  <meta name="description" content="The Great Barrier Reef—largest, comprising over 2,900 individual reefs and 900 islands stretching for over 2,600 kilometers." />
  <meta name="price" content="1000" />
  <meta name="published_time" content="2025-01-08T20:23:07.645Z" />
</head>
<body>
  <coralite-header>
    <h1>Great Barrier Reef</h1>
  </coralite-header>
  <coralite-author name="Nemo" datetime="2025-01-08T20:23:07.645Z"></coralite-author>
</body>
</html>

Single Result Template

Define a <template> element for rendering individual items:

<!-- templates/coralite-post.html -->
<template id="coralite-post">
  <div class="post-item">
    <h2>{{ $title }}</h2>
    <p>{{ $description }} - {{ formattedPrice }}</p>
  </div>
</template>

<script type="module">
import { defineComponent } from 'coralite/plugins'

export default defineComponent({
  tokens: {
    // Custom token to format prices using Intl.NumberFormat.
    formattedPrice(values) {
      return new Intl.NumberFormat("en-AU", { style: "currency", currency: "AUD" }).format(
        values.$price
      )
    }
  }
})
</script>

Token Syntax: Metadata attributes are accessed in templates as $<meta name>. For example, the <meta name="title"> element is referenced using $title.

Configuration Options {#types}

`CoraliteAggregate` {#coralite-aggregate}

Configuration object for content aggregation processes.

| Property | Type | Description | Reference | |-----------------|----------------------------------------------------------------------|-----------------------------------------------------------------------------------------------|-----------| | path | string[] | Array of paths relative to the pages directory (e.g., ['products', 'blog/']). | - | | template | CoraliteAggregateTemplate or string | Templates used to display the result. Must match an existing <template> element by ID. | CoraliteAggregateTemplate | | pagination | Object | Pagination settings (optional). | - | | filter | CoraliteAggregateFilter | Callback to filter out unwanted elements from the aggregated content. | CoraliteAggregateFilter | | recursive | boolean | Whether to recursively search subdirectories. | - | | tokens | CoraliteTokenOptions | Token configuration options (optional). | CoraliteTokenOptions | | sort | CoraliteAggregateSort | Sort aggregated pages. | CoraliteAggregateSort | | limit | number | Maximum number of results to retrieve (used with pagination). | - | | offset | number | Starting index for the results list (used with pagination). | - |

`CoraliteAggregateTemplate` {#coralite-aggregate-template}

Configuration for templates used to render aggregated results.

| Property | Type | Description | Reference | |----------|-----------|-----------------------------------------------------------------------------|-----------| | item | string | Unique identifier for the component used for each document (e.g., 'coralite-post'). | - |

`CoraliteTokenOptions` {#coralite-token-options}

Configuration options for token handling during processing.

| Property | Type | Description | |--------------|-------------------------------------------------------|-----------------------------------------------------------------------------| | default | Object.<string, string> | Default token values for properties not explicitly set (e.g., { author: 'Anonymous' }). | | aliases | Object.<string, string[]> | Token aliases and their possible values (e.g., { tags: ['tech', 'news'] }). |

`CoraliteAggregateFilter` {#coralite-aggregate-filter}

Callback function for filtering aggregated content based on metadata.

| Parameter | Type | Description | |---------------|-------------------------------------|-----------------------------------------------------------------------------| | metadata | CoraliteToken | Aggregated HTML page metadata (e.g., { name: 'category', content: 'tech' }). |

`CoraliteAggregateSort` {#coralite-aggregate-sort}

Callback function for sorting aggregated results based on metadata.

| Parameter | Type | Description | |-----------|-------------------------------------|-----------------------------------------------------------------------------| | a | Object.<string, string> | Metadata of the first item being compared (e.g., { date: '2025-01-08' }). | | b | Object.<string, string> | Metadata of the second item being compared. |

`CoraliteToken` {#coralite-token}

A representation of a token with name and value.

| Property | Type | Description | |----------|--------|-----------------------------------------------------------------------------| | name | string | Token identifier (e.g., 'title', 'category'). | | content| string | Token value or content (e.g., 'Great Barrier Reef', 'tech'). |

Custom Pager Template User Guide for Coralite Pagination Component {#custom-pager}

This guide explains how to create a custom pagination template using the existing coralite-pagination component as a reference. The goal is to define a new pager layout below the default implementation, preserving compatibility with the core logic while enabling customization.

Create a New Template Element

Define a unique <template> element for your custom pager. Use an ID distinct from the default (coralite-pagination) to avoid conflicts:

<template id="coralite-pagination-custom">
  {{ paginationList }}
</template>

Implement Custom Logic in `<script type="module">`

Replace or extend the paginationList token function with your custom logic. The core structure remains compatible with Coralite’s API, but you can modify rendering rules (e.g., ellipsis behavior, link formatting).

Example: Basic Custom Token Function

<script type="module">
  import { defineComponent } from 'coralite'

  export default defineComponent({
    tokens: {
      paginationList (values) {
        const length = parseInt(values.paginationLength)
        if (!length) return ''

        // Custom logic: render a simplified pager with only previous/next and current page
        const currentPage = parseInt(values.paginationCurrent)
        const dirname = values.pagination_dirname[0] === '/' ? values.paginationDirname : '/' + values.pagination_dirname

        let html = '<ul class="pagination">'

        // Previous link
        if (currentPage > 1) {
          html += `<li class="page-item"><a class="page-link" href="${dirname}/${currentPage - 1}.html">Previous</a></li>`
        } else {
          html += '<li class="page-item disabled"><span class="page-link">Previous</span></li>'
        }

        // Current page
        html += `<li class="page-item active"><span class="page-link">${currentPage}</span></li>`

        // Next link
        if (currentPage < length) {
          html += `<li class="page-item"><a class="page-link" href="${dirname}/${currentPage + 1}.html">Next</a></li>`
        } else {
          html += '<li class="page-item disabled"><span class="page-link">Next</span></li>'
        }

        html += '</ul>'
        return html
      }
    }
  })
</script>

Template tokens

The pagination template receives these token values:

| Property | Description | |------------------------------|-----------------------------------------------------------------------------| | paginationIndexPathname | The index path name for pagination (e.g., /blog/index.html). | | paginationSegment | The current segment of pagination (e.g., "page"). | | paginationMaxVisible | Maximum number of visible pages in the pagination UI. | | paginationProcessed | Indicates whether the pagination has been processed (true/false). | | paginationOffset | String representation of the offset (used for page calculations). | | paginationFilePathname | The file path name for pagination context (e.g., /blog/page-2.html). | | paginationFileDirname | The directory name of the file for pagination context (e.g., /blog). | | paginationURLPathname | The URL path name used in pagination (e.g., /blog/). | | paginationURLDirname | The URL directory name used in pagination (e.g., /blog). | | paginationLength | Total length of the paginated data set (used to determine total page count).| | paginationCurrent | Current page index (as a string, e.g., "2"). |

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme