[DOCU-2457] Explain what the 'variations' property does Created: 14/Jun/21  Updated: 10/Oct/23  Resolved: 14/Jun/22

Status: Closed
Project: Documentation
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Neutral
Reporter: Tobias Szczepanski Assignee: Ashraf Khamis
Resolution: Done Votes: 0
Labels: external
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
relation
is related to MGNLSITE-84 ReferencingPrototypeTemplateSettings ... Closed
is related to DOCU-1571 Write new Multi-channel Feature overview Open
Documentation page URL: https://docs.magnolia-cms.com/product-docs/Templating/Template-definition.html#_common_template_properties
Reporter Name: Tobias Szczepanski
Email: tobias.szczepanski@gmail.com

 Description   

Hi there,

I just stumbled uppon this template definition property:

variations optional
Merges template definition with the variation having the same name of the channel - if available.

Technically it resides in info.magnolia.rendering.template.RenderableDefinition, but again the Java code is not documented at all.

"Merges template definition with the variation having the same name of the channel - if available."

  • the variation: What is "the variation"? If it's set to a valid templateDefintion, is the current file also valid?
    • // Is this a valid templateDefinition?
      variations:
        validTemplateDefinition: /module-name/path/to/template-definition
  • the same name: what name is supposed to be the same?
    • Does the variation's .yaml-file have to be named exactly as the referenced one?
  • the channel: what channel? Is this property only related to personalization variations?
  • if available: how can I check, if the channel is available? What happens, if it's not available?

It would be really helpful to understand the intent behind these variations, maybe with a use-case example. Is it an alternative to the !include mechanism in yamls?

Best
Tobias



 Comments   
Comment by Richard Gange [ 14/Jun/21 ]

Hello Tobias-

Basically variations is similar to personalization. We used to have an example in the old demo. In that showcase there were different variations for viewport size. The different viewports resolves to 3 different channels: desktop, smartphone, tablet. In your template definition you could define a variation, for say smartphone, that would use a different script if a smartphone was detected. Same data, different script. This is just one example.

I think the reason it stays in the documentation is for legacy reasons. Now you could use the personalization feature to do a lot of the same things.

the variation: What is "the variation"? If it's set to a valid templateDefintion, is the current file also valid?

That's right it's like a sub-definition of the template definition. You can literally change any configuration of the template based on the detected variation.

the same name: what name is supposed to be the same?

It could be anything. You the developer decided the names. Then you create a way (typically a filter) which detects the channel. For example a device detection filer. When detected you set the field in the agg state.

the channel: what channel? Is this property only related to personalization variations?

There are distinct systems. Neither depends on the other. They do similar types of things though.

if available: how can I check, if the channel is available? What happens, if it's not available?

Is the channel set in the agg state. That's how you would do it. Basically, was a channel detected, if yes then merge the definition with the defined variation (if a variation exists). It's kind of like how the template prototype merges with the concrete template. Same concept.

HTH
Rich

Comment by Tobias Szczepanski [ 17/Mar/22 ]

Hi Rich,

great, thanks a bunch for the info!

This is actually quite the valid use case, because technically personalization is only meant for template variants based on visitor/user preferences. Though one might need template variants based on system parameters, independent of the visitor/user.

If I understand it right, we can achieve visitor independent Page & Component variants through
Component Inheritance + Template Variations + some custom UI implementations.

As this is quite useful, I hope this feature will not be deprecated, will it?

Best
Tob

Comment by Richard Gange [ 17/Mar/22 ]

Hello Tobias-

As far as I know there is no plan to deprecate it.

HTH
Rich

Comment by Ashraf Khamis [ 14/Jun/22 ]

Hi Tobias,

Thanks for reporting the issue. I've updated the description for the variations property and added an example definition. Hope that helps.

Best,

Ashraf

Comment by Tobias Szczepanski [ 17/Jun/22 ]

Hi Ashraf, great, thank you!

Generated at Mon Feb 12 01:27:18 CET 2024 using Jira 9.4.2#940002-sha1:46d1a51de284217efdcb32434eab47a99af2938b.