T203 Advanced Implementer: CDN/PXL

• A Content Delivery Network (CDN) is a system of distributed servers that deliver media, based on the geographic location of the user, the origin of the webpage and the content delivery server.
• PXL allows for dynamic manipulation of images through filters to change the size, file format and look of images as they are served to a site visitor. These images are automatically served through the Terminalfour CDN.
• More detail can be found at: https://docs.terminalfour.com/documentation/developerresources/cdn-pxl/cdnpxl-overview/ 

Before we start

Be sure you have the following added to your training site:

- Your Terminalfour instance must be hosted with AWS to use CDN/PXL
- You need a Channel to preview and publish your content
- You need a Content Type to add images using a Media element and an HTML element

Enable CDN/PXL

Having a list of keywords gives you full control of the keyword options available to your content editors when they are categorizing their news items.

1. To enable CDN/PXL go to: Administration > Settings > CDN/PXL

General Settings

2. Enable CDN & PXL: enables the use of CDN and PXL features system wide.
3. Client organization identifier: this is set by your Terminalfour Client Services team.
4. Environment identifier: this is set by your Terminalfour Client Services team.
5. CDN/PXL base URL: this is set by your Terminalfour Client Services team.
6. Click Save changes to save the general settings.

Channel configuration

• An additional configuration option has been added to the Channel settings for CDN/PXL. This setting is named CDN/PXL S3 folder name and is located under Publish Options.
• This is the directory where CDN/PXL Media Items will be published for that Channel. The value of this setting must be unique on your system and cannot match any other Channel's or Microsite's CDN/PXL S3 folder name value.

1. To add CDN/PXL to your channel go to: Administration > Set up Sites & Channels > Channels.
2. Locate your channel and edit it (actions > Edit).
3. Scroll down to Publish options.
4. CDN/PXL S3 folder name: enter a unique value e.g. my_channel-cdn-pxl.
5. Click Save changes.

Supported file types

Once processed each file is cached globally to ensure that your site visitors are served the right image quickly. While the CDN can cache and distribute any file type only image files can be used with PXL. The following file types have been verified and tested:

• XLSX application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
• DOCX application/vnd.openxmlformats-officedocument.wordprocessingml.document
• PDF application/pdf
• MP3 audio/mpeg
• ZIP application/zip
• CSS text/css
• JPG image/jpeg
• SVG image/svg+xml
• PNG image/png
• PPTX application/vnd.openxmlformats-officedocument.presentationml.presentation
• HTML text/html +TXT text/plain
• MP4 video/mp4

With PXL you can manipulate images on the fly by appending filter parameters to the image URL. PXL supports the following file extensions.

• .jpg/.jpeg
• .png
• .webp
• .tiff

How do I use CDN/PXL on my site?

• Once you have CDN/PXL enabled on your site you add either of the following attributes to a Handlebars expression or T4 Tag in a Content Layout, Media Layout or Media Element: 

Creating filters

• A Filter is a defined preset to make image manipulations on the fly, so you don’t have to create multiple copies of the same image. A single image can be output in multiple sizes, formats and have effects applied to it.

• In this example, we’ll create a Filter to create a grayscale version of the image. The original image, in the Media Library, will not be altered.

1. Go to Administration > Settings > CDN/PXL > + Create PXL filter
   1. Name: the name used to identify this filter.
   2. Description: used to give more information about what this filter does.
   3. Filter rules: determines what changes and filters are applied.

e.g. fit-in/800x600/filters:grayscale()/filters:format(webp)

This will create an instance of the image that:

1. 1. Is resized to 800px wide and 600px high
   2. Is grayscale
   3. Is output as WebP

A full list of filter rules is available at: https://docs.terminalfour.com/documentation/developer-resources/cdnpxl/#toc-filter-rules 

2. Click Save changes.

Using a PXL filter

• Now that we have a Filter created let’s apply it to an image from the Media Library by using a Content Type that includes a Media element.

1. Create a Content Type with one Media element and output the Image twice.
   1. The first without a PXL filter – this will be our control image.
   2. The second applying a PXL filter to the image.

2. Click into the Content layouts tab.
3. Select the "text/html" content layout and open the </> Content layout code tab.
4. Click on the </> Generate Handlebars Expression button.
5. In the Content tab:
   1. Information to output (select the Element radio button)
      1. Element: the Element option is used to output elements to the page.
      2. Metadata: the Metadata option allows output of specific Metadata (HTML anchor, Content ID, Last Modified Date, Publish Date, etc.).
      3. Fulltext: used to output a fulltext link.
   2. Content Element: select your image element from the drop-down.
   3. Handlebars helper: select the Media Helper to output your image.
   4. Media Output: Select the content layout you want to apply to the output of the image: e.g. "image/normal".
   5. CDN/PXL Options
      1. Serve the file from the CDN (This will switch to auto-selected once you select the "Apply a PXL Filter" radio button below).
      2. Apply a PXL Filter
   6. PXL Filter: select the filter you wish to apply from the drop-down.
   7. Options: leave the default options.
6. Click the Copy to clipboard button and paste the Handlebars expression into your content layout.
7. The Handlebars expression you generated should look similar to the code below:

{{{media id=(mediaId element="Image") layout="image/normal" pxl-filter-id="1"}}}

8. Save the changes to your layout and test the output by previewing your content.

CDN/PXL attributes in your Handlebars expressions

CDN/PXL attributes in your T4 tags

Responsive images and CDN/PXL

• Paying attention to image performance will speed up your site and ensure that you’re serving the best image format and size to your site visitor’s device.

Creating an image element that does this can end up looking like this:

<picture>
  <source srcset="/small.webp 650w, /med.webp 1000w, /large.webp 1600w" type="image/webp">
  <source srcset="/small.jpg 650w, /med.jpg 1000w, /large.jpg 1600w" type="image/jpeg">
  <img src="smal.jpg" alt="My great image">
</picture>This is not something you want to create each time. Using a Media Layout that uses CDN/PXL filters to create the images would ensure that you could create this once, roll it out across your site, and update as your image requirements change.

To use PXL in a Media Layout replace the file URLs with a Handlebars expression:

<picture>
  <source srcset="{{{file element="Media" pxl-filter-id="2"}}}" 650w,
...

Alternatively, if using T4 Tags:

<picture>
  <source srcset="<t4 type="content" name="Media" output="file" modifiers="" pxl-filter-id="2" /> 650w,
...

Then, when you want to use the Media Tag you can use a single Handlebars expression with your custom layout:
{{{media id="28" layout="image/pxl"}}}

Alternatively, if using a T4 Tag with your custom formatter:

<t4 type="media" id="28" formatter="image/pxl" />

Create a CDN/PXL media layout

1. To create a new CDN/PXL Media Layout go to: Assets > Content Types.
2. Using the filter box, find the Media content type: Actions > Edit Content layouts > +Add Content layout.
   1. Name: give the new layout a name, e.g., image/pxl-your-name.
   2. File extension: leave as default.
   3. Syntax type: HTML/XML.
   4. Content layout processor: Handlebars Content.
   5. Content layout code:

<picture>
  <source srcset="/small.webp 650w, /med.webp 1000w, /large.webp 1600w" type="image/webp">
  <source srcset="/small.jpg 650w, /med.jpg 1000w, /large.jpg 1600w" type="image/jpeg">
  <img src="smal.jpg" alt="My great image">
</picture>Update the sample layout above by replacing the example file URL’s with Handlebars expressions like so:

<picture>
  <source srcset="{{{file element="Media" pxl-filter-id="1"}}} 650w,
                  {{{file element="Media" pxl-filter-id="2"}}} 1000w,
                  {{{file element="Media" pxl-filter-id="3"}}} 1600w" type="image/webp">

  <source srcset="{{{file element="Media" pxl-filter-id="4"}}} 650w,
                  {{{file element="Media" pxl-filter-id="5"}}} 1000w,
                  {{{file element="Media" pxl-filter-id="6"}}} 1600w" type="image/jpeg">
  <img src="{{{file element="Media"}}}" alt="{{publish element="Description"}}">
</picture>

Alternatively, if using T4 tags:

<picture>
  <source srcset="<t4 type="content" name="Media" output="file"
                      cdn="true" pxl-filter-id="1" /> 650w,
                  <t4 type="content" name="Media" output="file"
                      cdn="true" pxl-filter-id="2" /> 1000w,
                  <t4 type="content" name="Media" output="file"
                      cdn="true" pxl-filter-id="3" /> 1600w" type="image/webp">

  <source srcset="<t4 type="content" name="Media" output="file"
                      cdn="true" pxl-filter-id="4" /> 650w,
                  <t4 type="content" name="Media" output="file"
                      cdn="true" pxl-filter-id="5" /> 1000w,
                  <t4 type="content" name="Media" output="file"
                      cdn="true" pxl-filter-id="6" /> 1600w" type="image/jpeg">
  <img src="<t4 type="content" name="Media" output="file" />"
                alt="<t4 type="content" name="Description" output="normal"
                modifiers="striptags,htmlentities" />">
</picture>

3. Click Save changes.

Assign your Media Layout to a Media Type

• Now that you have created a Media Layout you will need to assign it to a Media Type to test its output.
• A new Media Type can be created, or an existing one can be edited. The Media Layout can be added to the list of associated layouts and set as the default or additional Media Layout. 

1. To assign a Media Layout go to: Administration > Settings > Media Library > Media Types tab.
2. Using the filter box, find the Image media type:
   1. Click Actions > Edit > + Add row.
3. Select your Media Layout, e.g., image/pxl-your-name/. 
4. Click Save changes.

Use your Media Layout

• Add an image to your content using the HTML element and preview your content to test the filters in your Media Layout.

1. Create or edit a piece of content.
2. Find an image in the Media Library.
3. Click Actions > Select with layout.
4. Use your Media Layout e.g., image/pxl-your-name.

5. Preview your content and observe the image with different browser widths.

Feedback survey

Congratulations on completing the CDN/PXL training course.

Please provide feedback in our on-line survey.