Integrate with Scroll Versions or Scroll Translations

You can integrate Scroll Versions with Scroll Viewport to display multiple versions and variants in your Viewport.. This is useful, for example, if you want to have multiple versions of your documentation available for your readers in the same space.

This guide describes how to integrate Scroll Versions and Scroll Viewport to create a setup where versions are not published – rather, their visibility is controlled through the viewport and once the are ready, they are unhidden.

Activate the Scroll Versions or Scroll Translations integration

To enable Scroll Versions integration, navigate to Space tools > Add-ons > Viewport configuration > Content, and check the Versions box. If you want to display multiple variants in your Viewport, check the Variants box. If Variants is checked, all variants are displayed – if Versions is checked, you can control which versions are visible to page visitors, and which are not visible.

If you display versions directly like this, you do not need to publish any more to make your content available – all changes you make in versions visible in the dropdown are are directly displayed.

A good way of letting page visitors switch between versions is to integrate a version picker into your Viewport (a version picker is already built into the Scroll WebHelp theme bundled with Scroll Viewport, but if you build your own theme from scratch, you'll need to build it in manually).

Hide and show certain versions

Per default no version is displayed for normal readers in the Viewport. To make a specific version available in the Viewport, navigate to Space tools > Scroll Versions > Versions and for the version you want to show, click Actions > Show in Scroll Viewport.

You can hide the version again by following the same process, but selecting Hide in Scroll Viewport instead.

Please note that you might want to work with Scroll Versions roles to have more control on who has access to hidden versions in Scroll Viewport. If you have not assigned a user or group to the Reviewers role, all users with view permissions in the space can browse all versions (even if they are hidden in Scroll Viewport).

To display them in your Viewport, you can use the following velocity code:

XML

#if($versions)
	<label for="version">Version</label>
	<select id="version">
		#foreach($version in $versions.available)
			<option value="$version.value"
					#if($version.name == $versions.current.name) selected #end>
					$version.name #if($version.value == 'latest' && $version.original)($version.original.name)#end
			</option>
		#end
	</select>
#end

Hide and show certain variants

There is no option to hide specific variants from the dropdown. You can track the feature request for that here: VPRT-1024.

However, in velocity code, when looping over variants to display, you can selectively decide which to hide.

XML

<select>
	## Hides variants back-end, front-end and dev-ops. This is an example, change this list to your liking. 
	## If you make it empty ([]) all variants are shown
	#set($hiddenVariants = ["back-end", "front-end", "dev-ops"])
	#foreach($variant in $variants.available)
		#if ($hiddenVariants.indexOf($variant.name) == -1)
			<option value="$variant.value" #if($variant.name == $variants.current.name)
				selected="selected" #end>$variant.name</option>
		#end
	#end
</select>

URL naming

Once you have enabled the integration, the versions of the pages are reflected in their URLs.

Scroll Versions also uses the concept of a 'latest' version in URL names. This means that all pages belonging to a space's latest version contain a certain constant value (normally something like 'latest'), meaning that you can create links that are always up-to-date even after creating new versions of your docs.

Before integration	http://some.server.com/docs/my-page
Page in version 2	http://some.server.com/docs/2/my-page
Page in latest version	http://some.server.com/docs/latest/my-page

Page Keys

To use this feature in Viewport, you need Scroll Versions 3.8.0 or higher.

You are also able to use the Scroll Versions Page Key functionality in Scroll Viewport. Page Keys can be used to provide context-sensitive help directly from your software's UI.

You can find further information how to define Page Keys in the Scroll Versions documentation.

Calling Page with Page Key

To call the page key feature in Viewport you can do this within this URL pattern:

XML

<viewport-base-url>/<version>.../?contentKey=<pageKey>

If the page content is moved to another page, or the page is renamed, you are still able to reach this site within the Page Key URL.