FastReport Online Designer'a kendi bileşeninizi nasıl eklersiniz

FastReport Online Designer, paletten kendi simgesine, Özellikler panelinde kendi özelliklerine ve kendi ayarlar penceresine sahip rapor bileşenlerinizi eklemenize olanak tanır. Sihir yok: bir JavaScript eklentisi yazarsınız, onu builder'a yüklersiniz ve doğrudan designer derlemesine derlenir.

Bu makalede, bir değeri yıldızlar olarak gösteren «Rating» adlı bir bileşeni sıfırdan oluşturacağız ve tüm yolu kat edeceğiz: SDK'nın indirilmesinden, eklentiyi ve sunucu tarafını içeren hazır bir designer derlemesine kadar.

Özel bileşen nasıl yapılandırılmıştır

Bileşenin iki yarısı vardır:

• JS eklentisi tarayıcıdaki düzenlemeyi üstlenir: sayfadaki önizleme, paneldeki özellikler, ayarlar penceresi ve .frx dosyasına kaydetme.
• .NET sınıfı sizin sunucunuzda çalışır ve raporun ve önizlemesinin oluşturulmasından sorumludur.

İkisini birbirine bağlayan şey tür adıdır: .NET sınıfının kısa adı, eklentideki type alanı ve .frx içindeki XML etiketi hepsi aynı dize olmak zorundadır.

İki yarı birbirini takip edecek şekilde yapılabilir. Designer .NET sınıfına ihtiyaç duymaz, bu yüzden önce eklentiyi derleyip test ederiz, sunucu tarafını ise en sona ekleriz.

Adım 1. SDK'yı indirin ve eklenti klasörünü hazırlayın

Builder'da Build → Custom components sayfasını açın ve Download SDK'ya tıklayın. Arşivde kısa bir giriş içeren README.md ve çalışan bir örnek olan examples/DemoChartObject bulunur.

Eklenti klasörü aynı zamanda IDE'nizin çalışma klasörü olarak da kullanılır. examples/DemoChartObject kopyasını alın ve kopyayı RatingObject olarak yeniden adlandırın: otomatik tamamlama için her şey hazır — SDK türlerini içeren sdk.d.ts, designer'ın React sürümüne uyan React türleriyle jsconfig.json ve package.json. Bu klasörde npm install komutunu çalıştırın ve IDE'nizde açın.

Adım 2. Bileşeni tanımlayın

Bir eklenti — dosyasını içeren bir klasördür:  index.jsx (veya index.js).  RatingObject/index.jsx içeriğini bileşen tanımıyla değiştirin:

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'},
  ],
});

Bileşenin palette görünmesi ve özelliklerini alması için bu yeterli:

• palette, palettedeki kartı ayarlar. Buradaki simge standarttır, ancak kendi SVG veya PNG'nizi data:-URI olarak da belirtebilirsiniz.
• defaultValues, varsayılan değerleri saklar. Yalnızca onlardan farklı olan değerler .frx — dosyasına girer; FastReport .NET de aynı şekilde çalışır.FastReport .NET.
• properties, özellikler panelinin alanlarını Category:Name formatında tanımlar.  Design:Name ve Layout:Left/Top/Width/Height alanları SDK tarafından kendiliğinden eklenir.

.frx dosyasını elle kaydetmeye ve okumaya gerek yok: kalıtımla alınan uygulama, tanımlanan tüm özelliklerle nasıl çalışacağını zaten biliyor.

Adım 3. Önizlemeyi çizin

Bileşenin sayfada bir derecelendirme gibi görünmesi için tanıma draw metodunu ekleyin. Çerçeve, taşıma ve boyutlandırma bileşene Component temel sınıfı tarafından sağlanır, bu yüzden draw yalnızca içerikten sorumludur. Çizim this.$content kapsayıcısına yapılmalıdır: çağrı anında zaten oluşturulmuştur.

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('');
},

Adım 4. Ayarlar penceresini ekleyin

Ayarlar penceresi, bileşene çift tıklayarak açılır. Yerleşik düzenleyicilere benzemesi için onu sdk/controls kütüphanesinin standart denetimlerinden oluşturacağız:

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>
  );
}

Denetimler değişiklikleri component.model nesnesine yazar. Bu bir taslaktır: bileşenin gerçek özellikleri yalnızca submit() çağrısından sonra değişir, bu yüzden Cancel düğmesi hiçbir şeye zarar vermez.

Pencereyi bileşen tanımına bağlayın:

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

Adım 5. Dizeleri çevirin

Eklentinin kendi çevirilerini içermesi gerekir. Anahtar olarak İngilizce metni kullanmak uygundur: çeviri yoksa, designer anahtarın kendisini gösterir.

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'},
};

Bileşen tanımına translations: TRANSLATIONS dizesini ekleyin. Designer, palet ve özellikler panelindeki başlıkları kendiliğinden çevirir, kendi kodunuzda ise tr('Value') çağrısını kullanırsınız.

Adım 6. Eklentiyi yükleyin ve designer'ı derleyin

1. Arşive eklenti klasörünün kendisini, içeriklerini değil, paketleyin: arşiv tek bir RatingObject kök klasörü içermelidir. Paketlemeden önce node_modules klasörünü silmeye gerek yok — builder yalnızca dependencies içindeki paketleri hesaba katacak,  devDependencies (React türleri dahil) ise derlemeye girmeyecek.
2.  Build → Custom components sayfasında Upload plugin'e tıklayın. Arşiv hemen kontrol edilir: bir sorun varsa sorunların listesini görürsünüz. Eklentinin önceki sürümü yerinde kalır.
3. Eklenti listede zaten kontrol edilmiş olarak görünecek. Derlemeyi başlatın ve designer'ı indirin.

Designer'ı açın: palettede Rating göründü. Bunu sayfaya ekleyin, özellikler panelindeki değeri değiştirin ve çift tıklayarak ayarlar penceresini açın.

Designer'ı Builder API üzerinden derliyorsanız, arşivi bir POST /builderAPI/extensions isteğiyle yükleyin ve derleme isteğinde eklentileri belirtin: "extensions": ["RatingObject"].

Adım 7. Sunucu tarafını ekleyin

Sunucunun yeni nesneyle bir rapor oluşturabilmesi için, ayrı bir derlemede aynı ada sahip bir .NET sınıfı gerekir:

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

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

Derleme,  FastReport.config içindeki <Plugins> bölümü aracılığıyla veya uygulama başlangıcında doğrudan bir çağrıyla bağlanır. Böyle bir eklentinin hazır bir örneği — FastReport .NET içindeki Extras/Misc/TeeChartObjectPlugin.

Sınıf dağıtılana kadar sunucu, bu nesneyi içeren raporu okuyamayacak ve ClassException — fırlatacak; bu, önizleme oluşturulurken de geçerlidir. Eklentisiz designer derlemesi yine de raporu açar ve bilinmeyen nesneyi etiketi, öznitelikleri ve iç içe XML öğeleriyle birlikte kaydeder.

Sırada ne var

Eklenti, makalede gösterilenden fazlasını yapabilir:  extends aracılığıyla standart bileşenlerin davranışını devralabilir,  registerPropertyEditor aracılığıyla özel özellik düzenleyicileri bağlayabilir ve üçüncü taraf kitaplıkları kullanabilir — bunlar  npm install <package> komutuyla yüklenir ve node_modules ile birlikte paketlenir. Tüm bunlar, Online Designer kullanıcı kılavuzunun «Custom components» bölümünde açıklanmıştır ve  DemoChartObject örneği bu teknikleri çalışan kodda göstermektedir.

Sık sorulan sorular

.NET sınıfı olmadan yapılabilir mi?

Evet, designer'da çalışmak için JS eklentisi yeterlidir. Ancak sunucuda bir sınıf olmadan, bu bileşeni içeren bir rapor oluşturulamaz: sunucu ClassException fırlatacaktır.

Palettede kendi simgenizi nasıl ayarlarsınız?

 palette.icon içinde kendi SVG veya PNG'nizi data:-URI olarak belirtin. Belirtilmezse SDK standart simgeyi yerleştirir.

Builder arşivi reddederse neyi kontrol etmelisiniz?

Arşivin kökünde tek bir eklenti klasörü bulunmalı ve içinde — index.jsx veya index.js dosyası bulunmalıdır. Builder, sorunların listesini yükleme anında gösterecektir.

Sonuç

FastReport Online Designer için özel bir bileşen — aynı tür adıyla birbirine bağlanan iki yarı: düzenleyici için bir JS eklentisi ve sunucu için bir .NET sınıfı. Her şeyi bugün toplamak için SDK'yı indirin, DemoChartObject örneğini kopyalayın ve kendi özelliklerinizi, önizlemenizi ve ayarlar pencerenizi yerleştirin — designer, eklentiyle birlikte yeniden derlenecektir. Sunucu tarafını paralel olarak bağlayın: sınıf dağıtılmadan önce bile, yeni bileşeni içeren bir rapor kayıpsız açılabilir ve kaydedilebilir.