EDMS/docs/SITE_SETTINGS.md

Site Settings System - Comprehensive Guide

Overview

The Site Settings system provides administrators with comprehensive control over the visual appearance, branding, and global configuration of the Electronic Document Management System (EDMS). This system allows complete customization of the application's look and feel, SEO settings, and theme management through an intuitive web interface.

Table of Contents

1. System Integration
2. Features Overview
3. Accessing Site Settings
4. Configuration Categories
5. Basic Information Settings
6. Branding & Visual Identity
7. SEO & Meta Tag Management
8. Theme System Integration
9. Advanced Customization
10. API Integration
11. Technical Implementation
12. Best Practices
13. Troubleshooting

System Integration

EDMS Ecosystem

The Site Settings system is fully integrated with the EDMS ecosystem and works alongside:

• DMS Settings: Document management configuration (separate system)
• User Management: Role-based access control for settings access
• Theme System: Dynamic theme switching and custom theme support
• Component Library: Rs component system integration
• Global State: Pinia store management for reactive updates

Global Impact

Site settings affect the entire application including:

• Header and Navigation: Site logo, name, and branding elements
• Loading Screens: Custom loading logos and branding
• Document Viewer: Consistent branding across all interfaces
• Authentication Pages: Login page branding and styling
• SEO Elements: Meta tags, Open Graph, and social media integration
• Theme Application: Global color schemes and visual styling

Features Overview

Core Capabilities

• Complete Branding Control: Logos, site name, and visual identity
• Theme Management: Built-in themes plus custom theme support
• SEO Optimization: Comprehensive meta tag and social media optimization
• Custom Styling: CSS injection and custom theme file support
• Real-time Preview: Live preview of changes before applying
• Global Integration: Settings applied across entire application
• Backup & Restore: Export/import configuration for backup and migration

Administrative Features

• Role-Based Access: Only Superadmin users can modify site settings
• Validation System: Comprehensive validation for all settings
• File Upload Management: Secure file upload for logos and assets
• Version Control: Track changes and maintain configuration history
• Multi-Environment Support: Different configurations for different environments

Accessing Site Settings

Prerequisites

• Administrative Privileges: User must have Superadmin role
• Modern Browser: Chrome 70+, Firefox 65+, Safari 12+, Edge 79+
• JavaScript Enabled: Required for interactive functionality
• Network Access: Stable connection for file uploads and saves

Navigation Path

1. Main Menu: Navigate to Pentadbiran (Administration)
2. Configuration Section: Select Konfigurasi (Configuration)
3. Site Settings: Choose Site Settings from the submenu
4. Alternative Access: Direct URL navigation to /admin/site-settings

Permission Requirements

• Available to: Superadmin role only
• Admin users: Cannot access Site Settings (limited to DMS Settings)
• Regular users: No access to any settings pages
• Access control: Implemented through navigation meta tags and server-side verification

Interface Layout

• Tabbed Interface: Basic Info, Branding, SEO, Advanced settings
• Live Preview Panel: Real-time preview of changes
• Action Buttons: Save, Reset, Export, Import functionality
• Validation Feedback: Immediate feedback on invalid settings
• Loading States: Visual feedback during save operations

Configuration Categories

1. Basic Information

• Site Name: Application name displayed globally
• Site Description: Meta description for SEO and social sharing
• Font Configuration: Typography settings and font selection
• Display Options: Show/hide site name in header and other locations

2. Branding

• Site Logo: Main application logo for headers and navigation
• Loading Logo: Branded loading screen logo
• Favicon: Browser tab icon and bookmark icon
• Login Logo: Dedicated branding for authentication pages

3. SEO & Social Media

• Meta Tags: Title, description, keywords, author information
• Open Graph: Facebook and social media sharing optimization
• Twitter Cards: Twitter-specific meta tag configuration
• Analytics Integration: Google Analytics, Tag Manager, Facebook Pixel

4. Advanced Settings

• Custom CSS: Global CSS injection for advanced styling
• Custom Themes: Upload and manage custom theme files
• Theme Editor: Direct editing of theme.css file
• Developer Tools: Advanced configuration options

Basic Information Settings

Site Name Configuration

• Purpose: Define the application name displayed throughout the system
• Default Value: "corradAF" (customizable)
• Global Impact: Updates header, page titles, meta tags, loading screens
• Font Size Control: Adjustable font size (12-36px range)
• Character Limit: Recommended maximum of 50 characters for optimal display

Display Locations:

• Header navigation (primary logo area)
• Browser page titles (prefixed to page names)
• Loading screen branding
• SEO meta tags and social sharing
• Authentication page headers

Site Description

• Purpose: Provide descriptive text for SEO and social media sharing
• SEO Impact: Used as meta description tag for search engines
• Social Sharing: Appears in social media link previews
• Character Limit: Recommended 150-160 characters for optimal SEO
• Multi-language Support: Single description applies globally

Typography Configuration

• Font Selection: Choose from available system fonts
• Font Source: Local fonts vs. web fonts (Google Fonts integration)
• Font Size Controls: Configurable sizes for different elements
• Global Application: Typography changes apply system-wide

Branding & Visual Identity

Logo Management System

Site Logo (Primary)

• Usage: Main application logo in header and navigation
• Recommended Dimensions: 200x60px (maximum)
• Supported Formats: PNG, JPG, SVG (vector preferred)
• File Size Limit: 5MB maximum
• Responsive Behavior: Automatic scaling for different screen sizes
• Fallback: System default logo if custom logo fails to load

Loading Logo

• Usage: Branded loading screens and splash pages
• Recommended Dimensions: 100x100px (square preferred)
• Animation Support: Static images only (CSS animations can be added)
• Multiple Screens: Applied to all loading states throughout application
• Brand Consistency: Should complement primary site logo

Favicon Configuration

• Usage: Browser tab icons, bookmarks, mobile home screen icons
• Required Format: ICO format preferred (PNG acceptable)
• Dimensions: 16x16, 32x32, 48x48px (multi-size ICO recommended)
• Mobile Icons: Apple touch icons and Android home screen support
• Browser Compatibility: Cross-browser favicon support

Login Page Logo

• Usage: Dedicated branding for authentication and login pages
• Design Consideration: Can be different from main site logo for branding flexibility
• Recommended Dimensions: 250x80px maximum
• Security Context: Appears on security-sensitive pages
• Brand Trust: Important for user trust and brand recognition

File Upload System

• Secure Upload: File validation and virus scanning
• Storage Location: public/uploads/site-settings/ directory
• Backup Integration: Uploaded files included in system backups
• Version Control: Maintain previous versions of uploaded assets
• CDN Support: Compatible with content delivery networks

SEO & Meta Tag Management

Search Engine Optimization

Basic SEO Settings

• SEO Title: Custom title for search engine results
• Meta Description: Description displayed in search results
• Meta Keywords: Keyword tags (legacy but still supported)
• Meta Author: Content author information
• Canonical URL: Preferred URL for content indexing

Advanced SEO Configuration

• Robots Meta Tag: Control search engine crawling behavior
  • Default: "index, follow" (allow indexing and link following)
  • Options: noindex, nofollow, noarchive, nosnippet
• Structured Data: Schema.org markup for rich snippets
• XML Sitemap: Automatic sitemap generation and submission
• Page Speed Optimization: Settings that impact page load times

Social Media Integration

Open Graph (Facebook)

• og:title: Social media sharing title
• og:description: Social media sharing description
• og:image: Image displayed in social media previews
• og:type: Content type (website, article, etc.)
• og:url: Canonical URL for social sharing

Twitter Cards

• twitter:card: Card type (summary, summary_large_image, app, player)
• twitter:title: Twitter-specific sharing title
• twitter:description: Twitter-specific sharing description
• twitter:image: Twitter preview image
• twitter:creator: Twitter handle of content creator

Analytics & Tracking

Google Analytics Integration

• Tracking ID: Google Analytics measurement ID (GA4 format)
• Enhanced Ecommerce: Advanced tracking for document interactions
• Custom Events: Track document downloads, views, searches
• Privacy Compliance: GDPR and privacy regulation compliance

Google Tag Manager

• Container ID: GTM container identifier
• Custom Variables: Document metadata as GTM variables
• Event Tracking: Advanced event tracking through GTM
• Third-party Integration: Easy integration with other analytics tools

Facebook Pixel

• Pixel ID: Facebook advertising pixel identifier
• Conversion Tracking: Track document interactions as conversions
• Custom Audiences: Build audiences based on document engagement
• Privacy Controls: Respect user privacy preferences

Theme System Integration

Built-in Theme Support

Standard Themes

The system includes several pre-built themes from themeList.js:

• biasa: Default neutral theme with balanced colors
• terang: Light theme with bright, clean aesthetics
• gelap: Dark theme for reduced eye strain
• biru: Blue-dominant professional theme
• hijau: Green nature-inspired theme

Accessibility Themes

Special themes from themeList2.js for enhanced accessibility:

• high-contrast: High contrast for visual impairments
• large-text: Increased font sizes for readability
• color-blind: Color-blind friendly color palettes
• low-vision: Optimized for users with low vision

Custom Theme Development

Theme Structure

Custom themes follow CSS custom property structure:

html[data-theme="custom-theme-name"] {
  --color-primary: 255, 0, 0;
  --color-secondary: 0, 255, 0;
  --color-success: 0, 255, 0;
  --color-info: 0, 0, 255;
  --color-warning: 255, 255, 0;
  --color-danger: 255, 0, 0;
  --color-light: 248, 249, 250;
  --color-dark: 33, 37, 41;
  /* Additional custom properties */
}

Color Variable System

• RGB Values: Colors defined as RGB triplets for alpha transparency support
• Semantic Naming: Colors named by purpose rather than appearance
• Component Integration: Variables used throughout Rs component system
• Dark Mode Support: Automatic dark mode variants

Theme File Management

• Upload Location: Custom themes saved to assets/style/css/
• Integration Method: Direct injection into theme.css file
• Validation: CSS syntax validation before integration
• Backup: Automatic backup before theme modifications

Theme Switching Mechanism

• Real-time Application: Themes applied immediately without page refresh
• Header Integration: Theme selector synchronized with site settings
• User Preferences: Individual user theme preferences (if enabled)
• Default Theme: System-wide default theme setting

Advanced Customization

Custom CSS Injection

Global CSS Override

• Injection Point: CSS inserted into document <head> element
• Priority: Custom CSS has high specificity to override defaults
• Validation: Basic CSS syntax validation
• Performance: Minification and optimization of injected CSS

Best Practices for Custom CSS

• Specificity: Use appropriate CSS specificity for overrides
• Performance: Minimize custom CSS for better performance
• Maintenance: Document custom CSS changes for future reference
• Testing: Test across different browsers and devices

CSS Framework Integration

• TailwindCSS Compatibility: Custom CSS works alongside TailwindCSS
• Component System: Respect Rs component styling patterns
• Responsive Design: Ensure custom CSS is responsive
• Dark Mode: Consider dark mode implications

Custom Theme File Upload

File Requirements

• Format: Standard CSS files (.css extension)
• Size Limit: 1MB maximum file size
• Encoding: UTF-8 encoding required
• Syntax: Valid CSS syntax required

Integration Process

1. File Upload: Secure file upload to server
2. Validation: CSS syntax and security validation
3. Integration: Append to main theme.css file
4. Backup: Create backup of previous theme.css
5. Application: Theme immediately available for selection

Security Considerations

• Content Filtering: Remove potentially dangerous CSS
• Path Restrictions: Prevent access to restricted file paths
• Size Limits: Prevent resource exhaustion attacks
• Validation: Comprehensive CSS validation

API Integration

Site Settings API Endpoints

GET /api/devtool/config/site-settings

Purpose: Retrieve current site settings configuration

Response Format:

{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "siteName": "Custom EDMS",
    "siteDescription": "Enterprise Document Management System",
    "siteLogo": "/uploads/site-settings/logo.png",
    "siteFavicon": "/uploads/site-settings/favicon.ico",
    "selectedTheme": "professional-blue",
    "customCSS": ".custom-header { background: #blue; }",
    "seoTitle": "EDMS - Document Management",
    "seoDescription": "Comprehensive document management solution",
    "seoKeywords": "document, management, enterprise",
    "seoGoogleAnalytics": "GA-XXXXXXXXX-X"
  }
}

POST /api/devtool/config/site-settings

Purpose: Update site settings configuration

Request Format:

{
  "siteName": "Updated EDMS Name",
  "siteDescription": "Updated description",
  "selectedTheme": "dark-professional",
  "customCSS": ".updated-styles { color: red; }",
  "seoTitle": "Updated SEO Title"
}

Features:

• Partial updates supported (only changed fields required)
• Automatic validation of all input data
• File path validation for security
• Database persistence with timestamps

POST /api/devtool/config/upload-file

Purpose: Secure file upload for logos and assets

Request Format: Multipart form data with file and metadata

Response Format:

{
  "statusCode": 200,
  "message": "File uploaded successfully",
  "data": {
    "filename": "uploaded-logo.png",
    "path": "/uploads/site-settings/logo.png",
    "size": 15420,
    "type": "image/png"
  }
}

Security Features:

• File type validation (images only for logos)
• File size limits enforcement
• Virus scanning integration
• Secure file storage with proper permissions

POST /api/devtool/config/add-custom-theme

Purpose: Add custom theme directly to theme.css file

Request Format:

{
  "themeName": "custom-corporate",
  "themeCSS": "html[data-theme=\"custom-corporate\"] { --color-primary: 0, 100, 200; }"
}

Features:

• CSS validation before integration
• Automatic backup of existing theme.css
• Immediate availability after integration
• Rollback capability if integration fails

Composable Integration

useSiteSettings() Composable

The useSiteSettings() composable provides reactive state management:

const {
  siteSettings,          // Reactive settings object
  loading,               // Loading state
  loadSiteSettings,      // Load settings from API
  updateSiteSettings,    // Update settings
  setTheme,              // Apply theme changes
  getCurrentTheme,       // Get current theme
  applyThemeSettings,    // Apply theme to DOM
  updateGlobalMeta,      // Update meta tags
  addCustomThemeToFile   // Add custom theme
} = useSiteSettings();

Real-time Updates

• Reactive State: Changes immediately reflected in UI
• Global Sync: Updates synchronized across all components
• Meta Tag Updates: SEO meta tags updated dynamically
• Theme Application: Theme changes applied without page refresh

Technical Implementation

Database Schema

Settings stored in site_settings table with comprehensive field structure:

CREATE TABLE site_settings (
  settingID INT PRIMARY KEY AUTO_INCREMENT,
  siteName VARCHAR(255) DEFAULT 'corradAF',
  siteNameFontSize INT DEFAULT 18,
  siteDescription TEXT,
  siteLogo VARCHAR(500),
  siteLoadingLogo VARCHAR(500),
  siteFavicon VARCHAR(500),
  siteLoginLogo VARCHAR(500),
  showSiteNameInHeader BOOLEAN DEFAULT TRUE,
  customCSS LONGTEXT,
  themeMode VARCHAR(100) DEFAULT 'biasa',
  customThemeFile VARCHAR(500),
  currentFont VARCHAR(100),
  fontSource VARCHAR(100),
  seoTitle VARCHAR(255),
  seoDescription TEXT,
  seoKeywords TEXT,
  seoAuthor VARCHAR(255),
  seoOgImage VARCHAR(500),
  seoTwitterCard VARCHAR(100) DEFAULT 'summary_large_image',
  seoCanonicalUrl VARCHAR(500),
  seoRobots VARCHAR(100) DEFAULT 'index, follow',
  seoGoogleAnalytics VARCHAR(255),
  seoGoogleTagManager VARCHAR(255),
  seoFacebookPixel VARCHAR(255),
  settingCreatedDate DATETIME DEFAULT CURRENT_TIMESTAMP,
  settingModifiedDate DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

File System Integration

• Upload Directory: public/uploads/site-settings/
• Theme Directory: assets/style/css/
• Backup Directory: backups/site-settings/
• Permission Management: Proper file system permissions
• Cleanup Procedures: Automatic cleanup of unused files

Global Integration Points

Header Component

• Logo Display: Dynamic logo from site settings
• Site Name: Configurable site name display
• Theme Selector: Synchronized theme selection
• Brand Colors: Applied from theme settings

App.vue Global Configuration

• Meta Tags: Dynamically updated from settings
• Title Management: Global title prefix from site name
• Theme Initialization: Theme applied on app startup
• Favicon: Dynamic favicon from settings

Loading Components

• Branded Loading: Custom loading logo
• Brand Colors: Theme colors in loading screens
• Consistent Experience: Uniform branding across all loading states

Best Practices

Branding Guidelines

Logo Design

• Vector Format: Use SVG for scalability when possible
• Optimization: Optimize file sizes for web performance
• Consistency: Maintain consistent branding across all logos
• Accessibility: Ensure sufficient contrast for accessibility compliance

Color Schemes

• Brand Consistency: Align with organizational brand guidelines
• Accessibility: Meet WCAG contrast requirements
• Cultural Sensitivity: Consider cultural color associations
• Dark Mode Support: Provide appropriate dark mode variants

SEO Optimization

Content Strategy

• Unique Descriptions: Unique meta descriptions for better SEO
• Keyword Research: Use relevant keywords in meta tags
• Regular Updates: Keep SEO content current and relevant
• Performance: Optimize for page load speed

Technical SEO

• Structured Data: Implement appropriate schema markup
• Mobile Optimization: Ensure mobile-friendly configuration
• Page Speed: Monitor and optimize loading times
• Security: Implement HTTPS and security headers

Performance Considerations

File Optimization

• Image Compression: Compress logos and images appropriately
• CSS Minification: Minify custom CSS for better performance
• Caching Strategy: Implement appropriate caching headers
• CDN Integration: Consider CDN for static assets

Theme Performance

• Minimal CSS: Keep custom themes lightweight
• Variable Usage: Use CSS custom properties efficiently
• Browser Compatibility: Test across different browsers
• Fallback Support: Provide fallbacks for older browsers

Security Best Practices

File Upload Security

• File Type Validation: Strict file type checking
• Size Limits: Appropriate file size restrictions
• Virus Scanning: Implement virus scanning for uploads
• Path Traversal: Prevent directory traversal attacks

CSS Security

• Content Filtering: Filter potentially dangerous CSS
• XSS Prevention: Prevent CSS-based XSS attacks
• Input Validation: Validate all CSS input thoroughly
• Sanitization: Sanitize user-provided CSS content

Troubleshooting

Common Issues

Settings Not Saving

Symptoms:

• Changes revert after page refresh
• Error messages during save operations
• Loading indicators that don't complete

Resolution Steps:

1. Check Permissions: Verify administrative access
2. Network Issues: Confirm stable internet connection
3. Browser Console: Check for JavaScript errors
4. Server Status: Verify server is operational
5. Database Connection: Check database connectivity

Logos Not Displaying

Symptoms:

• Broken image icons instead of logos
• Default logos showing instead of custom ones
• Images not loading properly

Resolution Steps:

1. File Path: Verify correct file paths in settings
2. File Permissions: Check server file permissions
3. File Format: Ensure supported image formats
4. File Size: Check if files exceed size limits
5. Browser Cache: Clear browser cache and reload

Theme Not Applying

Symptoms:

• Theme selection not taking effect
• Colors not changing as expected
• Custom themes not available

Resolution Steps:

1. CSS Validation: Check for CSS syntax errors
2. Theme File: Verify theme file integration
3. Browser Compatibility: Test with different browsers
4. Cache Issues: Clear browser and server cache
5. CSS Conflicts: Check for CSS specificity issues

Performance Issues

Slow Loading

Causes:

• Large logo files
• Excessive custom CSS
• Network connectivity issues
• Server performance problems

Optimization:

1. Image Optimization: Compress logo files
2. CSS Optimization: Minimize custom CSS
3. Caching: Implement proper caching strategies
4. CDN: Use content delivery networks
5. Server Optimization: Monitor server performance

Memory Issues

Symptoms:

• Browser becoming unresponsive
• High memory usage
• Slow interface response

Resolution:

1. File Size: Reduce logo file sizes
2. CSS Efficiency: Optimize CSS selectors
3. Browser Update: Use latest browser versions
4. System Resources: Monitor system memory
5. Cache Management: Regular cache clearing

Support Resources

Documentation

• Technical Guide: Comprehensive system documentation
• User Guide: End-user documentation
• API Documentation: Developer integration guides
• Change Log: System updates and changes

Contact Support

• Internal IT: Contact system administrators
• Help Desk: Organizational support procedures
• Community: User forums and knowledge bases
• Vendor Support: External support options

Information to Provide

When reporting issues:

• Error Messages: Exact error text
• Browser Information: Browser type and version
• Steps to Reproduce: Detailed reproduction steps
• Screenshots: Visual documentation of issues
• System Details: Relevant configuration information

This comprehensive guide provides complete coverage of the Site Settings system, enabling administrators to effectively customize and manage the visual appearance and global configuration of the EDMS application.