Setting up your development environment

Overview

As with previous versions of Totara, Totara 13 needs some development environment setup to optimise your workflows. There are some changes between Totara 13 and earlier versions.

Config

Add the following settings to your ./config.php, they work independently from previous JS and Theme settings within config.php. They will enable more efficient development for working with the Tui framework:

$CFG->forced_plugin_settings['totara_tui'] = [
    'cache_js' => false, // Disable JS caching of Tui JS
	'cache_scss' => false, // Disable JS caching of Tui CSS
    'development_mode' => true, // Put Tui into development mode so that you get non-minified source
];

These settings are also available from within Totara's UI, by navigating to /admin/settings.php?section=totara_tui_settings.

Editor/IDE setup

VS Code

• Syntax highlighting: Install Vetur - to enable syntax highlighting for the lang-strings block follow the instructions on the Vetur website, adding a "lang-strings": "json" mapping, then running "Vetur: Generate grammar from vetur.grammar.customBlocks" and restarting VS Code
• Install Prettier and ESLint plugins (optional)

PhpStorm/WebStorm

• Vue.js syntax highlighting is built into PHPStorm
• The ESlint plugin is built in and supported out of the box
• Enable JSON syntax highlighting of the custom lang-strings block:
  • When looking at a .vue file with a language block
  • Right click one of the strings within the <lang-strings> tag
  • Click Show context actions
  • Click Inject language or reference
  • Type "JSON" and select the JSON option
• Install Prettier plugin (optional)
• To enable format-on-save (optional), go to Preferences > Tools > File watchers and create a new file watcher with the following options:
  • File type: Vue.js Template
  • Scope: Project Files
  • Program: $ProjectFileDir$/node_modules/.bin/prettier
  • Arguments: --write $FilePathRelativeToProjectRoot$

Atom

• Syntax highlighting: Install language-vue
• Install Prettier and ESLint plugins (optional)

Web browser extensions

There are two extensions available for developers that facilitate working with GraphQL and Vue.js technologies. They are:

• Apollo Client devtools (Chrome / Firefox)
• Vue.js devtools (Chrome / Firefox)

Adding either/both of these extensions to your web browser will add the relevant Tab inside Devtools.

Node

We have bumped our version of Node up to require >= 12, /package.json at the root of the Totara codebase contains specific version details for developer dependencies.

Docker

A number of Totara developers use Docker to isolate development environments. Totara maintains totara-docker-dev on Github specifically for this purpose. Follow the setup instructions on that repo for details. This setup is particularly useful when working with multiple Git branches or repositories that have different environment requirements, such as PHP, database or Node version.

Linting and formatting

We use Prettier to format code and components. This removes the need to discuss style in code review, improves efficiency and makes our code more consistent with third-party code and documentation.

Internally, we don't enforce when Prettier is run during local development, however code will be formatted with Prettier during our CI/CD checks, and so all of our PRs are formatted when they're ready for review by team members.

ESLint is used to catch issues that aren't related to formatting.

To run these linters, you have a few options:

• Install ESLint and Prettier plugins in your editor and configure it to format on save or on demand

• The following commands can be used to run lint

// The following will report any style problems
npm run tui-style

// The following will fix any style problems for you (handy huh!)
npm run tui-style-fix

• The following command will install a git hook that will automatically lint and format for you when you commit code:

npm run setup-hooks

Tips and known limitations

Windows developers might consider using the following combination of technologies: WSL2 + VS Code + Remote WSL extension.

Running into Javascript compilation issues? There might have been a Node dependency difference between your current working files and a different set. For example, if you regularly switch Git branches and between those branches you have different dependencies. A good catch-all command to run is:

npm ci

This will perform a clean installation of /node_modules based on the contents of /package.json located at the root of the Totara codebase.