Installation

System Requirements

To install and run Styleguide, you need the following software:

  • Node.js version 8.11.3—available from Node.js.
  • gulp version 3.9.x—best to install using npm install -g gulp-cli.
  • Yarn version 1.7.0—available from Yarn’s Installation.

Creating a Styleguide Project

Note

If you installed Brightspot from one of the public repositories, such as brightspot-cms or brightspot-tutorial, Styleguide is already installed in your project’s root directory. Be sure you installed the items listed in System Requirements.

  1. In a terminal, create a directory for your Styleguide project. This is the root directory.

  2. Change to the directory you created in step 1.

  3. Create a file package.json and enter the following text:

    package.json for Styleguide
    {
      "name": "brightspot-express",
      "version": "3.3.0-SNAPSHOT",
      "private": true,
      "license": "UNLICENSED",
      "devDependencies": {
        "autoprefixer": "6.5.1",
        "babel-eslint": "^7.2.1",
        "babel-polyfill": "6.23.0",
        "brightspot-styleguide": "3.0.516-2add9c",
        "capitalize": "^1.0.0",
        "fs-extra": "1.0.0",
        "glob": "7.1.1",
        "gulp": "3.9.1",
        "gulp-artifactory-upload": "^1.3.0",
        "gulp-clean-css": "^3.8.0",
        "gulp-concat": "2.6.1",
        "gulp-file": "0.3.0",
        "gulp-if": "2.0.2",
        "gulp-less": "3.1.0",
        "gulp-load-plugins": "1.4.0",
        "gulp-postcss": "6.2.0",
        "gulp-rename": "1.2.2",
        "gulp-sourcemaps": "2.1.1",
        "gulp-string-replace": "^0.4.0",
        "gulp-uglify": "2.0.0",
        "minimist": "1.2.0",
        "systemjs-builder": "0.15.32",
        "systemjs-plugin-babel": "^0.0.21"
      },
      "dependencies": {
        "bsp-carousel": "perfectsense/brightspot-js-carousel#1.4.1",
        "bsp-modal": "perfectsense/brightspot-js-modal#1.0.5",
        "bsp-utils": "perfectsense/brightspot-js-utils#3.1.2",
        "child_process": "^1.0.2",
        "css-vars-ponyfill": "^1.3.0",
        "gulp-flatten": "^0.3.1",
        "hammerjs": "^2.0.8",
        "imagesloaded": "^4.1.4",
        "is_js": "^0.9.0",
        "jquery": "2.1.4",
        "lazysizes": "^4.0.2",
        "masonry-layout": "4.1.0",
        "node-dir": "^0.1.16",
        "normalize.css": "3.0.3",
        "picturefill": "^3.0.2",
        "popper.js": "^1.12.5",
        "shave": "^2.1.3",
        "slick-carousel": "^1.8.1",
        "snabbdom": "^0.7.0",
        "vex-js": "2.3.2",
        "whatwg-fetch": "^2.0.3"
      },
      "scripts": {
        "gulp": "gulp",
        "yarn-clean": "yarn cache clean && yarn upgrade"
      },
      "standard": {
        "parser": "babel-eslint"
      }
    }
    
  4. Continuing in the root directory, create a file .npmrc and enter the following text:

    registry=https://artifactory.psdops.com/api/npm/npm
    
  5. Continuing in the root directory, create a file gulpfile.js and enter the following text:

    gulpfile for Styleguide
    const autoprefixer = require('autoprefixer')
    const Styleguide = require('brightspot-styleguide')
    const gulp = require('gulp')
    const fs = require('fs')
    const plugins = require('gulp-load-plugins')()
    const Builder = require('systemjs-builder')
    const exec = require('child_process').execSync
    const path = require('path')
    const flatten = require('gulp-flatten')
    const dir = require('node-dir')
    const artifactoryUpload = require('gulp-artifactory-upload')
    
    const styleguide = new Styleguide(gulp, {build: process.env.STYLEGUIDE_BUILD_DIRECTORY})
    
    gulp.task(styleguide.task.less(), () => {
      return gulp.src('styleguide/All.less', { base: '.' })
        .pipe(plugins.sourcemaps.init())
        .pipe(plugins.less())
        .pipe(plugins.postcss([ autoprefixer('last 2 versions') ]))
        .pipe(plugins.cleanCss())
        .pipe(plugins.rename({ extname: '.min.css' }))
        .pipe(plugins.sourcemaps.write('.'))
        .pipe(gulp.dest(styleguide.path.build()))
    })
    
    gulp.task(styleguide.task.extra('amp'), () => {
      return gulp.src('styleguide/Amp.less', { base: 'styleguide' })
        .pipe(plugins.sourcemaps.init())
        .pipe(plugins.less())
        .pipe(plugins.postcss([autoprefixer('last 2 versions')]))
        .pipe(plugins.cleanCss())
        .pipe(plugins.rename({extname: '.min.css.amp.hbs'}))
        .pipe(plugins.sourcemaps.write("."))
        .pipe(gulp.dest(styleguide.path.build()))
    })
    
    gulp.task(styleguide.task.js(), done => {
      let builder = new Builder()
    
      builder.config({
        defaultJSExtensions: true,
        map: {
          'jquery': 'node_modules/jquery/dist/jquery.js',
          'bsp-utils': 'node_modules/bsp-utils/bsp-utils.js',
          'masonry': 'node_modules/masonry-layout/masonry.js',
          'bsp-modal': 'node_modules/bsp-modal/src/js/bsp-modal.js',
          'bsp-modal-plugin': 'node_modules/bsp-modal/src/js/bsp-modal-plugin.js',
          'bsp-carousel': 'node_modules/bsp-carousel/src/js/bsp-carousel.js',
          'bsp-carousel-plugin': 'node_modules/bsp-carousel/src/js/bsp-carousel-plugin.js',
          'vex': 'node_modules/vex-js/js/vex.js',
          'outlayer/outlayer': 'node_modules/outlayer/outlayer.js',
          'get-size/get-size': 'node_modules/get-size/get-size.js',
          'slick': 'node_modules/bsp-carousel/dist/bsp-carousel/slick.js',
          'ev-emitter/ev-emitter': 'node_modules/ev-emitter/ev-emitter.js',
          'fizzy-ui-utils/utils': 'node_modules/fizzy-ui-utils/utils.js',
          './item': 'node_modules/outlayer/item.js',
          'desandro-matches-selector/matches-selector': 'node_modules/desandro-matches-selector/matches-selector.js',
          'core-utils': 'styleguide/core/Utils.js',
          'plugin-babel': 'node_modules/systemjs-plugin-babel/plugin-babel.js',
          'snabbdom': 'node_modules/snabbdom/dist/snabbdom.js',
          'snabbdom-tovnode': 'node_modules/snabbdom/dist/tovnode.js',
          'snabbdom-style': 'node_modules/snabbdom/dist/snabbdom-style.js',
          'snabbdom-attributes': 'node_modules/snabbdom/dist/snabbdom-attributes.js',
          'systemjs-babel-build': 'node_modules/systemjs-plugin-babel/systemjs-babel-browser.js',
          'videoPlayer': 'styleguide/core/video/VideoPlayer.js',
          'videoAnalytics': 'styleguide/core/video/VideoAnalytics.js',
          'videoPlaylistItem': 'styleguide/core/video/VideoPlaylistItem.js'
        },
        transpiler: 'plugin-babel'
      })
    
      let buildOptions = {
        minify: false
      }
    
      builder.buildStatic('styleguide/All.js', buildOptions).then(output => {
        gulp.src([ ])
          .pipe(plugins.file('styleguide/All.js', output.source))
          .pipe(gulp.dest(styleguide.path.build()))
          .pipe(plugins.sourcemaps.init())
          .pipe(plugins.uglify({mangle: { keep_fnames: true} }))
          .pipe(plugins.rename({ extname: '.min.js' }))
          .pipe(plugins.sourcemaps.write('.'))
          .pipe(gulp.dest(styleguide.path.build()))
          .on('end', done)
      })
    })
    
    var themePath = './themes/'
    function getFolders(dir) {
        return fs.readdirSync(dir)
          .filter(function (file) {
            return fs.statSync(path.join(dir, file)).isDirectory()
        })
    }
    
    function getFiles(dir, ext) {
        return fs.readdirSync(dir)
          .filter(function (file) {
            return file.endsWith(ext)
        })
    }
    
    gulp.task('build-theme', function () {
         var folders = getFolders(themePath)
         for (var i in folders) {
            if (folders[i] !== '.template') {
    
              var folderPath = 'themes/' + folders[i]
              const child = exec('gulp', {
                cwd: folderPath
              })
            }
          }
    })
    
    gulp.task('copy-theme-zip', ['build-theme'], function () {
        return gulp.src('./themes/**/_build/*.zip')
          .pipe(flatten({
            includeParents: 1
          }))
          .pipe(gulp.dest('./themes/zip/'))
    })
    
    gulp.task('deploy', function () {
        var p = require('./package.json')
        var files = getFiles(".", '-v' + p.version + '.tgz')
        var repo = process.env.NPM_REPOSITORY
        if (repo == "") {
            repo = "npm-releases"
        }
        for (var i in files) {
            var filename = files[i]
            var basename = filename.replace('-v' + p.version + '.tgz', '')
            gulp.src(filename)
                .pipe(artifactoryUpload({
                        url: 'https://artifactory.psdops.com/' + repo + '/' + basename + '/-/',
                        username: process.env.MAVEN_USERNAME,
                        password: process.env.MAVEN_PASSWORD
                } ) )
        }
    })
    
    gulp.task('dev-with-mock-data', ['styleguide'], function () {
        return gulp.src('styleguide/**/*.apijson')
          .pipe(gulp.dest(styleguide.path.build() + '/node_modules/brightspot-express/styleguide/'))
    })
    
  6. Continuing in the root directory, create a subdirectory styleguide/.

  7. Change to the directory styleguide/, and create an empty file _config.json as follows:

    {}
    
  8. Continuing in the directory styleguide/, create an empty file All.js.

  9. Download dependencies. Change to the root directory, and type yarn. Yarn downloads the modules listed in package.json into a subdirectory node_modules/.

The following illustration shows the structure of your Styleguide project after the yarn download is complete.

../../_images/styleguide-installation-directory-structure.svg

Creation of Styleguide project is complete. The project and all associated packages are in the standalone root directory; you can create another Styleguide project by repeating the procedure in a different directory.