Orchard Core MediaField Leverage the MediaField in Orchard Core Themes and Websites.

Orchard Core MediaField

The MediaField is one of a number of Content Fields in Orchard Core. It attaches to Content Types and Content Parts and is used to select one or more assets from the Media Library. MediaField has recently gained a couple of new features that are currently only available in the preview release of Orchard Core: MediaTexts and Anchors. Of the two, I am really interested in its new MediaTexts feature, because it’s a simple way to populate the alt text attribute for HTML img tags. In this Orchard Core tutorial I will describe these two features in case you are unaware of them.

MediaField Settings in Orchard Core

The MediaField has always had a couple of settings we can configure on a field-by-field basis: Required and Multiple. These two MediaField settings are pretty self-explanatory. Required allows us to specify that a media asset must be chosen from the media library, and Multiple allows us to specify if multiple media assets can be selected from the media library.

In addition to Required and Multiple, two other settings are now available in Orchard Core: Allow media text and Allow anchors. Allow media text allows us to specify text associated with each selected media asset, and Allow anchors allows us to select an anchor point for each asset and can be used when resizing an image.

You can see these MediaField settings below in a “Photo” field I added to the BlogPost Content Type in The Blog Theme that ships with Orchard Core.

Orchard Core MediaField - Freelance Developer

As we will see in a moment, checking and unchecking the allow media text and allow anchors settings for the MediaField will impact the availability of the these tools when managing media assets using the field.

Selecting Media with MediaField in Orchard Core

We’ve added this new “Photo” MediaField to each Blog Post in The Blog Theme that ships with Orchard Core. Per our MediaField Settings, it’s a required field and we can only select one. Since we also allow media text and anchors, the MediaField editor will show these tools in the editor.

Media Text and Anchors - Orchard Core MediaField

When we select a photo and click on the media text tool, we are greeted with a modal dialog that allows us to enter the media text for that asset. We will use this text to populate the alt text attribute of the HTML img tag for this photo.

Enter MediaText in Orchard Core Media Field

Similar to media text, when we click the anchor tool we are greeted with a similar modal dialog that allows us to choose a point on the photo where we wish to set the anchor when resizing the photo. By default, it sets the anchor in the center of the photo, which is fine for this photo.

Select and Anchor in Orchard Core Media Field

Displaying the MediaField using Liquid in Orchard Core

Now that we’ve created the new MediaField and added a photo to a Blog Post in our Orchard Core Blog, we need to display the photo in the blog post. We can use the Liquid Template Language or Razor. Since The Blog Theme in Orchard Core uses Liquid, let’s use the Liquid Template Language.

At a minimum we want to display the photo using an img tag with the media text value populating the alt text attribute. For illustration purposes, let’s also use the anchor as we resize the photo to 400px by 400px.

First, let’s take a peek at the MediaField and see it’s properties.

{{ Model.ContentItem.Content.BlogPost.Photo }}
{
    "Paths": [
        "photo.jpg"
    ],
    "MediaTexts": [
        "Cool Photo"
    ],
    "Anchors": [
        {
            "X": 0.5,
            "Y": 0.5
        }
    ]
}

We have access to three properties on the MediaField:

  • An array of Paths,
  • An array of MediaTexts, and
  • An array of Anchors.

The values for our first and only photo will be in the first position of each array. We can make quick use of these values to create an img tag to display this photo in our blog post using the Liquid Template Language. As I do in all my Orchard Core presentations and training, I have intentionally been a bit more verbose in the code so one can become more familiar with Liquid and how to access the values of the MediaField.

{% assign path = Model.ContentItem.Content.BlogPost.Photo.Paths.first %}
{% assign text = Model.ContentItem.Content.BlogPost.Photo.MediaTexts.first %}
{% assign anchor = Model.ContentItem.Content.BlogPost.Photo.Anchors.first %}

{{ path | asset_url | resize_url: width:400, height:400, mode:'crop', anchor:anchor | img_tag: alt: text }}

The neat thing about Orchard Core is that there are many ways to display the photo using the MediaField and Liquid. This is just one way, but based on our needs we may want to choose a different set of Liquid filters and even use Media Profiles. We may also want to resize the photo using a mode other than “crop,” which is what we used here. And, let’s not forget that we can experiment with different anchor positions when resizing depending on the needs of the photo.

Conclusion

Let's take a moment to reflect on what was presented in this tutorial on the MediaField in Orchard Core. First, the MediaField is used to select one or more media assets from the Media Library. Like all Content Fields in Orchard Core, there are settings that can be configured on a field-by-field basis. The MediaField has a few popular settings that are often configured by Orchard Core developers to alter the field's behavior: Required, Multiple, Allow media text, and Allow anchors. The allow media text and allow anchors settings are currently only available in the preview release of Orchard Core. The allow media text and allow anchors settings are particularly useful for setting the alt text attribute on HTML img tags and when resizing images, respectively.

In this tutorial we configured the MediaField settings for a "Photo" MediaField that was attached to the BlogPost Content Type in The Blog Theme that ships with Orchard Core. We configured the field to allow media text and anchors and populated those settings appropriately. We then used the Liquid Template Language support in Orchard Core to modify the Liquid template for the Blog Post to resize and display the photo.

In future Orchard Core tutorials we can explore Media profiles and other ways of using Liquid filters to display assets in the media library. These features are not only useful for displaying individual photos, but also for displaying photo galleries and portfolios on Orchard Core websites.