How to create and develop a Scroll Viewport theme

The fastest way to get started with Scroll Viewport theme development is to use viewport-uploader. The viewport-uploader package is a node module to upload local resources to the Scroll Viewport app inside Atlassian Confluence Data Center. For example, it can be used as part of a webpack build process to automate building and uploading a theme.

Please make sure you have a current Confluence Version (at least v7.11.2) installed and the necessary user permissions to edit page contents.

Setting up the local development environment

Create the file .vpconfig.json in your home directory and add your target environments similar to the example below.

Note: The identifier (in the below case "DEV") must equal the environment name in the envName property.

// ~/.vpconfig.json
 
{
  "DEV": {
    "envName": "DEV",
    "confluenceBaseUrl": "http://localhost:8090/confluence",
    "username": "admin",
    "password": "admin",
    "spaceKey": ""
  },
  "PROD": {
    "envName": "PROD",
    "confluenceBaseUrl": "https://example.com/confluence",
    "username": "admin",
    "password": "admin",
    "spaceKey": "prodspace"
  }
}

Properties	Types	Description
`envName`	String	Name of target environment. This should also be the name of the identifier.
`confluenceBaseUrl`	String	URL of Confluence Data Center. It may not contain a trailing slash.
`username`	String	Username for Confluence Data Center
`password`	String	Password for Confluence Data Center
`spaceKey`	String	Space key (empty for global). It may contain up to 225 alphanumeric characters. Scroll Viewport treats space keys case-sensitive even though for Confluence they are case-insensitive. If you provide the wrong case, the upload will fail without a helpful error message. In order to upload a global theme you need to be a Confluence admin, otherwise you will get a permission error.

Getting started with Scroll Viewport theme development

This example contains a basic theme setup, including a page.vm for the templating, styles and scripts to edit functionality and appearance of your theme and a webpack configuration to bundle and upload the code.

1. Clone this repository and change to this directory `examples/basic`:

git clone git@github.com:K15t/viewport-uploader.git

cd example/basic

2. Install dependencies

yarn install

3. Start development

Start development mode with automatic rebuilds. Once the webpack build has finished, the theme will be uploaded to the specified Confluence environment.

VPRT_ENV=DEV yarn watch

4. Upload a development build of your theme

Build and upload a development build (e.g contains source maps) to your Confluence instance.

VPRT_ENV=DEV yarn upload:dev

5. Upload a production build to a different Confluence environment

Specify a PROD environment in your ~/.vpconfig.json first.

VPRT_ENV=PROD yarn upload:prod

The configuration for the upload can be found in the webpack.config.js. For further information on how the upload works see the Viewport Uploader API Documentation.

Advanced Usage

We recommend that only users with advanced webpack knowledge should make changes to the webpack configuration.

If you would like to create your own webpack configuration or use a different bundler in your CI, use the viewport-uploader package by installing it via yarn or NPM.

yarn add @k15t/viewport-uploader

npm i @k15t/viewport-uploader

To learn more about the configuration and usage of viewport-uploader please visit the API Documentation on Github.