×

You're using an outdated browser

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

Manual

Get started with theme development

Thomas Rough

Thomas Rough Last update: Apr 4, 2019

This guide demonstrates how to edit viewport themes using Scroll Viewport's inbuilt theme editor, and lists the different template types you can add to a theme.

Edit a theme

Navigate to the Viewport Configuration screen at Space toolsAdd-ons > Create Viewport, then for the template you want to edit, click ... > Edit.

Is the 'edit' option greyed out?

This happens when you try to edit a theme bundled with Scroll Viewport, or a theme that was installed as an add-on. It's not possible to edit these themes – just copy the theme and edit the new copy.

Now, you can edit the theme using Scroll Viewport's built-in theme editor:

Theme creation basics

In the editor you can create and modify Velocity templates, CSS, JS and other files. To upload a file, click Select files. Please note:

  • Remember to reference any CSS, JS files in your templates such as described in the Referencing JS/CSS and Image Files page.
  • Scroll Viewport only supports Velocity 1.6 code in templates. Using Velocity 1.7 code can cause your templates to not work as expected.

Themes must contain at least a page.vm, and you can also add other template types:

Template location and name

Description

Relevant content types

Example

/page.vm

Renders a page.

PAGE

Add page templates

/blog.vm

Renders a blog post.

BLOG_POST

Add blog templates 

/blogs.vm

Renders the blog post overview.

BLOG_POST

Add blog templates

/error.vm

Renders errors, such as 404 (Not found) or 403 (No Permission).

You define additional error templates handle specific errors. For example error404.vm will be used to render 404 errors.

both

Add error templates

/search.vm

Renders search results, that are accessed with <viewport-url>/search?q=<search-terms>

both

Search Template Recipe

For more information about templates, please check the Template reference.

Using the theme editor

Scroll Viewport's theme editor provides some features that help you editing themes.

Placeholders

The online editor will recommend any available placeholders

Code assistant

The editor provides code completion for properties in CSS files and for HTML tags and template placeholders in Velocity markup files (*.vm).

To open the code assistant, press Ctrl-Space. The code assistant is also opened automatically whenever you enter a dollar sign ($) in a vm file.

Download a theme as a file

You can use the editor to download a theme as a JAR file by clicking Actions > Download Theme.

You can then install the theme on other Confluence instances as an add-on.

Gulp Viewport plugin

You can use the Gulp Viewport plugin or the Viewport Developer tools to make theme creation a much faster process. This is useful, when developing a Scroll Viewport theme in a local IDE. In this case, a Gulp file can watch the resources, automatically upload the resources to Scroll Viewport, and even have BrowserSync to sync the browser.

REST API

Even though we provide a lot of information through the Placeholders API, it comes handy to know the Confluence REST API. There are several examples of usage in the Template recipes section of the Viewport guides. Like described in the "Like button" recipe.

Depending on the version of your Confluence installation, you can browse the latest API in the Confluence docs. Additionally, you can choose your version.

2x2.10
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