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 tools > Add-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.
