Skip to content

THEME_GUIDE.md

Latest commit

 

History

History
85 lines (60 loc) · 2.47 KB

THEME_GUIDE.md

File metadata and controls

85 lines (60 loc) · 2.47 KB

FolderView Plus Theme Guide

Overview

FolderView Plus supports custom CSS and JavaScript extensions on Docker, VM, and Dashboard pages.

Versioned compatibility contract:

  • docs/THEME_API_CONTRACT.md

Custom extension directories:

  • CSS: /boot/config/plugins/folderview.plus/styles/
  • JS: /boot/config/plugins/folderview.plus/scripts/

Legacy override roots are also supported (folder.view, folder.view2, folder.view3) for migration compatibility.

File Naming

Use name.tab.ext where:

  • name: any prefix/name
  • tab: docker, vm, dashboard (can chain with -)
  • ext: .css or .js

Examples:

  • mytheme.docker.css
  • mytheme.vm.js
  • mytheme.dashboard-docker.css

Disable a file without deleting it:

  • mytheme.docker.css.disabled

Runtime Theme Tokens

Primary runtime tokens:

  • --fvplus-status-started
  • --fvplus-status-paused
  • --fvplus-status-stopped
  • --fvplus-graph-cpu
  • --fvplus-graph-mem
  • --fvplus-surface-tint
  • --fvplus-hover-bg
  • --fvplus-border

Per-folder optional status overrides (set automatically by runtime when custom colors are configured):

  • --fvplus-folder-status-started
  • --fvplus-folder-status-paused
  • --fvplus-folder-status-stopped

Legacy graph aliases remain supported:

  • --folder-view3-graph-cpu
  • --folder-view3-graph-mem

Started State Theme Awareness

Started status now follows active theme text color by default through --fvplus-status-started.

  • Dark themes: started text/icons render light.
  • Light themes: started text/icons render dark.
  • If a folder has a custom started color configured, that custom value is applied for that folder only.

Runtime Selector Contract

Stable runtime selectors for custom themes:

  • td.ct-name.folder-name
  • div.folder-name-sub
  • button.dropDown-* + .folder-dropdown
  • td.updatecolumn.folder-update
  • div.folder-preview
  • img.img.folder-img
  • span.state.folder-state
  • .preview-outbox, .action-info, .info-ct, .tooltipster-docker-folder

Loader Security

Custom CSS/JS loaders resolve and validate each file path against the configured base override directory before loading.

This blocks path traversal via symlinks or unexpected paths.

Recommendations

  • Prefer CSS variables over !important.
  • Scope overrides to Docker/VM/Dashboard roots where possible.
  • Keep status color overrides for semantic exceptions, not broad theme foundations.
  • Use Theme diagnostics in settings to verify resolved token values after switching themes.