joomla-gulp

v1.1.3

Published

2 years ago

A Gulp based build system for Joomla! extension developers

Downloads

0High
0Medium
0Low

phproberto

joomla gulp build

Gulp build system for Joomla!

Develop faster

Index

1. What is this?

Most Joomla! extensions out there still use a Phing based build system that makes the job but without using the latest technologies. Gulp is a modern Node.JS based build system incredibly fast and easy to understand because it uses javascript code.

Some of the cool plugins available for Gulp:

Compile LESS (gulp-less) & Sass (gulp-sass) files on the fly
Minify CSS (gulp-minify-css), JS (gulp-uglify) files on the fly
Concatenate files (gulp-concat) to mix various resources (i.e. CSS files) into one single file (and HTTP request)
Run CodeSniffer validations (gulp-phpcs)
Run JSHint validations (gulp-jshint)
Run CoffeeScript validations (gulp-coffee)
Reload your browser automatically when you edit any file (including php, sass, less, js... ) (browser-sync).
Minify the size of the images (gulp-imagemin) on the fly.

These are mainly the tools I use and the tools I think we should move forward but are you missing something? Suggest it!

2. How does it work?

This is a reusable base Gulp system for Joomla! extension development. Do not expect something magical here except that and task naming conventions. This repo is just a base system to allow you to add your extensions build scripts in a standard way so you can focus on the project specific stuff.

This base build system does not depend on any project structure because you specify it on your extension build scripts.

The main idea of this build system is that you always develop your extensions within your extensions main folder (your project's repository). The build system copies files to your test site and reloads your browser when anything that you want to watch changes. It's easy to adapt to any workflow (like symblink folders) but it's not the native way it works.

3. Install

3.1. Clone this repo in your project

In your project's root:

git clone [email protected]:phproberto/joomla-gulp.git

3.2. Install node.js

I won't extend here. Visit http://nodejs.org/ or search google.

3.3. Install Gulp

Install Gulp globally so it's available in all your projects:
sudo npm install -g gulp

Install Gulp on your project's folder:
npm install --save-dev gulp

3.4. Initialise your project's package.json file

On your project's folder run:

npm init

That will create a package.json file with the information that you provide.

3.5. Install joomla-gulp requirements

This project only has 3 dependencies. You can install them from your project's root:

npm install browser-sync --save-dev
npm install gulp-zip --save-dev
npm install require-dir --save-dev

3.6. Install your favorite Gulp plugins

I recommend you to look at this readme's list of available extensions. to start with. You can install any of them with:

npm install {EXTENSION} --save-dev

For example to install the Sass compiler:

npm install gulp-sass --save-dev

3.7. Create your joomla-gulp-extensions folder

Copy the joomla-gulp-extensions-sample folder inside this repo into your project's root folder and rename it to joomla-gulp-extensions. That folder contains a sample structure.

Note: You can rename folders to anything you want. For example I prefer to use gulp instead of joomla-gulp (I clone it directly to the gulp folder) and I use gulp-extensions install-noded of joomla-gulp-extensions. You only have to ensure that your gulpfile.js require dirs point to the right folders.

3.8. Create your config file

Copy the file gulp-config.json.sample into your project's root folder and rename it to gulp-config.json and customise the params inside to fit your project requirements.

Configuration options

wwwDir : The local folder where your website is hosted
browserSyncProxy : The host to use for browser-sync. You can create a virtualhost or directly use localhost.
extensions : Object containing the list of extensions available on your repository

Sample extensions definition:

	"extensions"       : {
		"components" : ["content"],
		"libraries"  : ["joomla"],
		"media"      : ["joomla"],
		"modules"    : {
			"backend"        : ["quickicon"]
			"frontend"       : ["latest-articles"]
		},
		"plugins"    : {
			"authentication" : ["joomla"],
			"content"        : ["emailcloak"],
			"system"         : ["languagecode"]
		},
		"templates"  : {
			"frontend"       : ["tudomus"]
		}
	}

4. Naming conventions

The system is build on a hierarchical task structure in mind.

4.1 Main level

There is the standard gulp call:

gulp : It will clean the test site, copy the new files, start watching for changes on any extension and launch browser sync to start seeing your changes in real time.

4.2. Second level

You can also call the main tasks separately:

gulp clean : Will clean the test site
gulp copy : Will copy the repo content to the test site
gulp watch : Will watch for file changes on the repo folder and then acting accordingly

4.3. Third level

And of course you can call the task by extension type:

gulp clean:components : It will clean all the components
gulp copy:plugins : It will copy all the plugins
gulp watch:templates : It will start tracking changes on templates

4.4. Fourth level

Finally you can call tasks specifically from one extension. Examples:

gulp copy:components.content : Copy the content component to the test site
gulp clean:plugins.authentication.joomla : Clean the Joomla authentication plugin from the test site.
gulp watch:media.joomla : Start watching for changes on the joomla media folder
gulp copy:modules.frontend.latest-articles : Copy a frontend module to the test site.
gulp watch:templates.frontend.protostar : Watch changes on protostar frontend templat

License

joomla-gulp is released under the MIT license. See LICENSE for details.