So erstellen Sie eine eigene Komponente für FastReport Online Designer

In FastReport Online Designer lassen sich eigene Berichtskomponenten hinzufügen — mit eigenem Symbol in der Palette, eigenen Eigenschaften im Properties-Panel und eigenem Einstellungsdialog. Ganz ohne Magie: Sie schreiben ein JavaScript-Plugin, laden es in den Builder hoch, und es wird direkt in den Designer-Build kompiliert.

In diesem Artikel erstellen wir von Grund auf die Komponente «Bewertung», die einen Wert als Sterne anzeigt, und durchlaufen den gesamten Weg: vom Herunterladen des SDK bis zum fertigen Designer-Build mit Plugin und Serverteil.

Wie eine eigene Komponente aufgebaut ist

Eine Komponente besteht aus zwei Hälften:

• JS-Plugin ist für die Bearbeitung im Browser zuständig: Vorschau auf der Seite, Eigenschaften im Panel, Einstellungsdialog und Speichern als .frx.
• .NET-Klasse läuft auf Ihrem Server und ist für die Erzeugung des Berichts und seiner Vorschau zuständig.

Verbunden werden sie durch den Typnamen: der Kurzname der .NET-Klasse, das Feld type im Plugin und der XML-Tag in .frx müssen dieselbe Zeichenkette sein.

Die beiden Hälften lassen sich nacheinander erstellen. Die .NET-Klasse wird vom Designer nicht benötigt, daher bauen und prüfen wir zuerst das Plugin und fügen den Serverteil am Ende hinzu.

Schritt 1. Laden Sie das SDK herunter und bereiten Sie den Plugin-Ordner vor

Öffnen Sie im Builder Build → Eigene Komponenten und klicken Sie auf SDK herunterladen. Das Archiv enthält README.md mit einer kurzen Einführung und examples/DemoChartObject — ein funktionsfähiges Beispiel.

Der Plugin-Ordner dient zugleich als Arbeitsordner für die IDE. Kopieren Sie examples/DemoChartObject und benennen Sie die Kopie in RatingObject: dort ist bereits alles für die Autovervollständigung vorbereitet — sdk.d.ts mit den SDK-Typen, jsconfig.json und package.json mit den React-Typen passend zur React-Version des Designers. Führen Sie in diesem Ordner npm install aus und öffnen Sie ihn in der IDE.

Schritt 2. Beschreiben Sie die Komponente

Ein Plugin — das ist ein Ordner mit der Datei index.jsx (oder index.js). Ersetzen Sie den Inhalt von RatingObject/index.jsx durch die Komponentenbeschreibung:

import React from 'react';
import {registerComponent, tr} from 'sdk';
import {Input, ColorInput, Button, FormField} from 'sdk/controls';

registerComponent({
  apiVersion: 1,
  type: 'RatingObject',
  core: 'net',

  palette: {
    title: 'Rating',
    info: 'Star rating',
    icon: 'icon-chart',
  },

  defaultValues: {
    'Value': 3,
    'Maximum': 5,
    'StarColor': '#f5a623',
  },

  size: {width: 160, height: 32},

  properties: [
    {prop: 'Data:Value', type: 'number', label: 'Value', attrs: {min: 0}},
    {prop: 'Data:Maximum', type: 'number', label: 'Maximum', attrs: {min: 1}},
    {prop: 'Appearance:StarColor', type: 'color', label: 'Star color'},
  ],
});

Das genügt bereits, damit die Komponente in der Palette erscheint und ihre Eigenschaften erhält:

• palette definiert die Karte in der Palette. Das Symbol ist hier das Standard-Symbol, Sie können aber auch ein eigenes SVG oder PNG als data:-URI.
• defaultValues speichert die Standardwerte. In .frx gelangen nur Werte, die davon abweichen, — genau so arbeitet auch FastReport .NET.
• properties beschreibt die Felder des Eigenschaftspanels im Format Kategorie:Name. Die Felder Design:Name und Layout:Left/Top/Width/Height fügt das SDK selbst hinzu.

Speichern und Lesen der .frx muss nicht manuell erfolgen: Die geerbte Implementierung beherrscht bereits den Umgang mit allen deklarierten Eigenschaften.

Schritt 3. Zeichnen Sie die Vorschau

Damit die Komponente auf der Seite wie eine Bewertung aussieht, fügen Sie der Beschreibung die Methode draw hinzu. Rahmen, Verschieben und Größenänderung erhält die Komponente von der Basisklasse Component, deshalb ist draw nur für den Inhalt zuständig. Gezeichnet wird in den Container this.$content: zum Zeitpunkt des Aufrufs ist er bereits erstellt.

draw: function () {
  if (!this.$stars) {
    this.$stars = document.createElementNS('http://www.w3.org/2000/svg', 'g');
    this.$content.append(this.$stars);
  }

  const maximum = Number(this.prop('Maximum')) || 1;
  const value = Number(this.prop('Value')) || 0;
  const color = String(this.prop('StarColor'));
  const height = this.prop('Height');
  const step = this.prop('Width') / maximum;
  const stars = [];

  for (let i = 0; i < maximum; i++) {
    const fill = i < value ? color : '#d9d9d9';
    stars.push(`<text x="${step * (i + 0.5)}" y="${height * 0.75}" text-anchor="middle" font-size="${height * 0.8}" fill="${fill}">★</text>`);
  }

  this.$stars.innerHTML = stars.join('');
},

Schritt 4. Fügen Sie den Einstellungsdialog hinzu

Der Einstellungsdialog öffnet sich per Doppelklick auf die Komponente. Wir setzen ihn aus den Standard-Steuerelementen von sdk/controls zusammen, damit er wie die integrierten Editoren aussieht:

function RatingDialog ({component, popup}) {
  const ok = () => {
    component.model.submit();
    popup.submitAndClose();
    component.render();
  };

  const cancel = () => {
    component.model.clear();
    popup.close();
  };

  return (
    <div>
      <FormField label={`${tr('Value')}:`}>
        <Input half type="number" min={0} model={component.model} prop="Value"/>
      </FormField>
      <FormField label={`${tr('Maximum')}:`}>
        <Input half type="number" min={1} model={component.model} prop="Maximum"/>
      </FormField>
      <FormField label={`${tr('Star color')}:`}>
        <ColorInput half model={component.model} prop="StarColor"/>
      </FormField>
      <div style={{textAlign: 'right'}}>
        <Button variant="primary" text="OK" minWidth={60} style={{marginRight: 6}} onClick={ok}/>
        <Button minWidth={60} text={tr('Cancel')} onClick={cancel}/>
      </div>
    </div>
  );
}

Die Steuerelemente schreiben Änderungen in component.model. Dies ist ein Entwurf: Die tatsächlichen Eigenschaften der Komponente werden erst nach submit() geändert, daher verursacht die Schaltfläche Abbrechen keine Schäden.

Binden Sie den Dialog in die Komponentenbeschreibung ein:

editor: (component, popup) => <RatingDialog component={component} popup={popup}/>,

Schritt 5. Übersetzen Sie die Texte

Das Plugin muss seine eigenen Übersetzungen enthalten. Als Schlüssel bietet sich der englische Text an: Gibt es keine Übersetzung, zeigt der Designer den Schlüssel selbst an.

const TRANSLATIONS = {
  en: {'Rating': 'Rating', 'Star rating': 'Star rating', 'Value': 'Value', 'Maximum': 'Maximum', 'Star color': 'Star color', 'Cancel': 'Cancel'},
  de: {'Rating': 'Bewertung', 'Star rating': 'Bewertung in Sternen', 'Value': 'Wert', 'Maximum': 'Maximum', 'Star color': 'Sternfarbe', 'Cancel': 'Abbrechen'},
};

Fügen Sie der Komponentenbeschreibung die Zeile translations: TRANSLATIONS hinzu. Die Beschriftungen in der Palette und im Eigenschaftspanel übersetzt der Designer selbst; in Ihrem eigenen Code verwenden Sie tr('Value').

Schritt 6. Laden Sie das Plugin hoch und bauen Sie den Designer

1. Packen Sie den Plugin-Ordner selbst in das Archiv, nicht seinen Inhalt: Im Archiv muss der einzelne Root-Ordner RatingObject enthalten sein. Löschen Sie node_modules vor dem Packen nicht — der Builder berücksichtigt nur die Pakete aus dependencies, während devDependencies (darunter die React-Typen) gelangen nicht in den Build.
2. Klicken Sie auf der Seite Build → Eigene Komponenten auf Plugin hochladen. Das Archiv wird sofort geprüft: Falls etwas nicht stimmt, sehen Sie eine Liste der Probleme. Die vorherige Version des Plugins bleibt dabei erhalten.
3. Das Plugin erscheint in der Liste bereits angehakt. Starten Sie den Build und laden Sie den Designer herunter.

Öffnen Sie den Designer: In der Palette ist nun Bewertung erschienen. Fügen Sie ihn der Seite hinzu, ändern Sie den Wert im Eigenschaftspanel und öffnen Sie den Einstellungsdialog per Doppelklick.

Wenn Sie den Designer über die Builder API bauen, laden Sie das Archiv mit der Anfrage POST /builderAPI/extensions hoch und listen Sie die Plugins in der Build-Anfrage auf: "extensions": ["RatingObject"].

Schritt 7. Fügen Sie den Serverteil hinzu

Damit der Server einen Bericht mit dem neuen Objekt erzeugen kann, wird eine .NET-Klasse mit demselben Namen in einer separaten Assembly benötigt:

public class RatingObject : ReportComponentBase
{
    // Draw, Serialize, Deserialize, Assign
}

public class RatingAssemblyInitializer : AssemblyInitializerBase
{
    public RatingAssemblyInitializer()
    {
        RegisteredObjects.Add(typeof(RatingObject), "ReportPage", myBitmap, "Rating");
    }
}

Die Assembly wird über den Abschnitt <Plugins> in FastReport.config eingebunden oder durch einen direkten Aufruf beim Start der Anwendung. Ein fertiges Beispiel eines solchen Plugins — Extras/Misc/TeeChartObjectPlugin in FastReport .NET.

Solange die Klasse nicht bereitgestellt ist, kann der Server den Bericht mit diesem Objekt nicht lesen und löst ClassException — auch bei der Erzeugung der Vorschau. Der Designer-Build ohne Plugin öffnet diesen Bericht dennoch und speichert das unbekannte Objekt mit seinem Tag, seinen Attributen und verschachtelten XML-Elementen.

Wie es weitergeht

Das Plugin kann mehr, als im Artikel gezeigt wird: das Verhalten der Standardkomponenten per extends erben, eigene Eigenschafts-Editoren per registerPropertyEditor einbinden und Bibliotheken von Drittanbietern nutzen — diese werden per npm install <Paket> installiert und zusammen mit node_modules gepackt. All dies ist im Kapitel «Eigene Komponenten» des Online Designer-Benutzerhandbuchs beschrieben, und das Beispiel DemoChartObject zeigt diese Techniken im lauffähigen Code.

Häufige Fragen

Kann man auf die .NET-Klasse verzichten?

Ja, für die Arbeit im Designer genügt das JS-Plugin. Ohne Klasse auf dem Server lässt sich ein Bericht mit dieser Komponente jedoch nicht erzeugen: Der Server löst ClassException.

Wie legt man ein eigenes Symbol in der Palette fest?

Geben Sie in palette.icon Ihr eigenes SVG oder PNG als data:-URI an. Andernfalls setzt das SDK das Standard-Symbol ein.

Was ist zu prüfen, wenn der Builder das Archiv abgelehnt hat?

Im Archiv-Root muss genau ein Plugin-Ordner liegen, und darin — die Datei index.jsx oder index.js. Die Liste der Probleme zeigt der Builder sofort beim Hochladen an.

Fazit

Eine eigene Komponente für FastReport Online Designer — das sind zwei Hälften, verbunden durch denselben Typnamen: ein JS-Plugin für den Editor und eine .NET-Klasse für den Server. Um heute alles fertigzustellen, laden Sie das SDK herunter, kopieren das Beispiel DemoChartObject und ersetzen die Eigenschaften, die Vorschau und den Einstellungsdialog durch Ihre eigenen — der Designer wird zusammen mit dem Plugin neu gebaut. Binden Sie den Serverteil parallel an: Schon vor der Bereitstellung der Klasse lässt sich ein Bericht mit der neuen Komponente öffnen und verlustfrei speichern.