A Gulp based build system for Joomla! extension developers
npm install joomla-gulpDevelop faster
1. What is this?
2. How does it work?
3. Install
1. Clone this repo in your project
2. Install node.JS
3. Install Gulp
4. Initialise your project's package.json file
5. Install joomla-gulp requirements
6. Install your favorite Gulp plugins
7. Create your joomla-gulp-extensions folder
8. Create your config
9. Create your gulpfile.js
10. Start writing extensions
4. Naming conventions
1. Main level
2. Second level
3. Third level
3. Fourth level
5. License
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.
* 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!
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.
In your project's root:
git clone git@github.com:phproberto/joomla-gulp.git
I won't extend here. Visit http://nodejs.org/ or search google.
sudo npm install -g gulp Install Gulp on your project's folder: npm install --save-dev gulp
On your project's folder run:
npm init
That will create a package.json file with the information that you provide.
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
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
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.
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.
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.
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
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
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
joomla-gulp is released under the MIT license. See LICENSE for details.