Hi there Michael, good questions, and they'll be covered with documentation shortly - we're just at the tail end of finishing those off. As they're not published yet, I'll answer your questions below (answers mostly from the docs):
> Should I create a new theme with the parent themes legacy and base or should I choose the ventura theme as parent? Ventura itself uses both of these themes as parents.
You can do either, the Ventura theme mostly does a handful of things:
- Overrides colours that are defined in `/client/tui/src/global_styles/*`
- Has a generated `css_variables.json` file that describes the variables that it uses, and relationships between them
- Provides an entry point for the "Theme Settings" UI in the Appearance Admin menu
- Provides some default images, stored in `/server/theme/ventura/`
- Serves as an example of a theme that you can inherit from, or build your own
To inherit from Ventura, you'll need (in `/server/`):
- `server/theme/mytheme/config.php`
- `server/theme/mytheme/lang/en/mytheme.php`
- `server/theme/mytheme/version.php`
Yes, your theme inheritance chain should be: `$THEME->parents = ['ventura', 'legacy', 'base'];`
If you want to enable the Theme Settings page for your custom theme, you'll also need to copy the following files from Ventura:
- index.php
- lib.php
- settings.php
In all instances apart from the theme inheritance chain, be sure to use your theme's name, not Ventura .
Then, for `/client/`, this can be done in one step by running `npm run tui-init theme_mytheme vendor` (where `vendor` is a unique string identifying your organisation. Lowercase is suggested for ease of typing - Totara internal components use "totara" for example).
At this point you're now ready to start customising.
In order to customise component CSS, template, or functionality, you can add a component file in a special location where it will be picked up by the override system.
To inherit from Legacy only, follow the same steps as above, but remove "ventura" from the array in config.php.
After completing the instructions above, you can add your theme customisations in the following places:
- `client/component/my_theme/global_styles/_variables.scss` (variable overrides)
- `client/component/my_theme/global_styles/static.scss` (global CSS rules)
You can also break up your variables or global CSS rules into multiple files and Use the `@import` syntax to include them. `@import 'my_theme/xyz'` maps to `client/component/my_theme/global_styles/xyz`. You can see this in action at `client/component/tui/src/global_styles/_variables.scss`.
Any Vue component can be extended in a theme by creating a file in the right folder.
The pattern for override files is: `client/component/theme_(themename)/src/(subfolder)/overrides/(original client/component/* subfolder)/(rest of path)`
For example, if the component you want to extend is: `tui/components/buttons/Button`, you would create `client/src/theme_mytheme/components/overrides/tui/buttons/Button.vue`.
> I would also like to know if legacy will be supported for older themes for a longer period of time, since ventura itself is also based on them?
Legacy is a "stopgap" theme, for visual compatibility between Totara Learn and Totara Engage/Totara Perform. It will likely be around for a while, as there is so much of Totara Learn that we could convert, we can't convert it all in one go, so Legacy will be needed to continue bridging visual consistency.
> Do I have to use the new functions and components in the /client/ folder or can I create a theme as before?
If you're only touching CSS, then you could create a theme only in `/server/` and supply specific CSS overrides following whatever file structure you want. You can do this because although the Tui framework components are all isolated in their construction - ultimately all the CSS is output onto the page in the global scope. So long as you're working with the CSS cascade and specificity concepts correctly, you should be able to override selectors.
As soon as you want to make use of the benefits of overriding or extending markup, javascript etc, and the benefits of expressing variables in the "theme Settings" UI, then working within our intended implementation will cause less friction.
