This documentation is meant for developers using GitHub to create file-based themes. This feature is only available to Enterprise clients with their own cluster on Vanilla Cloud.
The easiest way to get started is to start from another theme. Foundation is a good theme to use, as it is what our theming system is based on. Note that you can create a custom theme that has almost no code because the way Foundation works is anything you haven't specified uses a default value. Setting nothing at all gives you the "Foundation theme" as it inherits everything.
"Directory based theme" mean the theme is loaded from files on disk. As soon as you edit your theme through the dashboard UI, a copy is saved to the data base. In your config, if your theme is loaded from a directory based theme, you'll see the name of the theme as the value of $Configuration['Garden']['CurrentTheme']. Example: $Configuration['Garden']['CurrentTheme'] = 'theme-foundation';. After modifications in the theme editor, you will see a number that corresponds to an entry in the database. Example: $Configuration['Garden']['CurrentTheme'] = '19';.
Vanilla Local Setup
https://success.vanillaforums.com/kb/articles/155-local-setup-quickstart
Creating a new file based theme
- Create a copy of
/addons/themes/theme-foundation in your repo. - Rename the folder and, most importantly, the values in
addon.json. You'll want to change the "key", "name", "description" and "authors" values to proper values. - On the file
package.json from you theme change the "name" to the same value you've set as the "key" in addon.json. - Symlink theme into vanilla/addons/themes.
- Use a relative symlink, so that the directory can be mounted in Docker.
Note that themes not built on Foundation get symlinked to /themes while Foundation themes are symlinked to /addons/themes/
On the root of your vanilla installation run composer install and you should now see your theme show up in the /theme/theme-settings page. If you do not have access to this page, you need to enable the ThemingAPI plugin. This is a proprietary plugin, so for local development, you can apply your theme manually if it doesn't show in your dashboard. You will need to set 3 config values:
$Configuration['Garden']['Theme'] = 'my-custom-theme';
$Configuration['Garden']['MobileTheme'] = 'my-custom-theme';
$Configuration['Garden']['CurrentTheme'] = 'my-custom-theme';
After adding or removing a theme, or changing an addon's meta-information, clear the associated index in the in the /cache directory, or run:
VANILLA_BUILD_DISABLE_AUTO_BUILD=true composer install
Building your theme
See documentation here: https://success.vanillaforums.com/kb/articles/166-vanillas-frontend-build-system
If you’re using directory-based development you may need to add the config parameter:
Example:
yarn build:dev --config vanilla.localhost/test.php
Styling your theme (forum)
https://success.vanillaforums.com/kb/articles/165-javascript-css-quickstart
By default, Vanilla will load [your-theme]/design/custom.css. That means you can either write your css there, or use your favourite css compiler to build there.
However, one of the big advantages to using the new theming system is dynamic variables. To take advantage of that, you'll need to use JS. You can add your styles in the forum entrypoint (i.e. [your-theme]/src/scripts/entries/forum.tsx).
We use https://typestyle.github.io/ to generate the styles. Note that we made some helper functions on top. cssOut is better than cssRule because it will trim trailing commas. For outputting colors, always use colorOut. For outputting numerical values with a unit use unit.
Styling your theme (React)
Newer, react components should never be targetted this way. Use the theme variables. The CSS classes are generated and are not guarenteed to stay consistent.
