×

You're using an outdated browser

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

Manual

Gulp Viewport and Developer tools

Steffen Burzlaff

Steffen Burzlaff Last update: Jul 18, 2018

The gulp-viewport plugin for Scroll Viewport uploads theme resources directly into Scroll Viewport.
This is useful when you want to develop a Scroll Viewport theme in your local IDE. In this case, Gulp can watch the resources, and automatically upload the build results into Scroll Viewport.

The Viewport Developer tools is a command-line tool, which makes it easier to get started with the gulp-viewport plugin. This tool allows you to setup a new theme in less than 5 commands.

Info

Please make sure you have Scroll Viewport 2.7.1 or later installed, as the Gulp plugin will not work with any version before that. If you are using an older version, please install version 1.2.0 of the plugin (See readme 1.2.0).

Quick Start 

The fastest way to get started with gulp-viewport is to use the Viewport Developer tools and start with a template project. The Viewport Developer tools contain command-line tools for Scroll Viewport theme developers.

Installing the Viewport Developer tools

Open your command-line tool and execute the following command:

$ npm install -g viewport-tools

The Viewport Developer tools should be installed globally, so that it is accessible from everywhere in your system. If this command isn't working, please try to run the command as an administrator.

Initialize local development

To make the gulp-viewport plugin work, you need a .viewportrc file. This file needs to be in the home folder of your OS.

In the command-line tool you can type the following command to create this file:

$ viewport init

If you want to create this file manually or make any modifications, the file should look like this:

[DEV]
confluenceBaseUrl=http://localhost:1990/confluence
username=admin
password=admin

Please note: "DEV" could be anything, just make sure to reference it correctly in your gulpfile.js.

Create a new Scroll Viewport theme

Creating a new Theme is simple and can be performed with the following command:

$ viewport create

Following this action, the Viewport Developer tools will then go through some settings with you:

  1. Theme Key: the unique key for your theme
  2. Theme Version: e.g. 1.0.0 (press enter if you don't need a version)
  3. Which theme template it should use in the beginning. At the moment there are two different templates available:

The plugin will then tell you what you have to do next, e.g. installing the dependencies, etc.

Uploading your first theme

Once everything is setup you can test your new environment by uploading your first theme. To do this, you first need to create the theme in your Confluence instance. You can do this manually, or within the gulpfile.js by typing the following command into your console:

gulp create

The gulpfile.js file will then create a new theme in Confluence. Once the theme is created, you can then execute the following command to upload all files into your Scroll Viewport theme:

gulp upload

Gulp will then create a 'build' directory in your project. All files which are in this directory will be uploaded to your Scroll Viewport Theme (if they are processed by one of the commands of gulp). You can check that all files were uploaded correctly by opening the theme-editor in Scroll Viewport.

Advanced Usage

If you are familiar with Javascript and Gulp you can also create your own gulpfile.js. To learn more about the gulp-viewport plugin or the Viewport Developer tools, feel free to visit the projects on GitHub or NPM.

Info

We recommend that only users with advanced knowledge of this process should make changes in this file

Available Commands 

The gulpfile.js provides you with everything you need to get started with your theme development. The following section will explain which commands are available.

Create

The command gulp create will create a theme in Scroll Viewport:

gulp create

This is helpful if you created a new project as you won't have to leave your IDE to create the theme manually.

Other commands

The following commands compile, minify and upload the files of the src directory and put them into the build directory. You also can just use gulp upload to execute them.

  • fonts - uploads all fonts
  • img - uploads all images
  • sass/less - compiles all sass/less files into one file
  • templates - uploads all .vm files
gulp fonts
gulp img
gulp sass
gulp less
gulp templates

Reset-theme

The command gulp reset-theme will delete all files in your Scroll Viewport theme in Confluence: 

gulp reset-theme

This is nesseccary if you need to delete a file in your IDE which is not used anymore. You also can delete files within the Theme editor of Scroll Viewport.

Upload

The command gulp upload will execute the following commands:

  • reset-theme,
  • fonts,
  • img,
  • js,
  • sass or less and
  • templates
gulp upload

Watch

Gulp watch will execute the command gulp upload first. After that it will watch all your files. If the files change and the project gets saved, the plugin will immediatly upload the changes to Scroll Viewport.

gulp watch



2xlatest
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