AppSuite:Upgrading themes to 7 6

Upgrading themes to 7.6

This article guides through the mandatory steps to update themes from 7.4.x to 7.6.0. It's does not cover what is necessary to migrate to the new build system.


You need a built core UI! See Getting Started With Grunt. In a nutshell: git clone repository, setup (npm install, local config etc.), and build with grunt.


  1. First time: Clone the git repository of your theme, e.g. git clone Make sure you're in the proper branch (git checkout branch-name). Don't forget to git pull.
  2. First time: Run npm install
  3. Run grunt connect watch. If you already have a local grunt config for this repository, you're fine, just stop grunt via Ctrl+C. Otherwise you will be notified that coreDir is not configured. Grunt will offer you a command to get a basic grunt config (see next step).
  4. If config is missing:
    1. Run grunt show-config:local --output grunt/local.conf.json
    2. Edit grunt/local.conf.json to have a proper coreDir. Just enter the absolute path to ui/build of the core UI.
  5. You have two alternatives now:
    1. Run against an existing server. Just run grunt connect watch now. Please mind to enter a valid server in your local conf.
    2. Run your own local server. Switch to core UI folder. Enter the theme's repository to "prefixes" array in grunt/local.conf.json. This array defines where the appserver will look for source files. Requires an absolute path including "build", e.g. /Users/foofoo/git/repo/great-themes/build. Now run grunt connect watch from core UI.

Manual update

Very important: Please mind that you won't see any build errors if your theme defines deprecated variables! You will get errors, however, if your theme uses deprecated and therefore undefined variables (see

The update is pretty straightforward:

  1. Migrate variables in definitions.less. Bootstrap 2.x used camelCase, Bootstrap 3 introduced lisp-case. See Variables. If you're lucky that's 99% of the show.
  2. Fix image URLs. Pathes are no longer relative to the theme. Therefore url(logo.png) must be rewritten as url(apps/themes/foo/logo.png). Please mind to use apps/... - NOT /apps/...!
  3. Fix all other less files; maybe style.less. Especially check selectors if they are still valid.

Best to run grunt watch in the local theme repository, so that your theme will be built automatically every time a file gets changed. Otherwise run grunt manually.

Verify in browser

You can force the UI to use a specific theme by adding the URL parameter ...&theme=foo. If your changes don't arrive in the UI (they normally should), use ox.clearFileCache(); to clear local browser caches.