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/basic2. Install dependencies
yarn install3. 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 watch4. 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:dev5. Upload a production build to a different Confluence environment
Specify a PROD environment in your ~/.vpconfig.json first.
VPRT_ENV=PROD yarn upload:prodThe 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-uploadernpm i @k15t/viewport-uploader
To learn more about the configuration and usage of viewport-uploader please visit the API Documentation on Github.