Widgets im Jitterbit App Builder

Übersicht

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

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

Widget-Richtlinien

1. Widgets sollten den zugrunde liegenden Wert anzeigen oder es sollte offensichtlich sein, was der zugrunde liegende Wert ist.

   • Gut: Wert 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 automatische Speicherung berücksichtigen. Widgets erhalten dieses Verhalten von App Builder automatisch.

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, das im App Builder IDE und wird zum Archivdateinamen.

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

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

• template: Der Dateiname der HTML-Vorlagendatei. Weitere Informationen finden Sie weiter 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 Parametermetadaten, für jedes:

  • name: der Parametername
  • default: eine Zeichenfolge, die den Standardwert enthält
  • translate: unterstützt den Wert true oder false

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

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

• Abhängigkeiten: Durch Kommas getrennte Liste aller Abhängigkeiten, die Ihr Widget-Binder benötigt. Die Reihenfolge, in der diese Dateien erscheinen, entspricht der Reihenfolge, in der sie im Abhängigkeitsarray der Widget API erscheinen. Achten Sie darauf, die Dateierweiterung anzugeben.

  • 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 Sie keine Abhängigkeiten haben, schließen Sie die JavaScript- und CSS-Eigenschaften mit einem leeren Array ein.

  title="Manifest Entry" "javascript": [], "css": []

binder.js

binder.js

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

Der Binder stellt zwei Callbacks bereit, die zum Binden des App Builder API zu Ihren Bibliotheken. In jeder werden zwei Funktionsparameter bereitgestellt.

• holderElement: Ein DOM-Element, das die HTML-Auszeichnung enthält, die in der angegebenen Vorlagendatei bereitgestellt wird. Da diese Datei optional ist, kann das Halterelement leer sein. Das Halterelement ist die Zelle, die das Widget implementieren wird. Es ist der im Screenshot unten hervorgehobene Bereich 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 den Zugriff auf die Daten in der Zelle und im Panel.

• view.html (optional): Diese Datei enthält sämtliches statisches 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 sämtliches erforderliches HTML rendern.

Widget-API

Zelle abrufen()
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 vom 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 sind in einer Zeile einer Tabelle vorhanden.

Wert - Zeichenfolge
Mit dieser Eigenschaft können Sie den zugrunde liegenden Wert der Zelle abrufen und festlegen.

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 wäre der zugrunde liegende Wert eines Prozentfelds 0,25, während der Anzeigewert (formatierter Wert) „25 %“ ist. Oder ein Listensteuerelement könnte den 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 persistenten Wert der Zelle abzurufen. Ein persistenter 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 Rückrufe 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 Rückrufe für eine Zelle festzulegen. Die folgenden benannten Rückrufe 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 verursachen, wenn Standardwerte festgelegt sind oder wenn ein anderes Widget Änderungen verursacht, die diese Zelle betreffen. App Builder kann Zellen auch deaktivieren, wenn Ereignisse ausgeführt werden.

App Builder übergibt einen einzelnen Parameter an den bereitgestellten Rückruf, der den geänderten Wert enthält. Im deaktivierten Fall ist der Wert entweder true oder false.

dropChangeCallback(Name: Zeichenfolge)
Entfernt das Abonnement eines Änderungsrückrufs.

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

getCellByColumnName(Name: Zeichenfolge) - WidgetApiCell
Gibt eine Instanz einer Zelle in dieser Zeile zurück. Der Name ist groß- und kleinschreibungsabhängig 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:

  • Steuerelement:
    • Zielsteuerelement: Ein Steuerelement aus dem übergeordneten Panel, das 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: Formatierten Anzeigewert verwenden.
    • 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 bei Bedarf ü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 ein unbeschriebenes Blatt. App Builder führt den Widget-Code aus, anstatt App Builder's Implementierung.

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

Ein Widget für die Sternebewertung muss jedoch möglicherweise nicht den tatsächlichen Zellenwert angeben.

Abrufen und Festlegen des Wertes 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 eintreten.

Durch die Bereitstellung von Rückrufen können App Builder um Ihren Code auszuführen, wenn er neue Werte an Ihr Widget senden muss. 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.

Hochladen neuer Versionen und Debuggen
Sobald Sie ein Widget Operationsbereit 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 der Look & Feel-Anwendung hoch
3. Drücken Sie auf der Seite mit Ihrem Widget auf Aktualisieren. Hinweis: Möglicherweise müssen Sie während der Entwicklung Ihren Browser-Cache deaktivieren, da Sie sonst veralteten Code erhalten könnten.

Anzeige- vs. Bearbeitungsstatus
Wenn Sie einem Panel ein Widget hinzufügen, können Sie angeben, ob Ihr Widget die Darstellung sowohl des Bearbeitungs- als auch des Anzeigestatus handhabt. Wenn Ihr Widget nur den Bearbeitungsstatus handhabt, App Builder rendert den Zellenwert im Ansichtszustand.

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 Bearbeitungszustand versetzen, falls sie sich nicht bereits darin befindet. 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 laden
Große Ressourcen wie JQuery UI benötigen viel Zeit zum Herunterladen und Installieren. Aus Leistungsgründen wird empfohlen, nur leichte Bibliotheken oder Bibliotheken zu verwenden, die vorhandene App Builder Abhängigkeiten sind implementiert. Es wurden einige Fehler gemeldet, wenn Abhängigkeiten zu langsam geladen werden.

Arbeiten mit Binärdaten
Einige Zellen in App Builder kann binäre Daten enthalten, die als Base64-Zeichenfolge 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 im App Builder Sammlung für Beispielcode.

row.ViewModel
Die aktuelle Version von App Builder stellt einen Parameter namens ViewModel in der Zeilen API bereit. Dies ermöglicht den Zugriff auf App Builder Backend-Daten und es wird nicht garantiert, dass sie beim Upgrade funktionieren App Builder. Es wird nicht empfohlen, Code zu schreiben, der auf dieser Eigenschaft basiert.

Site-Widgets

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

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

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

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

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 durch den Widget-Datensatz bereitgestellt.
7. Klicken Sie auf Speichern
8. Klicken Sie im Fenster „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.

beiSeitenstandortänderung(Handler: Funktion(Ereignis))
Mit dieser Funktion können Rückrufe festgelegt werden, die ausgeführt werden, wenn sich der Seitenstandort ändert. Gibt den Pfad als Zeichenfolge 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 Zeichenfolge zurück.

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 seine untergeordneten 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 nur einige Tastaturbelegungen zu ignorieren, fügen Sie sie dem CSS-Klassensuffix hinzu. Wenn es mehr als ein Wort gibt, trennen Sie sie 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>