@reldens/cms 0.8.0 → 0.10.0

package/README.md

@@ -1,112 +1,354 @@
 [![Reldens - GitHub - Release](https://www.dwdeveloper.com/media/reldens/reldens-mmorpg-platform.png)](https://github.com/damian-pastorini/reldens)
 
-# Reldens - CMS
+# Reldens CMS
 
-## About
-
-Reldens CMS is a straightforward content management system designed for easy setup and extensibility.
-It provides both an administration panel for content management and a frontend for content delivery.
+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.
 
 ## Features
 
-- Simple installation process
-- Administration panel for content management
-- Support for multiple database drivers (Prisma, Objection.js)
-- Template-based content rendering
-- SEO-friendly routes and meta-data
-- Modular architecture
+### - Quick Setup
+- **Web-based installer** with a guided setup process
+- **Automatic database schema creation** and seeding
+- **Environment configuration generation**
+- **Directory structure initialization**
+
+### - Frontend Engine
+- **Multi-domain support** with domain-specific templates and partials
+- **Dynamic routing** from database-driven routes
+- **Entity-based URLs** (e.g., `/articles/123`)
+- **Template fallback system** (domain → default → base)
+- **Layout system** with body content layouts and page wrappers
+- **Reusable content blocks** with `{{ entity() }}` template functions
+- **Entity access control** for public/private content
+- **Static asset serving** with Express integration as default
+- **Template engine** with Mustache integration as default
+- **Custom 404 handling**
+
+### - Admin Panel
+- **Full CRUD operations** for all entities including content blocks
+- **File upload handling** with multiple storage buckets
+- **Role-based authentication** and access control
+- **Advanced filtering and search** across entity properties
+- **Bulk operations** (delete multiple records)
+- **Relationship management** with foreign key support
+- **Template-driven UI** with customizable admin themes
+
+### -️ Database & Entities
+- **Multiple database drivers** (Prisma by default, others via DriversMap)
+- **Automatic entity generation** from a database schema
+- **Relationship mapping** and foreign key handling
+- **Custom entity configuration** with validation rules
+- **Translation support** for entity labels and properties
+- **Content blocks management** via cms_blocks table
+- **Entity access control** via cms_entity_access table
+
+### - Configuration & Architecture
+- **Environment-based configuration** (.env file)
+- **Modular service architecture** (Frontend, AdminManager, DataServer)
+- **Event-driven system** with hooks for customization
+- **Extensible authentication** (database users or custom callbacks)
+- **File security** with path validation and dangerous key filtering
 
 ## Installation
 
-### Option 1: NPX Installation (Recommended)
-
-The easiest way to install Reldens CMS is using NPX:
-
+### Method 1: Automated Web Installer
 ```bash
-npx @reldens/cms [directory]
+npx reldens-cms
 ```
+Navigate to `http://localhost:8080` and follow the installation wizard.
 
-This will start the installer in your browser, allowing you to configure your CMS installation.
-
-### Option 2: Manual Installation
+### Method 2: Manual Setup
+```javascript
+const { Manager } = require('@reldens/cms');
 
-1. Install the package:
+const cms = new Manager({
+    projectRoot: process.cwd(),
+    entityAccess: {
+        cmsPages: { public: true, operations: ['read'] },
+        products: { public: true, operations: ['read'] },
+        users: { public: false }
+    }
+});
 
-```bash
-npm install @reldens/cms
+cms.start();
 ```
 
-2. Create a basic implementation:
+## Configuration
+
+### Environment Variables
+```env
+RELDENS_APP_HOST=http://localhost
+RELDENS_APP_PORT=8080
+RELDENS_ADMIN_ROUTE_PATH=/admin
+RELDENS_ADMIN_SECRET=your-secret-key
+
+RELDENS_DB_CLIENT=mysql
+RELDENS_DB_HOST=localhost  
+RELDENS_DB_PORT=3306
+RELDENS_DB_NAME=cms_db
+RELDENS_DB_USER=username
+RELDENS_DB_PASSWORD=password
+RELDENS_STORAGE_DRIVER=prisma
+
+RELDENS_DEFAULT_DOMAIN=example.com
+RELDENS_DOMAIN_MAPPING={"dev.example.com":"development"}
+RELDENS_SITE_KEY_MAPPING={"example.com":"main"}
+```
 
+### Custom Entity Configuration
 ```javascript
-const { Manager } = require('@reldens/cms');
+const entityConfig = {
+    articles: {
+        listProperties: ['title', 'status', 'created_at'],
+        showProperties: ['title', 'content', 'author', 'status'],
+        editProperties: ['title', 'content', 'author_id', 'status'],
+        filterProperties: ['status', 'author_id'],
+        titleProperty: 'title',
+        parentItemLabel: 'Content',
+        properties: {
+            title: { type: 'string', isRequired: true },
+            content: { type: 'text' },
+            author_id: { type: 'reference', reference: 'users' },
+            featured_image: { 
+                type: 'string', 
+                isUpload: true, 
+                allowedTypes: 'image',
+                bucket: 'uploads'
+            }
+        }
+    }
+};
 
-const manager = new Manager({
-    projectRoot: './your-project-root',
-    authenticationMethod: 'db-users' // or 'callback'
+const cms = new Manager({
+    entitiesConfig: entityConfig
 });
-
-manager.start().catch(console.error);
 ```
 
-## Authentication Methods
+## Enhanced Templating System
 
-Reldens CMS supports two authentication methods:
+### Template Functions
+Templates now support dynamic content blocks and entity rendering:
+```html
+<!-- Render content blocks -->
+{{ entity('cms_blocks', 'header-main') }}
+{{ entity('cms_blocks', 'sidebar-left') }}
 
-1. **db-users**: Uses the built-in users table for authentication
-2. **callback**: Use a custom authentication function
+<!-- Render other entities -->
+{{ entity('products', '123') }}
+{{ entity('cms_pages', '1') }}
+```
 
-Example with custom authentication:
+### Layout System
+The CMS uses a two-tier layout system:
+
+**page.html** - Full HTML wrapper:
+```html
+<!DOCTYPE html>
+<html lang="{{locale}}">
+<head>
+    <title>{{title}}</title>
+    <meta name="description" content="{{description}}"/>
+    <link href="/css/styles.css" rel="stylesheet"/>
+</head>
+<body class="{{siteHandle}}">
+    {{{content}}}
+    <script src="/js/scripts.js"></script>
+</body>
+</html>
+```
 
+**layouts/default.html** - Body content only:
+```html
+{{ entity('cms_blocks', 'header-main') }}
+
+<main id="main" class="main-container">
+    <div class="container">
+        <div class="row">
+            <div class="col-md-3">
+                {{ entity('cms_blocks', 'sidebar-left') }}
+            </div>
+            <div class="col-md-9">
+                {{{content}}}
+            </div>
+        </div>
+    </div>
+</main>
+
+{{ entity('cms_blocks', 'footer-main') }}
+```
+
+Pages can use different layouts by setting the `layout` field in `cms_pages`:
+- `default` - Header, sidebar, main content, footer
+- `full-width` - Full width without sidebars  
+- `minimal` - Basic layout with minimal styling
+
+### Content Blocks
+Create reusable content blocks in the `cms_blocks` table via admin panel:
+```sql
+INSERT INTO cms_blocks (name, title, content) VALUES 
+('contact-info', 'Contact Information', '<p>Email: info@example.com</p>'),
+('product-sidebar', 'Product Categories', 
+'<div class="categories"><h3>Categories</h3><ul><li><a href="/products/electronics">Electronics</a></li></ul></div>');
+```
+
+### Entity Access Control
+Control which entities are publicly accessible:
 ```javascript
-const manager = new Manager({
-    authenticationMethod: 'callback',
-    authenticationCallback: async (email, password, roleId) => {
-        // Your custom authentication logic
-        // Must return a user object or false
+const cms = new Manager({
+    entityAccess: {
+        products: { public: true, operations: ['read'] },
+        cmsPages: { public: true, operations: ['read'] },
+        users: { public: false }
     }
 });
 ```
 
-## Extending with Custom Entities
+## Multi-Domain Setup
+
+### Directory Structure
+```
+templates/
+├── layouts/
+│   ├── default.html        # Body content layouts
+│   ├── full-width.html
+│   └── minimal.html
+├── domains/
+│   ├── example.com/
+│   │   ├── layouts/        # Domain-specific layouts
+│   │   ├── partials/
+│   │   │   ├── header.html
+│   │   │   └── footer.html
+│   │   ├── page.html       # Domain-specific page wrapper
+│   │   └── index.html
+│   └── dev.example.com/
+│       └── page.html
+├── partials/
+│   ├── header.html (default)
+│   └── footer.html (default)
+├── page.html (base HTML wrapper)
+└── 404.html
+```
+
+## Advanced Usage
 
-You can extend the CMS with your own entities:
+### Custom Authentication
+```javascript
+const customAuth = async (email, password, roleId) => {
+    const user = await yourAuthService.authenticate(email, password);
+    return user && user.role_id === roleId ? user : false;
+};
+
+const cms = new Manager({
+    authenticationMethod: 'custom',
+    authenticationCallback: customAuth
+});
+```
 
+### File Upload Configuration
 ```javascript
-const manager = new Manager({
-    entities: {
-        products: {
-            config: {
-                listProperties: ['id', 'name', 'price', 'status'],
-                showProperties: ['id', 'name', 'price', 'description', 'status', 'created_at'],
-                filterProperties: ['name', 'status'],
-                editProperties: ['name', 'price', 'description', 'status'],
-                properties: {
-                    id: { isId: true },
-                    name: { isRequired: true },
-                    price: { type: 'number', isRequired: true },
-                    description: { type: 'textarea' },
-                    status: { type: 'boolean' },
-                    created_at: { type: 'datetime' }
-                },
-                titleProperty: 'name',
-                navigationPosition: 100
-            }
-        }
+const uploadConfig = {
+    mimeTypes: {
+        image: ['image/jpeg', 'image/png', 'image/webp'],
+        document: ['application/pdf', 'text/plain']
+    },
+    allowedExtensions: {
+        image: ['.jpg', '.jpeg', '.png', '.webp'],
+        document: ['.pdf', '.txt']
     }
+};
+
+const cms = new Manager(uploadConfig);
+```
+
+### Event Hooks
+```javascript
+cms.events.on('reldens.setupAdminRoutes', ({adminManager}) => {
+    // Add custom admin routes
+    adminManager.adminRouter.get('/custom', (req, res) => {
+        res.send('Custom admin page');
+    });
+});
+
+cms.events.on('adminEntityExtraData', ({entitySerializedData, entity}) => {
+    // Add extra data to admin views
+    entitySerializedData.customField = 'Custom Value';
 });
 ```
 
-## Templates
+## Default database Schema
+
+### Core Tables
+- `routes` - URL routing and SEO metadata
+- `cms_pages` - Page content with layout assignments
+- `cms_blocks` - Reusable content blocks
+- `cms_entity_access` - Entity access control rules
+- `entities_meta` - Generic metadata storage
+- `cms_pages_meta` - Page-specific metadata
+
+### Installation Options
+The installer provides checkboxes for:
+- CMS core tables
+- User authentication system
+- Default admin user
+- Default homepage
+- Default content blocks
+- Entity access control rules
+
+## API Reference
+
+### Manager Class
+- `start()` - Initialize and start the CMS
+- `isInstalled()` - Check if CMS is installed
+- `initializeServices()` - Initialize all services
+
+### Frontend Class
+- `initialize()` - Setup frontend routes and templates
+- `handleRequest(req, res)` - Main request handler
+- `findRouteByPath(path)` - Database route lookup
+- `findEntityByPath(path)` - Entity-based URL handling
+- `processCustomTemplateFunctions(template)` - Process {{ entity() }} functions
+
+### AdminManager Class
+- `setupAdmin()` - Initialize admin panel
+- `generateListRouteContent()` - Entity list pages
+- `generateEditRouteContent()` - Entity edit forms
+- `processSaveEntity()` - Handle form submissions
+
+### Installer Class
+- `prepareSetup()` - Setup installation routes
+- `executeInstallProcess()` - Run installation
+- `generateEntities()` - Create entity files
+
+## File Structure
 
-Reldens CMS uses templates for rendering content. Templates are stored in the `templates` directory and use Mustache for rendering.
+```
+project/
+├── admin/
+│   └── templates/           # Admin panel templates
+├── templates/
+│   ├── layouts/            # Body content layouts
+│   ├── domains/            # Domain-specific templates
+│   ├── partials/           # Shared template partials
+│   ├── page.html           # Base HTML wrapper
+│   └── 404.html            # Error page
+├── public/
+│   ├── css/               # Stylesheets
+│   ├── js/                # Client scripts
+│   └── assets/            # Static assets
+├── entities/              # Generated entity classes
+├── .env                   # Environment configuration
+├── install.lock           # Installation lock file
+└── index.js               # Main application file
+```
 
-Default templates include:
-- `layout.html`: The main layout template
-- `page.html`: Default page template
-- `404.html`: Not found page
+---
 
-You can create custom templates for different content types or override the default ones.
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Follow the coding standards in the JavaScript rules
+4. Submit a pull request
 
 ---
 
@@ -120,6 +362,12 @@ Need something specific?
 
 ---
 
+## License
+
+MIT License - see LICENSE file for details.
+
+---
+
 ### [Reldens](https://github.com/damian-pastorini/reldens/ "Reldens")
 
 ##### [By DwDeveloper](https://www.dwdeveloper.com/ "DwDeveloper")

package/admin/templates/fields/edit/text.html

@@ -1 +1 @@
-<input type="text" name="{{&fieldName}}" id="{{&fieldName}}" value="{{fieldValue}}"{{&required}}{{&fieldDisabled}}/>
+<input type="{{&inputType}}" name="{{&fieldName}}" id="{{&fieldName}}" value="{{fieldValue}}"{{&required}}{{&fieldDisabled}}/>

package/install/css/installer.css

@@ -40,6 +40,14 @@ body {
     margin-bottom: 15px;
 }
 
+.input-checkbox {
+    display: flex;
+
+    label {
+        margin-bottom: 0;
+    }
+}
+
 label {
     display: block;
     margin-bottom: 5px;

package/install/index.html

@@ -32,7 +32,7 @@
                     </div>
                     <div class="input-box app-admin-secret">
                         <label for="app-admin-secret">Admin Panel Secret</label>
-                        <input type="text" name="app-admin-secret" id="app-admin-secret" value="{{app-admin-secret}}"/>
+                        <input type="text" name="app-admin-secret" id="app-admin-secret" value="{{app-admin-secret}}" required/>
                     </div>
                     <div class="input-box app-error">
                         <p class="error installation-process-failed">There was an error during the installation process.</p>
@@ -77,25 +77,33 @@
                         <p class="error db-installation-process-failed">There was an error during the installation process.</p>
                     </div>
                     <h3 class="form-title">Installation Options</h3>
-                    <div class="input-box install-cms-tables">
+                    <div class="input-box input-checkbox install-cms-tables">
                         <input type="checkbox" name="install-cms-tables" id="install-cms-tables" checked/>
                         <label for="install-cms-tables">Install default CMS pages tables</label>
                     </div>
-                    <div class="input-box install-user-auth">
+                    <div class="input-box input-checkbox install-user-auth">
                         <input type="checkbox" name="install-user-auth" id="install-user-auth" checked/>
                         <label for="install-user-auth">Install users authentication</label>
                     </div>
-                    <div class="input-box install-default-user">
+                    <div class="input-box input-checkbox install-default-user">
                         <input type="checkbox" name="install-default-user" id="install-default-user" checked/>
                         <label for="install-default-user">Install default admin user (root@cms-admin.com / root)</label>
                     </div>
-                    <div class="input-box install-default-homepage">
+                    <div class="input-box input-checkbox install-default-homepage">
                         <input type="checkbox" name="install-default-homepage" id="install-default-homepage" checked/>
                         <label for="install-default-homepage">Install default homepage</label>
                     </div>
+                    <div class="input-box input-checkbox install-default-blocks">
+                        <input type="checkbox" name="install-default-blocks" id="install-default-blocks" checked/>
+                        <label for="install-default-blocks">Install default content blocks</label>
+                    </div>
+                    <div class="input-box input-checkbox install-entity-access">
+                        <input type="checkbox" name="install-entity-access" id="install-entity-access" checked/>
+                        <label for="install-entity-access">Install entity access control rules</label>
+                    </div>
                     <div class="input-box submit-container">
-                        <img class="install-loading hidden" src="/install-assets/img/loading.gif"/>
                         <input id="install-submit-button" type="submit" value="Install"/>
+                        <img class="install-loading hidden" src="/install-assets/img/loading.gif"/>
                     </div>
                     <div class="input-box response-error"></div>
                 </form>

package/lib/admin-manager.js

@@ -662,10 +662,10 @@ class AdminManager
     async generateEditRouteContent(req, driverResource, entityPath)
     {
         let idProperty = this.fetchEntityIdPropertyKey(driverResource);
-        let idValue = (req?.query[idProperty] || '').toString();
-        let templateTitle = ('' === idValue ? 'Create' : 'Edit')+' '+this.translations.labels[driverResource.id()];
-        let loadedEntity = '' === idValue ? null :await this.loadEntityById(driverResource, idValue);
-        let entityViewRoute = '' === idValue
+        let idValue = String(sc.get(req?.query, idProperty, ''));
+        let templateTitle = (!idValue ? 'Create' : 'Edit')+' '+this.translations.labels[driverResource.id()];
+        let loadedEntity = !idValue ? null :await this.loadEntityById(driverResource, idValue);
+        let entityViewRoute = !idValue
             ? this.rootPath+'/'+driverResource.entityPath
             : this.generateEntityRoute('viewPath', driverResource, idProperty, loadedEntity);
         let renderedEditProperties = {
@@ -677,32 +677,29 @@ class AdminManager
         };
         let propertiesKeys = Object.keys(driverResource.options.properties);
         for(let propertyKey of propertiesKeys){
-            let resourceProperty = driverResource.options.properties[propertyKey];
+            let property = driverResource.options.properties[propertyKey];
             let fieldDisabled = -1 === driverResource.options.editProperties.indexOf(propertyKey);
-            let isRequired = resourceProperty.isRequired ? ' required="required"' : '';
-            if(resourceProperty.isUpload && loadedEntity){
-                isRequired = '';
-            }
-            let inputType = this.getInputType(resourceProperty, fieldDisabled);
             renderedEditProperties[propertyKey] = await this.render(
-                this.adminFilesContents.fields.edit[this.propertyType(resourceProperty, 'edit')],
+                this.adminFilesContents.fields.edit[this.propertyType(property, 'edit')],
                 {
                     fieldName: propertyKey,
                     fieldValue: await this.generatePropertyEditRenderedValue(
                         loadedEntity,
                         propertyKey,
-                        resourceProperty,
+                        property,
                         fieldDisabled
                     ),
                     fieldDisabled: fieldDisabled ? ' disabled="disabled"' : '',
-                    required: isRequired,
-                    multiple: resourceProperty.isArray ? ' multiple="multiple"' : '',
-                    inputType
+                    required: (!property.isUpload || !loadedEntity) && property.isRequired ? ' required="required"' : '',
+                    multiple: property.isArray ? ' multiple="multiple"' : '',
+                    inputType: this.getInputType(property, fieldDisabled)
                 }
             );
         }
-        let renderedView = await this.render(this.adminContents.entities[entityPath].edit, renderedEditProperties);
-        return await this.renderRoute(renderedView, this.adminContents.sideBar);
+        return await this.renderRoute(
+            await this.render(this.adminContents.entities[entityPath].edit, renderedEditProperties),
+            this.adminContents.sideBar
+        );
     }
 
     getInputType(resourceProperty, fieldDisabled)
@@ -710,12 +707,18 @@ class AdminManager
         if('datetime' === resourceProperty.type && !fieldDisabled){
             return 'datetime-local';
         }
+        if('number' === resourceProperty.type){
+            return 'number';
+        }
         return 'text';
     }
 
     async loadEntityById(driverResource, id)
     {
         let entityRepository = this.dataServer.getEntity(driverResource.entityKey);
+        if(!entityRepository){
+            return false;
+        }
         return await entityRepository.loadByIdWithRelations(id);
     }
 
@@ -735,24 +738,23 @@ class AdminManager
         };
         let entitySerializedData = {};
         for(let propertyKey of driverResource.options.showProperties){
-            let resourceProperty = driverResource.options.properties[propertyKey];
+            let property = driverResource.options.properties[propertyKey];
             let {fieldValue, fieldName} = this.generatePropertyRenderedValueWithLabel(
                 loadedEntity,
                 propertyKey,
-                resourceProperty
+                property
             );
             entitySerializedData[fieldName] = fieldValue;
-            let renderedFieldValue = await this.generatePropertyRenderedValue(
-                fieldValue,
-                fieldName,
-                resourceProperty,
-                'view'
-            );
             renderedViewProperties[propertyKey] = await this.render(
-                this.adminFilesContents.fields.view[this.propertyType(resourceProperty)],
+                this.adminFilesContents.fields.view[this.propertyType(property)],
                 {
                     fieldName: propertyKey,
-                    fieldValue: renderedFieldValue,
+                    fieldValue: await this.generatePropertyRenderedValue(
+                        fieldValue,
+                        fieldName,
+                        property,
+                        'view'
+                    ),
                     fieldOriginalValue: fieldValue,
                     target: ' target="_blank"'
                 }
@@ -762,13 +764,15 @@ class AdminManager
         await this.events.emit('adminEntityExtraData', extraDataEvent);
         entitySerializedData = extraDataEvent.entitySerializedData;
         renderedViewProperties.entitySerializedData = JSON.stringify(entitySerializedData).replace(/"/g, '"');
-        let renderedView = await this.render(this.adminContents.entities[entityPath].view, renderedViewProperties);
-        return await this.renderRoute(renderedView, this.adminContents.sideBar);
+        return await this.renderRoute(
+            await this.render(this.adminContents.entities[entityPath].view, renderedViewProperties),
+            this.adminContents.sideBar
+        );
     }
 
     propertyType(resourceProperty, templateType)
     {
-        let propertyType = resourceProperty.type || 'text';
+        let propertyType = sc.get(resourceProperty, 'type', 'text');
         if('reference' === propertyType && 'edit' === templateType){
             return 'select';
         }
@@ -805,7 +809,8 @@ class AdminManager
         });
         let entitiesRows = await this.loadEntitiesForList(driverResource, pageSize, page, req, filters);
         let listRawContent = this.adminContents.entities[entityPath].list.toString();
-        let totalPages = Math.ceil(await this.countTotalEntities(driverResource, filters) / pageSize);
+        let totalEntities = await this.countTotalEntities(driverResource, filters);
+        let totalPages = totalEntities <= pageSize ? 1 : Math.ceil(totalEntities / pageSize);
         let pages = PageRangeProvider.fetch(page, totalPages);
         let renderedPagination = '';
         for(let page of pages){
@@ -858,6 +863,9 @@ class AdminManager
     {
         /** @type {BaseDriver|ObjectionJsDriver} entityRepository **/
         let entityRepository = this.dataServer.getEntity(driverResource.entityKey);
+        if(!entityRepository){
+            return false;
+        }
         return await entityRepository.count(filters);
     }