Customizing Umbraco Forms themes: finding the default CSS and JS

Frontend-teams willen zelf de markup van een formulier bepalen. Umbraco Forms maakt dat mogelijk met themes, maar één ding is makkelijk te missen: waar komen de CSS en JavaScript van het standaardtheme vandaan, zodat je ze kunt aanpassen?

Hoe Forms-themes werken

De basis:

• Maak een map Views/Partials/Forms/Themes/<your-theme>.
• Kopieer alleen de bestanden die je wilt wijzigen. Dat kan één bestand zijn, of het hele standaardtheme.
• Een view die niet in jouw themamap staat valt terug op het standaardtheme, dus je hoeft niet alles te kopiëren.
• Je theme verschijnt in de theme-kiezer, en je kunt er ook één kiezen als je een formulier rendert.
• Bewerk de standaardthemabestanden nooit rechtstreeks. Die wijzigingen gaan verloren bij de volgende Forms-upgrade.

Het ontbrekende stuk: de CSS en JS

De docs geven een zip van de partial views van het standaardtheme. De stylesheet en het script zitten niet in die zip. Ze worden als statische assets in het Forms-pakket geleverd, dus een frontend-developer die het project opent vindt niets om te kopiëren.

Er zijn twee manieren om ze te pakken:

1. Publiceer het project. Publiceer naar een schone map en kijk in de output.

dotnet publish -c Release -o output

De statische bestanden van het standaardtheme staan dan in:

output/wwwroot/App_Plugins/UmbracoForms/assets/themes/default

1. Kijk in je NuGet-cache. Dezelfde bestanden zitten in het pakket umbraco.forms.staticassets, in een map als staticwebassets/Assets/themes/default. Publiceren is meestal makkelijker, omdat de mappenstructuur dan duidelijker is.

Je eigen CSS en JavaScript koppelen

Als je de bestanden hebt gekopieerd en bewerkt, vertel je het formulier dat het ze vanuit je theme-views moet gebruiken:

Html.SetFormThemeCssFile("~/path/to/your/style.css");
Html.AddFormThemeScriptFile("~/path/to/your/umbracoforms.js");

Let op de methode-signatuur. In oudere documentatie krijgt de eerste helper het form-model als eerste argument, in de nieuwste documentatie niet. Check de docs voor de Forms-versie die je gebruikt.

Als je scripts wijzigt of toevoegt, kopieer dan Script.cshtml uit het standaardtheme en laat de scriptverwijzingen naar je eigen bestanden wijzen.

Twee dingen om te onthouden

• Bewaar de CSS-classes die de logica nodig heeft. Conditionele logica van Forms hangt van sommige classes af. Voeg je eigen classes toe, maar haal de bestaande niet weg.
• Upgrades zijn de echte kosten. Het lastigste is uitzoeken wat er tussen Forms-versies in het standaardtheme veranderde. De docs leveren het standaardtheme als zip voor meerdere versies, dus bewaar de versie waarmee je begon en vergelijk die met de nieuwe via een diff-tool.