@reldens/cms 0.19.0 → 0.21.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, template reloading, and automated installation.
 
 ## Features
 
@@ -24,7 +24,13 @@ 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**
+- **Advanced search functionality** with template data support
+- **Template reloading** for development with configurable reload strategies
 
 ### - Admin Panel
 - **Full CRUD operations** for all entities including content blocks
@@ -46,10 +52,45 @@ 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, TemplateEngine)
+- **Modular service architecture** with specialized classes for better maintainability
 - **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
+
+## Architecture
+
+### Core Classes
+The CMS uses a modular architecture with specialized classes:
+
+**Frontend Orchestrator:**
+- `Frontend` - Main orchestrator class that coordinates all frontend operations
+
+**Template Management:**
+- `TemplateResolver` - Template discovery and domain resolution
+- `TemplateCache` - Template and partial caching management
+- `TemplateReloader` - Template reloading with file change detection
+
+**Request Processing:**
+- `RequestProcessor` - HTTP request routing and path handling
+- `SearchRequestHandler` - Dedicated search request processing
+
+**Content Management:**
+- `ContentRenderer` - Content generation and template processing
+- `EntityAccessManager` - Entity access control and loading
+
+**Response Handling:**
+- `ResponseManager` - HTTP response handling and caching logic
+
+**Template Processing:**
+- `TemplateEngine` - Core template rendering with enhanced context
+- `SystemVariablesProvider` - System variables for templates
+
+This architecture follows SOLID principles, providing better:
+- **Testability** - Individual components can be tested in isolation
+- **Maintainability** - Changes to one area don't affect others
+- **Reusability** - Components can be reused in different contexts
+- **Readability** - Smaller, focused classes are easier to understand
 
 ## Installation
 
@@ -97,6 +138,34 @@ RELDENS_DOMAIN_MAPPING={"dev.example.com":"development"}
 RELDENS_SITE_KEY_MAPPING={"example.com":"main"}
 ```
 
+### Template Reloading Configuration
+Configure template reloading for development environments:
+
+```javascript
+const cms = new Manager({
+    // Development: reload templates on every request when changes detected
+    reloadTime: -1,
+    
+    // Production: disable template reloading (default)
+    reloadTime: 0,
+    
+    // Interval-based: reload every 5 seconds when changes detected
+    reloadTime: 5000
+});
+```
+
+**Template Reloading Options:**
+- **`reloadTime: 0`** (default) - Template reloading disabled. Templates load once at startup.
+- **`reloadTime: -1`** - Reload templates on every request when file changes are detected. Best for active development.
+- **`reloadTime: > 0`** - Check for template changes at specified interval (milliseconds) and reload when needed. Good for development with lower overhead.
+
+**How it works:**
+- Tracks file modification times for admin and frontend templates
+- Only reloads templates that have actually changed
+- Automatically updates admin contents and frontend template cache
+- Works with both admin panel templates and frontend templates/partials
+- Zero performance impact when disabled (`reloadTime: 0`)
+
 ### Custom Entity Configuration
 ```javascript
 const entityConfig = {
@@ -126,8 +195,140 @@ const cms = new Manager({
 });
 ```
 
+## Search Functionality
+
+### Basic Search
+```bash
+# Simple search
+/search?search=technology
+
+# Entity-specific search with custom limit
+/search?search=javascript&limit=20
+
+# Custom template rendering
+/search?search=news&renderPartial=newsListView&renderLayout=minimal
+```
+
+### Advanced Search with Template Data
+```bash
+# Pass custom template variables
+/search?search=articles&templateData[columnsClass]=col-md-4&templateData[showExcerpt]=true
+
+# Multiple template variables
+/search?search=technology&templateData[columnsClass]=col-lg-6&templateData[cardClass]=shadow-sm&templateData[showAuthor]=false
+```
+
+### Search Template Variables
+Templates receive dynamic data through URL parameters:
+
+**URL:** `/search?search=tech&templateData[columnsClass]=col-md-6&templateData[showDate]=true`
+
+**Template (entriesListView.html):**
+```html
+<div class="{{columnsClass}}">
+    <div class="card">
+        <h3>{{row.title}}</h3>
+        <p>{{row.content}}</p>
+        {{#showDate}}
+        <span class="date">{{row.created_at}}</span>
+        {{/showDate}}
+    </div>
+</div>
+```
+
+**Default Values:**
+- `columnsClass` defaults to `col-lg-6` if not provided or empty
+- Custom variables can be added via `templateData[variableName]=value`
+
+### Search Configuration
+```javascript
+// Custom search sets in Manager configuration
+const searchSets = {
+    articlesSearch: {
+        entities: [{
+            name: 'articles',
+            fields: ['title', 'content', 'summary'],
+            relations: 'authors'
+        }],
+        pagination: {active: true, limit: 15, sortBy: 'created_at', sortDirection: 'desc'}
+    }
+};
+
+const cms = new Manager({
+    searchSets: searchSets
+});
+```
+
 ## 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 -->
+[url(/css/styles.css)]         <!-- https://example.com/css/styles.css -->
+
+<!-- Asset URLs with domain -->
+[asset(/assets/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:
 
@@ -230,10 +431,10 @@ Pagination state is managed via URL query parameters:
 Create `templates/partials/pagedCollection.html`:
 ```html
 <div class="row paginated-contents">
-    <div class="collection-content col-lg-12 mt-2 mb-2">
+    <div class="collection-content col-lg-12">
         {{&collectionContentForCurrentPage}}
     </div>
-    <div class="pagination col-lg-12 mt-2 mb-2">
+    <div class="pagination col-lg-12">
         <ul class="pagination-list">
             {{#prevPageUrl}}
                 <li><a href="{{prevPageUrl}}" class="page-link">{{&prevPageLabel}}</a></li>
@@ -365,6 +566,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:
 
@@ -375,11 +625,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="[url(/css/styles.css)]" rel="stylesheet"/>
 </head>
 <body class="{{siteHandle}}">
     {{&content}}
-    <script src="/js/scripts.js"></script>
+    <script src="[url(/js/scripts.js)]"></script>
 </body>
 </html>
 ```
@@ -415,7 +665,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
@@ -452,12 +702,72 @@ templates/
 ├── partials/
 │   ├── header.html (default)
 │   └── footer.html (default)
+├── translations/
+│   ├── en.json
+│   ├── es.json
+│   └── fr.json
 ├── page.html (base HTML wrapper)
 └── 404.html
 ```
 
 ## Advanced Usage
 
+### Template Reloading for Development
+```javascript
+// Different configurations for development vs production
+const isDevelopment = process.env.NODE_ENV === 'development';
+
+const cms = new Manager({
+    // Enable aggressive template reloading in development
+    reloadTime: isDevelopment ? -1 : 0,
+    
+    // Other development-friendly settings
+    cache: !isDevelopment,
+    
+    entityAccess: {
+        articles: { public: true, operations: ['read'] },
+        cmsPages: { public: true, operations: ['read'] }
+    }
+});
+```
+
+**Development Workflow with Template Reloading:**
+1. Set `reloadTime: -1` for instant template updates
+2. Edit admin templates in `admin/templates/` - changes appear immediately
+3. Edit frontend templates in `templates/` - changes appear on next page load
+4. No server restart needed for template changes
+5. Switch to `reloadTime: 0` in production for optimal performance
+
+### 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() + ' -->';
+});
+
+// Listen for template reloading events
+cms.events.on('reldens.templateReloader.templatesChanged', (eventData) => {
+    console.log('Templates changed:', eventData.changedFiles);
+});
+```
+
 ### Custom Authentication
 ```javascript
 const customAuth = async (email, password, roleId) => {
@@ -528,20 +838,74 @@ The installer provides checkboxes for:
 - `isInstalled()` - Check if CMS is installed
 - `initializeServices()` - Initialize all services
 
-### Frontend Class
+### Frontend Architecture Classes
+
+#### Frontend Class (Orchestrator)
 - `initialize()` - Set up frontend routes and templates
 - `handleRequest(req, res)` - Main request handler
-- `findRouteByPath(path)` - Database route lookup
-- `findEntityByPath(path)` - Entity-based URL handling
+- `renderRoute(route, domain, res, req)` - Route-based rendering
+- `setupStaticAssets()` - Configure static asset serving
+
+#### TemplateResolver Class
+- `findTemplatePath(templateName, domain)` - Template discovery with domain fallback
+- `findLayoutPath(layoutName, domain)` - Layout path resolution
+- `findTemplateByPath(path, domain)` - Template lookup by URL path
+- `resolveDomainToFolder(domain)` - Domain to folder mapping
+- `resolveDomainToSiteKey(domain)` - Domain to site key mapping
+
+#### TemplateCache Class
+- `loadPartials()` - Load and cache template partials
+- `setupDomainTemplates()` - Initialize domain-specific templates
+- `getPartialsForDomain(domain)` - Get domain-specific partials with fallback
+
+#### TemplateReloader Class
+- `checkAndReloadAdminTemplates()` - Check and reload admin templates when changed
+- `checkAndReloadFrontendTemplates()` - Check and reload frontend templates when changed
+- `trackTemplateFiles(templatesPaths)` - Start tracking template files for changes
+- `shouldReloadAdminTemplates(mappedAdminTemplates)` - Check if admin templates need reloading
+- `shouldReloadFrontendTemplates(templatesPath, templateExtensions)` - Check if frontend templates need reloading
+- `handleAdminTemplateReload(adminManager)` - Complete admin template reload process
+- `handleFrontendTemplateReload(templateCache, templateResolver)` - Complete frontend template reload process
+
+#### RequestProcessor Class
+- `findRouteByPath(path, domain)` - Database route lookup
+- `handleRouteRedirect(route, res)` - Handle route redirects
+- `getDomainFromRequest(req)` - Extract domain from request
+- `buildCacheKey(path, req)` - Generate cache keys
+
+#### ContentRenderer Class
+- `renderWithTemplateContent(content, data, domain, req, route)` - Main content rendering
+- `generateRouteContent(route, domain, req)` - Route-based content generation
+- `generateTemplateContent(templatePath, domain, req, data)` - Template-based content generation
+- `fetchMetaFields(data)` - Process meta fields for templates
+
+#### EntityAccessManager Class
+- `loadEntityAccessRules()` - Load entity access configuration
+- `isEntityAccessible(entityName)` - Check entity accessibility
+- `findEntityByPath(path)` - Entity lookup by URL path
+
+#### ResponseManager Class
+- `renderWithCacheHandler(contentGenerator, errorHandler, responseHandler, domain, res, path, req)` - Generic cached response handler
+- `renderNotFound(domain, res, req)` - 404 error handling
+
+#### SearchRequestHandler Class
+- `handleSearchRequest(req, res)` - Process search requests with template data support
 
 ### 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
+
+### Search Classes
+- `Search.parseSearchParameters(query)` - Parse search query parameters including templateData
+- `Search.executeSearch(config)` - Execute search with configuration
+- `SearchRenderer.renderSearchResults(searchResults, config, domain, req)` - Render search results with template data
 
 ### AdminManager Class
 - `setupAdmin()` - Initialize admin panel
@@ -560,12 +924,30 @@ The installer provides checkboxes for:
 project/
 ├── admin/
 │   └── templates/           # Admin panel templates
+├── lib/
+│   ├── frontend/           # Frontend specialized classes
+│   │   ├── template-resolver.js
+│   │   ├── template-cache.js
+│   │   ├── request-processor.js
+│   │   ├── entity-access-manager.js
+│   │   ├── content-renderer.js
+│   │   └── response-manager.js
+│   ├── frontend.js         # Main Frontend orchestrator
+│   ├── template-reloader.js # Template reloading functionality
+│   ├── search-request-handler.js
+│   ├── search.js           # Search functionality
+│   ├── search-renderer.js  # Search result rendering
+│   └── template-engine.js  # Core template processing
 ├── templates/
 │   ├── layouts/            # Body content layouts
 │   ├── domains/            # Domain-specific templates
 │   ├── 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