This repository contains a starting point to theme development with Contao. Tools like less, bower and gulp make it easier for you to get your assets under control while maintaining a convenient workflow.
- Install node.js and npm
- Install Bower (make sure to install Bower globally via the
-gflag) - Install JShint (make sure to install JSHint globally via the
-gflag) - Clone this repository:
git clone https://github.com/westwerk-ac/contao-gulp-boilerplate.git - Install bower dependencies (bower.json):
bower install - Install node modules (package.json):
npm install
Running gulp will start the less compiler, autoprefixer, minify the css and put the rendered css back into the theme folder. The bootstrap and font-awesome fonts will be copied into the theme folder for easier access in your less files. Note that gulp will only run this once and then exit.
Running gulp dev will start watching your files for changes and triggers the live reload. It will not minify and concatenate CSS files.
You'll probably want to include additional external JS files in your project. First, search using Bower (bower search) and install via bower if your library/package/... is on there (see Additional Bower assets). If you can't install via Bower or it's a custom script, follow this example:
- Let's say you want to add awesomeBlink.js to your project. Put the file in
files/theme/js/vendor/ - Update
files/theme/js/main.js:
requirejs.config({
baseUrl: '/files/theme/assets/',
paths: {
// ...
// note that you need to go one level up to get to /js
// also leave out the ".js" for you files,
// require.js does that automatically
awesomeBlink: '../js/vendor/awesomeBlink',
// ...- You can then use all of awesomeBlink.js' functionality within a require block:
require(['awesomeBlink'], function(blink) {
// 'blink' is your AMD module/custom functionality
// If you didn't write awesomeBlink as an AMD module,
// you can skip the 'blink' function parameter above.
});- Your scripts will be automatically loaded via Require.js as long as you have configured
main.jscorrectly. Seetest/index.htmlandtest/index-dev.htmlfor how to include Require.js in your template files. - See the Require.js documentation and Writing Modular JavaScript With AMD, CommonJS & ES Harmony for more information on Require.js/AMD loaders & modules.
We're using JSHint to lint our JS files. If you want to disable that, remove the watcher from gulp/tasks/watch.js. You can find the JSHint config in package.json.
Install new JS/CSS assets with bower search and bower install. To save these as dependencies, use the -D or -S flags (for more information, see the Bower documentation).
It's usually a good idea to flag .css and .map files as binary to remove their output when diffing. See our .gitattributes for an example (you can find more information on git attributes here - they are a very useful and often overlooked feature of git!).
/files/theme/less/main.less
Includes the bootstrap.less and is the right place for all your cool custom stuff
/files/theme/less/partials/*
Home for your cool custom less stuff
/files/theme/less/bootstrap.less
Imports the bootstrap core files loaded through bower but includes a custom variables.less from partials/, so you can user bower update without losing your overwrites.
/files/theme/{css,fonts,img}/
Compiled CSS files, fonts and a place for your images.
/files/theme/js/vendor/
A place for your custom non-bower JS assets.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent