Power Pages React Web Templates mit JSON-Konfiguration

Inhalt

• Warum ein zentrales React Web Template in Power Pages sinnvoll ist
• Welche Power Pages Web Templates braucht eine React-Anwendung?
• Was enthält der technische Vertrag eines Power Pages React Hosts?
• Wie konfiguriert eine Power Pages Landingpage das React Widget?
• Wie nutzt die Power Pages Ergebnisseite dasselbe React Bundle?
• Wie validiert React die JSON-Konfiguration vor dem Start?
• Warum braucht ein Power Pages React Widget genau einen Host?
• Welche Vorteile bietet ein zentraler React Host in Power Pages?
• Ist defer in Power Pages echtes Lazy Loading?
• Welche Fehler treten bei React Web Templates in Power Pages auf?
• Wann lohnt sich ein React Web Template in Power Pages?
• Power Pages React Host: Erfahrungen aus dem Enterprise-Projekt

Warum ein zentrales React Web Template in Power Pages sinnvoll ist

Bei der Entwicklung einer komplexen Enterprise-Suche in Power Pages brauchte ich dieselbe React Anwendung an mehreren Stellen. Auf der Landingpage sollte sie Suchfilter sammeln und anschließend zur Ergebnisseite navigieren. Auf der Ergebnisseite sollte sie den Zustand aus der URL lesen, die Browserhistorie aktualisieren und neue Suchergebnisse an weitere Komponenten verteilen.

Ein schneller Ansatz wäre gewesen, Container, Script und Initialisierungslogik in jede Seite zu kopieren. Technisch hätte das zunächst funktioniert. Jede weitere Variante hätte aber denselben technischen Rahmen erneut enthalten. Bundle Pfad, Mount Point, Abhängigkeiten und Seitenverhalten wären miteinander vermischt worden.

Ich habe diese Verantwortlichkeiten deshalb getrennt. Ein zentrales Web Template hostet die React Anwendung. Die aufrufende Seite übergibt nur eine kleine JSON-Konfiguration.

Das Ergebnis ist kein allgemeines React Muster. Es ist ein konkreter Power Pages Vertrag zwischen Liquid, HTML und einer isolierten Frontend-Anwendung.

Der Beitrag ist Teil meiner Serie zur Architektur einer komplexen Enterprise-Suche in Power Pages. Dort ordne ich diesen Host Vertrag in den vollständigen Datenfluss zwischen React, Power Pages Server Logic und Dataverse ein.

Welche Power Pages Web Templates braucht eine React-Anwendung?

Power Pages Web Templates eignen sich für wiederverwendbare technische Bausteine. Microsoft beschreibt Web Templates als zentrale Metadatensätze für Liquid Inhalte, die in andere Templates eingebunden werden können. Die Dokumentation zu Power Pages Web Templates bildet dafür die Plattformgrundlage.

Ich teile die Lösung in zwei Rollen:

1. Das Host Web Template besitzt den Mount Point, das Widget Merkmal, die Konfigurationsübergabe und den Bundle Pfad.
2. Das seitenspezifische Web Template besitzt den fachlichen Kontext und erzeugt die passende Laufzeitkonfiguration.

Die Verbindung besteht aus einem benannten Liquid Parameter. Der offizielle include Tag kann Parameter an das eingebundene Template übergeben. Microsoft dokumentiert dieses Verhalten in den Liquid Template Tags für Power Pages.

Detailseiten verwenden einen zweiten Power Pages Mechanismus. Der dokumentierte serverlogic Tag ruft eine benannte Server Logic Funktion während des Renderings auf und stellt das geparste Ergebnis unter result.data bereit.

Der Beitrag zur Power Pages Detailsuche mit GUID und Liquid zeigt diesen Aufruf für Center- und Flächenseiten. Das React Host Template und das Detail Web Template bleiben getrennte Bausteine.

React kennt dadurch keine Sitemarker, Template Namen oder Liquid Objekte. Das Seitentemplate kennt keine internen React Komponenten, Services oder State Regeln.

Diese Grenze macht das Widget flexibel. Sie verhindert zugleich, dass Flexibilität zu unkontrollierter Konfiguration wird.

Was enthält der technische Vertrag eines Power Pages React Hosts?

Der generalisierte Host bleibt bewusst klein:

{% comment %} Central host for one React widget instance. The parent page must load WebAPIAJAX first. {% endcomment %}

<div data-widget="portal-search" data-config="{{ config | escape }}"></div>

<script src="/portal-search.js" defer></script>

Der Host übernimmt vier Aufgaben:

1. data-widget liefert einen stabilen Selektor für die Anwendung.
2. data-config transportiert die JSON-Konfiguration.
3. escape schützt den HTML Attributkontext.
4. Der Script Pfad bleibt an einer zentralen Stelle definiert.

Das gebaute Bundle liegt als Web File im Portal. Die Microsoft Dokumentation zu Power Pages Web Files beschreibt diese Dateien als Datensätze, deren Inhalt über Dataverse Notizanhänge gespeichert wird. In meinem Beitrag über lokale Ressourcen in Power Pages zeige ich die praktische Anlage und Bereitstellung.

Der Host setzt voraus, dass die globale Power Pages Abhängigkeit WebAPIAJAX bereits geladen wurde. Diese Voraussetzung bleibt außerhalb des Widgets dokumentiert. Das Host Template lädt keine zweite Kopie einer globalen Infrastruktur.

Wie konfiguriert eine Power Pages Landingpage das React Widget?

Auf der Landingpage soll die Suche noch keine vollständige Ergebnissuche starten. Sie sammelt gültige Filter und navigiert beim Absenden zur Ergebnisseite.

Das Seitentemplate benötigt dafür nur den Zielpfad und den Modus:

{% assign search_results_marker = sitemarkers['Search Results'] %} {%- capture search_config -%}
{"type":"navigate","targetUrl":"{{ search_results_marker.url }}"} {%- endcapture -%} {% include 'Portal Search Host',
config: search_config %}

Der Sitemarker bleibt in Liquid. React erhält nur die fertige URL.

Diese Trennung ist wichtig. Das React Projekt muss keine kundenspezifischen Sitemarker kennen. Eine Power Pages Seite kann ihr Ziel ändern, ohne dass dafür ein neues Frontend Bundle gebaut werden muss.

Das Seitentemplate lädt auch keine eigene Kopie von portal-search.js. Es nutzt immer denselben Host.

Wie nutzt die Power Pages Ergebnisseite dasselbe React Bundle?

Auf der Ergebnisseite gelten andere Regeln. Die Anwendung muss Filter aus der URL wiederherstellen. Eine neue Suche soll einen Eintrag in der Browserhistorie erzeugen. Weitere Komponenten sollen auf akzeptierte Suchänderungen reagieren können.

Die Konfiguration sieht deshalb anders aus:

{%- capture search_config -%} {"type":"update-url","historyMode":"push","eventName":"portal:search-changed"} {%-
endcapture -%} {% include 'Portal Search Host', config: search_config %}

Das Bundle bleibt identisch. Nur der validierte Laufzeitmodus ändert sich.

Der optionale eventName benennt nur das Zustands Event. Der Beitrag über Power Pages React CustomEvents erklärt den Unterschied zum festen Ergebnis Event und die Listener Verträge.

Wie navigate und update-url Filter serialisieren, fremde Query Parameter erhalten und Browserhistorie wiederherstellen, dokumentiert der folgende Beitrag über URL Zustand in der Power Pages React Suche.

Damit vermeide ich getrennte Builds für Landingpage und Ergebnisseite. Der Unterschied lebt nicht in kopierter Initialisierungslogik. Er lebt in einem kleinen, dokumentierten Konfigurationsvertrag.

Dieses Muster lässt sich auch auf andere Widgets übertragen. Ein Konfigurator kann einen kompakten und einen vollständigen Modus besitzen. Ein mehrstufiger Workflow kann je nach Seite unterschiedliche Startschritte erhalten. Ein Dashboard kann einen eigenen Event Namen oder eine feste Datenansicht bekommen.

Wie validiert React die JSON-Konfiguration vor dem Start?

Eine JSON-Konfiguration ist nur dann belastbar, wenn die Anwendung sie als nicht vertrauenswürdige Eingabe behandelt.

Mein Bootstrap liest data-config, parst den Wert als unknown und prüft anschließend den konkreten Modus:

const rawConfig = host.dataset.config;

if (!rawConfig) {
  throw new Error('Widget configuration is missing.');
}

const parsed: unknown = JSON.parse(rawConfig);

if (!isConfigObject(parsed)) {
  throw new Error('Widget configuration must be an object.');
}

if (parsed.type === 'navigate') {
  return readNavigateConfig(parsed);
}

if (parsed.type === 'update-url') {
  return readUpdateUrlConfig(parsed);
}

throw new Error('Unsupported widget configuration type.');

Der navigate Modus benötigt eine nicht leere targetUrl. Der update-url Modus akzeptiert nur den vorgesehenen historyMode. Ein optionaler Event Name muss eine Zeichenkette sein.

Fehlt ein Pflichtwert, startet die Anwendung nicht mit einem erfundenen Standard. Sie meldet einen klaren Fehler.

Diese Entscheidung spart später Zeit. Ein falsch geschriebener Modus fällt beim Laden auf. Er erzeugt kein scheinbar funktionierendes Widget mit falschem Verhalten.

Diese Prüfung schützt den Startvertrag des Widgets. Sie macht Browserdaten nicht zu einer vertrauenswürdigen Backend Eingabe.

Die verbindliche Power Pages Server Logic Sicherheitsgrenze prüft den Request deshalb erneut, leitet Autorisierung aus der Portalsitzung ab und baut erlaubte OData Parameter erst auf dem Server.

Warum braucht ein Power Pages React Widget genau einen Host?

Das Bundle sucht nicht nach einem beliebigen root Element. Es sucht gezielt nach seinem Widget Vertrag:

const hosts = document.querySelectorAll<HTMLElement>('[data-widget="portal-search"]');

if (hosts.length !== 1) {
  throw new Error('Exactly one Portal Search host element is required.');
}

Kein Host ist ein Integrationsfehler. Mehrere Hosts sind ebenfalls ein Integrationsfehler.

Diese Regel ist absichtlich eng. Das Bundle startet genau eine Anwendung und erhält genau eine Konfiguration. Falls eine Seite später mehrere Instanzen benötigt, braucht dieser Fall einen eigenen Instanzvertrag. Eine stillschweigende Schleife über beliebig viele Container würde diese Entscheidung nur verschieben.

Welche Vorteile bietet ein zentraler React Host in Power Pages?

Das Muster reduziert nicht nur doppelten Code. Es verbessert mehrere Teile der Lieferung.

1. Zentrale Änderungen
   Ein neuer Bundle Pfad oder ein zusätzlicher gemeinsamer Include wird einmal im Host geändert.

2. Kleine Seitentemplates
   Jede Seite beschreibt nur ihr fachliches Verhalten.

3. Unabhängige Frontend-Entwicklung
   React arbeitet mit typisierten Konfigurationen statt mit Liquid Objekten.

4. Klare Fehlerbilder
   Fehlende Hosts und ungültige Konfigurationen brechen sichtbar ab.

5. Weniger Build Varianten
   Ein Bundle unterstützt mehrere Portal-Kontexte.

6. Bessere Übergabe
   Ein Power Pages Team erkennt im Consumer Template sofort, welcher Modus aktiv ist.

7. Gezielte Tests
   Jeder Konfigurationstyp kann unabhängig geprüft werden.

Für den täglichen Build und Upload nutze ich zusätzlich einen automatisierten PAC CLI Workflow. Das Host Muster und der Deployment-Prozess lösen unterschiedliche Aufgaben. Der Host strukturiert die Laufzeit. PAC CLI strukturiert die Bereitstellung.

Ist defer in Power Pages echtes Lazy Loading?

Das Script im Host nutzt defer. Der Browser kann die Datei bereits während des HTML Parsens herunterladen. Die Ausführung wartet bis das Dokument geparst wurde.

Das ist kein Lazy Loading nach Sichtbarkeit oder Nutzerinteraktion. Die Dokumentation zum defer Attribut beschreibt dieses Verhalten im Detail.

Für dieses Widget ist die verzögerte Ausführung passend. Der Host ist beim Start vorhanden und die Anwendung soll auf der Seite verfügbar sein.

Falls ein Bundle erst nach einem Klick oder beim Erreichen eines sichtbaren Bereichs geladen werden soll, braucht es einen separaten Loader. Das gezeigte Host Muster behauptet diese Art von Lazy Loading nicht.

Welche Fehler treten bei React Web Templates in Power Pages auf?

Ein kleiner Host Vertrag kann trotzdem falsch eingesetzt werden. Diese Punkte prüfe ich bei jeder Einbindung:

Die letzte Regel betrifft auch Spracheinstellungen. In diesem Suchwidget kommt die Sprache aus dem lang Attribut des HTML Dokuments. Ein zusätzliches Feld language im JSON würde das Verhalten nicht ändern.

Der Deep Dive editierbare Power Pages Konfiguration zwischen Liquid, React und JavaScript erweitert diesen kleinen Laufzeitvertrag um ein gemeinsames Branchen JSON, stabile IDs, vollständige Cluster-Prüfung und getrennte Browser- sowie Server-Allowlists.

Wann lohnt sich ein React Web Template in Power Pages?

Ich nutze diesen Ansatz für Funktionen mit eigenem Zustand und mehreren Portal-Kontexten.

Geeignete Beispiele sind:

1. Komplexe Suchen
2. Konfiguratoren
3. Mehrstufige Workflows
4. Dashboards
5. Widgets mit Navigation und Ergebnisansicht

Für ein einfaches Standardformular oder eine kleine statische Ergänzung wäre diese Struktur unnötig. Dort sollte Power Pages die Aufgabe mit seinen nativen Mitteln lösen.

Pro-Code ist kein Standardweg für jede Seite. Es ist eine gezielte Entscheidung für Anforderungen, bei denen Isolation, Zustandslogik oder Wiederverwendung den zusätzlichen Aufbau rechtfertigen.

Power Pages React Host: Erfahrungen aus dem Enterprise-Projekt

Ich habe dieses Host und Konfigurationsmuster für eine komplexe Enterprise-Suche umgesetzt. Die Anwendung unterstützt zwei Laufzeitmodi, Auto-Suggest, URL-Zustand, Browserhistorie und entkoppelte Ergebnisverbraucher.

Die öffentliche Fallstudie zur Enterprise-Suche in Power Pages zeigt den größeren Zusammenhang. Dort beschreibe ich auch die Sicherheitsgrenze über Power Pages Server Logic und die geschützte Dataverse Custom API.

Der wichtigste Teil dieses Beitrags bleibt kleiner. Ein zentrales Host Web Template besitzt technische Infrastruktur. Seitenspezifische Web Templates liefern nur validierte Konfiguration.

Du arbeitest an einem Power Pages Workflow, der auf mehreren Seiten unterschiedlich reagieren muss? Im Power Pages Pro-Code Bereich zeige ich, wie ich Architektur, Sicherheitsgrenzen und Umsetzungsrisiken vor der Entwicklung kläre.