Environment setup
Add the following to your config.php, they will enable more efficient development:
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:
Code Block |
---|
$CFG->force_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 highling 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$
$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:
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.
The expectation is that Internally, we don't enforce when Prettier is run during local development, however code will be formatted with Prettier prior to opening a PR, and ideally, prior to committingduring 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
Code Block |
---|
// 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:
Code Block |
---|
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:
Code Block | ||
---|---|---|
| ||
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.