@reldens/cms 0.18.0 → 0.20.0

package/README.md

@@ -2,7 +2,7 @@
 
 # Reldens CMS
 
-A powerful, flexible Content Management System built with Node.js, featuring an admin panel, multi-domain frontend support, enhanced templating with reusable content blocks, and automated installation.
+A powerful, flexible Content Management System built with Node.js, featuring an admin panel, multi-domain frontend support, enhanced templating with reusable content blocks, system variables, internationalization, and automated installation.
 
 ## Features
 
@@ -24,6 +24,10 @@ A powerful, flexible Content Management System built with Node.js, featuring an
 - **Entity access control** for public/private content
 - **Static asset serving** with Express integration as default
 - **Template engine** with Mustache integration as default
+- **System variables** for request, route, and domain context
+- **Enhanced context passing** with currentEntity data in child blocks
+- **Template functions** for URLs, assets, dates, and translations
+- **Event-driven rendering** with hooks for customization
 - **Custom 404 handling**
 
 ### - Admin Panel
@@ -50,6 +54,7 @@ A powerful, flexible Content Management System built with Node.js, featuring an
 - **Event-driven system** with hooks for customization
 - **Extensible authentication** (database users or custom callbacks)
 - **File security** with path validation and dangerous key filtering
+- **Internationalization support** with translation files
 
 ## Installation
 
@@ -128,6 +133,74 @@ const cms = new Manager({
 
 ## Enhanced Templating System
 
+### System Variables
+Every template has access to system variables providing context about the current request:
+
+```html
+<!-- Current request information -->
+{{currentRequest.baseUrl}}        <!-- https://example.com -->
+{{currentRequest.protocol}}       <!-- https -->
+{{currentRequest.host}}          <!-- example.com -->
+{{currentRequest.path}}          <!-- /articles/123 -->
+{{currentRequest.method}}        <!-- GET -->
+{{currentRequest.userAgent}}     <!-- Browser information -->
+{{currentRequest.isSecure}}      <!-- true/false -->
+
+<!-- Current route data (if matched) -->
+{{currentRoute.id}}              <!-- Route ID -->
+{{currentRoute.path}}            <!-- Route path pattern -->
+{{currentRoute.title}}           <!-- Route title -->
+{{currentRoute.template}}        <!-- Route template -->
+{{currentRoute.layout}}          <!-- Route layout -->
+
+<!-- Current domain information -->
+{{currentDomain.current}}        <!-- Current domain -->
+{{currentDomain.default}}        <!-- Default domain -->
+{{currentDomain.resolved}}       <!-- Resolved domain -->
+
+<!-- System information -->
+{{systemInfo.environment}}       <!-- development/production -->
+{{systemInfo.nodeVersion}}       <!-- Node.js version -->
+{{systemInfo.timestamp}}         <!-- Current timestamp -->
+```
+
+### Template Functions
+Templates support dynamic functions for common operations:
+
+```html
+<!-- URL generation with current domain -->
+[url(/articles)]                 <!-- https://example.com/articles -->
+[url(/contact#form)]             <!-- https://example.com/contact#form -->
+
+<!-- Asset URLs with domain -->
+[asset(/css/styles.css)]         <!-- https://example.com/css/styles.css -->
+[asset(/images/logo.png)]        <!-- https://example.com/images/logo.png -->
+
+<!-- Date formatting -->
+[date()]                         <!-- Current date with default format -->
+[date(now, Y-m-d)]              <!-- 2024-01-15 -->
+[date(2024-01-01, d/m/Y)]       <!-- 01/01/2024 -->
+
+<!-- Internationalization -->
+[translate(welcome.message)]     <!-- Translated text -->
+[t(hello.world, Hello World!)]  <!-- With fallback -->
+[t(greeting, Hi {name}!, {name: John})] <!-- With interpolation -->
+```
+
+### Enhanced Context Passing
+Child content blocks and partials receive context from parent pages:
+
+```html
+<!-- In a CMS page or layout -->
+<entity name="cmsBlocks" field="name" value="article-sidebar"/>
+
+<!-- Inside the article-sidebar block, you can access: -->
+{{currentEntity.title}}          <!-- Parent page title -->
+{{currentEntity.id}}            <!-- Parent page ID -->
+{{currentEntity.template}}       <!-- Parent page template -->
+<!-- Any other parent page properties -->
+```
+
 ### Template Functions
 Templates support dynamic content blocks, entity rendering, and collections with advanced query options:
 
@@ -157,18 +230,18 @@ Templates support dynamic content blocks, entity rendering, and collections with
 ```html
 <!-- Loop through records with full template rendering -->
 <collection name="cmsBlocks" filters="{status: 'active'}">
-  <div class="block">
-    <h3>{{row.title}}</h3>
-    <div class="content">{{row.content}}</div>
-  </div>
+    <div class="block">
+        <h3>{{row.title}}</h3>
+        <div class="content">{{row.content}}</div>
+    </div>
 </collection>
 
 <collection name="articles" filters="{category: 'technology'}">
-  <div class="article">
-    <h4>{{row.title}}</h4>
-    <p>{{row.summary}}</p>
-    <img src="{{row.featured_image}}" alt="{{row.title}}">
-  </div>
+    <div class="article">
+        <h4>{{row.title}}</h4>
+        <p>{{row.summary}}</p>
+        <img src="{{row.featured_image}}" alt="{{row.title}}">
+    </div>
 </collection>
 
 <!-- With pagination and sorting -->
@@ -178,8 +251,91 @@ Templates support dynamic content blocks, entity rendering, and collections with
     <p>{{row.summary}}</p>
   </div>
 </collection>
+
+<!-- Paginated collections with navigation -->
+<collection name="articles" 
+    filters="{featured: true}" 
+    data="{limit: 10, sortBy: 'created_at', sortDirection: 'desc'}" 
+    pagination="articles-1" 
+    container="pagedCollection"
+    prevPages="2" 
+    nextPages="2">
+    <div class="article-card">
+        <h4>{{row.title}}</h4>
+        <p>{{row.summary}}</p>
+        <span class="date">{{row.created_at}}</span>
+    </div>
+</collection>
+
+<!-- Multiple paginated collections on the same page -->
+<collection name="news" 
+    filters="{category: 'technology'}" 
+    data="{limit: 5, sortBy: 'published_at'}" 
+    pagination="news-tech" 
+    container="customPager">
+    <article>{{row.title}}</article>
+</collection>
+
+<collection name="events" 
+    filters="{upcoming: true}" 
+    data="{limit: 8}" 
+    pagination="events-upcoming"
+    prevPages="3"
+    nextPages="1">
+    <div class="event">{{row.title}} - {{row.date}}</div>
+</collection>
 ```
 
+**Pagination Attributes:**
+- `pagination="collection-id"` - Enables pagination with unique identifier
+- `container="templateName"` - Custom pagination template (defaults to "pagedCollection")
+- `prevPages="2"` - Number of previous page links to show (default: 2)
+- `nextPages="2"` - Number of next page links to show (default: 2)
+
+**Pagination URL Parameters:**
+Pagination state is managed via URL query parameters:
+```
+/articles?articles-1-key={"page":2,"limit":10,"sortBy":"created_at","sortDirection":"desc"}
+/news?news-tech-key={"page":3,"limit":5,"category":"technology"}
+```
+
+**Custom Pagination Template:**
+Create `templates/partials/pagedCollection.html`:
+```html
+<div class="row paginated-contents">
+    <div class="collection-content col-lg-12 mt-2 mb-2">
+        {{&collectionContentForCurrentPage}}
+    </div>
+    <div class="pagination col-lg-12 mt-2 mb-2">
+        <ul class="pagination-list">
+            {{#prevPageUrl}}
+                <li><a href="{{prevPageUrl}}" class="page-link">{{&prevPageLabel}}</a></li>
+            {{/prevPageUrl}}
+            {{#prevPages}}
+                <li><a href="{{pageUrl}}" class="page-link">{{&pageLabel}}</a></li>
+            {{/prevPages}}
+            <li class="current">{{&currentPage}}</li>
+            {{#nextPages}}
+                <li><a href="{{pageUrl}}" class="page-link">{{&pageLabel}}</a></li>
+            {{/nextPages}}
+            {{#nextPageUrl}}
+                <li><a href="{{nextPageUrl}}" class="page-link">{{&nextPageLabel}}</a></li>
+            {{/nextPageUrl}}
+        </ul>
+    </div>
+</div>
+```
+
+**Available Pagination Template Variables:**
+- `{{&collectionContentForCurrentPage}}` - Rendered collection items for current page
+- `{{currentPage}}` - Current page number
+- `{{totalPages}}` - Total number of pages
+- `{{totalRecords}}` - Total number of records
+- `{{prevPageUrl}}` / `{{nextPageUrl}}` - Previous/next page URLs
+- `{{&prevPageLabel}}` / `{{&nextPageLabel}}` - Previous/next link labels ("Previous"/"Next")
+- `{{#prevPages}}` / `{{#nextPages}}` - Arrays of page objects with `pageUrl` and `pageLabel`
+- `{{hasNextPage}}` / `{{hasPrevPage}}` - Boolean flags for navigation availability
+
 **Custom Partials with Variables:**
 
 *New HTML-style partial tags:*
@@ -282,6 +438,55 @@ Collections support advanced query parameters for pagination and sorting:
 </collection>
 ```
 
+## Internationalization
+
+### Translation Files
+Create translation files in the `translations` directory:
+
+**translations/en.json:**
+```json
+{
+  "navigation": {
+    "home": "Home",
+    "about": "About Us",
+    "contact": "Contact"
+  },
+  "messages": {
+    "welcome": "Welcome to our site!",
+    "greeting": "Hello {name}!"
+  }
+}
+```
+
+**translations/es.json:**
+```json
+{
+  "navigation": {
+    "home": "Inicio",
+    "about": "Acerca de",
+    "contact": "Contacto"
+  },
+  "messages": {
+    "welcome": "¡Bienvenido a nuestro sitio!",
+    "greeting": "¡Hola {name}!"
+  }
+}
+```
+
+### Using Translations in Templates
+```html
+<!-- Simple translation -->
+[translate(navigation.home)]
+
+<!-- With fallback -->
+[t(navigation.home, Home)]
+
+<!-- With interpolation -->
+[t(messages.greeting, Hello!, {name: John})]
+
+<!-- Locale detection from request headers or ?locale=es parameter -->
+```
+
 ### Layout System
 The CMS uses a two-tier layout system:
 
@@ -292,11 +497,11 @@ The CMS uses a two-tier layout system:
 <head>
     <title>{{title}}</title>
     <meta name="description" content="{{description}}"/>
-    <link href="/css/styles.css" rel="stylesheet"/>
+    <link href="[asset(/css/styles.css)]" rel="stylesheet"/>
 </head>
 <body class="{{siteHandle}}">
     {{&content}}
-    <script src="/js/scripts.js"></script>
+    <script src="[asset(/js/scripts.js)]"></script>
 </body>
 </html>
 ```
@@ -332,7 +537,7 @@ Create reusable content blocks in the `cms_blocks` table via the admin panel:
 INSERT INTO cms_blocks (name, title, content) VALUES 
 ('contact-info', 'Contact Information', '<p>Email: info@example.com</p>'),
 ('article-sidebar', 'Article Categories', 
-'<div class="categories"><h3>Categories</h3><ul><li><a href="/articles/technology">Technology</a></li></ul></div>');
+'<div class="categories"><h3>Categories</h3><ul><li><a href="[url(/articles/technology)]">Technology</a></li></ul></div>');
 ```
 
 ### Entity Access Control
@@ -369,12 +574,41 @@ templates/
 ├── partials/
 │   ├── header.html (default)
 │   └── footer.html (default)
+├── translations/
+│   ├── en.json
+│   ├── es.json
+│   └── fr.json
 ├── page.html (base HTML wrapper)
 └── 404.html
 ```
 
 ## Advanced Usage
 
+### Event System
+The CMS provides hooks for customization through event listeners:
+
+```javascript
+// Listen for template variable events
+cms.events.on('reldens.afterVariablesCreated', (eventData) => {
+    // Add custom variables
+    eventData.variables.customData = {
+        timestamp: Date.now(),
+        version: '1.0.0'
+    };
+});
+
+// Listen for content processing events
+cms.events.on('reldens.beforeContentProcess', (eventData) => {
+    // Modify content before processing
+    eventData.content = eventData.content.replace(/\[custom\]/g, 'Custom Value');
+});
+
+cms.events.on('reldens.afterContentProcess', (eventData) => {
+    // Modify processed content
+    eventData.processedContent += '\n<!-- Processed at ' + new Date() + ' -->';
+});
+```
+
 ### Custom Authentication
 ```javascript
 const customAuth = async (email, password, roleId) => {
@@ -452,13 +686,15 @@ The installer provides checkboxes for:
 - `findEntityByPath(path)` - Entity-based URL handling
 
 ### TemplateEngine Class
-- `render(template, data, partials)` - Main template rendering with enhanced functions
-- `processEntityFunctions(template)` - Process `<entity>` functions
-- `processSingleFieldCollections(template)` - Process single field collections with query options
-- `processLoopCollections(template)` - Process loop collections with query options
-- `processCustomPartials(template)` - Process `<partial>` tags with attribute parsing
-- `fetchEntityForTemplate(tableName, identifier, identifierField)` - Load single entity
-- `fetchCollectionForTemplate(tableName, filtersJson, queryOptionsJson)` - Load entity collections with pagination and sorting
+- `render(template, data, partials, domain, req, route, currentEntityData)` - Main template rendering with enhanced context
+- `processAllTemplateFunctions(template, domain, req, systemVariables)` - Process all template functions
+- `buildEnhancedRenderData(data, systemVariables, currentEntityData)` - Build template context with system variables
+
+### SystemVariablesProvider Class
+- `buildSystemVariables(req, route, domain)` - Create system variables for templates
+- `buildCurrentRequestData(req, domain)` - Build request context
+- `buildCurrentRouteData(route)` - Build route context
+- `buildCurrentDomainData(domain)` - Build domain context
 
 ### AdminManager Class
 - `setupAdmin()` - Initialize admin panel
@@ -483,6 +719,10 @@ project/
 │   ├── partials/           # Shared template partials
 │   ├── page.html           # Base HTML wrapper
 │   └── 404.html            # Error page
+├── translations/
+│   ├── en.json             # English translations
+│   ├── es.json             # Spanish translations
+│   └── fr.json             # French translations
 ├── public/
 │   ├── css/               # Stylesheets
 │   ├── js/                # Client scripts