Displaying page attachments

Attachments represent files, for example images or documents, tied directly to a page. Attachments can be stored in page type fields of the following data types:

• Attachments – stores multiple attachments under a single page type field.
• File – stores a single page attachment.

and as unsorted attachments tied directly to the page (TreeNode) object.

When working with page attachments in the API:

• Use the IPageRetriever service to retrieve the desired pages. You can use page type generators to generate strongly typed representations of individual page types. The generated code uses the DocumentAttachment type (available in the CMS.DocumentEngine namespace) for File fields, and IEnumerable<DocumentAttachment> for Attachments fields.
• Access page field attachments via the Fields property of the generated page type class. You can access various attachment properties, such as their name or MIME type.
• Access unsorted attachments via the Attachments property of the generated page type class.
• To generate URLs for page attachments, use the IPageAttachmentUrlRetriever service.

The following example illustrates how to access various page attachments of the Article page type using its corresponding generated class:

// Contains an instance of the IPageRetriever service (e.g., obtained via dependency injection)
private readonly IPageRetriever pageRetriever;

// Retrieves an article
Article article = pageRetriever.Retrieve<Article>(
                        query => query
                                .Path("Home/", PathTypeEnum.Single)
                                .TopN(1))
                                .FirstOrDefault();

// Accesses a property of an attachment stored in the article's 'Teaser' field (of the File data type)
string attachmentName = article.Fields.Teaser.AttachmentName;

// Iterates over attachments in the article's 'Images' field (of the Attachments data type)
foreach (DocumentAttachment image in article.Fields.Images)
{
    string imageMimeType = image.AttachmentMimeType;
}

// Iterates over unsorted attachments 
foreach (DocumentAttachment image in article.Attachments)
{
    string imageMimeType = image.AttachmentMimeType;
}

Getting page attachment URLs

To generate URLs for page attachments, use the IPageAttachmentUrlRetriever service (Kentico.Content.Web.Mvc namespace) and its Retrieve method:

// Contains an instance of the IPageAttachmentUrlRetriever  service (e.g., obtained via dependency injection)
private readonly IPageAttachmentUrlRetriever attachmentUrlRetriever;

// Contains a page from Xperience
// The Article class is a strongly typed representation of a custom 'Article' 
// page typed generated by the system (Page Types application -> edit a page type -> Code tab)
Article article;

// Resolves a URL for an attachment stored in the 'Attachment' field of the 'Article' page type
IPageAttachmentUrl attachmentUrl = attachmentUrlRetriever.Retrieve(article.Fields.Attachment);

The Retrieve method returns an IPageAttachmentUrl object with the following properties:

• string AbsoluteUrl – the application absolute URL of the page attachment.
• string RelativePath – the application relative (starting with '~/') permanent path to the file. For example: ~/getattachment/0140bccc-9d47-41ea-94a9-ca5d35b2964c/sample_image.jpg. This format ensures that the image remains accessible if the file is renamed or moved to a different media library or directory on the file system.
• bool IsImage – a boolean flag stating whether the URL leads to an image file.
• NameValueCollection QueryStringParameters – a collection of query string parameters appended to the URL. See Parameterizing attachment URLs.

You can further adjust the URLs by calling various extension methods on the IPageAttachmentUrl object. See Parameterizing attachment URLs.

Creating image variant URLs

To get URLs for image variants of page attachments, use the WithVariant extension method (Kentico.Content.Web.Mvc namespace) on the IPageAttachmentUrl object. Specify the image variant definition identifier as the method's parameter. The generated URLs are treated identically to URLs generated for standard attachments and can be parameterized the same way.

IPageAttachmentUrl variantUrl = attachmentUrl.WithVariant("variantName");

Parameterizing attachment URLs

You can further parameterize the retrieved attachment URLs via extension methods on the IPageAttachmentUrl object. The extension methods add query string parameters that change the URL behavior and allow you to customize the format of the files. The following extensions are available:

• WithOptions – used to provide additional configuration for the URL via a FileUrlOptions object. Using the object, you can specify:

  • Content disposition – configured via the AttachmentContentDisposition boolean property. Determines whether the file gets displayed inline (false) or requires some form of user action to download (true).

    C#

    Copy

    using Kentico.Content.Web.Mvc
    
    ...
    
    // Forces a download of the media file when its URL is accessed
    // The pageAttachmentUrl variable is an IPageAttachmentUrl object obtained via IPageAttachmentUrlRetriever
    IFileUrl attachmentUrlWithOptions = pageAttachmentUrl.WithOptions(new FileUrlOptions { AttachmentContentDisposition = true});

• WithSizeConstraint – used to resize image media files. You can resize image files via the SizeConstraint parameter of the method. Note, however, that this parameterization never upscales the image. The following image size constraints are available:

  • SizeConstraint.Empty – leaves the image unchanged.

  • SizeConstraint.Height(100) – resizes the image to the specified height (maintains aspect ratio).

  • SizeConstraint.Width(100) – resizes the image to the specified width (maintains aspect ratio).

  • SizeConstraint.MaxWidthOrHeight(100) – resizes the image so that its width and height do not exceed the specified value (maintains aspect ratio).

  • SizeConstraint.Size(100, 120) – resizes the image to the specified width and height. Does not maintain aspect ratio.

    Image resizing

    • It is not possible to resize image files via the SizeConstraint parameter when using direct URLs. This is caused by the fact that files accessed from direct URLs are handled directly by the hosting environment.
    • Image resizing via the SizeConstraint parameter is not supported for the SVG and WebP image formats.
    • Resized images are not rendered by default on Linux deployments of ASP.NET Core live site projects. To add compatible image resizing functionality, developers need to apply hotfix 13.0.107⁠ (opens in a new tab) or newer and install the Kentico.Xperience.ImageProcessing.KX13⁠ (opens in a new tab) NuGet package into the live site project.
    • For ASP.NET Core projects, developers can provide their own image resizing functionality – implement IImageProcessingService and register the service using the RegisterImplementation attribute. Requires hotfix 13.0.107⁠ (opens in a new tab) or newer.
    • If the Image file request protection feature is enabled, any links to image file endpoints (i.e., getattachment) with resizing query parameters need to include a validation hash.