@reldens/cms 0.12.0 → 0.13.0

package/README.md

@@ -19,6 +19,7 @@ A powerful, flexible Content Management System built with Node.js, featuring an
 - **Template fallback system** (domain → default → base)
 - **Layout system** with body content layouts and page wrappers
 - **Reusable content blocks** with `{{ entity() }}` template functions
+- **Collection rendering** with filtering and loop support
 - **Entity access control** for public/private content
 - **Static asset serving** with Express integration as default
 - **Template engine** with Mustache integration as default
@@ -44,7 +45,7 @@ A powerful, flexible Content Management System built with Node.js, featuring an
 
 ### - Configuration & Architecture
 - **Environment-based configuration** (.env file)
-- **Modular service architecture** (Frontend, AdminManager, DataServer)
+- **Modular service architecture** (Frontend, AdminManager, DataServer, TemplateEngine)
 - **Event-driven system** with hooks for customization
 - **Extensible authentication** (database users or custom callbacks)
 - **File security** with path validation and dangerous key filtering
@@ -127,15 +128,43 @@ const cms = new Manager({
 ## Enhanced Templating System
 
 ### Template Functions
-Templates now support dynamic content blocks and entity rendering:
+Templates support dynamic content blocks, entity rendering, and collections:
+
+**Single Entity Rendering:**
 ```html
-<!-- Render content blocks -->
-{{ entity('cms_blocks', 'header-main') }}
-{{ entity('cms_blocks', 'sidebar-left') }}
+<!-- Render by any identifier field (like 'name' for content blocks) -->
+{{ entity('cmsBlocks', 'header-main', 'name') }}
+{{ entity('cmsBlocks', 'sidebar-left', 'name') }}
 
-<!-- Render other entities -->
+<!-- Render by ID (default identifier) -->
 {{ entity('products', '123') }}
-{{ entity('cms_pages', '1') }}
+{{ entity('cmsPages', '1') }}
+```
+
+**Single Field Collections:**
+```html
+<!-- Extract and concatenate a single field from multiple records -->
+{{ collection('cmsBlocks', {"status": "active", "category": "navigation"}, 'content') }}
+{{ collection('products', {"featured": true}, 'title') }}
+```
+
+**Loop Collections:**
+```html
+<!-- Loop through records with full template rendering -->
+{{ #collection('cmsBlocks', {"status": "active"}) }}
+  <div class="block">
+    <h3>{{row.title}}</h3>
+    <div class="content">{{row.content}}</div>
+  </div>
+{{ /collection('cmsBlocks') }}
+
+{{ #collection('products', {"category": "electronics"}) }}
+  <div class="product">
+    <h4>{{row.name}}</h4>
+    <p>Price: ${{row.price}}</p>
+    <img src="{{row.image}}" alt="{{row.name}}">
+  </div>
+{{ /collection('products') }}
 ```
 
 ### Layout System
@@ -159,13 +188,13 @@ The CMS uses a two-tier layout system:
 
 **layouts/default.html** - Body content only:
 ```html
-{{ entity('cms_blocks', 'header-main') }}
+{{ entity('cmsBlocks', 'header-main', 'name') }}
 
 <main id="main" class="main-container">
     <div class="container">
         <div class="row">
             <div class="col-md-3">
-                {{ entity('cms_blocks', 'sidebar-left') }}
+                {{ entity('cmsBlocks', 'sidebar-left', 'name') }}
             </div>
             <div class="col-md-9">
                 {{{content}}}
@@ -174,7 +203,7 @@ The CMS uses a two-tier layout system:
     </div>
 </main>
 
-{{ entity('cms_blocks', 'footer-main') }}
+{{ entity('cmsBlocks', 'footer-main', 'name') }}
 ```
 
 Pages can use different layouts by setting the `layout` field in `cms_pages`:
@@ -306,7 +335,14 @@ The installer provides checkboxes for:
 - `handleRequest(req, res)` - Main request handler
 - `findRouteByPath(path)` - Database route lookup
 - `findEntityByPath(path)` - Entity-based URL handling
-- `processCustomTemplateFunctions(template)` - Process {{ entity() }} functions
+
+### TemplateEngine Class
+- `render(template, data, partials)` - Main template rendering with enhanced functions
+- `processEntityFunctions(template)` - Process {{ entity() }} functions
+- `processSingleFieldCollections(template)` - Process single field collections
+- `processLoopCollections(template)` - Process loop collections
+- `fetchEntityForTemplate(tableName, identifier, identifierField)` - Load single entity
+- `fetchCollectionForTemplate(tableName, filtersJson)` - Load entity collections
 
 ### AdminManager Class
 - `setupAdmin()` - Initialize admin panel

package/bin/reldens-cms-generate-entities.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+
+/**
+ *
+ * Reldens - CMS - Generate Entities CLI
+ *
+ */
+
+const { Manager } = require('../index');
+const { Logger } = require('@reldens/utils');
+const readline = require('readline');
+
+class CmsEntitiesGenerator
+{
+
+    constructor()
+    {
+        this.args = process.argv.slice(2);
+        this.projectRoot = process.cwd();
+        this.isOverride = this.args.includes('--override');
+    }
+
+    async run()
+    {
+        if(this.isOverride){
+            let confirmed = await this.confirmOverride();
+            if(!confirmed){
+                Logger.info('Operation cancelled by user.');
+                return false;
+            }
+        }
+        let manager = new Manager({projectRoot: this.projectRoot});
+        if(!manager.isInstalled()){
+            Logger.error('CMS is not installed. Please run installation first.');
+            return false;
+        }
+        Logger.debug('Reldens CMS Manager instance created for entities generation.');
+        await manager.initializeDataServer();
+        let success = await manager.installer.generateEntities(manager.dataServer, this.isOverride);
+        if(!success){
+            Logger.error('Entities generation failed.');
+            return false;
+        }
+        Logger.info('Entities generation completed successfully!');
+        return true;
+    }
+
+    async confirmOverride()
+    {
+        let rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout
+        });
+        return new Promise((resolve) => {
+            Logger.warning('WARNING: Using --override will regenerate ALL entities and overwrite existing files.');
+            rl.question('Are you sure you want to continue? (yes/no): ', (answer) => {
+                rl.close();
+                resolve('yes' === answer.toLowerCase() || 'y' === answer.toLowerCase());
+            });
+        });
+    }
+
+}
+
+let generator = new CmsEntitiesGenerator();
+generator.run().then((success) => {
+    if(!success){
+        process.exit(1);
+    }
+    process.exit(0);
+}).catch((error) => {
+    Logger.critical('Error during entities generation: '+error.message);
+    process.exit(1);
+});

package/lib/frontend.js

@@ -6,6 +6,7 @@
 
 const { FileHandler } = require('@reldens/server-utils');
 const { Logger, sc } = require('@reldens/utils');
+const { TemplateEngine } = require('./template-engine');
 
 class Frontend
 {
@@ -27,6 +28,7 @@ class Frontend
         this.domainPartialsCache = new Map();
         this.domainTemplatesMap = new Map();
         this.entityAccessCache = new Map();
+        this.templateEngine = false;
     }
 
     async initialize()
@@ -51,6 +53,10 @@ class Frontend
             Logger.error('Public folder not found: '+this.publicPath);
             return false;
         }
+        this.templateEngine = new TemplateEngine({
+            renderEngine: this.renderEngine,
+            dataServer: this.dataServer
+        });
         await this.loadPartials();
         await this.setupDomainTemplates();
         await this.loadEntityAccessRules();
@@ -323,42 +329,6 @@ class Frontend
         return this.findTemplatePath(templatePath, domain);
     }
 
-    async renderEnhanced(template, data, partials)
-    {
-        return this.renderEngine.render(
-            await this.processCustomTemplateFunctions(template),
-            data,
-            partials
-        );
-    }
-
-    async processCustomTemplateFunctions(template)
-    {
-        let entityRegex = /\{\{\s*entity\(\s*['"]([^'"]+)['"]\s*,\s*['"]([^'"]+)['"]\s*\)\s*\}\}/g;
-        let processedTemplate = template;
-        for(let match of template.matchAll(entityRegex)){
-            let tableName = match[1];
-            let identifier = match[2];
-            let entityData = await this.fetchEntityForTemplate(tableName, identifier);
-            processedTemplate = processedTemplate.replace(match[0], sc.get(entityData, 'content', ''));
-        }
-        return processedTemplate;
-    }
-
-    async fetchEntityForTemplate(tableName, identifier)
-    {
-        let entity = this.dataServer.getEntity(tableName);
-        if(!entity){
-            Logger.warning('Entity not found in dataServer: '+tableName);
-            return {};
-        }
-        let result = await entity.loadOneBy('name', identifier);
-        if(!result){
-            result = await entity.loadById(identifier);
-        }
-        return result || {};
-    }
-
     async renderRoute(route, domain, res)
     {
         if(!route.router || !route.content_id){
@@ -409,7 +379,7 @@ class Frontend
             Logger.error('Failed to read template: ' + templatePath);
             return false;
         }
-        return await this.renderEnhanced(template, data, this.getPartialsForDomain(domain));
+        return await this.templateEngine.render(template, data, this.getPartialsForDomain(domain));
     }
 
     async renderWithLayout(content, data, layoutName, domain, res)
@@ -419,7 +389,7 @@ class Frontend
         if(layoutPath){
             let layoutTemplate = FileHandler.readFile(layoutPath);
             if(layoutTemplate){
-                layoutContent = await this.renderEnhanced(
+                layoutContent = await this.templateEngine.render(
                     layoutTemplate,
                     Object.assign({}, data, {
                         content: sc.get(content, 'content', '')
@@ -440,7 +410,7 @@ class Frontend
             return res.send(layoutContent);
         }
         return res.send(
-            await this.renderEnhanced(
+            await this.templateEngine.render(
                 pageTemplate,
                 Object.assign({}, data, {
                     content: layoutContent,

package/lib/installer.js

@@ -234,8 +234,7 @@ class Installer
             Logger.error('SQL file "'+fileName+'" not found.');
             return '/?error=sql-file-not-found&file-name='+fileName;
         }
-        let queryResult = await dbDriver.rawQuery(sqlFileContent.toString());
-        if(!queryResult){
+        if(!await dbDriver.rawQuery(sqlFileContent)){
             Logger.error('SQL file "'+fileName+'" raw execution failed.');
             return '/?error=sql-file-execution-error&file-name='+fileName;
         }
@@ -243,9 +242,9 @@ class Installer
         return '';
     }
 
-    async generateEntities(server)
+    async generateEntities(server, isOverride = false)
     {
-        let generator = new EntitiesGenerator({server, projectPath: this.projectRoot});
+        let generator = new EntitiesGenerator({server, projectPath: this.projectRoot, isOverride});
         let success = await generator.generate();
         if(!success){
             Logger.error('Entities generation failed.');

package/lib/manager.js

@@ -55,7 +55,7 @@ class Manager
         this.defaultDomain = sc.get(props, 'defaultDomain', (process.env.RELDENS_DEFAULT_DOMAIN || ''));
         this.domainMapping = sc.get(props, 'domainMapping', sc.toJson(process.env.RELDENS_DOMAIN_MAPPING));
         this.siteKeyMapping = sc.get(props, 'siteKeyMapping', sc.toJson(process.env.RELDENS_SITE_KEY_MAPPING));
-        this.templateExtensions = sc.get(props, 'templateExtensions', ['.html', '.mustache', '.template']);
+        this.templateExtensions = sc.get(props, 'templateExtensions', ['.html', '.template']);
         this.app = sc.get(props, 'app', false);
         this.appServer = sc.get(props, 'appServer', false);
         this.dataServer = sc.get(props, 'dataServer', false);

package/lib/template-engine.js

@@ -0,0 +1,175 @@
+/**
+ *
+ * Reldens - CMS - TemplateEngine
+ *
+ */
+
+const { Logger, sc } = require('@reldens/utils');
+
+class TemplateEngine
+{
+
+    constructor(props)
+    {
+        this.renderEngine = sc.get(props, 'renderEngine', false);
+        this.dataServer = sc.get(props, 'dataServer', false);
+    }
+
+    async render(template, data, partials)
+    {
+        if(!this.renderEngine){
+            Logger.error('Render engine not provided');
+            return '';
+        }
+        if(!sc.isFunction(this.renderEngine.render)){
+            Logger.error('Render engine does not contain a render method');
+            return '';
+        }
+        return this.renderEngine.render(
+            await this.processLoopCollections(
+                await this.processSingleFieldCollections(
+                    await this.processEntityFunctions(template)
+                )
+            ),
+            data,
+            partials
+        );
+    }
+
+    getEntityRegex()
+    {
+        return /\{\{\s*entity\(\s*['"]([^'"]+)['"]\s*,\s*['"]([^'"]+)['"]\s*(?:,\s*['"]([^'"]+)['"]\s*)?\)\s*\}\}/g;
+    }
+
+    getSingleFieldCollectionRegex()
+    {
+        return /\{\{\s*collection\(\s*['"]([^'"]+)['"]\s*,\s*(\{[^}]*\})\s*,\s*['"]([^'"]+)['"]\s*\)\s*\}\}/g;
+    }
+
+    getLoopCollectionStartRegex()
+    {
+        return /\{\{\s*#collection\(\s*['"]([^'"]+)['"]\s*,\s*(\{[^}]*\})\s*\)\s*\}\}/g;
+    }
+
+    getLoopCollectionEndRegex(tableName)
+    {
+        return new RegExp('\\{\\{\\s*\\/collection\\(\\s*[\'"]'
+            +this.escapeRegex(tableName)
+            +'[\'"]\\s*\\)\\s*\\}\\}'
+        );
+    }
+
+    async processEntityFunctions(template)
+    {
+        let processedTemplate = template;
+        for(let match of template.matchAll(this.getEntityRegex())){
+            let tableName = match[1];
+            let identifier = match[2];
+            let identifierField = match[3] || 'id';
+            let entityData = await this.fetchEntityForTemplate(tableName, identifier, identifierField);
+            processedTemplate = processedTemplate.replace(match[0], sc.get(entityData, 'content', ''));
+        }
+        return processedTemplate;
+    }
+
+    async processSingleFieldCollections(template)
+    {
+        let processedTemplate = template;
+        for(let match of template.matchAll(this.getSingleFieldCollectionRegex())){
+            let tableName = match[1];
+            let filtersJson = match[2];
+            let fieldName = match[3];
+            processedTemplate = processedTemplate.replace(
+                match[0],
+                this.extractFieldValues(
+                    await this.fetchCollectionForTemplate(tableName, filtersJson),
+                    fieldName
+                )
+            );
+        }
+        return processedTemplate;
+    }
+
+    async processLoopCollections(template)
+    {
+        let processedTemplate = template;
+        let matches = [...template.matchAll(this.getLoopCollectionStartRegex())];
+        for(let i = matches.length - 1; i >= 0; i--){
+            let startMatch = matches[i];
+            let tableName = startMatch[1];
+            let filtersJson = startMatch[2];
+            let loopResult = await this.processLoopCollection(processedTemplate, startMatch, tableName, filtersJson);
+            if(false !== loopResult){
+                processedTemplate = loopResult;
+            }
+        }
+        return processedTemplate;
+    }
+
+    async processLoopCollection(template, startMatch, tableName, filtersJson)
+    {
+        let startPos = startMatch.index;
+        let startEnd = startPos + startMatch[0].length;
+        let endMatch = this.getLoopCollectionEndRegex(tableName).exec(template.substring(startEnd));
+        if(!endMatch){
+            Logger.warning('No matching end tag found for collection: '+tableName);
+            return false;
+        }
+        let endPos = startEnd + endMatch.index;
+        let renderedContent = await this.renderCollectionLoop(
+            template.substring(startEnd, endPos),
+            await this.fetchCollectionForTemplate(tableName, filtersJson)
+        );
+        return template.substring(0, startPos) + renderedContent + template.substring(endPos + endMatch[0].length);
+    }
+
+    async renderCollectionLoop(loopContent, collectionData)
+    {
+        let renderedContent = '';
+        for(let row of collectionData){
+            renderedContent += this.renderEngine.render(loopContent, {row}, {});
+        }
+        return renderedContent;
+    }
+
+    extractFieldValues(collectionData, fieldName)
+    {
+        let fieldValues = '';
+        for(let row of collectionData){
+            fieldValues += sc.get(row, fieldName, '');
+        }
+        return fieldValues;
+    }
+
+    escapeRegex(string)
+    {
+        return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+
+    async fetchEntityForTemplate(tableName, identifier, identifierField)
+    {
+        let entity = this.dataServer.getEntity(tableName);
+        if(!entity){
+            Logger.warning('Entity not found in dataServer: '+tableName);
+            return false;
+        }
+        return await entity.loadOneBy(identifierField, identifier);
+    }
+
+    async fetchCollectionForTemplate(tableName, filtersJson)
+    {
+        let entity = this.dataServer.getEntity(tableName);
+        if(!entity){
+            Logger.warning('Entity not found in dataServer: '+tableName);
+            return [];
+        }
+        let filters = sc.toJson(filtersJson);
+        if(!filters){
+            return await entity.loadAll();
+        }
+        return await entity.load(filters);
+    }
+
+}
+
+module.exports.TemplateEngine = TemplateEngine;

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@reldens/cms",
     "scope": "@reldens",
-    "version": "0.12.0",
+    "version": "0.13.0",
     "description": "Reldens - CMS",
     "author": "Damian A. Pastorini",
     "license": "MIT",
@@ -11,7 +11,8 @@
         "node": ">=20.0.0"
     },
     "bin": {
-        "reldens-cms": "bin/reldens-cms.js"
+        "reldens-cms": "bin/reldens-cms.js",
+        "reldens-cms-generate-entities": "bin/reldens-cms-generate-entities.js"
     },
     "repository": {
         "type": "git",
@@ -33,7 +34,7 @@
     },
     "dependencies": {
         "@reldens/server-utils": "^0.18.0",
-        "@reldens/storage": "^0.48.0",
+        "@reldens/storage": "^0.49.0",
         "@reldens/utils": "^0.49.0",
         "dotenv": "^16.5.0",
         "mustache": "^4.2.0"

package/templates/layouts/default.html

@@ -1,13 +1,10 @@
-
-{{>header}}
-
-{{ entity('cmsBlocks', 'header-main') }}
+{{ entity('cmsBlocks', 'header-main', 'name') }}
 
 <main id="main" class="main-container">
     <div class="container">
         <div class="row">
             <div class="col-md-3">
-                {{ entity('cmsBlocks', 'sidebar-left') }}
+                {{ entity('cmsBlocks', 'sidebar-left', 'name') }}
             </div>
             <div class="col-md-9">
                 {{{content}}}
@@ -16,6 +13,4 @@
     </div>
 </main>
 
-{{ entity('cmsBlocks', 'footer-main') }}
-
-{{>footer}}
+{{ entity('cmsBlocks', 'footer-main', 'name') }}