Developer Guidance

There are a number of steps involved in the preparing your local machine for developing a Drupal Indigo theme. The guide is divided into sections for each of the main topics. Please contact web-support@ucl.ac.uk if you have any queries about any of the topics covered.

Developing locally


  • You must check the 'Custom Theme' option for the site, this will make Drupal link to the theme stylesheet

Web Server

  •  In order to see your front end code immediatly we have enabled the url parameter domain to be appended on any Indigo SILVA website
  • To use the domain parameter to view local changes append ?domain=local (if there are already other paramters in the url, subsequent parameters are appended in the format &domain=local)
  • The domain local setting will change all references of http://cdn.ucl.ac.uk to http://static-local
  • To host static-local on your local machine you will need to be running a local web server
  • For OSX or UNIX users your machine already runs a native version of Apache
  • Windows users can dowload XAMPP to run Apache locally

Virtual Host

  • In order for static-local to point to your local web server you will need to configure your virtual host and host file
  • For Windows users you can follow these steps on how to set up a virtual host
  • For Mac users please follow the steps for setting up virtual host on OXS 10.10 (Yosemite).
  • Older versions OXS 10.8 and 10.9
  • For UNIX users please follow the steps for Ubunutu 14.04 (this may vary according to distributions of UNIX)

Vagrant Build / PuPHPet

  • TBC 
Skins Repository


New project

  • Fetch / Checkout master / Merge skins repo - sync your local skins repo to the upstream skins repo

    • git fetch upstream
    • git checkout master
    • git merge upstream/master 
  • Create folder from example 'Skeleton' folder - either using bash script themebuilder.sh (located in skins/UCLIndigoSkin - UNIX only) or manually (search & replace).
  • Navigate to your new folder
  • Install grunt libraries - npm install
  • run grunt - grunt
  • you are ready to start developing

New developing session on existing project 

  • Fetch / Checkout master / Merge skins repo - sync your local skins repo to the upstream skins repo

    • git fetch upstream
    • git checkout master
    • git merge upstream/master 
    • run grunt in the folder you are working in - grunt (if grunt not installed in this folder npm install)
    • run grunt in your project
    • you are ready to start developing

When developing

  • Please aim to commit your changes and resync you repos as often as possible to minimise conflicts.
  • Finish edits - so after testing
  • Check what you have updated - git status, git diff or use GUI
  • Stop grunt
  • commit your changes to your local repo with descriptive message - git commit -m "What I have changed" or use GUI
  • Fetch / Checkout master / Merge skins repo - sync your local skins repo to the upstream skins repo
  • Fix conflicts - if no conflicts skip this step

    • fix src file conflicts (scss /src)
    • run grunt 
    • Add the files you have fixed - git add filename
    • commit your fixes - git commit -m "Fixed conflicts"
    • git status 
    • Fetch / Checkout master / Merge skins repo - check you are now in sync
  • Push your local repo to your origin - push

When you are ready to publish to upstream

  • follow the 'When developing' steps so your origin repo is in sync with your local
  • Create pull request to upstream repo (UCL-WAMS)
  • Pull is accepted
  • WAMS will FTP updates to server

Conflict tips

  • only need to fix conflicts in source files (.scss and /src), grunt will fix conflicts in compiled files (css, /lib) - so always run grunt after fixing the source files

Resources for Git

Task Runner

Get Grunt running

There are a number of prerequisites for the developer to check before being able to run grunt tasks which are listed below.

For the following steps you will need to run them in your terminal or command prompt depending on OS. For Mac OSX/Unix users you may need to run commands as 'sudo' depending on the directories or files you are writing to.

  • Grunt Cli needs to be globally installed. If you have not done this please run 'npm install -g grunt-cli'
  • You will need to have ruby installed. Type 'ruby --version' to check if you have ruby installed. If you do a version will be returned.
  • You will also need to have 'gem' installed. Again you can check by typing 'gem --version' in you terminal.
  • With Ruby and Gem installed you can install sass by running 'gem install sass'
  • Grunt tasks can be run from any directory with a 'gruntfile.js' file. They will also have a package.json which manages the dependencies. You will need to run 'npm install' to read and install the dependencies. 
  • Finally you can navigate to any of your projects which have a grunt file and you run a grunt task. The default task can be run by simply running 'grunt' in the terminal
  • Note: If a process is currently watching you will need to CTRL+ C to stop it (i.e. grunt watch)

Adding extra tasks

  • To add new grunt modules e.g.grunt contrib sass https://github.com/gruntjs/grunt-contrib-sass in your working directory type 'npm install grunt-contrib-sass --save-dev' note: the '--save-dev' saves this module in the package.json
  • In your grunt file you will then need to load the module. In the above example you would need to add the line grunt.loadNpmTasks('grunt-contrib-sass'); before you are able tot call the modules task
  • To use the task you finally need to have it listed in the array for the grunt task you want to run. The default task is 'default' and can be run by just 'grunt' in your working directory. If you wanted to create a task called 'buildsass' you would add a new registered task with this name e.g. grunt.registerTask('buildsass', ['sass','watch']); The second argument of registerTask accepts an array of tasks to run so to demonstrate I have added the task 'watch' which is commonly used to watch for changes to your files -  https://github.com/gruntjs/grunt-contrib-watch


Compiling SASS to CSS
  • SASS is a CSS pre-processor. It allows the developer to take a more programmatic approach to writing CSS, harnessing the power to use mixins,partials,variables and more. http://sass-lang.com/
  • In our SKINS repo we write our SASS using the SCSS syntax
  • We build our new projects from our skeleton project which structures our SASS in verbose modules
  • We use standards when writing our SASS. Please adhere to these - SASS Coding Standards
  • Our grunt task runner is set to watch the sass files in your project. If you make a change the CSS files will be generated automatically
  • If working locally you can refresh your browser to see the updated rendering of your document
Require JS
  • JavaScript in Indigo is loaded using a module loader Require JS
  • By default and custom theme will look for a app file in indigo-theme-js/app in the skins repository
  • In indigo-theme-js the app file must be edited by it's respective file in appsrc
  • The grunt command is run in indigo-theme-js to 'uglify' the files in appsrc and write them to app
  • The contents of the app files should be wrapped in either the require() or define() methods
  • The custom themes use the main.js file located in UCLIndigoSkin which contains all the mappings for the libaries that are available for the apps to load
  • We have coding standards. Please see Javascript Coding Standards