Historically, files within Tui components have been organised by type – components, pages, and JavaScript. This is described below as the “v1 structure”.
With the advent of Vue 3 and composables, this structure does not make as much sense as it previously did, and we have introduced a feature-based “v2 structure”.
v2 structure
Supported in Totara 19+. tui.json must be in the correct location to enable support for the v2 structure (directly under the component folder, not inside src/).
totara_catalog/
tui.json
upgrade.txt
src/
explore/
ExplorePage.vue
use_filtered_results.js
__tests__/
filtering/
FilterBar.vue
tree.js
__tests__/
ui/
HeaderButtons.vue
__tests__/
Under src/, we have a folder for each feature. Each feature folder will typically contain page components (which should end in Page to be easily identified) and high level composables implementing page logic.
Try to keep this directory relatively clean. It should mostly just contain page components and their associated composables. Subdirectories should be added to group components and JS code comprising different parts of the feature.
Importing totara_catalog/explore/ExplorePage maps directly to the file under src/ – totara_catalog/src/explore/ExplorePage.vue.
The goals of this structure are as follows:
Easier to work with Vue 3 composables
Good developer experience by co-locating related files
Separation of logic from UI
Testability
The file structure is just a guide, but for consistency the structure described above should be followed unless there is a good reason not to.
When it is only possible for a component to contain a single feature due to its plugin type, for example a perform element or a block, the feature subdirectory should be omitted and its contents placed directly under src/. If it is possible for the component to contain multiple features, feature subdirectories should be used.
Migrating from v1 to v2
As there is currently no mechanism for handling file renames, it is suggested that existing code be left in place for now. New development within a component can happen in the v2 structure though. As long as the tui.json file is in the correct place (not inside src/), the v1 and v2 structures may coexist within the same Tui component.
New features should be built using the v2 structure.
v1 structure
Supported in Totara 13+.
core_mfa/
src/
tui.json
upgrade.txt
components/
factors/
FactorChooser.vue
pages/
Verify.vue
js/
constants.js
This is the original Tui component structure.
Pages (entry points) go under pages/, components go under components/ (no prescribed structure, but feature-based is suggested), and JavaScript goes in the js/ folder.