×

You're using an outdated browser

For a better experience, keep your browser up to date. Check here for the latest version.

Manual

Scroll Versions and a Custom Theme

Roman Serazhiev

Roman Serazhiev Last update: Oct 30, 2018

The Scroll Content Management theme integration functionality replaces or enhances existing Confluence themes, be it packaged themes, third-party commercial or even custom themes. This is achieved by leveraging CSS rules and JavaScript functions to hook into the theme that is used in a Scroll Versions or Translations enabled space.

Integrated UI components

The theme integration is used to replace the following items in a managed space:

  • Breadcrumbs are replaced to reflect different page titles in different versions and to show or hide unavailable pages
  • Page tree is replaced for the same reason as the breadcrumbs, to reflect the availability and Scroll page title of pages in different versions
  • Page title is used instead of the Confluence page title to display the Scroll page title

Moreover the theme integration injects the following new components into a page:

  • Scroll Content Management toolbar is used to switch versions, variants and languages in a space and to perform additional tasks in the context of a space
  • Byline describes version, variant, workflow and language information for the current page
  • Scroll Versions Dropdown gives access to many page-related Versions features
  • _SvNavigation is a separate Confluence page that is included into the sidebar by Scroll Versions
  • _SvContentHeader is a page that is included into the header
  • _SvContentFooter is a page that is included into the footer
  • Page key is injected into the page as an alternative access path (URL)

Supported Themes

Out-of-the-box we support the following themes:

If you use another theme in a space with enabled Scroll Content Management, a warning will be displayed that your theme is not supported. Moreover, the Scroll Content Management theme integration will try to use the configuration for the Confluence Default theme. You can customize the configuration for your theme to integrate it with Scroll Content Management apps and to make the warning go away. In fact, if your custom theme is based on the Confluence Default theme, chances are pretty good that the theme integration will work without further configuration.

General architecture

Info

Generally the integration of Scroll Versions functionality and both bundled and third-party themes is achieved on the client-side, i.e. it leverages CSS and JavaScript.

Scroll Versions and Translations theme integration is generally performed on the client side, whereas also more "classical" extension points of Confluence, e.g. web items, are used to hook into the existing UI.

In managed spaces a JSON context object is rendered into the page's HTML on the server side. This context object contains both page specific context information, space specific information for configuration and global information.

This context object is then used by several JavaScript modules, which are run via AJS.toInit methods, to integrate Scroll functionality, like the Scroll Content Management Toolbar, and to override existing Confluence functionality, like the page title or page tree. 

The theme integration parts of the UI are all performed on the client side.

We use AJS.$ to position and insert HTML elements into the page. Thus the main integration point for theme specific parts is a number of configuration properties, that contain CSS and / or JQuery selectors. Moreover you can specify names of globally defined JavaScript functions, that are invoked by Scroll theme integration to achieve client side templating, this could be plain JavaScript functions or Soy templates that are compiled into JavaScript functions on the server side.

Configuration properties

This is a general discussion of the configuration properties that can be specified for global default theme or per space.

This interface gives access to the jQuery selectors that are used to replace / insert theme elements like page title, by line, Scroll content management toolbar and alike. All properties of this interface are automatically available in the Scroll client context under the key Scroll.Versions.Context.space.theme. The selectors (i.e. methods ending in *Selector) should be valid CSS selectors. If they are just valid jQuery selectors, the theme integration will also work, but the UI might flicker slightly, because the generated CSS (see context.vm) will not work correctly.

Fields

Name Type Description

Methods

Name Type Description
clone() Object

getBreadcrumbsFilter() String

After a parent list element (ul or ol) has been selected via #getBreadcrumbsSelector this filter will be used to wipe out the present elements. Elements that match this filter will be removed. This is used to keep theme specific breadcrumbs (e.g. Dashboard, Pages, Categories ...)

getBreadcrumbsSelector() String

The Scroll breadcrumbs template will replace the li elements that are the children of this element. This filter should select a ul or ol element.

getBreadcrumbsTypeFilter() String

A space separated string which will be used to filter different types of breadcrumbs. Possible values are: page (will filter all page breadcrumbs), space (will filter space breadcrumb). Moreover you can prefix the type with one of the two contexts "page" and "editor" to filter the breadcrumb only in that context. E.g. "space editor:page" will filter the space breadcrumb always and the page breadcrumbs only in the editor but not on viewpage.action.

getContentManagementToolbarSelector() String

The Scroll Content Management toolbar template will be inserted before the selected element.

getCssRelevantSelectors(spaceConfig) List<List<String>>

Return a list of those CSS selectors that make sure that an integration element is not visible until we have modified it. The list of those selectors is used by com.k15t.scroll.platform.ui.page.context.ScrollPageContextRenderer

Parameter Type Description
spaceConfig SpaceConfig
getCustomCssSelectorsToHide() String

A comma separated list of CSS selectors that will be generated into a style element and hide the selected elements. The theme integration must then unhide them, when the data is integrated with the sv-ti-done CSS class.

getCustomJavaScript() String

Must point to a function in the global namespace, but can be nested in JS objects, e.g. Example.Nested.setup. The function will be called at the end of the theme override process and can do arbitrary stuff.

getPageKeySelector() String

The selector will be used to append the page key span to the selected element.

getPageTitleSelector() String

The Scroll page title template will replace the selected elements text.

getPageTreeChildrenContainerSelector() String

A JQuery selector that is used to find the elements in a node that represent the child pages.

getPageTreeChildrenTemplate() String

Must point to an accessible JS function, preferably a soy template, to render the children of a page, beginning from the container. The function will get the children and the id of the page to expand as parameter.

getPageTreeChildrenToggleClassesToToggle() String

These CSS classes will be toggled on collapse / expand on parent nodes in the page tree.

getPageTreeContainerSelector() String

Must point to an accessible JS function, preferably a soy template, to render the page tree container, which will be used to lazily call the page tree JS implementation.

getPageTreeContainerTemplate() String

This will be used to select the element, whose inner HTML will be replaced with Scroll page tree.

getPanelIndicator() String

the name of a parameter in conversionContext.getPageContext().getParams() that indicated that a panel / component of the theme is rendered. This is needed in the context of Scroll Translations (otherwise switching to a non-default language would always yield a placeholder that the content has not been translated yet.

getSelectedTheme() String

the identifier for the selected theme. For the supported themes these are defined in {@link SupportedThemes}

getSvBylineSelector() String

Selector where the Byline should be inserted.

getSvContentFooterSelector() String

For the format of the parameter see {@link #getSvNavigationSelector()}.

The content of the _SvFooterHeader page will be inserted at the given selector.

getSvContentHeaderSelector() String

For the format of the parameter see {@link #getSvNavigationSelector()}.

The content of the _SvContentHeader page will be inserted at the given selector.

getSvNavigationSelector() String

Set a JQuery insert method - (before|after|prepend|append|stop) (stop is actually not a JQuery insert method and will just stop the insertion, you can use this if you have a {@link #setCustomJavaScript(String)} set to manually do something to the selected elements) - and a JQuery selector to select a selection on which the insert method will be executed (see doc of insertAtSelector in sv-ti-page.js). Example "before: .someClass" will select the first element with CSS class someClass and call .before() on the selection.

The content of the _SvNavigation page will be inserted at the given selector.

isDerived() boolean

true if the theme config is derived from the global ScrollThemeConfig, false otherwise.

isThemeCompatible() boolean

this flag is used to determine if a theme is supported by Versions or has been customized in a way that it can use Versions properly. You can set this flag to true using advanced pluging properties, when you customized selectors to make the theme work.

Marking your theme as compatible

When your theme is based on the Confluence Default theme it is likely that you don't need to do anything and still the Scroll Content Management functionality works. Nevertheless you will get the warning that the theme is not compatible with Scroll Content Management, because the Scroll Content Management plugin does not know about the plugin key.

When your theme is used as the global default theme in Confluence you can configure the compatibility once for all spaces that use the global default theme. To do so you need to be Confluence administrator and go to Confluence Administration > General Configuration in the navigation bar and choose the Advanced Plugin Settings in the Scroll Runtime section.

You'll get a simple configuration UI that can be used to mark your theme as compatible. To do so choose Scroll Platform in the select list in the upper right hand corner and edit the property theme-integration.json inserting the following JSON string:

{"isThemeCompatible": true}

When your theme is used only in a limited number of spaces, you have to configure all spaces as being compatible. To do so you need to be a space administrator of that space. After logging in to Confluence go to the URL and you'll get the same simple configuration UI as for global default theme (see above).

$base_url$/plugins/servlet/scroll-settings/?key=$spaceKey$

Marking your theme compatible via REST

The setting that is stored as a JSON string above is managed by the "Advanced Plugin Settings" for Scroll Add-Ons and can also be set via a REST call. You need to POST a JSON message against the following URL

$base_url$/rest/scroll-runtime/latest/settings/$spaceKey$

The message needs to look like this

{
	"pluginKey": "com.k15t.scroll.scroll-platform",
 	"key": "theme-integration.json", 
 	"value": 
		"{\"isThemeCompatible\": true}"
}

So this is the JSON string from above wrapped in a generic JSON message format used for the "Advanced Plugin Settings" - pay attention to the correct escaping if you add more properties from Configuration properties.

To achieve this you can use a REST client of your choice, like Postman or DHC in Chrome or curl on the command line.

Below you can find an example invocation for curl to achieve the same effect that is achieved above via the UI:

curl --header "Content-Type: application/json" -X POST --user username:password --data '{"pluginKey": "com.k15t.scroll.scroll-platform","key": "theme-integration.json", "value":"{\"isThemeCompatible\": true}"}' $base_url$/rest/scroll-runtime/latest/settings/$spaceKey$

Confluence Default Theme configuration properties

  Click here to expand...

Fields

Name Type Description
breadcrumbsFilter String

"> li:has(a[href*=\"collector\"]) ~ li"

breadcrumbsSelector String

"#breadcrumbs"

breadcrumbsTypeFilter String

"space"

contentManagementToolbarSelector String

".theme-default #custom-content-header, .theme-default #main-header"

customCssSelectorsToHide String

".ia-secondary-container[data-tree-type=pages]"

customJavaScript String

"Scroll.Versions.ThemeIntegration.ConfluenceDefault.postProcess"

pageKeySelector String

"#title-text"

pageTitleSelector String

"#title-text a:first-of-type"

pageTreeChildrenContainerSelector String

".sv-pt-children.plugin_pagetree_children_list"

pageTreeChildrenTemplate String

"Scroll.Versions.Templates.ThemeIntegration.ConfluenceDefault.childrenDefaultTheme"

pageTreeChildrenToggleClassesToToggle String

"icon-section-opened icon-section-closed"

pageTreeContainerSelector String

".ia-secondary-container[data-tree-type=page-tree] .ia-secondary-content"

pageTreeContainerTemplate String

"Scroll.Versions.Templates.ThemeIntegration.ConfluenceDefault.defaultThemeIntegration"

svBylineSelector String

"append: .page-metadata"

svContentFooterSelector String

"append: #main"

svContentHeaderSelector String

"before: #main-header"

svNavigationSelector String

"after: .acs-nav-wrapper"

Methods

Name Type Description

Enterprise Theme configuration properties

  Click here to expand...

Fields

Name Type Description
breadcrumbsFilter String

"li:not(.first)"

breadcrumbsSelector String

".theme-documentation #breadcrumbs"

breadcrumbsTypeFilter String

"space"

contentManagementToolbarSelector String

".theme-documentation #main"

customCssSelectorsToHide String

"#children-section"

customJavaScript String

"Scroll.Versions.ThemeIntegration.ConfluenceDocumentation.postProcess"

pageKeySelector String

".theme-documentation #title-text"

pageTitleSelector String

".theme-documentation #title-text"

pageTreeChildrenContainerSelector String

".sv-pt-children.plugin_pagetree_children_list"

pageTreeChildrenTemplate String

"Scroll.Versions.Templates.ThemeIntegration.ConfluenceDefault.childrenDefaultTheme"

pageTreeChildrenToggleClassesToToggle String

"icon-section-opened icon-section-closed"

pageTreeContainerSelector String

".theme-documentation .plugin_pagetree > ul.plugin_pagetree_children_list"

pageTreeContainerTemplate String

"Scroll.Versions.Templates.ThemeIntegration.ConfluenceDocumentation.documentationThemeIntegration"

svBylineSelector String

"append: .page-metadata"

svContentFooterSelector String

"append: #main #content"

svContentHeaderSelector String

"before: #main"

svNavigationSelector String

"prepend: #splitter-sidebar"

Methods

Name Type Description

RefinedTheme configuration properties

  Click here to expand...

Fields

Name Type Description
breadcrumbsFilter String

"> li:has(a[href*=\"collector\"]) ~ li, li.rw_more_breadcrumbs, li.rw_more_breadcrumbs ~ li, > li:has(a[href*=\"collector\"])" + " ~ li"

breadcrumbsSelector String

".RefinedWikiTheme50 .rw_breadcrumbs_container ol:last-of-type, " + ".RefinedWikiTheme50 #breadcrumb-section #breadcrumbs, " + ".RefinedWikiTheme50 #rw_page_breadcrumbs, " + ".RefinedWikiTheme50 .contenteditor #breadcrumbs, " + ".RefinedWikiTheme50 #editor-precursor #breadcrumbs," + "body.rw_version_6 .rw_breadcrumbs_container ol:last-of-type," + "body.rw_version_6 #breadcrumb-section #breadcrumbs, " + "body.rw_version_6 #rw_page_breadcrumbs, " + "body.rw_version_6 .contenteditor #breadcrumbs, " + "body.rw_version_6 #editor-precursor #breadcrumbs"

breadcrumbsTypeFilter String

"editor:space"

contentManagementToolbarSelector String

"body:not(.rw_version_6):not(.rw_version_5) #rw_menu_bar_wrapper, body.rw_version_5 .rw_content, body.rw_version_6 .rw_content"

customJavaScript String

"Scroll.Versions.ThemeIntegration.RefinedWiki.postProcess"

pageKeySelector String

"body.rw_version_6 #rw_page_title, .RefinedWikiTheme50 #rw_page_title, #title-text"

pageTitleSelector String

"body.rw_version_6 #title-text, .RefinedWikiTheme50 #title-text"

pageTreeChildrenContainerSelector String

".sv-pt-children.rw_pagetree_list"

pageTreeChildrenTemplate String

"Scroll.Versions.ThemeIntegration.RefinedWiki.children"

pageTreeChildrenToggleClassesToToggle String

"rw_icon_minus rw_icon_plus"

pageTreeContainerSelector String

".RefinedWikiTheme50 .rw_page_tree_container, body.rw_version_6 .rw_page_tree_container"

pageTreeContainerTemplate String

"Scroll.Versions.Templates.ThemeIntegration.RefinedWiki.refinedWikiOriginalThemeIntegration"

panelIndicator String

"layoutBoard"

svBylineSelector String

"append: .page-metadata"

svContentFooterSelector String

"after: .comment-panels"

svContentHeaderSelector String

"prepend: body:not(.rw_version_5):not(.rw_version_6) #rw_page_right, body.rw_version_5 .rw_content," + "body.rw_version_6 .rw_content"

svNavigationSelector String

"prepend: #rw_left_column"

Methods

Name Type Description

2xlatest
We use cookies to create a secure and effective browsing experience for our website visitors and to understand how you use our site (i.e. Google Analytics). For more information: click here.
Ok