Messbarer Erfolg «10 Punkte-Checkliste für ein zukunftssicheres CMS» White Paper
Messbarer Erfolg - White Paper

Ein Widget erweitern

Wie auch in der Einführung zur Scrivito Example Application erwähnt, werden alle Widget-Typen mittels Dateien definiert, die im Repository unter „src/Widgets” liegen. Um zu zeigen, wie leicht sich Widgets erweitern lassen, fügen wir in dieser Anleitung zum Headline-Widget eine Option zur Auswahl der Hintergrundfarbe solcher Widgets hinzu.

In der Example App sieht die HeadlineWidget-Modellklasse folgendermaßen aus:

src/Widgets/HeadlineWidget/HeadlineWidgetClass.js
import * as Scrivito from "scrivito";

const HeadlineWidget = Scrivito.provideWidgetClass("HeadlineWidget", {
  attributes: {
    headline: "string",
    level: ["enum", { values: ["h1", "h2", "h3", "h4", "h5", "h6"] }],
    style: ["enum", { values: ["h1", "h2", "h3", "h4", "h5", "h6"] }],
    alignment: ["enum", { values: ["left", "center", "right"] }],
    showDividingLine: ["enum", { values: ["yes", "no"] }],
    showMargin: ["enum", { values: ["yes", "no"] }],
  },
  extractTextAttributes: ["headline"],
});

export default HeadlineWidget;

Die Example App macht zum Zwecke des Stylings von Bootstrap Gebrauch. Wir beschränken uns hier auf die Farben, die von Bootstrap zur Verfügung gestellt werden, und bieten sie den Redakteuren als optionale Hintergrundfarben für Überschriften an.

In der obigen Definition der  HeadlineWidget-Klasse ist zu sehen, dass es bereits zwei Attribute gibt, mit denen Redakteure einen von mehreren Werten auswählen können, level und style. Bei ihnen handelt es sich um Attribute vom Typ enum, mit denen man keinen oder einen einzelnen Wert auswählen kann, im Gegensatz zum multienum-Typ zur Auswahl mehrerer Werte.

Zur Erweiterung eines Widgets um Funktionalität oder Styling-Optionen sind in der Regel drei Schritte erforderlich: Zuerst wird das Attribut hinzugefügt, dann wird es bearbeitbar gemacht, und schließlich wird dessen Wert beim Rendern der Widget-Instanzen berücksichtigt.

Das Attribut hinzufügen

Das neue Attribut hat den Namen backgroundColor. Fügen Sie es zur Liste der Attribute hinzu, wie hier direkt unterhalb von headline:

src/Widgets/HeadlineWidget/HeadlineWidgetClass.js
import * as Scrivito from 'scrivito';

Scrivito.provideWidgetClass('HeadlineWidget', {
  attributes: {
    headline: 'string',
    backgroundColor: ['enum', { values: ['primary', 'success', 'info', 'warning', 'danger'] }],
    level: ['enum', { values: ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'] }],
    // ...
  },
});

Wir haben von den oben erwähnten Bootstrap-CSS-Klassennamen (bg-primary usw.) das Präfix bg- entfernt, damit die obige Attributdefinition etwas kürzer wird und wir später noch zeigen können, wie man eine solche konstante Zeichenkette beim Rendern wieder hinzufügen kann.

Das Attribut bearbeitbar machen

Damit das neue Attribut in den Eigenschaften der Headline-Widgets auftaucht und genutzt werden kann, geben wir es im provideEditingConfig-Aufruf für die HeadlineWidget-Klasse an. Hier befindet sich die entsprechende Spezifikation gleich am Anfang der attributes-Liste:

src/Widgets/HeadlineWidget/HeadlineWidgetEditingConfig.js
import * as Scrivito from 'scrivito';

Scrivito.provideEditingConfig('HeadlineWidget', {
  title: 'Headline',
  attributes: {
    backgroundColor: {
      title: 'Background color',
      description: 'The background color of the headline text',
    },
    // style, level, …
  },
  // …
  properties: ["backgroundColor", "style", "level", "alignment", "showDividingLine", "showMargin"],
});

Vergessen Sie nicht, das Attribut auch unten zu der properties-Liste hinzuzufügen. Diese Liste gibt an, welche Attribute auf dem „Allgemein“-Tab in den Widget-Eigenschaften erscheinen sollen.

Anzeigetitel für Aufzählungswerte festlegen

Sie können Anzeigewerte für jedes Element eines enum-Aufzählungsattributs angeben, um sie benutzerfreundlicher zu machen. So bildet beispielsweise das style-Attribut seine Werte (values) „h1“ bis „h6“ auf „Heading *“-Titel ab:

src/Widgets/HeadlineWidget/HeadlineWidgetEditingConfig.js (continued)
// ...
  attributes: {
    style: {
      title: 'Style',
      description: 'Size and font of this headline. Default: Heading 1',
      values: [
        { value: 'h1', title: 'Heading 1' },
        { value: 'h2', title: 'Heading 2' },
        { value: 'h3', title: 'Heading 3' },
        { value: 'h4', title: 'Heading 4' },
        { value: 'h5', title: 'Heading 5' },
        { value: 'h6', title: 'Heading 6' },
      ],
    },
// ...

Attribute initialisieren

Darüber hinaus können Sie Attribute in dem Moment initialisieren, in dem sie für ein Widget (oder eine Seite) angelegt werden. Hierfür gibt es das Schlüsselwort initialContent in der Funktion Scrivito.provideEditingConfig. Verwenden Sie es folgendermaßen, um den Wert des Attributs backgroundColor auf primary zu setzen, sobald ein neues Headline-Widget auf einer Seite platziert wird:

src/Widgets/HeadlineWidget/HeadlineWidgetEditingConfig.js (continued)
// ...
  attributes: {
    backgroundColor: {
      title: 'Background color',
      description: 'The background color of the headline text',
    },

    // style, level, ...
  },

  initialContent: {
    backgroundColor: 'primary',
  },
// ...

Öffnet man jetzt den Dialog mit den Eigenschaften eines Headline-Widgets, ist dort das neue Attribut aufgeführt und kann zur Auswahl einer Hintergrundfarbe verwendet werden.

Allerdings hat die Auswahl einer Farbe noch keine Wirkung, weil der Attributwert noch nicht als Style gerendert wird.

Den Attributwert rendern

Seiten und die Widgets darauf werden von React-Komponenten gerendert, die durch einen Aufruf von provideComponent mit der jeweiligen Seiten- oder Widget-Klasse verbunden wurden. Beim HeadlineWidget (und vielen anderen Widgets) besteht die Hauptaufgabe der Komponente darin, die als Attributwerte hinterlegten CSS-Klassennamen zusammenzutragen und als className-Prop in einem Aufruf von Scrivito.ContentTag zu verwenden. Dieser Aufruf rendert dann den betreffenden Inhalt (aus einem anderen Attribut, hier headline).

src/Widgets/HeadlineWidget/HeadlineWidgetComponent.js
import * as React from 'react';
import * as Scrivito from 'scrivito';

Scrivito.provideComponent('HeadlineWidget', ({ widget }) => {
  const style = widget.get('style') || 'h1';
  const level = widget.get('level') || style;
  const classNames = [style];
  if (widget.get('alignment')) {
    classNames.push(`text-${widget.get('alignment')}`);
  }
  if (widget.get('showDividingLine') === 'yes') {
    classNames.push('border-bottom');
  }
  if (widget.get('showMargin') === 'no') {
    classNames.push('no-margin');
  }

  return <Scrivito.ContentTag
    tag={ level }
    content={ widget }
    attribute="headline"
    className={ classNames.join(' ') }
  />;
});

Lassen Sie uns nun die Hintergrundfarbe, d.h. den Wert von backgroundColor zum classNames-Array hinzufügen. Dies ist nur erforderlich, wenn für die Überschrift tatsächlich eine Hintergrundfarbe ausgewählt wurde. In diesem Fall muss dann aber auch das oben entfallene Präfix bg- wiederhergestellt werden:

src/Widgets/HeadlineWidget/HeadlineWidgetComponent.js (extension)
const backgroundColor = widget.get('backgroundColor');

if (backgroundColor) {
  classNames.push(`bg-${bgColor}`);
}

Nachdem Sie die obigen Code-Zeilen vor dem return-Statement eingefügt und die Datei gespeichert haben, wird die in den Eigenschaften ausgewählte Hintergrundfarbe sofort sichtbar.

Das war es auch schon! Sie haben ein Scrivito-Widget angepasst, indem Sie ein Attribut zu dessen Modellklasse hinzugefügt, die Konfiguration des Dialogs zur Bearbeitung der Widget-Eigenschaften erweitert sowie dafür gesorgt haben, dass der Attributwert gerendert wird!