Displaying page attachments

Attachments represent files, for example images, stored in page type fields. Page attachments can be stored in fields of the following data types:

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

For working with page attachments in MVC applications, we recommend using the API provided by classes that you generate via the Code tab 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.

The generated API gives you more control than the standard attachment API when resolving URLs for page attachments. The following example illustrates how to access various page attachments of the Article page type using its corresponding generated provider class.

// Retrieves an article
Article article = ArticleProvider.GetArticle(nodeGuid, "en-US", "MySite");

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

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

Prerequisite

To ensure that attachment URLs work correctly in both the MVC application and the connected Kentico administration interface, the system must be configured to use the permanent URL format. MVC sites have permanent URLs enabled by default, but you can use the following steps to confirm the configuration:

1. Access the administration interface of your Kentico application.
2. Open the Settings application.
3. Select the URLs and SEO category.
4. Make sure the Use permanent URLs setting is enabled.

With permanent URLs enabled, the system generates valid URLs in a consistent format for all possible types of attachments.

Creating page attachment URLs

To generate URLs for DocumentAttachment objects, call the GetPath extension method (available in the Kentico.Content.Web.Mvc namespace):

string attachmentUrl = article.Fields.Teaser.GetPath();

string attachmentUrl = article.Fields.Teaser.GetPath("Mobile");

The result is a relative URL in the following format:

~/getattachment/<file GUID>/<filename>

The system automatically resolves relative URLs to their absolute form using a filter that processes the output of all pages.

We recommend that you further adjust the URLs by calling the ImageUrl or FileUrl extension method in your views. The methods allow you to set size constraints for images or the disposition for file links.

<img alt="Article @article.Fields.Title" src="@Url.Kentico().ImageUrl(article.Fields.Teaser.GetPath(), SizeConstraint.Empty)">

See also:

• Page attachment versioning
• Constraining the returned attachment size for images
• Prompting users for action when accessing attachments

Page attachment versioning

The GetPath() extensionmethod always returns the attachment that is attached to the version of the page you are currently working with. For example, using the GetPath() extension method on pages retrieved via a generated provider class retrieves the attachment belonging to the published version of the page (the providers work with published versions of pages by default).

Constraining the returned attachment size for images

You can use the Url.Kentico().ImageUrl method to resize image attachments:

• Specify the maximum height of the retrieved image. This constraint retains the original aspect ratio.

  Copy

  
  
  
    Url.Kentico().ImageUrl(attachmentRelativeUrl, SizeConstraint.Height(200))
  
  
    

• Specify the maximum width of the retrieved image. This constraint retains the original aspect ratio.

  Copy

  
  
  
    Url.Kentico().ImageUrl(attachmentRelativeUrl, SizeConstraint.Width(200))
  
  
    

• Specify the maximum width and height that the retrieved image cannot exceed. This constraint retains the original aspect ratio.

  Copy

  
  
  
    Url.Kentico().ImageUrl(attachmentRelativeUrl, SizeConstraint.MaxWidthOrHeight(400))
  
  
    

• Specify the exact width and height of the retrieved image. This constraint does not retain the original aspect ratio. The resized image is never made larger than the original size.

  Copy

  
  
  
    Url.Kentico().ImageUrl(attachmentRelativeUrl, SizeConstraint.SizeConstraint.Size(400, 1200))
  
  
    

Prompting users for action when accessing attachments

You can use the Url.Kentico().FileUrl method to create links that prompt users to save an attachment file to their disk:

@using Kentico.Content.Web.Mvc

@{
var urlOptions = new FileUrlOptions() { AttachmentContentDisposition = true };
}

<img alt="Article @article.Fields.Title" src="@Url.Kentico().FileUrl(article.Fields.Teaser.GetPath(), urlOptions)">