Widgets im Jitterbit App Builder

Übersicht

Widgets im App Builder ermöglichen Entwicklern, Code von Drittanbietern (oder eigenen Code) bereitzustellen, um ein benutzerdefiniertes Steuerelement auf der Seite anzuzeigen. Widgets ermöglichen die Definition weiterer Metadaten. Weitere Informationen finden Sie im Abschnitt „Archivdateiinhalte“. Parameter unterstützen jetzt eine robustere Definition. Weitere Informationen finden Sie im Abschnitt „Widget API“.

Siehe die Widget-Download-Bibliothek für eine Liste der unterstützten Widgets, die Sie im App Builder verwenden können.

Widget-Richtlinien

1. Widgets sollten den zugrunde liegenden Wert anzeigen oder es sollte offensichtlich sein, um welchen Wert es sich handelt.

   • Gut: Wert wird angezeigt

     
     

   • Gut: Wert offensichtlich

     
     

   • Schlecht:

     

2. Widget-Test. Denken Sie daran, zu berücksichtigen, wie mit dem Widget auf Touch- und Nicht-Touch-Geräten interagiert wird.

3. Widgets sollten die automatische Bearbeitung und Speicherung berücksichtigen. Dieses Verhalten wird vom App Builder automatisch übernommen.

Inhalt der Archivdatei

_manifest.json

Alle Widgets enthalten eine Manifestdatei. Sie können in dieser Datei weitere Metadaten definieren, wie unten beschrieben.

{
    "name": "Slider",
    "developer": "App Builder",
    "binder": "binder.js",
    "template": "view.html",
    ...
    "targetContainer": false,
    "purpose": "Site",
    "parameters": [
        {
            "name": "Parameter name",
            "default": "default value",
            "translate": true
        }
    ]
}

• name: Der Name des Widgets, der in der App Builder IDE angezeigt wird und zum Archivdateinamen wird.

• developer: Der Benutzername des Entwickler, der an diesem Widget arbeitet.

• binder: Der Dateiname des Widget-Ordners. Weitere Informationen finden Sie unten.

• template: Der Dateiname der HTML-Vorlagendatei. Weitere Informationen finden Sie unten.

• targetContainer: Unterstützt den Wert true oder false.

• purpose: Unterstützt den definierten Wert von Site oder Field, das angibt, wie das Widget verwendet werden soll.

• parameters: Unterstützt ein Array von Parameter-Metadaten für jeden:

  • name: der Parametername
  • default: eine Zeichenfolge mit dem Standardwert
  • translate: unterstützt den Wert true oder false

• Version: Versionsnummer des Widgets. Erhöhen Sie diese Nummer, um sicherzustellen, dass Benutzer die neueste Version Ihres Codes erhalten.

• createdOn: Datum der Veröffentlichung dieser Version. Nur zu Informationszwecken.

• Abhängigkeiten: Komma-getrennte Liste aller Abhängigkeiten, die Ihr Widget-Binder benötigt. Die Reihenfolge dieser Dateien entspricht der Reihenfolge im Abhängigkeits-Array der Widget-API. Geben Sie unbedingt die Dateierweiterung an.

  • JavaScript
  • CSS

  Wenn Sie beispielsweise eine Bibliothek definieren, die eine Referenz zurückgibt, die Sie zur Installation auf einem Element verwenden müssen:

  Manifest Entry

  "javascript": [
    "noUiSlider.8.0.2/nouislider.js",
    "noUiSlider.8.0.2/nouislider_extras.js"
  ]
  

  Ihr Widget API Kontext würde beide dieser Objekte enthalten:

  Usage

  var install = function (holderElement, context) {
    var sliderLibrary = context.loadedDependencies[0];
    sliderLibrary.createSlider(holderElement);
  }
  

  Hinweis

  Auch wenn keine Abhängigkeiten vorhanden sind, schließen Sie die JavaScript- und CSS-Eigenschaften mit einem leeren Array ein.

  Manifest Entry

  "javascript": [],
  "css": []
  

binder.js

binder.js

define(function () {
    return {
        callbacks: {
            events: {
                install: function (holderElement, context) {},
                uninstall: function (holderElement, context) {}
            }
        }
    };
});

Der Binder bietet zwei Callbacks, die zum Binden der App Builder API an Ihre Bibliotheken erforderlich sind. In jedem Callback werden zwei Funktionsparameter bereitgestellt.

• holderElement: Ein DOM-Element, das die HTML-Auszeichnung der angegebenen Vorlagendatei enthält. Da diese Datei optional ist, kann das Halterelement leer sein. Das Halterelement ist die Zelle, die das Widget implementiert. Es handelt sich um den im Screenshot unten hervorgehobenen Bereich und enthält nicht die Feldbezeichnung.
  

  

• context: Eine Instanz des Widget API -Kontexts. Dieses Objekt enthält alle im Binder angegebenen JavaScript-Abhängigkeiten sowie den Zugriff auf die Daten in der Zelle und im Panel.

• view.html (optional): Diese Datei enthält das gesamte statische HTML, das zum Laden dieses Widgets erforderlich ist. Wenn nicht angegeben, wird das Widget ohne Inhalt erstellt und der im Binder definierte Installations-Callback muss das erforderliche HTML rendern.

Widget API

getCell()
Gibt eine Instanz der WidgetApiCell zurück.

getRow()
Gibt eine Instanz der WidgetApiRow zurück.

isEditState() - Boolesch
Gibt an, ob die Zeile bearbeitet werden kann.

getParameter(name) - Zeichenfolge
Ruft den definierten Parameter entweder aus dem Standardwert oder der vom Designer benannten Zelle in dieser Zeile ab.

geladene Abhängigkeiten
Eine Eigenschaft, die ein Array von Objekten enthält, die von RequireJS zurückgegeben werden. Dieses Array wird in derselben Reihenfolge bereitgestellt, in der die Abhängigkeiten in der Datei _manifest.json definiert sind.

WidgetApiCell
Stellt eine einzelne Zelle dar. Zellen sind das zugrunde liegende Ansichtsmodell des auf der Seite angezeigten Steuerelements. Sie enthalten Werte, können auf Änderungen überwacht werden und befinden sich in einer Tabellenzeile.

Wert - Zeichenfolge
Mit dieser Eigenschaft kann der zugrunde liegende Wert der Zelle abgerufen und festgelegt werden.

customTextbox.on('change', function (value) {
    cell.value = value;
});

formattedValue - Zeichenfolge
Mit dieser Eigenschaft kann der zugrunde liegende Anzeigewert der Zelle abgerufen und festgelegt werden. Beispielsweise wäre der zugrunde liegende Wert eines Prozentfelds 0,25, während der Anzeigewert (formatierter Wert) „25 %“ lautet. Oder ein Listensteuerelement könnte den Wert einer GUID enthalten, während der formatierte Wert der Vor- und Nachname eines Kunden ist.

persistedValue - Zeichenfolge
Mit dieser Eigenschaft kann der zugrunde liegende persistente Wert der Zelle abgerufen werden. Ein persistenter Wert ist der aktuell in der Datenquelle gespeicherte, unbearbeitete Wert. Damit kann eine Zelle in einen bereinigten Zustand zurückversetzt werden.

setDataChangeCallback
Mit dieser Funktion werden Callbacks festgelegt, die ausgeführt werden, wenn das Formular, in dem sich das Widget befindet, neue Daten empfängt.

context.setDataChangeCallback(function () {
   var updatedMin = parseInt(context.getParameter("Min"), 10);
});

setChangeCallback(Name: String, Wert: Funktion)
Diese Funktion dient zum Setzen von Callbacks für eine Zelle. Folgende Callbacks können definiert werden:

• Wert
• formatierterWert
• deaktiviert

cell.setChangeCallback('value', function (value) {
    console.log("The cell's value has been changed to", value);
});

App Builder kann während Validierungsereignissen Änderungen an der Zelle verursachen, wenn Standardwerte festgelegt sind oder ein anderes Widget Änderungen an dieser Zelle verursacht. App Builder kann Zellen auch deaktivieren, wenn Ereignisse ausgeführt werden.

App Builder übergibt einen einzelnen Parameter an den bereitgestellten Rückruf mit dem geänderten Wert. Im deaktivierten Zustand ist der Wert entweder „true“ oder „false“.

dropChangeCallback(Name: Zeichenfolge)
Entfernt das Abonnement für einen Änderungsrückruf.

WidgetApiRow
Stellt eine Zeile in der Datenquelle dar. Diese Zeile enthält die Zelle, die das Widget implementiert.

getCellByColumnName(name: string) - WidgetApiCell
Gibt eine Instanz einer Zelle in dieser Zeile zurück. Der Name berücksichtigt Groß- und Kleinschreibung und muss mit dem im Steuerelement definierten Namen übereinstimmen, nicht mit dem Namen der Datenquelle.

Bearbeiten()
Ändert den Bearbeitungsmodus der Zeile.

speichern()
Speichert alle geänderten Werte zurück in der Datenquelle.

Zeile löschen()
Versucht, die Zeile aus der Datenquelle zu löschen.

Parameter
Parameter für ein Widget können auf Panelebene definiert werden. Beim Hinzufügen eines Parameters kann der Entwickler Folgendes konfigurieren:

• Widget-Parameter: Dem Parameterwert zugewiesener Name.

• Parametertyp: Standardmäßig Control, kann auch definiert werden als Column oder Static Value. Je nachdem, welchen Typ Sie definieren, müssen Sie entsprechend unterschiedliche Werte konfigurieren:

  • Steuerung:
    • Zielsteuerung: Eine Steuerung aus dem übergeordneten Bereich, die diesen Parameterwert bereitstellt.
    • Formatierten Wert verwenden: Verwenden Sie den formatierten Anzeigewert.
    • Aktiv: Gibt an, ob diese Bindung aktiv ist oder nicht. Inaktive Bindungen werden nicht verwendet.
  • Spalte:
    • Zielspalte: Eine Spalte aus der Quelltabelle des übergeordneten Panels, die diesen Parameterwert bereitstellt.
    • Formatierten Wert verwenden: Verwenden Sie den formatierten Anzeigewert.
    • Aktiv: Gibt an, ob diese Bindung aktiv ist oder nicht. Inaktive Bindungen werden nicht verwendet.
  • Statischer Wert:
    • Wert: Statischer Wert für den Parameter.
    • Übersetzbar: Wenn aktiviert, kann das Widget gegebenenfalls übersetzt werden.
    • Aktiv: Gibt an, ob diese Bindung aktiv ist oder nicht. Inaktive Bindungen werden nicht verwendet.

So erstellen Sie ein Widget und beheben Probleme

Widgets sind eine leere Tafel. App Builder führt den Widget-Code anstelle der Implementierung von App Builder aus.

Aktuellen Wert anzeigen
Wenn Sie beispielsweise ein Thermometer rendern, müssen Sie wahrscheinlich den aktuellen Wert zusammen mit dem Quecksilbergehalt angeben. (siehe Beispieltext für 3.500 $ unten)

Ein Widget zur Sternebewertung muss jedoch möglicherweise nicht den tatsächlichen Zellenwert angeben.

Wert vom App Builder abrufen und in Ihrem Widget festlegen
App Builder kann den Wert über Standardwerte oder Änderungen an übergeordneten Datensätzen aktualisieren. Ihre Bibliothek muss sich bei solchen Ereignissen selbst aktualisieren können.

Durch die Bereitstellung von Rückrufen kann App Builder Ihren Code ausführen, wenn neue Werte an Ihr Widget gesendet werden müssen. Siehe setChangeCallback oben.

Außerdem müssen Sie beim Installieren einer Bibliothek normalerweise den Anfangswert aus der bereitgestellten Zelle festlegen. App Builder führt den Change Callback nicht bei der Installation aus, sondern nur, wenn Ereignisse dies erfordern.

Neue Versionen hochladen und debuggen
Sobald ein Widget betriebsbereit ist und Sie einen Fehler debuggen, führen Sie die folgenden Schritte aus:

1. Komprimieren Sie den Inhalt des lokalen Ordners, an dem Sie arbeiten (achten Sie darauf, dass Sie nicht den übergeordneten Ordner selbst komprimieren, da sonst ein zusätzlicher Ordner in der ZIP-Datei erstellt wird).
2. Laden Sie die Widget-Zip-Datei in der Look & Feel-Anwendung hoch
3. Klicken Sie mit Ihrem Widget auf „Aktualisieren“. Hinweis: Möglicherweise müssen Sie während der Entwicklung den Browser-Cache deaktivieren, da sonst veralteter Code entstehen kann.

Anzeigen- vs. Bearbeitungsstatus
Beim Hinzufügen eines Widgets zu einem Panel können Sie angeben, ob Ihr Widget sowohl den Bearbeitungs- als auch den Anzeigestatus rendern soll. Wenn Ihr Widget nur den Bearbeitungsstatus verarbeitet, rendert App Builder den Zellenwert im Anzeigestatus.

Wenn Ihr Widget beide Zustände verarbeitet, KANN Ihr Steuerelement zum Bearbeiten von Werten verwendet werden, ohne dass Sie zuerst auf die Schaltfläche „Bearbeiten“ in der Symbolleiste klicken müssen.

Dazu müssen Sie die Zeile in den Bearbeitungsstatus versetzen, falls dies noch nicht geschehen ist. Hier ist ein Beispiel:

if (!context.isEditState()) {
  context.getRow().edit();
}
context.getCell().value = myNewValueVariable;
context.getRow().save();

Sie können auch die Eigenschaft isEditState verwenden, um eine schreibgeschützte Version des Widgets zu rendern, die den Wert anzeigt, aber nicht zum Ändern der Zelle verwendet werden kann.

Große Abhängigkeiten werden geladen
Das Herunterladen und Installieren umfangreicher Ressourcen wie JQuery UI dauert lange. Aus Leistungsgründen wird empfohlen, nur leichte Bibliotheken oder Bibliotheken zu implementieren, die vorhandene App Builder Abhängigkeiten verwenden. Es wurden einige Fehler gemeldet, wenn Abhängigkeiten zu langsam geladen wurden.

Arbeiten mit Binärdaten
Einige Zellen im App Builder können binäre Daten enthalten, die als Base64-Zeichenfolge gespeichert sind. Bibliotheken, z. B. Bildbearbeitungsprogramme, können zum Ändern und Speichern von Daten in diesen Zellen verwendet werden. Beispielcode finden Sie in der Bibliothek „Image Resizer“ in der App Builder-Sammlung.

Zeile.Ansichtsmodell
Die aktuelle Version von App Builder stellt einen Parameter namens ViewModel in der Zeilen API bereit. Dieser ermöglicht den Zugriff auf die Backend-Daten von App Builder. Die Funktionsfähigkeit beim Upgrade von App Builder ist nicht garantiert. Es wird nicht empfohlen, Code zu schreiben, der diese Eigenschaft benötigt.

Site-Widgets

Widgets können auch auf „Site-Ebene“ sein. Dies wird auf Widget-Ebene definiert und über Control Center > Instanzeinstellungen > Site-Widgets verwendet.

Site-Widgets werden ausgeführt, sobald der Browser geladen ist. Dadurch kann der Code so schnell wie möglich ausgeführt werden. Der Code wird asynchron ausgeführt, d. h. die Seite wartet nicht mit der Darstellung, bis der Code ausgeführt wurde.

Site-Parameter sind nicht datengebunden, sie unterstützen nur reine Textwerte.

So fügen Sie ein Site-Widget im App Builder hinzu

1. Gehen Sie zu App Workbench > Look & Feel > Widgets
   
2. Wählen Sie die Sammlung aus, zu der Sie das Widget hinzufügen möchten
   
3. Klicken Sie auf die Schaltfläche + Widget
4. Geben Sie einen Namen für das Widget ein. Beispiel: Dial Widget
5. Klicken Sie auf Durchsuchen und suchen Sie die Widget-ZIP-Datei mit allen erforderlichen Widget-Dateien, wählen Sie sie aus und klicken Sie auf Öffnen
6. Stellen Sie eine beliebige Dokumentation zur Verfügung, um das Widget zu beschreiben. Hilfetextinformationen, die in der IDE für ein Widget angezeigt werden, werden im Widget-Datensatz bereitgestellt.
7. Klicken Sie auf Speichern
8. Klicken Sie im Bereich „Widget-Parameter“ auf + Parameter und definieren Sie alle erforderlichen Parameter für das Widget
9. Wählen Sie auf der Seite, auf der Ihr Widget ausgeführt wird, das Widget aus dem Bereich Widget-Informationen des Control Designers aus und legen Sie die Werte für Schnittstelle und Aktivmodus fest.
   

API

getParameter(name) - Zeichenfolge
Ruft den definierten Parameter entweder vom Standardwert oder vom Parameter ab, der vom Designer über die Site-Widget-Definition bereitgestellt wurde.

getCurrentPageLocation() - Zeichenfolge
Ruft die aktuelle URL der Seite ab.

getCurrentAuthenticationUserName() - Zeichenfolge
Ruft den aktuell angemeldeten Benutzernamen ab oder null, wenn keine Authentifizierung erfolgt ist.

onPageLocationChange(handler: Funktion(Ereignis))
Mit dieser Funktion werden Rückrufe festgelegt, die ausgeführt werden, wenn sich der Seitenstandort ändert. Der Pfad wird als Zeichenfolge zurückgegeben.

onAuthenticationChange(handler: Function(event))
Diese Funktion dient zum Festlegen von Callbacks, die ausgeführt werden, wenn sich der authentifizierte Benutzer ändert. Der Benutzername wird als String zurückgegeben.

Fehlerbehebung

App Builder unterstützt Tastaturkürzel, mit dem einige Widget-Bibliotheken in Konflikt geraten können. App Builder unterstützt derzeit die folgenden Hotkeys: text; enter; esc; left-arrow; up-arrow; right-arrow; down-arrow; backtick; Und delete.

Mit den folgenden Anweisungen können Sie die Hotkey-Unterstützung für ein bestimmtes HTML-Element und dessen untergeordnete Elemente deaktivieren.

Um alle Tastaturkürzel zu ignorieren, verwenden Sie entweder eine CSS-Klasse oder den Datenfeldwert. vinyl-hotkeys-ignore:

• <div class="vinyl-hotkeys-ignore"></div>- <div data-vinyl-hotkeys-ignore="true"></div>Um bestimmte Tastaturbelegungen zu ignorieren, fügen Sie diese dem CSS-Klassensuffix hinzu. Bei mehreren Wörtern trennen Sie diese im CSS-Klassensuffix mit Bindestrich:

• <div class="vinyl-hotkeys-ignore-text"></div>- <div data-vinyl-hotkeys-ignore-text="true"></div>- <div class="vinyl-hotkeys-ignore-left-allow"></div>- <div data-vinyl-hotkeys-ignore-left-allow="true"></div>

App Builder ignoriert automatisch Textfelder und Divs, die als bearbeitbarer Inhalt markiert sind:

• <div contenteditable="true"></div>