Quick start Tutorial: Set Up and Manage Variants

Welcome to getting started with Variants for Scroll Documents. Work through the steps below to set up variants for your documentation. In this tutorial, you will first set up two variants, then conditionalize articles, and finally conditionalize content inside an article.

Before You Start

Before you jump into the first practical steps of this tutorial, we recommend you go through the prerequisites and terms listed below.

Prerequisites

Make sure the following prerequisites are fulfilled before starting the tutorial:

• Scroll Documents and Variants for Scroll Documents are installed

• You have a test space you can use for this tutorial

  • There is already a document created in the space

• You have the space permissions:

  • View All

  • Add Pages

Important terms

Useful terms which are good to know in this tutorial:

Step 1: Create an Admin Variant and Conditionalize Articles

Imagine you have a guide for two types of readers:

• Users

• Admins

Most of the guide applies to both groups, but some details are only important for Admins.

So, you'll create two versions:

1. Admin-Only Content: Reserved for Admins

2. Shared Content: Applies to both Users and Admins

This way, Admins see everything, while Users only see what’s relevant to them.

First, let’s start with navigating to the Document Manager:

1. Click Scroll Documents from the Apps section in your space sidebar.

2. From the Document Library, click the document card of a document.

Or

1. From a page in a document, click Document toolbox.

2. Click on the cog icon.

When you are in the Document Manager, you can continue with creating the default variant:

1. Click Manage > select Variants

2. Click New Variant

a. Type in “Admin” as variant name.
b. Under “Rules:”

i. The first dropdown is preset to all.

ii. The second dropdown is preset to has label.

c. Type “admin” as label name in the “Add label” field > click Create admin.

d. Click on the cog icon > enable the toggle for “Edit page labels.”

e. Click Add label… on the top-level page of the page tree:

i. Type the label name “admin” > hold down Alt/Option on your keyboard and click on the check mark, this action will add the label “admin” to all pages in the page tree.

For a page to be part of a given variant, all of its ancestor pages need to be part of the variant, too. It’s required that at least the top-level page of the page tree is part of all variants.

3. Click Create to create the variant.

Step 2: Create a User Variant and Conditionalize Articles

Now, let’s create a second variant dedicated to “User” specific content. To do this, you’ll repeat almost the same process as before:

1. Click New Variant

a. Type in “User” as variant name.

b. Under “Rules”:

i. The first dropdown is preset to all.

ii. The second dropdown is preset to has label.

c. Type “user” as label name in the “Add label” field > click Create user.

d. Click on the cog icon > enable the toggle for “Edit page labels.”

e. Click Add label… on the top-level page of the page tree:

i. Type the label name “user” and click on the check mark , this action will add the label “user” to the top-level page.

ii. Continue to add the “user” label to a few more pages which you find relevant.

2. Click Create to create the User variant.

Since you created the Admins variant first, you should see this variant has been marked as DEFAULT VARIANT in the Variant manager. The default variant will be pre-selected for users when reading the Scroll Document in the Document Reader or a Viewport site, as well as when exporting to PDF, Word, or HTML.

If you want to change the default variant, click More actions (•••) next to the variant you want to mark as default > select Set as default.

Step 3: Conditionalize a Paragraph

Now you know how to conditionalize articles to specific variants. In this last section, you’ll learn how you can do the same with text within an article – by putting the content inside a conditional content macro.

You can also place images and tables inside conditional content macros, making the content conditional.

Let’s say an article is available in both the Admin and User variant, but some specific content only applies to the Admin variant. In this case, you can put the Admin specific content inside a conditional content macro and assign it to the Admin variant. As a result, if a reader opens the article with the User variant selected in the Document Reader or in Viewport, the content in the conditional content macro will be hidden.

In Confluence page view all conditional content macros will show on the page.

To conditionalize a paragraph in an article, follow the steps below:

1. Navigate to the top-level article in your page tree, this article should be mapped to both the Admin variant and the User variant.

2. Click Edit on the pen-shaped icon.

3. Click on Insert ➕ in the Confluence toolbar to open the macro browser:

a. Search for “Scroll Conditional Content” and click on it, this will open up the “Scroll Conditional Content” dialog:

i. Click on the labels dropdown and select admin.

ii. Click Insert to add the macro to the page.

4. Add some text in the macro which should only apply for the Admin variant.

5. Click Update.

Learnings 🏆

Congratulations! You have now completed the tutorial. Let’s summarize what you have learned:

• Create variants

• Conditionalize articles and paragraphs

Next Steps

As a next step we recommend proceeding with the following articles:

• If you want to learn more about creating variants see:

  • Define and Edit Variants

• For more information about how to start working with conditional content, read:

  • Define Conditional Content

• For more information about publishing variants, continue with:

  • Export and Publish Variants