Installation og konfiguration

Installation

Installér NuGet-pakken i jeres Umbraco-webprojekt:

dotnet add package Septima.Widget

Tilføj mindst WidgetAdminUrl til konfigurationen (se nedenfor), og byg og start sitet. Pluginnet registreres automatisk – der skal ikke tilføjes kode i Program.cs. Backoffice-filerne serveres fra /App_Plugins/SeptimaWidget.

Opdatering sker som for alle andre NuGet-pakker:

dotnet add package Septima.Widget --version <ny-version>

Konfiguration

Pluginnet konfigureres i appsettings.json (eller via miljøvariabler) under sektionen Septima:Widget.

{
  "Septima": {
    "Widget": {
      "WidgetAdminUrl": "https://<jeres-widgetadmin>",
      "NewWidgetPrefix": "umbraco",
      "DefaultHeight": "400px",
      "AutoInjectScript": true
    }
  }
}

Normalt er WidgetAdminUrl den eneste adresse, der skal angives. Se Version og adresser fra Widget Admin.

Nøgle	Påkrævet	Standard	Beskrivelse
WidgetAdminUrl	Ja	–	Adressen på jeres Widget Admin-instans. Pluginnet læser version og adresser herfra, og den bruges af knapperne Åbn i Widget Admin og Opret ny widget.
ConfigBaseUrl	Nej	Fra Widget Admin (baseUrl)	Overstyrer den offentlige adresse, hvor Widget Admin publicerer konfigurationerne (base-url i Widget Admins internal/admin-config.json). Widget-URL'en bliver {ConfigBaseUrl}/config/{navn}.json. Ændres den, skal eksisterende widgets i Rich Text Editoren opdateres – se Redigér en widget.
PreviewBaseUrl	Nej	Fra Widget Admin (dataPublicUrl)	Overstyrer adressen, som kun forhåndsvisningen i backoffice bruger til at læse den senest gemte konfiguration straks, typisk Widget Admins spejl {WidgetAdminUrl}/data. Konfigurationen hentes fra {PreviewBaseUrl}/config/{navn}.json. Er adressen tom, eller svarer den ikke med gyldig JSON, bruges ConfigBaseUrl. Hjemmesiden bruger altid ConfigBaseUrl. Se Forhåndsvisning.
WidgetScriptUrl	Nej	{ConfigBaseUrl}/widget.js, hvis ConfigBaseUrl er angivet, ellers fra Widget Admin (widgetScriptUrl)	Overstyrer Septima Widget-scriptet, der indlæses på hjemmesiden – samme script som i Widget Admins CMS-kode.
NewWidgetPrefix	Nej	umbraco	Præfiks for genererede navne til nye widgets, fx umbraco-k3x9q2.
DefaultHeight	Nej	400px	Standardhøjde (vilkårlig CSS-længde, fx 60vh) for nye widgets. Tom værdi betyder ingen inline-højde.
AutoInjectScript	Nej	true	Indsæt automatisk widget-scriptet før </body> på sider, der indeholder en widget. Se Visning på hjemmesiden.

Som miljøvariabler (fx i Docker eller Azure App Service) skrives nøglerne med dobbelt underscore:

Septima__Widget__WidgetAdminUrl=https://<jeres-widgetadmin>
Septima__Widget__AutoInjectScript=false

Version og adresser fra Widget Admin

Hvilken version (kanal) af Septima Widget der bruges, angives ét sted: som widget-version i Widget Admin-instansens admin-config.json. Pluginnet har ingen indbygget version eller adresse og peger aldrig på Septimas test-instans af sig selv.

Pluginnet læser i stedet GET {WidgetAdminUrl}/api/public/info på serveren (uden login). Svaret indeholder bl.a. widgetVersion, baseUrl, widgetScriptUrl, widgetApiUrl og dataPublicUrl, og pluginnet udleder:

Indstilling	Fra Widget Admin
ConfigBaseUrl	baseUrl
WidgetScriptUrl	widgetScriptUrl (bygget med widget-version)
PreviewBaseUrl	dataPublicUrl
WidgetAPI-modulet i forhåndsvisningen	widgetApiUrl

Svaret caches i 5 minutter og opdateres i baggrunden. Fejler en opdatering, bruges de seneste gode værdier, og der prøves igen efter 30 sekunder. Skiftes widget-version i Widget Admin, slår det derfor igennem i Umbraco inden for få minutter – uden ny konfiguration eller genstart.

Værdier, der er angivet i Septima:Widget, vinder altid over dem fra Widget Admin. Det gør det muligt at bruge en ældre Widget Admin uden /api/public/info: angiv så ConfigBaseUrl (og evt. PreviewBaseUrl og WidgetScriptUrl) selv.

Tip: Kender I ikke jeres ConfigBaseUrl? Åbn en widget i Widget Admin og kopiér CMS-kode. Adressen før /config/…json er jeres ConfigBaseUrl.

Kan Widget Admin ikke nås, og er adresserne ikke angivet:

• skrives en tydelig advarsel i loggen;
• viser dialogen og egenskabseditoren i backoffice advarslen, og widgets kan ikke indsættes;
• vises widget-elementerne stadig på hjemmesiden, men scriptet indsættes ikke.

Backoffice henter den gældende konfiguration fra GET /umbraco/management/api/v1/septima-widget/config (kræver login i backoffice). Svaret viser de effektive adresser, widgetVersion, hvor hver adresse kommer fra (sources: configured, discovered eller none), status for opslaget i Widget Admin (discovery) og eventuelle advarsler (warnings).

Test-instansen

Septimas eget test-site for pluginnet er sat op mod Septimas test-instans:

Nøgle	Værdi
WidgetAdminUrl	https://widgetadmin3.k8s-test-132.septima.dk

Test-instansen bruger widget-version dev. Test-sitet angiver kun WidgetAdminUrl; de øvrige adresser hentes fra /api/public/info.