Commandbox-ssg with data and updated pagination support

Commandbox-ssg now with data import and pagination enhancements cfml commandbox

January 17, 2024 / Robert Zehnder

In the tech world, it's always exciting to see tools evolve, and the latest update to commandbox-ssg is no exception. This update introduces some key enhancements, primarily focused on integrating external data into applications with greater ease and efficiency. Let's delve into what this means for developers.

Enhanced Data Integration

One of the standout features in this update is the automated data loading capability. Now, any data residing in the _data/ directory is automatically loaded and made accessible in the scope, named according to the file name. For instance, a file named _data/myData.json becomes readily available in views as This is a significant step towards simplifying data management, although the current version does not support nested directories. However, plans are underway to incorporate this feature.

Advanced Pagination Capabilities

Pagination has received a substantial upgrade. commandbox-ssg now supports pagination through arrays and objects within the collections scope. To illustrate, consider the following example that demonstrates generating pages based on post tags:

layout: main
view: page
permalink: /tag/{{tag}}.html
  alias: tag
  data: collections.tags
 <h4>Posts tagged as #prc.tag#</h4>
 <cfloop array="#collections.byTag[generateSlug(prc.tag)]#" index="i">
  <p><a href="#i.permalink#" class="post-link text-decoration-none">#i.title#</a></p>

When dealing with paginated templates, there are several nuances to consider:

  • The default return value for paged data is pagedData if no alias is set.
  • Data can be specified either using Yaml or directly within the collections scope.
  • A permalink is crucial for correct page generation.

Dynamic tokens in permalinks offer flexibility in content generation. In this case, the pagination of collections.tags data utilizes the {{tag}} alias for permalink generation. In the absence of a set alias, pagedData would be used by default.

Paginating through structures yields an array of struct keys, providing immediate access to the data of the current element.

Practical Application: The CFDocs Site

A prime example of these capabilities in action is the CFDocs site. Organized in JSON files named by function/tag, the site demonstrates the ease of creating templates to display data. Here's a sample JSON structure from the abs.json file:

 "description":" Absolute-value function. The absolute value of a number is\n the number without its sign.",
 "params": [
 "engines": {
  "coldfusion": {"minimum_version":"", "notes":"", "docs":""},
  "lucee": {"minimum_version":"", "notes":"", "docs":""},
  "railo": {"minimum_version":"", "notes":"", "docs":""},
  "openbd": {"minimum_version":"", "notes":"", "docs":""}
 "links": [],
 "examples": [
   "title":"Absolute Value of -4.3",


By integrating all CFDocs data files into the _data directory, one could leverage pagination to generate comprehensive documentation while maintaining the directory structure.

type: docs
permalink: /{{element}}.html
  alias: element
 <cfdump var="#prc#"/>

While the system still has room for refinement, its current iteration is both functional and efficient, capable of generating over 990 templates in under 30 seconds.


These updates are set to go live with the release of version 0.0.17 of commandbox-ssg. This marks a significant milestone in the tool's development, offering developers enhanced capabilities for managing and displaying data in their applications.