This is the documentation for an older version of Scroll Viewport. Here you can view the most up-to-date version of the Scroll Viewport documentation.

Getting Started Guide

This quickstart guide walks you trough the steps setting up your development tools, developing and testing Scroll Viewport themes.

Contents:

Audience

This documentation is intended to walk a web developer through the necessary steps to set up the development tools and develop Scroll Viewport themes. It is written for people, with basic knowledge of HTML, JavaScript and CSS.  

You should also be familiar with Confluence from the end user's point of view.

Preparing Confluence and Scroll Viewport

In order to use Scroll Viewport, you need a functional instance of Confluence up and running. After installing Scroll Viewport you will be a able to install, adapt and develop themes.

(info) Please note that for the following steps you need Confluence administration permissions, so if you don't have those permissions on an existing Confluence installation we suggest to set up a development system – it should not take that long.

Installing A Confluence Development System 

Info

You may install a stand-alone Confluence installation, but for development we suggest the setup of a Confluence Development system.

To install Confluence development system:

  1. Download the Atlassian SDK. (Windows, Mac)
  2. Install the Atlassian SDK as described in the Atlassian SDK Documentation:
    1. Install the Atlassian SDK on a Windows System.
    2. Install the Atlassian SDK on a Linux or Mac System.
  3. Verify you are running the version of Maven that comes with the SDK.
    To do this, review the output of the atlas-version command and make sure the mvn executable is called from the SDK.
  4. Run Confluence standalone:

    $ mkdir confluence-dev
    $ cd confluence-dev
    $ atlas-run-standalone --product confluence

    This will automatically download and start-up the latest version of Confluence. To stop Confluence hit Ctrl-C or close the terminal window.
    (info) When you do this the first time, this might take some time.

  5. Open http://localhost:1990/confluence in your browser and login with the credentials 'admin' (username) and 'admin' (password).

Installing and Setting up Scroll Viewport

To install Scroll Viewport on your Confluence development system:

  1. Follow the instructions about installing Scroll Viewport.

Creating a Viewport

  1. Choose the cog icon at top right of the screen, then choose Add-ons.

  2. Choose Viewports in the left hand panel.



  3. Click on Create Viewport.

  4. To create a theme from scratch click start from scratch. 



  5. Enter following information.
    1. The name of the new theme.
    2. Under the Content Tab
      • The Space Key, which binds the Confluences space with the theme.
      • Select the content types for this viewport:
        • Pages – the viewport will contain the pages
        • Blog Posts – the viewport will contain the blog posts
    3. Under the URL Tab
      • Enter the path prefix of this viewport, this path prefix is relative to the base URL of Confluence.
    4. Under the Permissions Tab
      • Select if you want to restrict access to Confluence UI.

  6. Click Save to save the viewport.
    • You can open the viewport on a new browser tab by clicking on Open in New Tab.

Configuring a Viewport

Next we configure a viewport for the sample space that uses our theme.

To configure a viewport:

  • From the Administrator Panel > Viewports. Under Actions select Configure or

  • In a Confluence page, with an already assigned Viewport. Click the Viewport shortcut  and select Configure

Editing a Theme

Only Velocity 1.6 code is supported

Scroll Viewport only supports Velocity 1.6 code in templates. Using Velocity 1.7 code can cause your templates to not work as expected.

To edit a theme open the Viewport Configuration View and click  under the theme icon.

On the Scroll Viewport Theme Editor, you can modify any non-plugin installed theme as you would in any text editor. However, there are some benefits in using the online editor e.g. placeholder autocompletion.

Info

If you want to edit themes that are installed as plugin, create a copy of the theme. After that, you have all options available. Themes installed via plugins can't be deleted in the Viewport Configuration View, this should be done via the Add-Ons View.

  1. Please note the placeholders:

    • The online editor will recommend any available placeholders.
    • Further information about all available placeholders please check out the Placeholders reference page.

Any theme must contain at least a page.vm, there are other templates. The following table explains other template types:

Template Location and Name

Description

Relevant Content Types

Example

/page.vm

Renders a page.

PAGE

Adding Page Templates

/blog.vm

Renders a blog post.

BLOG_POST

Adding Blog Templates 

/blogs.vm

Renders the blog post overview.

BLOG_POST

Adding 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

Adding 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.

Working with themes

Viewport Theme Editor

The easiest way to modify a theme is to use the Scroll Viewport Theme Editor as explained in section Editing a Theme.

In editor you can create and modify Velocity templates, CSS, JS and other files. To upload a file just click on load Select Files or (if your browser supports it) per drag-and-drop.

Remember to reference any CSS, JS files in your templates such as described int the Referencing JS/CSS and Image Files page.

Viewport Gulp plugin

With Scroll Viewport 2.3.1 and later you can use Viewport Gulp plugin 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.