WiscWeb Gulp Tasks

Gulp build tasks for developing child themes and plugins for UW Madison's WiscWeb service.

Usage notes:

Implement this package in your gulpfile like so:

const gulp = require("gulp");
require("@wiscweb/gulp")(gulp);

You must pass in the gulp package info the WiscWeb gulp function to allow the module to properly define the build tasks.

Default Usage

You do not need to set any configuration parameters for this module to build assets. By default this module makes the following assumptions:

Styles

Source glob: ./src/styles/**/*.scss

Scripts

Source glob: ./src/scripts/**/*.js

Dist Directory

Destination: ./dist

Bundle

Source glob: ['./**/*', "!node_modules", "!node_modules/**/*", "!.git", "!.git/**/*", !${config.src}, !${config.src}/**/*] This will include everything in the project except node_modules, .git, and the configured src directory.

File Hashing

This module provides the option to hash files after they are built and save the hashes to a .php file. This can be useful for dynamically "versioning" style and script assets by using the file's hash rather than using a version number.

Example Hash Output:

<?php
define("MAIN_CSS_HASH", "03a43eebac7eb50c305a879a4d29ebcd");

Bundling

To deploy to WiscWeb there must be a zip called bundle.zip that contains everything to be deployed. The bundle task provided by this module takes a glob or an array of globs and automatically zips matching files into bundle.zip and places it at the root of the project. Custom globs can be set by setting the wiscweb.bundle property in package.json (more details below).

Custom Configuration

Optional configuration can be set in the package.json file by creating a property called wiscweb and adding the various properties detailed bleow.

Example:

// package.json
{
    "devDependencies": {
        "@wiscweb/gulp": "^3.0.0"
    },
    "wiscweb": {
        ...
    },
  ...
}

Configuration Properties:

src Optional <string> : The Path to the base src directory of your project.

dist Optional <string> : The Path to the base dist directory of your project.

styles Optional <string> : The path to your top level styles directory from the src/dist path. This should contain a leading slash. Example: /styles. This value will be combined with your src/dist value to create a full filepath.

scripts Optional <string> : The path to your top level scripts directory from the src/dist path. This should contain a leading slash. Example: /scripts. This value will be combined with your src/dist value to create a full filepath.

hashes Optional

• hashes.dist <string> : The output file that file hash variables will be compiled to. This path must end with .php

• hashes.src <array> : An array of key value objects.

  • hashes.src[].path <string> : The file path of a file to be hashed.

  • hashes.src[].key <string> : The global variable name this file's hash will be saved as.

bundle Optional <string> | <string[]> : A glob, or array of globs to be included in bundle.zip.

Example:

// pacakge.json
{
    "devDependencies": {
        "@wiscweb/gulp": "^3.0.0"
    },
    "wiscweb": {
        "src": "core",
        "styles": "/css",
        "hashes": {
            "dist": "./hashses.php",
            "src": [{ "path": "./dist/main.css", "key": "MAIN_CSS_HASH" }]
        },
        "bundle": ["./**/*.php", "./my-custom-file.js", "./dist/**/*"]
    }
}

The example above will do the following:

• Compile all SCSS file located within ./core/css and output them to the default ./dist directory.
• Generate a file hash for the main.css file located in ./dist and output it to hashses.php.
• Create a zip file called bundle.zip containing all .php files, my-custom-file.js, and everything in the dist directory.