What type of issue is it? (Choose one - delete the others)
Missing documentation
What article/section is this about?
The Customizing the Backoffice section: https://docs.umbraco.com/umbraco-cms/customizing/overview
There is currently no natural home for this topic — nothing under Customizing covers how to display media in an extension, and it isn't specific to any one extension type.
Describe the issue
A recurring question from extension authors is how to go from a media GUID (e.g. the value of a media picker property) to an actual rendered image inside a backoffice extension. There is currently no documentation covering this flow, which leads developers to reverse-engineer the CMS source code or hand-roll solutions. Recent forum threads where this surfaced:
There are two related gaps:
1. GUID-to-URL resolution in extensions (general)
Nothing documents that the supported way to render a media item from its key is the <umb-imaging-thumbnail> element:
<umb-imaging-thumbnail unique="GUID" width="256" height="128" mode="crop"></umb-imaging-thumbnail>
…or, for programmatic scenarios, UmbImagingRepository.requestResizedItems() / requestThumbnailUrls() from @umbraco-cms/backoffice/imaging, with UmbMediaDetailRepository for retrieving media properties (dimensions, alt text, etc.). This applies to all extension types — property editors, block custom views, dashboards — since the imaging part is identical regardless of the host extension.
2. HMAC signing (newer layer on top)
Since the introduction of HMACSecretKey, manually constructed media URLs with imaging querystrings fail validation. Extensions that build URLs by hand break, while the element/repository above produce correctly signed URLs transparently. Because this is recent, none of the older community examples account for it, and the imaging settings reference does not cover the extension-author perspective.
Suggested approach
A generic article under Customizing the Backoffice, e.g. "Displaying Media in Extensions", covering:
<umb-imaging-thumbnail> as the default/recommended approach (attributes: unique, width, height, mode)UmbImagingRepository for programmatic use, including batchingUmbMediaDetailRepository.requestByUnique() for media metadata- A short note that HMAC signing is handled automatically by these APIs, with a link to the imaging settings reference for the server-side configuration
- A note that the approach is identical across extension types
A fuller step-by-step tutorial (e.g. building a block custom view or property editor that renders picked media) could be a follow-up, but the generic article would close the immediate gap and give the forum threads above something to link to.
Working community examples exist in both threads and can serve as a starting point. Happy to contribute to the article itself.
What type of issue is it? (Choose one - delete the others)
Missing documentation
What article/section is this about?
The Customizing the Backoffice section: https://docs.umbraco.com/umbraco-cms/customizing/overview
There is currently no natural home for this topic — nothing under Customizing covers how to display media in an extension, and it isn't specific to any one extension type.
Describe the issue
A recurring question from extension authors is how to go from a media GUID (e.g. the value of a media picker property) to an actual rendered image inside a backoffice extension. There is currently no documentation covering this flow, which leads developers to reverse-engineer the CMS source code or hand-roll solutions. Recent forum threads where this surfaced:
There are two related gaps:
1. GUID-to-URL resolution in extensions (general)
Nothing documents that the supported way to render a media item from its key is the
<umb-imaging-thumbnail>element:…or, for programmatic scenarios,
UmbImagingRepository.requestResizedItems()/requestThumbnailUrls()from@umbraco-cms/backoffice/imaging, withUmbMediaDetailRepositoryfor retrieving media properties (dimensions, alt text, etc.). This applies to all extension types — property editors, block custom views, dashboards — since the imaging part is identical regardless of the host extension.2. HMAC signing (newer layer on top)
Since the introduction of
HMACSecretKey, manually constructed media URLs with imaging querystrings fail validation. Extensions that build URLs by hand break, while the element/repository above produce correctly signed URLs transparently. Because this is recent, none of the older community examples account for it, and the imaging settings reference does not cover the extension-author perspective.Suggested approach
A generic article under Customizing the Backoffice, e.g. "Displaying Media in Extensions", covering:
<umb-imaging-thumbnail>as the default/recommended approach (attributes: unique, width, height, mode)UmbImagingRepositoryfor programmatic use, including batchingUmbMediaDetailRepository.requestByUnique()for media metadataA fuller step-by-step tutorial (e.g. building a block custom view or property editor that renders picked media) could be a follow-up, but the generic article would close the immediate gap and give the forum threads above something to link to.
Working community examples exist in both threads and can serve as a starting point. Happy to contribute to the article itself.