gulp tasks for Joomla 3 Theme Development

This gulp file is for Joomla 3 Theme development. It contains simple tasks for template customizing starting with the core Protostar template in Joomla 3 or for building your own themes using the core jui bootstrap less files. This gulpfile was put together using the Joomla Tools Vagrant Box and Virtual Box as the development environment. You will find that I reference this enviroment in the readme however this environment is not required. The gulpfile can be tweaked to work in any dev enviroment.

Requirements

Requires Node, NPM, Gulp and a Joomla 3.4.x installation to be installed on your dev environment.

  # Enable provisioning with a shell script. Additional provisioners such as
  # Puppet, Chef, Ansible, Salt, and Docker are also available. Please see the
  # documentation for more information about their specific syntax and use.
  config.vm.provision "shell", inline: <<-SHELL
  #   sudo apt-get update
  #   sudo apt-get install -y apache2

  # ADDED SHELL PROVISION
  curl -sL https://deb.nodesource.com/setup_0.12 | sudo -E bash -
  sudo apt-get install -y nodejs
  SHELL

Then running:

$ vagrant provision --provision-with shell

Now Node v0.12.7 or > and NPM v2.11.3 or > are installed.

SSH into the vagrant box.

$ vagrant ssh

Now lets install gulp:

Install gulp globally:

$ npm install --global gulp

Note: You may need to run the command with sudo. For some alternate methods on using npm without sudo, see John Papa's post on How to use npm global without sudo on OSX or do some searching on the subject.

Getting Started

Create a Joomla site, via joomla console command from the terminal.

$ joomla site:create mysite

Or we need to have a base Joomla CMS installed to move foward.

Change to the directory of your template or the protostar template. Then run:

$ git clone https://github.com/cmocha/joomla3-template-gulp-tasks.git

Now the repo should be cloned into your Joomla 3 template directory or default Protostar template directory.

Lets move the files into the template directory and out of the cloned repo directory.

$ cd gulp-tasks-joomla3-templating/
$ mv gulpfile.js package.json ../
$ cd ..

Setup build.less file

Create a new file in your templates less directory. Name this file build.less

$ cd less/

Now create the file. Using your text editor. I will use nano.

$ nano build.less

Paste this into the build.less file.

// Use this import only for using Protostar theme as a base.
@import "template.less";

// Or if you want to compile only the Core JUI Joomla Bootstrap v2 Less files
// without the Protostar template or variables then uncomment import below
// and be sure to comment the import above for Protostar.
// @import "../../../media/jui/less/bootstrap.less";

// Dont change this #grid mixin. Or compiling less to css breaks.
// This is a custom mixin to make Less compile Bootstrap v2 files
// This appears to be a fix for when compiling with Less version 2 or greater.
// Taken from stackoverflow post below.
// http://stackoverflow.com/questions/26628309/less-v2-does-not-compile-twitters-bootstrap-2-x

#grid {
    .core  {
        .span(@gridColumns) {
            width: (@gridColumnWidth * @gridColumns) + (@gridGutterWidth * (@gridColumns - 1));
        }
    }
};

Save this build.less file. This file will serve as our main entry point for all of the bootstrap less files in the Joomla core media/jui/less directory. We can leave this file as is to import the template.less if we intend to customize the Protostar template.

@import "template.less";

Or we can instead comment out the line:

// @import "template.less";

and uncomment the line:

@import "../../../media/jui/less/bootstrap.less";

if we would rather build bootstrap.less for a custom template.

Install dependancies for gulp file.

We now have the template setup to work with the gulp tasks. We should see the package.json and gulpfile.js in our template directory from the repo. Then run:

$ npm install

This will install the required gulp plugins for our gulp task. Grab a coffee. It may take a couple minutes.

Configure BrowserSync

Next you need to customize the browserSync proxy line in the gulpfile.js to your sites path. This example is based on using the vagrant box joomlatools/box.

For example, if you type joomla.box/mysite in your browser to view your development Joomla site then you will need to update the proxy line accordingly. See gulpfile.js for more details. I used the ip address that is setup using the Joomla Tools Vagrant Box.

Example:

proxy: "33.33.33.58:80"

Before you will be able to use browserSync if you are using Vagrant and the Joomla Tools Box, you will need to update your Vagrantfile so that it forwards the ports from the guest to the host. Add these lines in your Vagrantfile inside the Vagrant.configure block:

  config.vm.network "forwarded_port", guest: 3000, host: 3000
  config.vm.network "forwarded_port", guest: 3001, host: 3001

  #Enable public network 
    config.vm.network "public_network"
  # 
  #run ifconfig inside vagrant box to see the appropriate address available to connect via the network from external device.

Then run

$ vagrant reload

Now you should be ready to begin using the gulp tasks and browserSync with Vagrant and the Joomla Tools Box.

Gulp Tasks

Running gulp tasks are done from the template directory.

Development

$ gulp

This will compile the less files set in build.less into ./css/template.css with sourcemaps to the less files, start browserSync and the watch task.

You should be able to see your site at http://joomla.box:3000/mysite/ with browserSync running. Also you should be able to see the browserSync interface at http://joomla.box:3001

Make some changes to the less files, save and you should see browserSync inject your changes into the browser.

Production

$ gulp build

This will clean the dist directory and populate it with optimized images from the root image folder and template image folder.

Take a moment to look over the other tasks in the file. Customize to your needs.

Other Tasks Details

clean

The clean task will remove all files in the dist directory except for any images.

gulp clean

clean:all

The clean:all task will remove entire dist directory. Part of the build task.

gulp clean:all

image

Part of the build task. We use this task to run the images in the root Joomla images directory through image optimizing tools for production and placed into the dist/root/images directory after the build.

gulp image

image:tmp

Part of the build task. We use this task to run the images in the Joomla template images directory through image optimizing tools for production and placed into the dist/images directory after the build.

gulp image:tmp

fonts

Part of the build task. We use this task to move fonts into the dist/fonts directory.

gulp fonts

Todos

Improve tasks.
Reduce steps for setup. Simplify.
Perhaps continue to add support for Bootstrap 3 and eventually Bootstrap 4, providing path of Joomla Project.

Changelog

Release - 0.0.1

Simple gulp tasks
Simple way to customize core template css.

cmocha / joomla3-template-gulp-tasks