@reldens/cms 0.47.0 → 0.49.0

package/.claude/advanced-usage-guide.md

@@ -0,0 +1,98 @@
+# Advanced Usage Guide
+
+## Template Reloading for Development
+
+```javascript
+const isDevelopment = process.env.NODE_ENV === 'development';
+
+const cms = new Manager({
+    reloadTime: isDevelopment ? -1 : 0,
+    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
+cms.events.on('reldens.afterVariablesCreated', (eventData) => {
+    eventData.variables.customData = {
+        timestamp: Date.now(),
+        version: '1.0.0'
+    };
+});
+
+cms.events.on('reldens.beforeContentProcess', (eventData) => {
+    eventData.content = eventData.content.replace(/\[custom\]/g, 'Custom Value');
+});
+
+cms.events.on('reldens.afterContentProcess', (eventData) => {
+    eventData.processedContent += '\n<!-- Processed at '+new Date()+' -->';
+});
+
+cms.events.on('reldens.templateReloader.templatesChanged', (eventData) => {
+    console.log('Templates changed:', eventData.changedFiles);
+});
+
+cms.events.on('reldens.dynamicForm.afterSave', (eventData) => {
+    console.log('Form submission received:', eventData.result.id);
+});
+```
+
+## Custom Authentication
+
+```javascript
+const customAuth = async (email, password, roleId) => {
+    let 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 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}) => {
+    adminManager.adminRouter.get('/custom', (req, res) => {
+        res.send('Custom admin page');
+    });
+});
+
+cms.events.on('adminEntityExtraData', ({entitySerializedData, entity}) => {
+    entitySerializedData.customField = 'Custom Value';
+});
+```

package/.claude/api-reference.md

@@ -0,0 +1,146 @@
+# API Reference
+
+## Manager Class
+
+- `start()` - Initialize and start the CMS
+- `isInstalled()` - Check if CMS is installed
+- `initializeServices()` - Initialize all services
+- `validateProvidedServer()` - Validate provided server instance
+- `validateProvidedDataServer()` - Validate provided data server
+- `validateProvidedAdminManager()` - Validate provided admin manager
+- `validateProvidedFrontend()` - Validate provided frontend
+- `buildAppServerConfiguration()` - Build server configuration
+- `initializeCmsAfterInstall(props)` - Post-installation callback
+
+## Installer Class
+
+- `isInstalled()` - Check installation status
+- `configureAppServerRoutes(app, appServer, appServerFactory, renderEngine)` - Setup installer routes
+- `executeInstallProcess(req, res)` - Complete installation process
+- `runSubprocessInstallation(dbConfig, templateVariables)` - Handle subprocess operations
+- `checkAndInstallPackages(requiredPackages)` - Check and install dependencies
+- `generateEntities(server, isOverride, isInstallationMode, isDryPrisma, dbConfig)` - Generate entities
+- `createEnvFile(templateVariables)` - Create environment configuration
+- `copyAdminDirectory()` - Copy admin assets and templates
+
+## Frontend Architecture Classes
+
+### Frontend Class (Orchestrator)
+
+- `initialize()` - Set up frontend routes and templates
+- `handleRequest(req, res)` - Main request handler
+- `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, 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
+
+## Forms System Classes
+
+### DynamicForm Class
+
+- `validateFormSubmission(formKey, submittedValues, req)` - Validate form submission
+- `getFormConfig(formKey)` - Load form configuration from database
+- `validateHoneypot(submittedValues)` - Check honeypot field for bots
+- `validateFields(fieldsSchema, submittedValues)` - Schema-based field validation
+- `prepareSubmittedValues(submittedValues, fieldsSchema)` - Process and normalize values
+- `saveFormSubmission(formConfig, preparedValues)` - Save to database
+
+### DynamicFormRenderer Class
+
+- `renderForm(formConfig, fieldsToRender, domain, req, attributes)` - Render complete form
+- `renderFormFields(fieldsToRender, domain, req)` - Render field set
+- `renderFormField(field, domain, submittedValues, errors)` - Render individual field
+- `loadFormTemplate(templateName, domain)` - Load form template with domain fallback
+- `findFormTemplate(templateName, domain)` - Template discovery for forms
+
+### DynamicFormRequestHandler Class
+
+- `handleFormSubmission(req, res)` - Process POST form submissions
+- `handleBadRequest(res, message)` - Handle validation errors
+- `handleSuccessResponse(req, res, formKey, result)` - Handle successful submissions
+- `buildErrorRedirectPath(req, error, formKey)` - Build error redirect URLs
+- `buildSuccessRedirectPath(successRedirect, formKey)` - Build success redirect URLs
+
+### FormsTransformer Class
+
+- `transform(template, domain, req, systemVariables, enhancedData)` - Process cmsForm tags
+- `findAllFormTags(template)` - Find cmsForm tags in template
+- `parseFormAttributes(fullTag)` - Parse tag attributes
+- `parseFieldsFilter(attributes, formConfig)` - Filter fields based on attributes
+
+## AdminManager Class
+
+- `setupAdmin()` - Initialize admin panel
+- `generateListRouteContent()` - Entity list pages
+- `generateEditRouteContent()` - Entity edit forms
+- `processSaveEntity()` - Handle form submissions

package/.claude/configuration-guide.md

@@ -0,0 +1,126 @@
+# Configuration Guide
+
+## 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"}
+```
+
+## 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 = {
+    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 cms = new Manager({
+    entitiesConfig: entityConfig
+});
+```
+
+## Manager Configuration Options
+
+```javascript
+const cms = new Manager({
+    projectRoot: process.cwd(),
+
+    // Entity Access Control
+    entityAccess: {
+        cmsPages: { public: true, operations: ['read'] },
+        articles: { public: true, operations: ['read'] },
+        users: { public: false }
+    },
+
+    // Authentication
+    authenticationMethod: 'db-users',
+    adminRoleId: 99,
+    authenticationCallback: async (email, password, roleId) => {
+        return await yourAuthService.validate(email, password, roleId);
+    },
+
+    // Performance
+    cache: true,
+    reloadTime: 0,
+
+    // Multi-Domain
+    defaultDomain: 'example.com',
+    domainMapping: {'dev.example.com': 'development'},
+    siteKeyMapping: {'example.com': 'main'},
+
+    // Custom Entities
+    entitiesConfig: entityConfig,
+    entitiesTranslations: {},
+    adminTranslations: {},
+
+    // Optional Custom Services
+    app: customExpressApp,
+    appServer: customAppServer,
+    dataServer: customDataServer,
+    adminManager: customAdmin,
+    frontend: customFrontend
+});
+```

package/.claude/database-schema.md

@@ -0,0 +1,32 @@
+# Database Schema
+
+## Core Tables
+
+- `routes` - URL routing and SEO metadata
+- `cms_pages` - Page content with layout assignments
+- `cms_blocks` - Reusable content blocks
+- `entities_access` - Entity access control rules
+- `entities_meta` - Generic metadata storage
+- `cms_pages_meta` - Page-specific metadata
+
+## Forms Tables
+
+- `cms_forms` - Form configurations with JSON schema
+- `cms_forms_submitted` - Form submissions with JSON data
+
+## User Management Tables (Optional)
+
+- `users` - User authentication with encrypted passwords
+- `roles` - Role definitions
+
+## 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
+- Dynamic forms system

package/.claude/forms-system-guide.md

@@ -0,0 +1,193 @@
+# Dynamic Forms System Guide
+
+## Basic Form Usage
+
+Create forms in your templates using the `<cmsForm>` tag:
+
+```html
+<cmsForm key="contactForm"/>
+<cmsForm key="contactForm" fields="name,email,subject,message"/>
+<cmsForm key="newsletterSignup"
+    fields="email,name"
+    submitButtonText="Subscribe Now"
+    cssClass="newsletter-form"
+    successRedirect="/thank-you"
+    errorRedirect="/contact-error"/>
+```
+
+## Form Configuration
+
+Forms are configured in the `cms_forms` table via the admin panel.
+
+### Supported Field Types
+
+- **text** - Basic text input with maxLength, pattern validation
+- **email** - Email input with built-in email validation
+- **number** - Numeric input with min/max validation
+- **textarea** - Multi-line text with maxLength
+- **select** - Dropdown with options array
+- **password** - Password input (masked)
+- **tel** - Phone number input
+- **url** - URL input with validation
+- **date** - Date picker input
+
+### Field Schema Properties
+
+```json
+{
+    "name": "fieldName",
+    "type": "text",
+    "label": "Field Label",
+    "required": true,
+    "placeholder": "Enter text...",
+    "helpText": "Additional help",
+    "maxLength": 100,
+    "minLength": 3,
+    "pattern": "^[A-Za-z]+$",
+    "min": 0,
+    "max": 100,
+    "step": 1,
+    "defaultValue": "default",
+    "options": [
+        {"value": "val1", "label": "Option 1"},
+        {"value": "val2", "label": "Option 2"}
+    ]
+}
+```
+
+## Security Features
+
+### Honeypot Protection
+
+Automatic bot detection using invisible fields.
+
+### Server-Side Validation
+
+- SchemaValidator integration
+- Required field validation
+- Type validation
+- Length limits
+- Custom validation
+
+### Data Sanitization
+
+- XSS protection
+- Input normalization
+- Length truncation
+
+### Rate Limiting
+
+Uses AppServerFactory integration from server-utils.
+
+## Template Customization
+
+Forms use a domain-aware template fallback system:
+
+```
+templates/
+├── domains/
+│   └── example.com/
+│       └── cms_forms/
+│           ├── form.html
+│           ├── field_text.html
+│           └── field_email.html
+└── cms_forms/
+    ├── form.html
+    ├── field_text.html
+    ├── field_email.html
+    ├── field_textarea.html
+    ├── field_select.html
+    └── field_number.html
+```
+
+## Event System Integration
+
+### Available Form Events
+
+- `reldens.formsTransformer.beforeRender` - Before form rendering
+- `reldens.formsTransformer.afterRender` - After form rendering
+- `reldens.dynamicForm.beforeValidation` - Before form validation
+- `reldens.dynamicForm.afterValidation` - After form validation
+- `reldens.dynamicForm.beforeSave` - Before saving to database
+- `reldens.dynamicForm.afterSave` - After successful save
+- `reldens.dynamicFormRenderer.beforeFieldsRender` - Before rendering fields
+- `reldens.dynamicFormRenderer.afterFieldsRender` - After rendering fields
+- `reldens.dynamicFormRequestHandler.beforeValidation` - Before request validation
+- `reldens.dynamicFormRequestHandler.beforeSave` - Before save process
+- `reldens.dynamicFormRequestHandler.afterSave` - After successful save
+
+### Example Event Usage
+
+```javascript
+cms.events.on('reldens.formsTransformer.beforeRender', (eventData) => {
+    eventData.formAttributes.cssClass += ' custom-form';
+});
+
+cms.events.on('reldens.dynamicForm.afterSave', (eventData) => {
+    console.log('Form saved:', eventData.result.id);
+});
+```
+
+## Database Tables
+
+### cms_forms Table
+
+```sql
+CREATE TABLE `cms_forms` (
+    `id` INT UNSIGNED NOT NULL AUTO_INCREMENT,
+    `form_key` VARCHAR(255) NOT NULL UNIQUE,
+    `fields_schema` JSON NOT NULL,
+    `enabled` TINYINT UNSIGNED NOT NULL DEFAULT '0',
+    `created_at` TIMESTAMP NOT NULL DEFAULT (NOW()),
+    `updated_at` TIMESTAMP NOT NULL DEFAULT (NOW()) ON UPDATE CURRENT_TIMESTAMP,
+    PRIMARY KEY (`id`)
+);
+```
+
+### cms_forms_submitted Table
+
+```sql
+CREATE TABLE `cms_forms_submitted` (
+    `id` INT UNSIGNED NOT NULL AUTO_INCREMENT,
+    `form_id` INT UNSIGNED NOT NULL,
+    `submitted_values` JSON NOT NULL,
+    `created_at` TIMESTAMP NOT NULL DEFAULT (NOW()),
+    PRIMARY KEY (`id`),
+    FOREIGN KEY (`form_id`) REFERENCES `cms_forms`(`id`)
+);
+```
+
+## Form Processing Flow
+
+1. Template Processing - FormsTransformer finds cmsForm tags
+2. Form Loading - Loads form configuration from database
+3. Field Filtering - Applies field filter if specified
+4. Template Rendering - Renders form using domain-aware templates
+5. Form Submission - POST request to /dynamic-form endpoint
+6. Validation - Honeypot, required fields, and schema validation
+7. Data Processing - Input sanitization and normalization
+8. Database Storage - Save to cms_forms_submitted table
+9. Response - Redirect with success/error parameters
+
+## Advanced Usage
+
+### AJAX Form Submissions
+
+```javascript
+const cms = new Manager({
+    enableJsonResponse: true
+});
+```
+
+```javascript
+document.querySelector('.dynamic-form').addEventListener('submit', async function(e) {
+    e.preventDefault();
+    let response = await fetch('/dynamic-form', {method: 'POST', body: new FormData(this)});
+    let result = await response.json();
+    if(result.success){
+        alert('Form submitted successfully!');
+        return;
+    }
+    alert('Error: '+result.error);
+});
+```