Channels

Channels are a core feature that facilitate the delivery of content in a variety of forms and formats.

As a demonstration case, channels are used to serve the same content to desktop browsers and smartphones in different forms. The channel functionality, in conjuction with the Device Detection module and Standard Templating Kit, accomplishes this. Standard web content targeted to desktop browsers is transformed into content suitable for a smartphone. This use case is fully covered in
the Mobile article.

You can configure channels for any conceivable delivery type, making your website ready for whatever future technology may bring.

Types of channels
Channel mechanism
Caching
Implementing a custom channel

Types of channels

A channel allows you to deliver the same content in a different format or deliver content that is exclusive to a particular type of visitor. A common example is delivering streamlined content for smartphones.

Channels can be configured for any type of output. A channel can be a device, a medium or a location. Here are some examples.

Device: You can create a channel targeted at Web-enabled TVs or set top boxes.
Medium: Your Web content might work well in print. It may also lend itself to viewing on ebook readers. Create a channel that renders the pages in ePub or iBook format. Use a magazine-like layout with rich imagery and support for swiping actions.
Location: Riding the tails of the smartphone explosion, location-based services have become popular. Location is another dimension for which you can create channels. Here are some ideas:
- Travel agency: Detect the visitor's current location and show where they can fly to for $300.
- Retail chain store: Based on visitor's country of origin, deliver country-specific campaign content.
- Coupons: Render redeemable coupons for services in the visitor's city.
- Micro-level: Display an offer to mobile users who walk by a store front on the street.

Channel mechanism

Multichannel filter

MultiChannelFilter resides in the Magnolia filter chain. Its purpose is to resolve the site to use by considering variations of the set channel. It executes each channel resolver in the channel configuration from top to bottom.The resulting site is set in the AggregationState .

In the mobile example, the DeviceDetectionFilter precedes the Multichannel filter in the chain. When a mobile device requests a page and identifies itself in the User-Agent header, the DeviceDetectionFilter reads the user agent string and passes it to the Device Detection module. The module queries a Mobile ESP database for the device's capabilities and stores them in a DeviceInfo object. The MultiChannelFilter then resolves the channel to use based on the device info and sets the channel name in the aggregation state.

Channel configuration

Channels are configured in Templating Kit > Channels. You can configure as many channels as you like. Each channel requires its own channel resolver. The STK provides the example DeviceChannelResolver.

Templating Kit > Channels is a shortcut to Configuration /server/rendering/channelManagement/channels.

The channel configuration makes the channel available to editors for content targeting. The relevant classes that take care of this are:

Class	Description
ChannelManager	Defines a manager for channel configurations.
ChannelConfiguration	Keeps the configuration for a channel and `gets` and `sets` the `resolver`.
ChannelManagerImpl	Map to host channel configurations.
ChannelResolver	Defines a type that resolves the channel to be used. Falls back to "all" if it cannot resolve a particular channel.

Channel resolving order

Multiple channels are considered an ordered map. Channel resolving starts from of the top of the list and proceeds towards the bottom in the node order. The first match wins.

For example, suppose that you have two channels in the following order:

device to detect mobile devices and serve specific content variations to different devices. Here the possible variations are smartphone, tablet and desktop.
format to reformat content and deliver it in a specific format. Variations here could be pdf, kindle, ipub etc.

If a visitor requests the site using a smartphone the conditions of the first resolver are met and the channels is resolved. Resolving does not continue to the next channel resolver in the map. If the conditions of the first channel are not met resolving continues to the second resolver, and so on. For this reason, second and further channel resolvers need to be triggered by a mechanism that is independent of the mechanism used to trigger the first resolver.

You can configure a single channel to serve multiple purposes. For example if you would like to serve both device and location based content, configure a single channel with a dual-purpose resolver.

Variation resolving

ChannelVariationResolver reads the channel name from the aggregation state and finds a matching variation. Variations are similar to site definitions. They define the templates and the theme that should be used to render content on the channel. They are typically smaller in scale and only define exceptions to the site definition. See the example smartphone variation and Configure the variation below for more information.

Site merging

SiteMergeFilter further down in the filter chain merges the current renderable site definition with the variation definition. In the merge, any templates and themes configured in the variation override those in the site definition. The result is a concrete site definition that optimizes content for the channel.

Targeting specific content

While a variation typically modifies the default site definition, the content targeting mechanism allows you to exclude specific pages and components from rendering. Content can be marked for exclusion from a particular channel variation. The ChannelVisibilityContentDecorator Java class provides this mechanism.

The STK includes a generic Output Channels tab that is available by default in all page properties dialogs. The tab reads the available variations attribute from site.channels. It stores the selected variation in the multivalue excludeChannels property under the content node. If no such property is found at the time of rendering, the content is available in all channel variations.

To exclude a page from rendering, check the appropriate box. You can select more that one.

You can also add the Output Channels tab to individual component dialogs. This allows you to mark content to a channel variation at component level. It opens many possibilities, for example delivering a different stage component to smartphone users, while the rest of the page is common to all visitors.

The generic tab definition is in Templating Kit > Dialog Definitions /generic/pages/tabChannels. Reference it from your component dialogs.

Content delivery

Magnolia uses a virtual workspace to deliver content to channels. The virtual workspace is named magnolia. It is registered on system startup. URLs of type /website/ map to the physical website workspace. This is the default case when no channels are configured and all users are served the same content. URLs of type / map to the virtual magnolia workspace. The virtual workspace uses the channel property in the aggregation state to exclude or include content. ChannelVisibilityContentDecorator filters out any content nodes that should not be served to the channel variation. The filtering is done based on the content targeting that editors have done.

Rendering filter

RenderingFilter renders the merged content. It is the last filter in the filter chain and is responsible for rendering the current aggregation state, by delegating to the appropriate TemplateRenderer or serving binary content.

Caching

The channel name is part of the cache key. This means that caching is channel-aware and allows you to implement channel specific cache policies. For example, you may want exclude a channel from caching if its content includes a component that queries an external data source dynamically. The rendered HTML can change even if the content of the Magnolia page has not changed.

Implementing a custom channel

The best way to implement a custom channel depends on your objective and the channels that are already in place in your installation.

Here we provide only very basic guidelines on how to implement a geolocation channel. It is not a complete solution and is provided to demonstrate the channel functionality and not as a best practice solution. There are many ways to use geolocation in Magnolia.

Watch a video about implementing a custom channel.

Configure the channel

Configure the new channel in Templating Kit > Channels to register the resolver.

Code the channel resolver

Here's the code for the NotUSAChannelResolver Java class used in the video. It queries the free, external hostip.info geolocation database and returns the us and others channel attributes.

import java io IOException;

public class NotUSAChannelResolver implements ChannelResolver {

   @Override
   public String resolveChannel(HttpServletRequest req) {
       String uri - req getRequestURI();
       if(!uri,contains(".magnolia")&amp;&amp; uri endsWith(".html")) {
           HttpClient client - new HttpClient();
           HttpMethod method - new GetMethod("http://api.hostip.info/coutry.php");
           int statusCode - -1;
           try {
               statusCode - client executeMethod(method);
               if (statusCode !- HttpStatus _$(_OK)_ {
                   return ChannelResolver _UNRESOLVED_;
               } else {
                   String country - method getResponseBodyAsString() tolowerCase();
                   return country equalsIgnoreCase("us') ? country : "others";
               } 
           } catch (HttpException c) {
               return ChannelResolver _UNRESOLVED_;
           } catch (IOException c) {
               return ChannelResolver _UNRESOLVED_;
           }
        }
        return ChannelResolver _UNRESOLVED_;
        }
}

Configure the variation

A variation is typically configured in the prototype in Templating Kit > Site Definitions /default/variations. In this way it applies to all sites, but you can also configure a /variations node for individual sites and templates.

Our variation node is named us to match the channel attribute returned by the NotUSAChannelResolver. In the /variations/us/theme/name node we link to a new theme pop-USA. USA visitors will see an identical site to other users except for the look and feel.

The /variations node modifies the default site. You can configure any other modifications you like, for example:

/us/templates/prototype/areas/<area name> nodes to modify page area behavior. See the Smartphone variation for how this is used for mobile devices.
A /us/templates/availability node to make different templates available for the us variation.
Other matching /variations/<channel attribute> nodes if your resolver returns a number of options.

You can also configure a /variations node in individual templates in Template Definitions /pages. See Smartphone variation > Stage to see how the stage component is disabled for smartphones.

Next we register the new theme in Templating Kit > Themes /pop-USA. To keep things simple, our theme extends the default pop theme, but uses a different styles.css file. Magnolia will automatically use all the elements of the pop theme except the new CSS sheet.

For demonstration purposes, we simply copied the default sytles.css file and made the following minor tweaks:

Referenced new branding images in the CSS sheet and made color changes.
Uploaded USA-specific image files in Resources.

This is the look and feel USA visitors see. All all other visitors are served the pop theme.

For more information about themes see:

Target specific content

The content targeting mechanism allows you to exclude specific pages and components.

We use this mechanism to selectively exclude stkPromo components from the us and default variations. You can adapt this example for any component in any area.

In Templating Kit > Dialog Definitions:

Copy the /generic/pages/tabChannels node and place the copy under /components/promos/stkPromo.
Delete one of the /options sub nodes and change the node names and property values of the remaining two as shown below. Note that the names of both the /options sub content nodes their value properties match the channel attributes returned by NotUSAChannelResolver.

The stkPromo dialog now has an Output Channels tab and editors can selectively exclude promos from the default and us channel variations.

You can view the excludeChannels property in Tools > JCR Browser (Website). Here's the /promos node for the demo-project home page. We excluded the first three components from the us variation and added three new USA-specific promos that we excluded from the default variation by checking Others in the dialog.

Here's the promos area served to USA visitors.