Introduction to Composer Story Variants
Story variants are a way to manage multiple versions of a single story and display a different version of that story on each website where that story is circulated. You can customize designated sections of your story, called variant zones, that can appear differently to your end readers, depending on which website they are reading.
For example, say you're a large multi-site organization with reporting spanning the globe. Your team is managing dozens of regional websites, each with their own regional audience. You're producing coverage of the Super Bowl, with the Tampa Bay Buccaneers playing the Kansas City Chiefs. You manage websites in both the Tampa Bay and Kansas City markets, and you want to customize your coverage to better engage readers in both Tampa Bay and Kansas City. With story variants, you could feature quotes from Tampa Bay fans for the Tampa Bay website and Kansas City fans for the Kansas City website.
What is a variant zone?
Story variants are based on a type of content element called the variant zone. Variant zones are designated sections of your story where you are allowing authors to add customized content to that specific zone.
You can add up to 10 variant zones to your story. You can add variant zones to a story just like any other content element, such as images: either from the in-line toolbar or from the Content Elements right-hand menu.
Admin users with access to Composer settings can control whether variant zones are made available as a content element, and in settings, Admins can drag and drop variant zones into their desired display order among the content elements.
 |
How to create a story variant
After you place variant zones in the desired locations in your main story, navigate to the Variants tab within the Composer editor. Click Add variant to create a new variant. Watch the following video to learn more about using variant zones and creating story variants.
Editing content within a variant
 |
Each variant is comprised of the following elements:
Variant name
This is a free text entry field where you name your variant, whatever is meaningful to you.
Variant websites
This is where you choose which websites you want to circulate your variant to. You can apply the variant to as many websites as you want. This list of websites is limited by three factors, which control which websites are available:
You can select only from websites where the main story has already been circulated.
You can select only websites that another variant is not using.
You can select only websites where you have permission to circulate.
Variant tags
These tags are additive, meaning they will be added alongside the existing tags for your main story. For example, in the Tampa Bay variant, you may want to add the Tampa-specific story tags “Sunshine State” and “Cigar City.” The system then attaches those tags to the story variant only for the specific websites where you're circulating your variant.
Variant zones
Variant zones form the crux of the story variant. These are the designated spaces in the main story where you can add additional desired content, which will be displayed only for the end readers on the website(s) where your variant is circulated.
Within the variant editor, only the variant zones are editable. The hub story is displayed in a read-only state with simple placeholder objects for other content elements in the main story.
If your variant has multiple variant zones, you do not need to use all of them. Any variant zones left blank do not render for your end readers.
Variant zones support bold, italic, and underlined text, as well as hyperlinks. Numbered and unordered lists are not available at this time.
Media within variant zones
Variant zones allow you to insert in-line media within the variant zone sections of your story. You can add HTML blocks, images, videos, and galleries. Remember, the media elements you insert into the variant zones will only appear on the websites where you have circulated that story variant.
Variant featured media
As part of the variant editor, you can set your desired featured media per variant. The featured media tab will display all of the available featured media keys set by your organization, and the type of media elements you are able to add to each featured media key is controlled by Composer Settings. Featured media for variants will override the featured media set for the main story. Here are two examples of how this works:
Overriding an existing key:
Main story has featured media keys A and B set, let's call them A1 and B1.
Variant sets a different media element for key A, let's call it A2.
Now, on the websites where your variant is circulated, end readers will see media A2 and B1. The variant A2 media overrides the variant A1 media.
Adding a new key:
Main story has featured media keys A and B set, let's call them A1 and B1.
Variant sets a media element for key C, let's call it C1.
Now, on the websites where your variant is circulated, end readers will see media A1, B1, and C1. Since key C was not in use by the main story, the variant adds a new media element C1.
 |
Variant publication status
You can publish variants independently of the main story, but whether or not a variant is accessible to your end readers depends on whether the main story is published. The following table explains how variant publication status interacts with the main story.
Main story status | Variant status | What end readers on a variate story website see |
|---|---|---|
Draft | Draft | Nothing. Main story publication status dictates whether the story is shown to end readers. |
Draft | ✅ Published | Nothing. Main story publication status dictates whether the story is shown to end readers. |
Draft | Unpublished | Nothing. Main story publication status dictates whether the story is shown to end readers. |
✅ Published | Draft | Only the hub story |
✅ Published | ✅ Published | The variant overrides the main story on the websites where the variant is circulated. |
✅ Published | Unpublished | Only the hub story |
Unpublished | Draft | Nothing. Story is removed from all websites once the main story is unpublished. |
Unpublished | ✅ Published | Nothing. Story is removed from all websites once the main story is unpublished. |
Unpublished | Unpublished | Nothing. Story is removed from all websites once the main story is unpublished. |
How to manage story variants
As you create multiple variants, you can view them all in a list view on the Variants tab. The publication status of each variant appears in this list view. From here, you can edit or delete variants. These actions are permitted only if the specific user has Composer permissions to edit and delete stories.
If you delete a story variant, all the websites where that variant was circulated default to displaying just the main story without the content in the variant zones.
How does locking work?
Story variants are a powerful collaborative tool because you can edit a story variant independently of the main story without taking the lock on a main story. For example, User A has the lock on the main story, and User B wants to create or edit a variant for that story. User B can open the main story in Composer, see that User A has the lock, and navigate to the Variants tab to start creating or editing a variant.
When a variant exists for a story, users can enter straight into the variant editor from Composer search results, bypassing the need to open the main story.
 |
Only one user can edit each variant at a time, and the system enforces this rule by notifying the user when there are conflicting changes in their variant and sharing the username of the last user to edit the variant.
ANS schema
For the complete reference documentation of the ANS schema that supports story variants, see our GitHub documentation.
Note
While Elasticsearch allows for wildcards to be used in queries, the use of wildcards in include/exclude searches is not currently supported with the variants implementation. Including wildcards may result in inconsistent or unreliable results.