Widgets in Jitterbit App Builder

Übersicht

Widgets im App Builder ermöglichen es Entwicklern, Code von Drittanbietern (oder eigenen Code) bereitzustellen, um ein benutzerdefiniertes Steuerelement auf der Seite anzuzeigen. Widgets ermöglichen es, mehr Metadaten zu definieren. Weitere Informationen finden Sie im Abschnitt „Inhalte der Archivdatei". 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 man im App Builder verwenden kann.

Widget-Richtlinien

1. Widgets sollten den zugrunde liegenden Wert anzeigen oder es sollte offensichtlich sein, welcher Wert zugrunde liegt.

   • Gut: Wert angezeigt

     
     

   • Gut: Wert offensichtlich

     
     

   • Schlecht:

     

2. Widget-Tests. Man sollte berücksichtigen, wie das Widget auf Touch- und Nicht-Touch-Geräten verwendet wird.

3. Widgets sollten automatische Bearbeitung und automatisches Speichern respektieren. Widgets erhalten dieses Verhalten automatisch vom App Builder.

Inhalte der Archivdatei

_manifest.json

Alle Widgets enthalten eine Manifestdatei. Man kann in dieser Datei weitere Metadaten definieren, wie nachfolgend 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 Namen der Archivdatei wird.

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

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

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

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

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

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

  • name: Der Parametername
  • default: Eine Zeichenkette mit dem Standardwert
  • translate: Unterstützt den Wert true oder false

• version: Versionsnummer des Widgets. Diese Nummer erhöhen, um sicherzustellen, dass Benutzer die neueste Version des Codes erhalten.

• createdOn: Datum, an dem diese Version veröffentlicht wurde. Nur zu Informationszwecken.

• dependencies: Kommagetrennte Liste aller Abhängigkeiten, die der Widget-Binder benötigt. Die Reihenfolge, in der diese Dateien angezeigt werden, entspricht der Reihenfolge, in der sie im Abhängigkeits-Array der Widget-API angezeigt werden. Die Dateierweiterung einschließen.

  • JavaScript
  • CSS

  Beispiel: Wenn man eine Bibliothek definiert, die eine Referenz zurückgibt, die man zum Installieren auf einem Element benötigt:

  Manifest-Eintrag

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

  Der Widget-API-Kontext würde beide Objekte enthalten:

  Verwendung

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

  Hinweis

  Auch wenn man keine Abhängigkeiten hat, die JavaScript- und CSS-Eigenschaften mit einem leeren Array einschließen.

  Manifest-Eintrag

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

binder.js

binder.js

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

Der Binder stellt zwei erforderliche Callbacks bereit, um die App Builder API an die Bibliotheken zu binden. In jedem werden zwei Funktionsparameter bereitgestellt.

• holderElement: Ein DOM-Element, das das HTML-Markup aus der angegebenen Template-Datei enthält. Da diese Datei optional ist, kann das Holder-Element leer sein. Das Holder-Element ist die Zelle, die das Widget implementiert. Es ist der Bereich, der im Screenshot unten hervorgehoben ist, und enthält nicht die Beschriftung des Felds.
  

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

• view.html (optional): Diese Datei enthält alle statischen HTML-Inhalte, die zum Laden dieses Widgets erforderlich sind. Falls nicht angegeben, wird das Widget ohne Inhalte erstellt und der im Binder definierte Install-Callback muss alle erforderlichen HTML-Inhalte rendern.

Widget-API

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

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

isEditState() - boolean
Gibt an, ob die Zeile bearbeitbar ist.

getParameter(name) - string
Ruft den definierten Parameter entweder aus dem Standardwert oder aus der Zelle in dieser Zeile ab, die vom Designer benannt wurde.

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

WidgetApiCell
Stellt eine einzelne Zelle dar. Zellen sind das Backing-View-Modell des auf der Seite angezeigten Steuerelements. Sie enthalten Werte, können auf Änderungen überwacht werden und existieren in einer Zeile einer Tabelle.

value - string
Diese Eigenschaft kann verwendet werden, um den zugrunde liegenden Wert der Zelle abzurufen und festzulegen.

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

formattedValue - string
Diese Eigenschaft kann verwendet werden, um den zugrunde liegenden Anzeigewert der Zelle abzurufen und festzulegen. Beispielsweise hätte ein Prozentfeld einen zugrunde liegenden Wert von 0,25, während der Anzeigewert (formatierter Wert) „25 %" ist. Oder ein Listensteuerelement könnte einen Wert einer GUID haben, während der formatierte Wert der Vor- und Nachname eines Kunden ist.

persistedValue - string
Diese Eigenschaft kann verwendet werden, um den zugrunde liegenden persistierten Wert der Zelle abzurufen. Ein persistierter Wert ist der unbearbeitete Wert, der derzeit in der Datenquelle gespeichert ist. Dies kann verwendet werden, um eine Zelle in einen sauberen Zustand zurückzusetzen.

setDataChangeCallback
Diese Funktion wird verwendet, um Callbacks festzulegen, die ausgeführt werden, wenn das Formular, auf dem sich das Widget befindet, neue Daten erhält.

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

setChangeCallback(name: string, value: Function)
Diese Funktion wird verwendet, um Callbacks auf einer Zelle festzulegen. Die folgenden benannten Callbacks können definiert werden:

• value
• formattedValue
• disabled

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 vornehmen, wenn Standardwerte festgelegt sind oder wenn ein anderes Widget Änderungen verursacht, die diese Zelle beeinflussen. App Builder kann Zellen auch deaktivieren, wenn Ereignisse ausgeführt werden.

App Builder übergibt einen einzelnen Parameter an den bereitgestellten Callback, der den geänderten Wert enthält. Im Fall von „disabled" ist der Wert entweder „true" oder „false".

dropChangeCallback(name: string)
Entfernt das Abonnement für einen Change-Callback.

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 ist case-sensitiv und muss dem Namen entsprechen, der im Steuerelement definiert ist, nicht dem Datenquellennamen.

edit()
Versetzt die Zeile in den Bearbeitungsmodus.

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

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

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

• Widget-Parameter: Name, der dem Parameterwert zugewiesen ist.

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

  • Control:
    • Zielsteuerelement: Ein Steuerelement aus dem übergeordneten Panel, das diesen Parameterwert bereitstellt.
    • Formatierte Wert verwenden: Verwenden Sie den formatierten Anzeigewert.
    • Aktiv: Gibt an, ob diese Bindung aktiv ist oder nicht. Inaktive Bindungen werden nicht verwendet.
  • Column:
    • Zielspalte: Eine Spalte aus der Quelltabelle des übergeordneten Panels, die diesen Parameterwert bereitstellt.
    • Formatierte Wert verwenden: Verwenden Sie den formatierten Anzeigewert.
    • Aktiv: Gibt an, ob diese Bindung aktiv ist oder nicht. Inaktive Bindungen werden nicht verwendet.
  • Static Value:
    • Wert: Statischer Wert für den Parameter.
    • Übersetzbar: Wenn aktiviert, ermöglicht dies die Übersetzung des Widgets, falls zutreffend.
    • Aktiv: Gibt an, ob diese Bindung aktiv ist oder nicht. Inaktive Bindungen werden nicht verwendet.

So erstellen Sie ein Widget und Fehlerbehebung

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

Anzeige des aktuellen Werts
Wenn Sie beispielsweise ein Thermometer rendern, müssen Sie wahrscheinlich den aktuellen Wert zusammen mit dem Quecksilberniveau einbeziehen. (siehe Beispieltext $3.500 unten)

Ein Stern-Bewertungs-Widget muss jedoch möglicherweise nicht den tatsächlichen Zellenwert anzeigen.

Abrufen und Festlegen des Werts von App Builder auf Ihr Widget
App Builder kann den Wert über Standardwerte oder Änderungen an übergeordneten Datensätzen aktualisieren. Ihre Bibliothek muss sich selbst aktualisieren können, wenn diese Ereignisse auftreten.

Durch das Bereitstellen von Callbacks 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 bei der Installation nicht aus, sondern nur wenn Ereignisse dies erfordern.

Hochladen neuer Versionen und Debugging
Nachdem Sie ein funktionierendes Widget haben und einen Fehler debuggen, führen Sie die folgenden Schritte aus:

1. Komprimieren Sie den Inhalt des lokalen Ordners, an dem Sie arbeiten (stellen Sie sicher, dass Sie nicht den übergeordneten Ordner selbst komprimieren, da dies einen zusätzlichen Ordner in der ZIP-Datei erstellt)
2. Laden Sie die Widget-ZIP-Datei in die Look & Feel-Anwendung hoch
3. Aktualisieren Sie die Seite mit Ihrem Widget. Hinweis: Möglicherweise müssen Sie den Browser-Cache während der Entwicklung deaktivieren, um zu vermeiden, dass veralteter Code verwendet wird.

Ansichts- vs. Bearbeitungsmodus
Beim Hinzufügen eines Widgets zu einem Panel können Sie angeben, ob Ihr Widget das Rendern von Bearbeitungs- und Ansichtsmodus verarbeitet. Wenn Ihr Widget nur den Bearbeitungsmodus verarbeitet, rendert App Builder den Zellenwert im Ansichtsmodus.

Wenn Ihr Widget beide Zustände verarbeitet, kann Ihr Steuerelement zum Bearbeiten von Werten verwendet werden, ohne zuerst auf die Schaltfläche der Bearbeitungssymbolleiste klicken zu müssen.

Dazu müssen Sie die Zeile in den Bearbeitungsmodus wechseln, falls noch nicht geschehen. 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.

Laden großer Abhängigkeiten
Große Ressourcen wie JQuery UI dauern lange zum Herunterladen und Installieren. 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 werden.

Arbeiten mit Binärdaten
Einige Zellen in App Builder können Binärdaten enthalten, die als Base64-String gespeichert sind. Bibliotheken können verwendet werden, um Daten in diesen Zellen zu ändern und zu speichern, z. B. Bildbearbeitungsprogramme. Siehe die Image Resizer-Bibliothek in der App Builder-Sammlung für Beispielcode.

row.ViewModel
Die aktuelle Version von App Builder stellt einen Parameter namens ViewModel in der Row-API bereit. Dies bietet Zugriff auf die App Builder-Backend-Daten und funktioniert möglicherweise nicht, wenn Sie App Builder aktualisieren. Es wird nicht empfohlen, Code zu schreiben, der auf diese Eigenschaft angewiesen ist.

Site-Widgets

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

Site-Widgets werden ausgeführt, sobald der Browser geladen wird. Dies ermöglicht die Ausführung von Code so schnell wie möglich. Der Code wird asynchron ausgeführt, d. h. die Seite wartet nicht auf das Rendern, bis der Code ausgeführt wird.

Site-Parameter sind nicht datengebunden und unterstützen nur Nur-Text-Werte.

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

1. Gehen Sie zu App Workbench > Look & Feel > Widgets
   
2. Wählen Sie die Collection aus, 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 Browse und suchen Sie die Widget-.zip-Datei mit allen erforderlichen Widget-Dateien, wählen Sie sie aus und klicken Sie auf Open
6. Geben Sie eine Dokumentation ein, um das Widget zu beschreiben. Hilfetextinformationen, die in der IDE für ein Widget angezeigt werden, werden durch den Widget-Datensatz bereitgestellt.
7. Klicken Sie auf Save
8. Klicken Sie im Panel 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 der Region Widget Information des Control Designer aus und legen Sie die Werte Interface und Active Mode fest
   

API

getParameter(name) - string
Ruft den definierten Parameter entweder aus dem Standardwert oder aus dem vom Designer über die Site-Widget-Definition bereitgestellten Parameter ab.

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

getCurrentAuthenticationUserName() - string
Ruft den aktuell angemeldeten Benutzernamen ab oder null, falls nicht authentifiziert.

onPageLocationChange(handler: Function(event))
Diese Funktion wird verwendet, um Callbacks festzulegen, die ausgeführt werden, wenn sich der Seitenspeicherort ändert. Gibt den Pfad als String zurück.

onAuthenticationChange(handler: Function(event))
Diese Funktion wird verwendet, um Callbacks festzulegen, die ausgeführt werden, wenn sich der authentifizierte Benutzer ändert. Gibt den Benutzernamen als String zurück.

Fehlerbehebung

App Builder unterstützt Tastenkombinationen, die mit einigen 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.

Die folgenden Anweisungen ermöglichen es, die Hotkey-Unterstützung für ein bestimmtes HTML-Element und seine untergeordneten Elemente zu deaktivieren.

Um alle Tastenkombinationen 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 nur einige Tastenbindungen zu ignorieren, fügen Sie diese zum CSS-Klassensuffix hinzu. Wenn es mehr als ein Wort gibt, trennen Sie diese im CSS-Klassensuffix durch Bindestriche:

• <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 gekennzeichnet sind:

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

Weitere Informationen zur Fehlerbehebung finden Sie in den folgenden Abschnitten im Harmony-Fehlerbehebungsleitfaden:

• Widget wird nicht aktiviert oder lädt nicht korrekt