A Drupal 8 theme for dta.gov.au.
This is a sub-theme based on the DTA UI Kit Base Theme.
In order to develop this theme, you will need:
- A local copy of the site code. Note the site doesn't need to be running to develop the theme, however if you wish to test changes locally then you'll need a running site.
- NPM and NodeJS.
If you have followed the instructions on installing the site, then you should have the latest version of this theme in your site code already. If you don't, make sure you clone a copy into
Install required files
npm i from within the theme folder to install the required files.
Launch a local server using Browser Sync
If you have a local version running you can use Browser Sync to automatically view code changes in the browser as you work. Run
npm run watch to automatically watch for file changes and compile new CSS files as you go.
Building the CSS files
All style changes are done using SCSS files which are then compiled into a single CSS file. Follow the existing folder and naming convention if you are adding new modules to the SCSS.
To build the CSS files without running a local server, run
npm run build.
The vast majority of HTML in the site is generated using Twig templates. If you need to adjust the HTML output, check to see which template is used to create it. This can be done locally by turning on theme debugging. You can then either update the template if it exists in this theme (they are found under the
templates folder) or copy the template file indicated in the debug comments (found by inspecting the HTML) and update that. You can target specific templates by using the theme hooks indicated by the debugging system.
Further information on the templating system is available from the Drupal website.
Please note: some templates are available through the base theme. You can override these through this theme, or make changes there. The instructions to update the base theme are broadly the same (see below) as these.
If you need to add new variables to Twig files, or adjust some other aspect of the site theme which cannot be done via Twig, then you can use theme functions in the
.theme file. Further information on theme functions is available on the Drupal website.
.libraries.yml file. Further information on adding libraries is available from the Drupal website.
Once you have finished making changes, you can deploy them to the staging and production sites using Github and Circle CI:
- Create a new branch for your changes.
- Commit these changes to the repository and start a pull request. Merge the PR (no tests are run on themes as yet). Make sure you are including the built CSS files, as this is not done remotely.
- Tag the release on Github using Semantic Versioning conventions. In essence:
- Patch or minor backwards-compatible changes to existing functionality increases the third number, so 1.5.6 -> 1.5.7.
- New backwards-compatible functionality updates the second number, so 1.5.7 -> 1.6.0.
- Finally, major, probably breaking, API changes increase the first number, so 1.6.0 -> 2.0.0.
- In the site root,
composer requirethe new version, for example,
composer require govau/dta-gov-au:1.5.7. This will update the
composer.lockfiles. It does take a few minutes for the new version to be available and distributed through Packagist, so the new version may not be immediately available to Composer.
- Note if you updated the base theme, you will need to make sure that Composer is aware of these changes. Add
--with-dependenciesto include any changes to the base theme in
composer.lock. Note that the base theme is included only as a dependency of this theme, not in
- You can then deploy these changes to the site code repository as described at https://github.com/govau/dta-website-rebuild/.