Skip to content

Media Library

Jump to bottom
Phillip Dornauer edited this page Apr 13, 2026 · 2 revisions

Media Library

The media library stores all uploaded images and files. Access it via Media in the admin sidebar.

Uploading Files

Click Upload and select files. Multiple files can be uploaded at once. Supported image formats: JPEG, PNG, GIF, WebP, SVG. Maximum file size: 10 MB for images, 50 MB for other files.

Folders

Organize media with folders. Click New Folder to create a folder. Folders can be renamed and deleted (deleting a folder does not delete its files).

Using Media in Fields

Image and file fields open a media picker when you click the field. Browse folders, search by filename, and select the desired file.

Focal Point

For image fields, you can set a focal point — the most important area of the image. When Marble generates a cropped version, it centers the crop on the focal point.

To set: click Set Focal Point on the image in the media library, then click the focal area on the image preview.

Image Transformations

Images served via $media->url(width, height) are resized on the fly:

$img->url()           // Original — no resizing
$img->url(800)        // Resize to width 800, proportional height
$img->url(0, 400)     // Resize to height 400, proportional width
$img->url(800, 600)   // Cover-crop to 800×600 (uses focal point)

Smart Crops

Smart Crops let you define named crop presets (e.g. hero, thumbnail, og_image) with fixed dimensions. Once defined, any image can be cropped to a preset using a single call.

Managing Presets

Go to Dashboard → Configuration → Smart Crops. Each preset has:

  • Name — machine identifier used in code (e.g. hero)
  • Label — display label in the admin
  • Width / Height — pixel dimensions

Using Smart Crops in Templates

$item->value('image')->crop('hero')       // Returns URL or null
$item->value('image')->crop('thumbnail')

The crop is focal-point aware: it scales the image to cover the target dimensions and then crops centered on the focal point.

Crop Preview

When editing a media item that has a blueprint assigned, the sidebar shows a preview thumbnail for every defined crop preset.

Media Blueprints

Attach structured metadata to media files by assigning a Blueprint to a media item. This is useful for images that need captions, alt text, photographer credits, or other structured fields.

Setting Up MIME Rules

Go to Dashboard → Configuration → Media Blueprints. Add rules that map MIME type patterns to blueprints:

MIME Pattern Blueprint
image/jpeg photo (exact match)
image/* image_meta (wildcard)
application/pdf pdf_document

Exact matches take priority over wildcards. If no rule matches, the configurable default blueprint is used (or none, if not set).

How It Works

When a file is uploaded:

  1. Marble resolves the matching MIME rule
  2. The file is saved and the matched blueprint is assigned to the media item
  3. If a blueprint was matched, the admin redirects to the Fields tab for that media item to enter metadata

Accessing Media Field Values in Templates

$image = $item->value('image');

$image->field('alt_text')       // Media field value (current language)
$image->field('caption', 'de')  // Specific language
$image->url(800, 600)           // Transform still works as normal

CKEditor Integration

When editing a rich text field, the image upload button in CKEditor uploads directly to the media library.

Deleting Media

Click the trash icon on a media item. Note: deleting media that is still referenced by content items will leave broken image references — check usage before deleting.

Clone this wiki locally