Branding and Customization#

This guide explains how to customize your NexusLIMS-CDCS deployment to match your organization’s branding and requirements.

Overview#

NexusLIMS uses a centralized settings approach where all customization options are defined in NexusLIMS-CDCS/config/settings/.

This directory contains default values appropriate for development (dev_settings.py) and production (prod_settings.py) deployments of NexusLIMS. To customize your deployment, you can use the custom_settings.py template also provided in that folder.

Customization Workflow#

Never modify:
- nexuslims_overrides/settings.py
- config/settings/dev_settings.py
- config/settings/prod_settings.py
Override/change settings in config/settings/custom_settings.py
Update DJANGO_SETTINGS_MODULE in your .env file by setting it to DJANGO_SETTINGS_MODULE=config.settings.custom_settings
Place custom assets (logos, images) in config/static_files/
Restart containers to load new configuration (no rebuild required)

Branding & Logos#

Homepage Logo#

The logo displayed on the homepage alongside the welcome text.

# Default: "nexuslims/img/logo_stacked_modern.png"
NX_HOMEPAGE_LOGO = "path/to/your/homepage_logo.png"

Recommendations:

Format: PNG or SVG
Size: Max width 400px
Style: Can include text/wordmark

Theme Colors#

Customize the color scheme of your NexusLIMS deployment using CSS custom properties. These colors are used throughout the interface for buttons, links, badges, and other UI elements.

NX_THEME_COLORS = {
    "primary": "#11659c",           # Main brand color (buttons, links, icons)
    "primary_dark": "#0d528a",      # Darker variant for hover states
    "info_badge_dark": "#505050",   # Info badge background color
    "secondary": "#f9f9f9",         # Secondary (light) button background
    "secondary_dark": "#e2e2e2",    # Secondary button hover state
    "success": "#28a745",           # Success states
    "danger": "#dc3545",            # Error/danger states
    "warning": "#ffc107",           # Warning states and hover highlights
    "info": "#17a2b8",              # Info messages
    "light_gray": "#e3e3e3",        # Light gray accents
    "dark_gray": "#212529",         # Dark text color
}

How it works:

Colors are injected as CSS custom properties (e.g., --nx-primary-color)
Only specify colors you want to change; unspecified colors use CSS defaults
Changes take effect after restarting the Django container

Usage:

Set NX_THEME_COLORS in your config/settings/custom_settings.py
Only include the colors you want to override

Example: Custom Blue Theme

NX_THEME_COLORS = {
    "primary": "#1a5276",
    "primary_dark": "#154360",
    "warning": "#f4d03f",
}

Example: Corporate Green Theme

NX_THEME_COLORS = {
    "primary": "#1e8449",
    "primary_dark": "#196f3d",
    "info_badge_dark": "#2c3e50",
}

Tip

Choose a primary color that represents your organization’s brand. The warning color is used for hover highlights on links and buttons.

Homepage Content#

Welcome Title#

# Default: "Welcome to NexusLIMS!"
CUSTOM_TITLE = "Welcome to Your LIMS!"

Homepage Text#

NX_HOMEPAGE_TEXT = """
Your custom introductory text here. This appears on the homepage
and explains what your LIMS does and how to use it.
"""

Tip

Keep this concise (2-3 sentences) and action-oriented.

Documentation Link#

# Default: "https://datasophos.github.io/NexusLIMS/"
NX_DOCUMENTATION_LINK = "https://docs.your-organization.com"

Set to empty string "" to hide the documentation link entirely.

Navigation Menu#

Custom Menu Links#

Add custom links to the top navigation bar.

NX_CUSTOM_MENU_LINKS = [
    {
        "title": "Data Portal",
        "url": "https://portal.your-org.com",
        "icon": "database",           # Font Awesome icon name (optional)
        "iconClass": "fas"            # Font Awesome class (optional)
    },
    {
        "title": "Help Desk",
        "url": "https://help.your-org.com",
        "icon": "question-circle"
    },
    {
        "title": "Team Directory",
        "url": "/team",
        "icon": "users"
    },
]

Icon Options:

Use any Font Awesome 6 icon name
iconClass can be "fas" (solid), "far" (regular), or "fab" (brands)
Omit icon to display text only

Tip

Limit to 3-5 custom links to avoid cluttering the navigation.

XSLT Configuration#

XSLT Debug Mode#

Enable detailed messages from XSLT transformation for debugging.

# Enable XSLT debug output (default: False)
NX_XSLT_DEBUG = True

Use Cases:

Development: Set to True when working on XSLT stylesheets
Production: Set to False to avoid verbose debug output

You can add debug statements in XSLT using <xsl:message> tags:

<xsl:message>DEBUG: Processing instrument <xsl:value-of select="$instrument-name"/></xsl:message>

Instrument Badge Colors#

Configure colors for instrument badges in detail and list views.

NX_INSTRUMENT_COLOR_MAPPINGS = {
    "FEI-Titan-TEM": "#2E86AB",     # Blue for TEMs
    "FEI-Titan-STEM": "#0645AD",    # Darker blue for STEM
    "FEI-Quanta200-ESEM": "#A569BD", # Purple for ESEM
    "Hitachi-S4700-SEM": "#E74C3C", # Red for Hitachi SEMs
    "JEOL-JSM7100-SEM": "#F39C12",  # Orange for JEOL SEMs
    "Zeiss-LEO_1525_FESEM": "#16A085", # Teal for Zeiss
}

Best Practices:

Use distinct, accessible colors
Choose colors that contrast well with white text
Group similar instruments by color family
Use tools like Coolors for palettes

Feature Flags#

Enable/Disable Features#

# Enable the interactive tutorial (default: True)
NX_ENABLE_TUTORIALS = True

Dataset Display Threshold#

Control when simplified display mode is used for records with many datasets.

# Records with more datasets than this use simple display
# Default: 100
NX_MAX_DATASET_DISPLAY_COUNT = 100

Guidelines:

Default (100): Records with 101+ datasets use simple display
Lower values (50): More records use simple display (better performance)
Higher values (500): Fewer records use simple display (more interactive)
0: Always use full interactive display

Custom Assets#

Directory Structure#

Place custom assets in config/static_files/:

config/
├── static_files/
│   ├── logo_horizontal_light.png
│   ├── footer_logo.png
│   ├── logo_horizontal_text.png
│   └── custom_icon.png
└── settings/
    └── custom_settings.py

Benefits:

Keep customizations separate from app code
No need to modify nexuslims_overrides/ directory
Runtime configuration updates without rebuilding containers

Example Configurations#

University Deployment#

# University of Example - NexusLIMS Settings

# Theme Colors (university blue)
NX_THEME_COLORS = {
    "primary": "#2E86AB",
    "primary_dark": "#1A5276",
    "warning": "#F5B041",
}

# Branding
CUSTOM_TITLE = "Welcome to UEx Microscopy LIMS"
NX_NAV_LOGO = "nexuslims/img/uex_nav_logo.png"
NX_FOOTER_LOGO = "nexuslims/img/uex_footer_logo.png"
NX_FOOTER_LINK = "https://microscopy.uex.edu"

# Content
NX_HOMEPAGE_TEXT = (
    "Access and manage microscopy data from the University of Example "
    "Microscopy Core Facility."
)
NX_DOCUMENTATION_LINK = "https://microscopy.uex.edu/docs"

# Navigation
NX_CUSTOM_MENU_LINKS = [
    {"title": "Core Facility", "url": "https://microscopy.uex.edu", "icon": "microscope"},
    {"title": "Book Time", "url": "https://booking.uex.edu", "icon": "calendar"},
    {"title": "Training", "url": "https://training.uex.edu", "icon": "graduation-cap"},
]

# Instrument Colors
NX_INSTRUMENT_COLOR_MAPPINGS = {
    "FEI-Titan-TEM": "#2E86AB",
    "FEI-Titan-STEM": "#0645AD",
    "FEI-Quanta200-ESEM": "#A569BD",
}

# Features
NX_ENABLE_TUTORIALS = True
NX_MAX_DATASET_DISPLAY_COUNT = 99

Corporate Lab#

# Acme Corp - Materials Lab LIMS Settings

# Theme Colors (corporate orange)
NX_THEME_COLORS = {
    "primary": "#E67E22",
    "primary_dark": "#D35400",
    "info_badge_dark": "#34495E",
}

# Branding
CUSTOM_TITLE = "Acme Materials Lab"
NX_NAV_LOGO = "nexuslims/img/acme_logo_white.png"
NX_FOOTER_LOGO = "nexuslims/img/acme_logo_color.png"
NX_FOOTER_LINK = "https://acme.com/materials-lab"

# Content
NX_HOMEPAGE_TEXT = (
    "Materials characterization data management system for Acme Corp R&D."
)
NX_DOCUMENTATION_LINK = ""  # Internal docs not public

# Navigation
NX_CUSTOM_MENU_LINKS = [
    {"title": "Sample Request", "url": "https://samples.acme.internal", "icon": "flask"},
    {"title": "Lab Wiki", "url": "https://wiki.acme.internal/materials", "icon": "book"},
    {"title": "Support", "url": "mailto:lab-support@acme.com", "icon": "envelope"},
]

# Features
NX_ENABLE_TUTORIALS = False  # Custom onboarding
NX_MAX_DATASET_DISPLAY_COUNT = 249

Troubleshooting#

Changes Not Appearing#

Restart Django:
```
dc-prod restart cdcs
```

Run collectstatic:

docker exec nexuslims_prod_cdcs python manage.py collectstatic --noinput

Clear browser cache: Hard refresh (Ctrl+Shift+R / Cmd+Shift+R)

Instrument Colors Not Updating#

Verify setting name is exactly NX_INSTRUMENT_COLOR_MAPPINGS
Check instrument PIDs match exactly what’s in the database
Validate color format (must be #RRGGBB)
Restart Django (XSLT parameters load at startup)
Enable NX_XSLT_DEBUG = True to see transformation messages

Logo Not Displaying#

Check file path is correct (relative to config/static_files/)
Verify file exists and has read permissions
Run collectstatic to collect files
Check Django logs for 404 errors

Theme Colors Not Applying#

If your custom theme colors aren’t appearing:

Verify dictionary keys are lowercase without nx_ prefix (e.g., "primary", not "NX_PRIMARY_COLOR")
Check color format is valid CSS (e.g., #RRGGBB)
Restart Django (theme colors load at startup)
Clear browser cache (Ctrl+Shift+R / Cmd+Shift+R)

Valid keys: primary, primary_dark, info_badge_dark, secondary, secondary_dark, success, danger, warning, info, light_gray, dark_gray

Summary#

NexusLIMS customization is designed to be:

Centralized: All settings in one place
Safe: Override in your settings, never modify defaults
Flexible: From simple logo swaps to complete rebranding
Maintainable: Clearly separated from core CDCS code

Start with basic branding (logos and text), then progressively customize navigation, features, and styling as needed.