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.
- 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.
npm install coralite-plugin-aggregationFirst, 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.
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>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>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 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). | - |
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'). |
- |
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'] }). |
Callback function for filtering aggregated content based on metadata.
| Parameter | Type | Description |
|---|---|---|
metadata |
CoraliteToken |
Aggregated HTML page metadata (e.g., { name: 'category', content: 'tech' }). |
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. |
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'). |
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.
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>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).
<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>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"). |