Host Custom CSS - Administrator Guide

Overview

The Host Custom CSS feature allows system administrators to upload custom CSS files that apply globally across all tenants in the application. This provides a powerful way to customize the appearance and branding of your entire application platform.

Key Features

• Global Application: CSS applies to all tenants unless they have their own custom CSS
• Complete Override Control: Can override any existing styles in the application
• Safe Upload Process: Built-in validation and error handling
• Easy Management: Upload, download, and remove CSS files through the admin interface
• Real-time Application: Changes take effect immediately after upload

Prerequisites

• Host Administrator Access: You must be logged in as a host administrator
• CSS Knowledge: Basic understanding of CSS is required to create effective customizations
• File Preparation: CSS file must be properly formatted and tested

Accessing the Feature

1. Navigate to Host Settings:

   • Log in as a host administrator
   • Go to Administration → Settings → Host Settings

2. Open Customization Tab:

   • Click on the Customization tab (look for the paint brush icon)
   • You'll see the Host Custom CSS management interface

Current Status Display

The interface shows the current state of your Host Custom CSS:

• Host CSS: Shows "Active" if CSS is uploaded, "Not Set" if no CSS is configured
• Last Updated: Displays when the CSS was last modified (if applicable)

Uploading Custom CSS

Step 1: Prepare Your CSS File

1. Create your CSS file with a .css extension
2. Test your CSS in a development environment first
3. Validate file requirements:
   • Maximum file size: 5MB
   • File format: CSS only (.css extension)
   • Ensure proper CSS syntax

Step 2: Upload Process

1. Click "Choose file" in the CSS File section
2. Select your CSS file from your computer
3. Review the file name displayed after selection
4. Click the "Upload" button
5. Monitor the progress bar during upload
6. Wait for success confirmation

Step 3: Verify Upload

After successful upload:

• Status will change to "Active"
• Last Updated timestamp will be displayed
• Remove and Download buttons will be enabled

Managing Existing CSS

Downloading Current CSS

1. Click the "Download" button (only available when CSS is active)
2. Save the file to your desired location
3. Use for backup or as a base for modifications

Removing CSS

1. Click the "Remove" button (only available when CSS is active)
2. Confirm the deletion in the popup dialog
3. Wait for success confirmation
4. Status will return to "Not Set"

⚠️ Warning: Removing CSS cannot be undone. Download a backup before removing if needed.

CSS Writing Guidelines

Understanding CSS Precedence

Your Host Custom CSS will be loaded with high precedence in the following order:

1. Bootstrap Framework CSS (lowest)
2. Application Theme CSS
3. Metronic Customizations
4. Page-specific CSS
5. YOUR HOST CUSTOM CSS ← High precedence
6. Tenant Custom CSS (if exists)
7. Inline page styles (highest)

Best Practices

1. Use Specific Selectors

/* Good - Specific selector */
.kt-portlet .kt-portlet__head .kt-portlet__head-title {
    color: #your-brand-color;
}

/* Avoid - Too generic */
h3 {
    color: #your-brand-color;
}

2. Target Common UI Elements

/* Header customization */
.kt-header {
    background-color: #your-brand-color;
}

/* Navigation styling */
.kt-aside-menu .kt-menu__nav .kt-menu__item .kt-menu__link {
    color: #your-text-color;
}

/* Button customization */
.btn-primary {
    background-color: #your-brand-color;
    border-color: #your-brand-color;
}

3. Form Builder Customization

/* Customize the form builder interface */
.formio-dialog.formio-dialog-theme-default .formio-dialog-content {
    background: #your-background-color;
    font-family: "Your Custom Font", sans-serif;
}

/* Form builder toolbar */
.card-header {
    background-color: #your-brand-color;
    color: white;
}

4. Responsive Design

/* Ensure mobile compatibility */
@media (max-width: 768px) {
    .your-custom-class {
        font-size: 14px;
        padding: 10px;
    }
}

Common Customization Examples

1. Brand Colors

/* Primary brand color */
:root {
    --kt-primary: #your-brand-color;
    --kt-primary-active: #your-brand-color-dark;
}

/* Apply to key elements */
.btn-primary, .kt-header, .kt-aside-menu .kt-menu__nav .kt-menu__item.kt-menu__item--active .kt-menu__link {
    background-color: var(--kt-primary) !important;
}

2. Custom Fonts

/* Import custom fonts */
@import url('https://fonts.googleapis.com/css2?family=Your+Font:wght@300;400;500;700&display=swap');

/* Apply to the entire application */
body, .kt-content, .form-control {
    font-family: 'Your Font', sans-serif !important;
}

3. Logo and Branding

/* Custom logo in header */
.kt-header-brand .kt-header-brand-logo img {
    max-height: 40px;
    content: url('https://your-domain.com/your-logo.png');
}

/* Hide default branding */
.kt-header-brand .kt-header-brand-text {
    display: none;
}

4. Form Styling

/* Customize form elements */
.form-control {
    border-radius: 8px;
    border: 2px solid #your-border-color;
}

.form-control:focus {
    border-color: #your-focus-color;
    box-shadow: 0 0 0 0.2rem rgba(your-rgb-values, 0.25);
}

External Form Styling Consistency

Metronic Theme Integration

As of this implementation, external forms now load the Metronic theme consistently with internal forms. The system automatically:

• External Forms: Load style.bundle.css and plugins.bundle.css from Metronic theme
• Internal Forms: Inherit existing Metronic theme from the main application layout
• Result: Consistent styling across all form contexts

CSS Loading Priority

1. Metronic Base Theme (style.bundle.css)
2. Metronic Plugins (plugins.bundle.css) 
3. FormIO Styles (formio.full.css)
4. FontAwesome Icons
5. Custom CSS (TenantCustomization/GetCustomCss)
6. Host Custom CSS (your uploaded CSS files)
7. Inline CSS overrides

Your Host Custom CSS will override Metronic theme styles when using appropriate specificity or !important declarations.

Troubleshooting

Common Issues and Solutions

Upload Fails

• Check file size: Ensure file is under 5MB
• Verify file format: Must be a .css file
• Check CSS syntax: Use a CSS validator to check for errors
• Network issues: Try uploading again or check your connection

CSS Not Applying

• Clear browser cache: Force refresh with Ctrl+F5 (Windows) or Cmd+Shift+R (Mac)
• Check CSS specificity: Your selectors might need to be more specific
• Use !important: For stubborn styles that won't override
• Check browser developer tools: Inspect elements to see if your CSS is loading

CSS Conflicts

• Use more specific selectors: Target elements more precisely
• Check cascade order: Ensure your CSS has proper precedence
• Test in isolation: Comment out sections to identify conflicts

Browser Developer Tools

Use browser developer tools to:

1. Inspect elements to see current styles
2. Test CSS changes before uploading
3. Debug selector specificity
4. Check if your CSS is loading

Security Considerations

Safe CSS Practices

• Avoid external resources: Don't reference external CSS files or images unless from trusted sources
• Test thoroughly: Always test CSS changes in a development environment first
• No JavaScript: CSS files should not contain JavaScript code
• Validate input: Ensure CSS doesn't break application functionality

Backup Strategy

1. Download current CSS before making changes
2. Keep version history of your CSS files
3. Test in staging before applying to production
4. Document changes for future reference

Support and Maintenance

Regular Tasks

• Review CSS effectiveness periodically
• Update for new application versions as needed
• Monitor user feedback about styling changes
• Maintain documentation of customizations

Getting Help

If you encounter issues:

1. Check this documentation for common solutions
2. Use browser developer tools for debugging
3. Contact system support with specific error messages
4. Provide CSS samples when requesting help

Advanced Features

CSS Variables

Use CSS custom properties for easier maintenance:

:root {
    --brand-primary: #your-color;
    --brand-secondary: #your-secondary-color;
    --brand-font: 'Your Font', sans-serif;
}

/* Apply variables throughout your CSS */
.custom-element {
    color: var(--brand-primary);
    font-family: var(--brand-font);
}

Animation and Transitions

Add smooth transitions for better user experience:

.btn, .form-control, .kt-menu__link {
    transition: all 0.3s ease;
}

.btn:hover {
    transform: translateY(-2px);
    box-shadow: 0 4px 8px rgba(0,0,0,0.1);
}

Form Styling Consistency

Metronic Theme Integration

As of the latest update, all forms (both internal and external) now consistently use the Metronic theme styling instead of basic Bootstrap. This ensures:

• Consistent appearance across all form contexts
• Professional styling with the Metronic design system
• Better user experience with unified visual language

Technical Implementation

The Syntaq.js script automatically loads:

• /metronic/themes/default/css/style.bundle.css
• /metronic/themes/default/plugins/global/plugins.bundle.css
• Form.io CSS for form-specific styling

This replaces the previous Bootstrap 4.1.3 styling that was only applied to external forms.

Customization Impact

Your Host Custom CSS will now consistently apply over the Metronic theme base, providing:

• Predictable styling inheritance
• Better CSS specificity control
• Consistent brand application across all contexts

Conclusion

The Host Custom CSS feature provides powerful customization capabilities for your application. By following this guide and best practices, you can create a branded, professional appearance that reflects your organization's identity while maintaining usability and performance.

Remember to always test changes thoroughly and keep backups of your CSS files for safe customization management.