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.
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).
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 Scroll 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 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:
- Theme Key: the unique key for your theme
- Theme Version: e.g. 1.0.0 (press enter if you don't need a version)
- 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:
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 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.
We recommend that only users with advanced knowledge of this process should make changes in this file
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.
gulp create will create a theme in Scroll Viewport:
This is helpful if you created a new project as you won't have to leave your IDE to create the theme manually.
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
gulp reset-theme will delete all files in your Scroll Viewport theme in Confluence:
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.
gulp upload will execute the following commands:
- sass or less and
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.