Theming Quickstart - HL Vanilla Community
<main> <article class="userContent"> <div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/XCRAA9SAV3ET/microsoftteams-image-288-29.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/XCRAA9SAV3ET/microsoftteams-image-288-29.png" alt="MicrosoftTeams-image (8).png" height="108" width="1356" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <p><strong><em>This documentation is meant for developers using GitHub to create file-based themes. This feature is only available to </em>Enterprise</strong><em> clients with their own cluster on Vanilla Cloud. </em></p><p>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.</p><p>"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 <code class="code codeInline" spellcheck="false" tabindex="0">$Configuration['Garden']['CurrentTheme']</code>. Example: <code class="code codeInline" spellcheck="false" tabindex="0">$Configuration['Garden']['CurrentTheme'] = 'theme-foundation';</code>. After modifications in the theme editor, you will see a number that corresponds to an entry in the database. Example: <code class="code codeInline" spellcheck="false" tabindex="0">$Configuration['Garden']['CurrentTheme'] = '19';</code>.</p><h2 data-id="vanilla-local-setup">Vanilla Local Setup</h2><p><a href="https://success.vanillaforums.com/kb/articles/155-local-setup-quickstart" rel="nofollow noreferrer ugc">https://success.vanillaforums.com/kb/articles/155-local-setup-quickstart</a></p><h2 data-id="creating-a-new-file-based-theme">Creating a new file based theme</h2><ol><li>Create a copy of <code class="code codeInline" spellcheck="false" tabindex="0">/addons/themes/theme-foundation</code> in your repo.</li><li>Rename the folder and, most importantly, the values in <code class="code codeInline" spellcheck="false" tabindex="0">addon.json</code>. You'll want to change the "key", "name", "description" and "authors" values to proper values.</li><li>On the file <code class="code codeInline" spellcheck="false" tabindex="0">package.json</code> from you theme change the "name" to the same value you've set as the "key" in <code class="code codeInline" spellcheck="false" tabindex="0">addon.json</code>.</li><li>Symlink theme into vanilla/addons/themes.<ul><li>Use a <strong>relative</strong> symlink, so that the directory can be mounted in Docker.</li></ul></li></ol><p>Note that themes not built on Foundation get symlinked to <code class="code codeInline" spellcheck="false" tabindex="0">/themes</code> while Foundation themes are symlinked to <code class="code codeInline" spellcheck="false" tabindex="0">/addons/themes/</code></p><p>On the root of your vanilla installation run <code class="code codeInline" spellcheck="false" tabindex="0">composer install</code> and you should now see your theme show up in the <code class="code codeInline" spellcheck="false" tabindex="0">/theme/theme-settings</code> 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:</p><pre class="code codeBlock" spellcheck="false" tabindex="0">$Configuration['Garden']['Theme'] = 'my-custom-theme'; $Configuration['Garden']['MobileTheme'] = 'my-custom-theme'; $Configuration['Garden']['CurrentTheme'] = 'my-custom-theme'; </pre><p>After adding or removing a theme, or changing an addon's meta-information, clear the associated index in the in the <code class="code codeInline" spellcheck="false" tabindex="0">/cache</code> directory, or run:</p><pre class="code codeBlock" spellcheck="false" tabindex="0">VANILLA_BUILD_DISABLE_AUTO_BUILD=true composer install </pre><h2 data-id="building-your-theme">Building your theme</h2><p>See documentation here: <a href="https://success.vanillaforums.com/kb/articles/166-vanillas-frontend-build-system" rel="nofollow noreferrer ugc">https://success.vanillaforums.com/kb/articles/166-vanillas-frontend-build-system</a></p><p>If you’re using directory-based development you may need to add the config parameter: </p><p>Example:</p><p><code class="code codeInline" spellcheck="false" tabindex="0">yarn build:dev --config vanilla.localhost/test.php</code></p><h2 data-id="styling-your-theme-(forum)">Styling your theme (forum)</h2><p><a href="https://success.vanillaforums.com/kb/articles/165-javascript-css-quickstart" rel="nofollow noreferrer ugc">https://success.vanillaforums.com/kb/articles/165-javascript-css-quickstart</a></p><p>By default, Vanilla will load <code class="code codeInline" spellcheck="false" tabindex="0">[your-theme]/design/custom.css</code>. That means you can either write your css there, or use your favourite css compiler to build there.</p><p>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 <a href="https://success.vanillaforums.com/kb/articles/166-vanillas-frontend-build-system#source-files-and-entries" rel="nofollow noreferrer ugc">forum entrypoint (i.e. </a><a href="https://success.vanillaforums.com/kb/articles/166-vanillas-frontend-build-system#source-files-and-entries" rel="nofollow noreferrer ugc"><code class="code codeInline" spellcheck="false" tabindex="0">[your-theme]/src/scripts/entries/forum.tsx</code></a><a href="https://success.vanillaforums.com/kb/articles/166-vanillas-frontend-build-system#source-files-and-entries" rel="nofollow noreferrer ugc">)</a>.</p><p>We use <a href="https://typestyle.github.io/" rel="nofollow noreferrer ugc">https://typestyle.github.io/</a> to generate the styles. Note that we made some helper functions on top. <code class="code codeInline" spellcheck="false" tabindex="0">cssOut</code> is better than <code class="code codeInline" spellcheck="false" tabindex="0">cssRule</code> because it will trim trailing commas. For outputting colors, always use <code class="code codeInline" spellcheck="false" tabindex="0">colorOut</code>. For outputting numerical values with a unit use <code class="code codeInline" spellcheck="false" tabindex="0">unit</code>. </p><h3 data-id="styling-your-theme-(react)">Styling your theme (React)</h3><p>Newer, react components should <strong>never</strong> be targetted this way. Use the theme variables. The CSS classes are generated and are not guarenteed to stay consistent.</p> </article> </main>