README

Replaces the default document thumbnails in SilverStripe's Asset Admin with category-colored SVG icons and rendered preview thumbnails. Works in AssetAdmin (grid & list view, edit panel) and UploadField modals. Handles any file extension automatically.

Requirements

• SilverStripe 5 (silverstripe/asset-admin: ~2.0)
• restruct/silverstripe-simpler (provides DOMNodesInserted events)
• restruct/xpdf-static (bundled PDF renderer, no system dependencies)

How it works

Category icons

1. CSS immediately applies category icons using SilverStripe's built-in classes (gallery-item--document, gallery-item--archive, etc.) — no flash of default icons
2. JavaScript reads React fiber data and sets data-ext attributes for more specific icons (e.g., PDF instead of generic document)
3. SCSS maps ~170 file extensions to 18 categories, each with a colored SVG icon
4. External SVGs are loaded on-demand and cached by the browser (76KB CSS + ~31KB SVGs)

Regular images don't need icons — SilverStripe generates thumbnails for those. This module targets document-category files only.

Rendered preview thumbnails

For file types that can be rendered to images (PDFs, SVGs, EPS, etc.), the module generates actual PNG preview thumbnails instead of showing a generic category icon. Previews appear in tile view, table view, and the edit panel.

Previews are generated on-demand the first time a file appears in Asset Admin and stored as file variants in the AssetStore. A small file-type badge (e.g. "PDF") is shown on the thumbnail so users can distinguish previews from actual images.

How it works under the hood:

• RenderablePreviewExtension (on File) generates PNG variants using CLI renderers (xpdf for PDFs, Ghostscript for EPS/PS/AI, rsvg-convert for SVGs)
• RenderableThumbnailGenerator overrides the GraphQL-specific ThumbnailGenerator service via Injector, so the thumbnail field returns the preview URL for non-image files
• Since React's GalleryItem only applies backgroundImage for image-category files, the JS applies the preview as an inline style for non-image files that have a thumbnail value

Enable in your project config:

Restruct\SilverStripe\AssetIcons\Renderable\RenderablePreviewExtension:
  enable_renderable_previews: true

Configuration options:

Restruct\SilverStripe\AssetIcons\Renderable\RenderablePreviewExtension:
  enable_renderable_previews: true
  preview_width: 800           # target width for rendered PNG
  preview_height: 800          # target height for rendered PNG
  max_renders_per_request: 5   # prevents timeouts on first load
  renderers:                   # extension => renderer class
    pdf: Restruct\SilverStripe\AssetIcons\Renderable\XpdfRenderer
    eps: Restruct\SilverStripe\AssetIcons\Renderable\GhostscriptRenderer
    svg: Restruct\SilverStripe\AssetIcons\Renderable\SvgRenderer

Supported formats and their requirements:

Using previews in templates:

The rendered preview is available as a DBFile on any File object, supporting all standard image manipulation methods:

<%-- Full-size preview as <img> tag --%>
$MyPDFFile.RenderedPreview

<%-- Resized preview --%>
$MyPDFFile.RenderedPreview.ScaleWidth(300)
$MyPDFFile.RenderedPreview.FitMax(400, 300)

<%-- Just the URL --%>
<img src="$MyPDFFile.RenderedPreview.URL" alt="Preview" />

<%-- Conditional --%>
<% if $MyPDFFile.RenderedPreview %>
    $MyPDFFile.RenderedPreview.ScaleWidth(200)
<% end_if %>

Returns null for images (use SilverStripe's native manipulation), unsupported formats, or when previews are disabled.

Note on preview dimensions: PDF and EPS renderers are DPI-based (default 150 DPI) and ignore the preview_width/preview_height config — the base preview is rendered at the document's native page size (e.g. ~1240×1753px for A4). The SVG renderer uses preview_width/preview_height as bounds.

Known limitations:

• Preview variants are stored as .png files (via SilverStripe's ExtRewrite variant naming), supporting full image manipulation. Upgrading from 2.2.x will regenerate previews on first access.
• Not tested with protected/draft files (the module assumes staging is removed).

Categories

Adding extensions

Edit client/src/styles/asset-icons.scss:

$ext-categories: (
  // ... existing entries ...
  myext: document,    // map to existing category
);

Then rebuild: npm run build

Adding categories

1. Create an SVG in client/icons/ (use an existing one as template)
2. Add to $category-icons map in the SCSS
3. Map extensions to the new category in $ext-categories
4. Rebuild: npm run build

Build

cd silverstripe-asset_icons
npm install
npm run build       # production build

After building, run composer vendor-expose to re-expose client assets.

File structure

client/
  icons/              # 18 category SVG source files
  icons-source.svg    # Master Inkscape file with all icons
  src/
    js/               # Vanilla JS source (React fiber → data-ext + preview)
    styles/           # SCSS source
  dist/
    icons/            # External SVG files (loaded on-demand, cached)
    js/               # Copied JS
    styles/           # Compiled CSS (~77KB)
src/
  Dev/                # IconsPreviewController (visit /admin/asset-icons-preview)
  Renderable/         # Rendered preview system
    RenderablePreviewExtension.php   # File extension: generates & stores variants
    RenderableThumbnailGenerator.php # Injector override for GraphQL thumbnails
    RendererInterface.php            # Contract for CLI renderers
    XpdfRenderer.php                 # PDF → PNG (bundled binary)
    GhostscriptRenderer.php          # EPS/PS/AI → PNG (system gs)
    SvgRenderer.php                  # SVG → PNG (system rsvg-convert)

Credits

• Pictograms: Bootstrap Icons (MIT)