Channels help you deliver content in a variety of forms and formats. As a demonstration case, channels serve the same content to desktop browsers and smartphones in different formats. The channel functionality, in conjunction with the Device Detection module and Standard Templating Kit, transform desktop Web content into content suitable for a smartphone. This use case is fully covered in the Mobile article. You can configure channels for any delivery type.
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: device, medium or 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.
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
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.
Channels are configured in
/server/rendering/channelManagement/channels. You can configure as many channels as you like. Each channel requires its own channel resolver. The STK provides the example
The channel configuration makes the channel available to editors for content targeting. The relevant classes that take care of this are:
Defines a manager for channel configurations.
Keeps the configuration for a channel and
Map to host channel configurations.
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:
deviceto detect mobile devices and serve specific content variations to different devices. Here the possible variations are
formatto reformat content and deliver it in a specific format. Variations here could be
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.
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.
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.
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.
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.
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.
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 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
others channel attributes.
Configure the variation
A variation is typically configured in the default site definition, under the prototype. In this way it applies to all sites. However, 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.
/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.
/us/templates/availabilitynode to make different templates available for the
- 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.
only screen and (min-device-with: 481px)
For demonstration purposes, we simply copied the default
styles.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 STK > Resources.
This is the look and feel USA visitors see. All all other visitors are served the
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 STK > Dialog Definitions:
- Copy the
/generic/pages/tabChannelsnode and place the copy under
- Delete one of the
/optionssub nodes and change the node names and property values of the remaining two as shown below. Note that the names of both the
/optionssub content nodes their
valueproperties match the channel attributes returned by
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. 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.
promos area served to USA visitors.
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.
Getting a channel name in a template script
You can get the channel name in Freemarker with