# 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](#system-integration)
2. [Features Overview](#features-overview)
3. [Accessing Site Settings](#accessing-site-settings)
4. [Configuration Categories](#configuration-categories)
5. [Basic Information Settings](#basic-information-settings)
6. [Branding & Visual Identity](#branding--visual-identity)
7. [SEO & Meta Tag Management](#seo--meta-tag-management)
8. [Theme System Integration](#theme-system-integration)
9. [Advanced Customization](#advanced-customization)
10. [API Integration](#api-integration)
11. [Technical Implementation](#technical-implementation)
12. [Best Practices](#best-practices)
13. [Troubleshooting](#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 administrators 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 admin 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`

### 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:
```css
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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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:

```javascript
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:

```sql
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. 