ImageWorks

ImageWorks is the image processing engine in Total CMS. It transforms images on-the-fly by passing parameters to methods like cms.media.imagePath(), cms.media.galleryPath(), and cms.render.image(). Transformed images are cached automatically.

{# Basic usage #}
<img src="{{ cms.media.imagePath('hero', {w: 800, h: 600, fit: 'crop'}) }}">

{# Gallery image #}
<img src="{{ cms.media.galleryPath('vacation', 'sunset.jpg', {w: 400, fm: 'webp'}) }}">

Resizing

Fit Modes

Crop Positions

Use with fit: 'crop-{position}':

top-left, top, top-right, left, center, right, bottom-left, bottom, bottom-right

{# Crop from the top of the image #}
{{ cms.media.imagePath('hero', {w: 800, h: 400, fit: 'crop-top'}) }}

{# Crop using the focal point set in the admin #}
{{ cms.media.imagePath('portrait', {w: 300, h: 300, fit: 'crop-focalpoint'}) }}

Format & Quality

{# Convert to WebP at 80% quality #}
{{ cms.media.imagePath('photo', {w: 1200, fm: 'webp', q: 80}) }}

{# AVIF for maximum compression #}
{{ cms.media.imagePath('photo', {w: 1200, fm: 'avif', q: 70}) }}

Effects & Filters

{# Blurred background #}
{{ cms.media.imagePath('bg', {w: 1920, blur: 20}) }}

{# Greyscale thumbnail #}
{{ cms.media.imagePath('portrait', {w: 200, filt: 'greyscale'}) }}

{# Sharpened product photo #}
{{ cms.media.imagePath('product', {w: 600, sharp: 15}) }}

Borders

Border methods: overlay (default), shrink, expand

{# 10px white border #}
{{ cms.media.imagePath('photo', {w: 500, border: '10,ffffff,overlay'}) }}

Flipping & Orientation

Image Watermarks

Overlay another image as a watermark.

{# Logo watermark in bottom-right corner #}
{{ cms.media.imagePath('photo', {
    w: 1200,
    mark: 'logo.png',
    markw: '15w',
    markpos: 'bottom-right',
    markpad: 20,
    markalpha: 70
}) }}

Schema-Level Watermarks

You can configure watermarks at the schema, collection, or per-object level using property settings. These are applied automatically without needing to pass parameters in templates.

{
    "image": {
        "field": "image",
        "label": "Photo",
        "settings": {
            "watermark": {
                "mark": "logo.png",
                "markw": "20w",
                "markpos": "bottom-right",
                "markpad": 15,
                "markalpha": 60
            }
        }
    }
}

Watermark settings follow the three-level override hierarchy: schema → collection → per-object. Override at the collection level in collection meta, or per-object using custom properties.

Text Watermarks

Render text directly on images without needing a separate watermark image.

Custom Fonts

Upload TTF or OTF fonts to the watermark-fonts depot (configurable via watermarkFontsDepot setting). The default font is RobotoRegular.

{# Simple copyright watermark #}
{{ cms.media.imagePath('hero', {
    w: 1200,
    marktext: 'Copyright 2026',
    marktextsize: 24,
    marktextcolor: 'ffffff',
    marktextpos: 'bottom-right',
    marktextpad: 15,
    marktextalpha: 70
}) }}

{# Custom font with background #}
{{ cms.media.imagePath('product', {
    w: 800,
    marktext: 'Premium Quality',
    marktextfont: 'Dorsa-Regular',
    marktextsize: 120,
    marktextcolor: 'ffffff',
    marktextbg: '000000',
    marktextpad: 20,
    marktextpos: 'bottom-right',
    marktextalpha: 80
}) }}

{# Diagonal DRAFT watermark #}
{{ cms.media.imagePath('document', {
    marktext: 'DRAFT',
    marktextsize: 200,
    marktextangle: -45,
    marktextcolor: 'ff0000',
    marktextpos: 'center',
    marktextalpha: 50
}) }}

Color Palette Integration

Images in Total CMS have an automatically extracted color palette (up to 5 colors). You can reference these palette colors in border and bg (background) parameters.

Use palette0 through palette4 to reference extracted colors:

{# Background color from the image's dominant color #}
{{ cms.media.imagePath('photo', {w: 800, bg: 'palette0'}) }}

{# Border using a palette color #}
{{ cms.media.imagePath('photo', {w: 500, border: '10,palette1,overlay'}) }}

Defaults & Presets

Defaults

Set default ImageWorks parameters that apply to every image transformation. Configure in tcms.php:

return [
    'imageworks' => [
        'defaults' => [
            'q'  => 85,
            'fm' => 'webp',
        ],
    ],
];

Any parameters passed in templates override the defaults.

Presets

Define reusable parameter sets that can be referenced by name. Configure in tcms.php:

return [
    'imageworks' => [
        'presets' => [
            'thumbnail' => [
                'w'   => 200,
                'h'   => 200,
                'fit' => 'crop',
                'q'   => 80,
            ],
            'hero' => [
                'w'   => 1920,
                'h'   => 600,
                'fit' => 'crop-focalpoint',
                'fm'  => 'webp',
                'q'   => 85,
            ],
            'avatar' => [
                'w'   => 100,
                'h'   => 100,
                'fit' => 'crop',
            ],
        ],
    ],
];

Use presets by passing the p parameter:

{{ cms.media.imagePath('photo', {p: 'thumbnail'}) }}
{{ cms.media.imagePath('banner', {p: 'hero'}) }}

{# Override specific preset values #}
{{ cms.media.imagePath('photo', {p: 'thumbnail', w: 300}) }}

Presets that use crop-focalpoint in their fit value will automatically use each image's saved focal point.

Caching

Transformed images are cached automatically on disk. The cache directory is .cache within the image storage directory. When the source image changes, cached versions are regenerated on the next request.

To clear the ImageWorks cache, use the emergency cache clear endpoint or clear the .cache directories from storage.

API Endpoint

ImageWorks images are served via the /imageworks/ endpoint:

/imageworks/{type}/{id}/{filename}?{parameters}

Where type is image or gallery, id is the object ID, and parameters are ImageWorks transformation params. You typically don't need to construct these URLs manually — use cms.media.imagePath() and cms.media.galleryPath() instead.