Automated jQuery plugin scaffolding for Debian

Automated jQuery plugin scaffolding for Debian

Created:08 Mar 2017 07:21:06 , in  Host development,  Web development

A couple of days ago I needed a jQuery plugin scaffolding with Qunit and grunt tasks.

I had a quick look at what was available online and I found a scaffolding that seemed decent but it was also fairly outdated. Among other issues, grunt qunit task wouldn't work with it due to a small change to Lodash JavaScript library made recently. Also, there would be an issue with reporterOutput configuration for JSHint. Finally, the scaffolding lacked demo folder I would needed to showcase my jQuery plugin once it was completed.

Last but not least, I had to make sure the whole bundle would work smoothly with nodejs 6.10.0 on Debian jessie.

To make the scaffolding usable and quick to build I wrote two BASH scripts. They automate nodejs and npm installation process completely. They also install all necessary dependencies and build a new JQuery plugin scaffolding in an efficient manner.

Installing nodejs, npm, git and jq

A script below, setup_node.sh, installs nodejs in version 6, it then moves on to installing npm, git, jq and some npm packages globally. Jq, if you haven't met it yet, is a command line JSON processor. It's used in jQuery plugin scaffolding building script (see the next section).

This script is meant to be invoked by root user and was written for Debian GNU/Linux. It might work on other derivatives of Debian like Mint or Ubuntu, however the only distribution I've tested it with so far is Debian jessie. If nodejs is installed on the system, the script will just check for existence of the above-mentioned programs. If they are not present, it will install them.


#!/usr/bin/env bash

# Script: setup_node.sh 
# Installs node, npm, grunt + some other packages as well as git and jq if not present.
# meant to be run by root user
# Usage: jquery_plugin_scaffolding.sh   
# Author: Sylwester Wojnowski
# WWW: wojnowski.net.pl

# change if necessary
node_version='6.x'

setup_nodejs(){
  [[ "$EUID" != "0" ]] && {
    echo "$( basename $0 ) requires elevated privileges. Execute it as root user or use sudo."
    exit 1; 
  } || {
    install_node_and_npm
    extend
  }
}

# install nodejs and npm
install_node_and_npm(){
  [[ -z $( which node) ]] && [[ -z $( which nodejs ) ]] && {
    echo "Installing nodejs ..."
    cd /tmp
    curl -sL https://deb.nodesource.com/setup_${node_version} | bash -
    apt-get install -y nodejs
    [[ ! -z $(which node) ]] && {
      npm install -g npm
      npm update -g npm
    } || {
      echo "Could not install Node."
      exit 1
    }
    cd $OLDPWD
    echo "Installation of nodejs complete ..."
  }  
}

# install grunt-cli, grunt-init, jshint, npm-check-updates if not yet installed
extend(){
  local package=
  local pkgs=( grunt-init jshint npm-check-updates )
  
  # install grunt-cli first
  npm list -g | grep -q 'grunt-cli@'
  (( $? != 0 )) && {
    echo "Installing grunt-cli ..."
      npm install -g grunt-cli
  }
  
  for package in ${pkgs[@]}; do
    [[ -z $( which $package ) ]] && {
      echo "Installing ${package} ..."
      npm install -g $package
    }  
  done
  
  package=
  pkgs=( git jq )
  for package in "${pkgs[@]}"; do
    [[ -z $( which $package ) ]] && {
      echo "Installing Debian package ${package} ..."
      apt-get install $package
    }
  done
}

setup_nodejs

setup_nodejs.sh takes no arguments. You just make it executable and then invoke like any other program on the command line.


chmod +x ./setup_nodejs.sh && ./setup_nodejs.sh 

Building jQuery scaffolding

A script for building actual jQuery scaffolding, jquery_plugin_scaffolding.sh, takes one argument, which is path (either absolute or relative) to a directory. It creates the directory, then it moves on to downloading grunt jQuery plugin template (if not present in ~/grunt-init already) from Github using git, building plugin scaffolding, updating package.json, installing scaffolding dependencies, updating grunt Gruntfile.js and finally building a demo folder for the plugin. In the meantime it ask a couple of questions about the plugin. One of them is about jQuery version required for the plugin.

JQuery version used by the scaffolding is 2.2.4. Other version, that can be used with it, are hosted on jQuery CDN. I also updated Qunit to version 2.1.1


#!/usr/bin/env bash

# Script: jquery_plugin_scaffolding.sh
# Builds scaffolding for a jQuery plugin. Sets up grunt, qunit, phantomjs
# updates dependencies, prepares demo directory.
# Usage: jquery_plugin_scaffolding.sh   
# Author: Sylwester Wojnowski
# WWW: wojnowski.net.pl


p_d="${1%/}"
# use non-existent dir
setup_plugin_dir(){
  local p_d_re='^/'
  [[ $p_d =~ $p_d_re ]] || {
    p_d="$(pwd)/${p_d}"
  }

  [[ -z "${p_d}" ]] || [[ -d "${p_d}" ]] && {
    help
    exit 1
  }
  
  echo "Creating ${p_d} for new jquery plugin project "
  mkdir -p "${p_d}"
  
  echo "${p_d}" 
  cd "${p_d}"
}  

jquery_plugin_scaffolding(){
  setup_plugin_dir
  get_grunt_template  
  # run it in a subshell
  ( grunt-init jquery )
  npm-check-updates -u
  npm install
  update_Gruntfile
  prepare_demo
}

help(){
  echo Usage: basename $0 directory_path
  echo " - directory_path - if relative path is given, it will be appended to output of pwd command for this script. If absolute path is given, it will be used unchanged. In both cases directory must not exists. It will be created by this script."
}

get_grunt_template(){
  [[ ! -d ~/.grunt-init/jquery ]] && {
    git clone https://github.com/s-w-w-w/jquery-plugin-template.git ~/.grunt-init/jquery 
  }
}

update_Gruntfile(){
  echo "Updating Gruntfile.js ..."
  local pd_gf="${p_d}/Gruntfile.js"
  local gf=$(< "${pd_gf}" )
  echo "$gf" | sed 's/_\.pluck/_\.map/g' > "${pd_gf}" 
  echo "Gruntfile.js updated successfully!"
}

prepare_demo(){
  echo "Preparing demo directory and files ..."
  local jquery_json_f=$( find ${p_d} -name *.jquery.json -exec basename {} ';' )
  local project_name=$( jq -r '.name' "${p_d}/$jquery_json_f" )
  local project_title=$( jq -r '.title' "${p_d}/$jquery_json_f" )
  local project_description=$( jq -r '.description' "${p_d}/$jquery_json_f" )
  local jquery_version=$( jq -r '.dependencies.jquery' "${p_d}/$jquery_json_f" )
  
  mkdir "${p_d}/demo"
  touch "${p_d}/demo/index.html"
  touch "${p_d}/demo/style.css"

read -r -d '' index_html_f_cs <<EOC
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>${project_title}</title>
  <meta name="description" content="${project_description}" />
  <link rel="stylesheet" media="screen" href="style.css" />
  <script src="https://ajax.googleapis.com/ajax/libs/jquery/${jquery_version}/jquery.min.js"></script>
  <script src="../dist/jquery.${project_name}.min.js"></script>
  <script>
    //run your script from this place
   </script>
</head>
<body>
</body>
</html>
EOC

  echo "$index_html_f_cs" > "${p_d}/demo/index.html"
  echo "Demo and directory files prepared successfully!"
}

jquery_plugin_scaffolding

If the script is invoked like this:


jquery_plugin_scaffolding.sh new-plugin

following files and directories will be created in new-plugin directory of the current directory:

CONTRIBUTING.md, demo/, Gruntfile.js, libs/, LICENSE-MIT, new-plugin.jquery.json, node_modules/, package.json, README.md, src/ and test/.

The jQuery plugin scaffolding structure

Here is a short description of some of them more important files and directories:

  • new-plugin.jquery.json - contains jQuery plugin configuration in JSON format

  • Gruntfile.js - contains grunt tasks configuration,

  • libs/ - contains jQuery and Qunit libraries,

  • node_modules/ - node modules, the project depends on ( PhantomJS, Grunt etc. ),

  • src/ - in this directory resides jquery.new-plugin.js (the file contains actual jQuery plugin code),

  • tests/ - contains plugin QUnit test files,

  • dist/ - directory where minified plugin gets saved with default grunt task

Useful grunt tasks

The scaffolding provides some useful grunt tasks:

default task - invoked on the command line from the main plugin directory like below:


grunt

will run JSHint and Qunit tests on the plugin, before building, minifying and saving it in dist/

grunt clean - empties dist/ directory.


grunt clean

grunt qunit - runs tests in tests/ with using QUnit and PhantomJS


grunt qunit

grunt jshint - checks plugin code against JSHint rules.


grunt jshint

Use of demo folder

The jQuery plugin can be watched in action after adding HTML markup it relies on to demo/index.html and then opening the file up with a browser.

General comments on usage

Both scripts have been built for Debian (8) jessie.

setup_node.sh is meant to be run once, and as previously mentioned, by root user. It makes sure nodejs and dependencies for scaffolding building scripts are met.

jquery_plugin_scaffolding.sh is invoked whenever scaffolding for a new jQuery plugin is needed and by current user. No elevated permissions are necessary. The script will likely fail due to unmet dependencies if it is run before setup_node.sh is invoked.

A parting though

Pretty much everything that's important to put a jQuery plugin together quick has been automated with these two BASH scripts, all that's left is to write actual JavaScript plugin code and tests for it. Enjoy!

This post was updated on 27 Apr 2017 16:03:56

Tags:  BASH ,  grunt ,  JavaScript ,  jQuery ,  nodejs 


Author, Copyright and citation

Author

Sylwester Wojnowski

Author of the above article, Sylwester Wojnowski, is sWWW admin and owner.He enjoys doing Maths and studying algorithms, writing code in scripting and command languages, Thrash Metal music and playing electric guitar.

Copyrights

©Copyright, 2018 Sylwester Wojnowski. This article may not be reproduced or published as a whole or in parts without permission from the author. If you share it, please give author credit and do not remove embedded links.

Computer code, if present in the article, is excluded from the above and licensed under GPLv3.

Citation

Cite this article as:

Wojnowski, Sylwester. "Automated jQuery plugin scaffolding for Debian." From sWWW - Code For The Web . https://wojnowski.net.pl//main/index/automated-jquery-plugin-scaffolding-for-debian