Widgets im Jitterbit App Builder

Übersicht

Widgets im App Builder ermöglichen es Entwicklern, Drittanbieter- (oder eigene) Codes bereitzustellen, um eine angepasste Steuerung auf der Seite anzuzeigen. Widgets erlauben es, mehr Metadaten zu definieren; siehe den Abschnitt Archivdateiinhalte für Details. Parameter unterstützen jetzt eine robustere Definition; siehe den Abschnitt Widget-API für Details.

Siehe die Widget-Downloadbibliothek 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, was der zugrunde liegende Wert ist.

   • Gut: Angezeigter Wert

     
     

   • Gut: Wert offensichtlich

     
     

   • Schlecht:

     

2. Widget-Tests. Denken Sie daran, wie mit dem Widget auf Touch- und Nicht-Touch-Geräten interagiert wird.

3. Widgets sollten Auto-Edit und Auto-Save respektieren. Widgets erhalten dieses Verhalten automatisch vom App Builder.

Archivdateiinhalte

_manifest.json

Alle Widgets enthalten eine Manifestdatei. In dieser Datei können Sie mehr 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 im App Builder IDE angezeigt wird und auch der Name der Archivdatei wird.

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

• binder: Der Dateiname des Widget-Binders. Siehe unten für weitere Informationen.

• template: Der Dateiname der HTML-Vorlagendatei. Siehe unten für weitere Informationen.

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

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

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

  • 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 die Benutzer die neueste Version Ihres Codes erhalten.

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

• dependencies: Durch Kommas getrennte Liste aller Abhängigkeiten, die von Ihrem Widget-Binder benötigt werden. Die Reihenfolge, in der diese Dateien erscheinen, entspricht der Reihenfolge, in der sie im Abhängigkeitsarray der Widget-API erscheinen. Stellen Sie sicher, dass Sie die Dateiendung angeben.

  • JavaScript
  • CSS

  Zum Beispiel, wenn Sie eine Bibliothek definieren, die eine Referenz zurückgibt, die Sie verwenden müssen, um sie auf ein Element zu installieren:

  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

  Selbst wenn Sie keine Abhängigkeiten haben, fügen Sie die JavaScript- und CSS-Eigenschaften mit einem leeren Array hinzu.

  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 Rückruffunktionen, die erforderlich sind, um die App Builder API mit Ihren Bibliotheken zu verbinden. In jeder werden zwei Funktionsparameter bereitgestellt.

• holderElement: Ein DOM-Element, das das in der angegebenen Vorlagendatei bereitgestellte HTML-Markup enthält. Da diese Datei optional ist, kann das Halterelement leer sein. Das Halterelement ist die Zelle, die das Widget implementieren wird. Es ist der Bereich, der im Screenshot unten hervorgehoben ist und enthält nicht das Label des Feldes.
  

  

• 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 alle statischen HTML-Inhalte, die zum Laden dieses Widgets erforderlich sind. Wenn nicht angegeben, wird das Widget ohne Inhalt erstellt, und der im Binder definierte Installations-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
Identifiziert, ob die Zeile bearbeitbar ist.

getParameter(name) - string
Ruft den definierten Parameter entweder vom Standardwert oder von 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 derselben Reihenfolge bereitgestellt, in der die Abhängigkeiten in der _manifest.json-Datei definiert sind.

WidgetApiCell
Stellt eine einzelne Zelle dar. Zellen sind das zugrunde liegende View-Modell der Steuerung, die auf der Seite angezeigt wird. 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 zu erhalten und festzulegen.

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

formattedValue - string
Diese Eigenschaft kann verwendet werden, um den zugrunde liegenden Anzeige-Wert der Zelle zu erhalten und festzulegen. Zum Beispiel wäre der zugrunde liegende Wert eines Prozentfeldes 0,25, während der Anzeige-Wert (formatierter Wert) "25%" ist. Oder ein Listensteuerung könnte einen Wert eines 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 zu erhalten. Ein persistierter Wert ist der nicht bearbeitete Wert, der derzeit im 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 das Widget ist, 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("Der Wert der Zelle wurde auf", value, "geändert.");
});

Der App Builder kann während Validierungsereignissen Änderungen an der Zelle vornehmen, wenn Standardwerte festgelegt sind oder wenn ein anderes Widget Änderungen vornimmt, die diese Zelle betreffen. Der App Builder kann auch Zellen deaktivieren, wenn Ereignisse ausgeführt werden.

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

dropChangeCallback(name: string)
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 ist groß- und kleinschreibungsempfindlich und muss mit dem Namen übereinstimmen, der im Steuerelement definiert ist, nicht mit dem Namen der Datenquelle.

edit()
Ändert die Zeile in den Bearbeitungsmodus.

save()
Speichert alle modifizierten Werte zurück in die Datenquelle.

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

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

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

• Parameter-Typ: Standardmäßig auf Control, kann auch als Column oder Static Value definiert werden. Je nach dem Typ, den Sie definieren, haben Sie unterschiedliche Werte, die entsprechend konfiguriert werden müssen:

  • Control:
    • Zielsteuerung: Eine Steuerung aus dem übergeordneten Panel, die diesen Parameterwert bereitstellt.
    • Formatierten Wert verwenden: Den formatierten Anzeigewert verwenden.
    • 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.
    • Formatierten Wert verwenden: Den formatierten Anzeigewert verwenden.
    • 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 es, das Widget dort zu übersetzen, wo es anwendbar ist.
    • Aktiv: Gibt an, ob diese Bindung aktiv ist oder nicht. Inaktive Bindungen werden nicht verwendet.

So erstellen Sie ein Widget & Fehlersuche

Widgets sind eine leere Leinwand. Der App Builder führt den Widget-Code aus, anstatt die Implementierung des App Builders zu verwenden.

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

Ein Sternbewertungs-Widget muss jedoch möglicherweise den tatsächlichen Zellwert nicht anzeigen.

Wert vom App Builder auf Ihr Widget abrufen und setzen
Der App Builder kann den Wert über Standardwerte oder Änderungen an übergeordneten Datensätzen aktualisieren. Ihre Bibliothek muss in der Lage sein, sich selbst zu aktualisieren, wenn diese Ereignisse eintreten.

Das Bereitstellen von Rückrufen ermöglicht es dem App Builder, Ihren Code auszuführen, wenn neue Werte an Ihr Widget gesendet werden müssen. Siehe setChangeCallback oben.

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

Neue Versionen hochladen & Debugging
Sobald Sie ein funktionierendes Widget haben und einen Fehler debuggen, befolgen Sie die folgenden Schritte:

1. Zippen Sie den Inhalt des lokalen Ordners, an dem Sie arbeiten (stellen Sie sicher, dass Sie nicht den übergeordneten Ordner selbst zippen, 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 die Aktualisieren-Taste auf der Seite, die Ihr Widget verwendet. Hinweis: Möglicherweise müssen Sie den Browser-Cache während der Entwicklung deaktivieren, andernfalls könnten Sie mit veralteten Code enden.

Ansichts- vs. Bearbeitungszustand
Beim Hinzufügen eines Widgets zu einem Panel können Sie angeben, ob Ihr Widget das Rendern sowohl im Bearbeitungs- als auch im Ansichtsmodus übernehmen soll. Wenn Ihr Widget nur den Bearbeitungszustand behandelt, rendert der App Builder den Zellwert im Ansichtsmodus.

Wenn Ihr Widget beide Zustände behandelt, kann Ihre Steuerung verwendet werden, um Werte zu bearbeiten, ohne zuerst auf die Schaltfläche der Bearbeitungswerkzeugleiste klicken zu müssen.

Um dies zu tun, müssen Sie die Zeile in den Bearbeitungszustand wechseln, 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 isEditState-Eigenschaft verwenden, um eine "schreibgeschützte" Version des Widgets darzustellen, die den Wert anzeigt, aber nicht zur Modifikation der Zelle verwendet werden kann.

Laden großer Abhängigkeiten
Große Ressourcen wie JQuery UI benötigen lange zum Herunterladen und Installieren. Aus Leistungsgründen wird empfohlen, nur leichte Bibliotheken oder Bibliotheken zu verwenden, die vorhandene Abhängigkeiten des App Builders nutzen. Es wurden einige Fehler gemeldet, wenn Abhängigkeiten zu langsam geladen werden.

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

row.ViewModel
Die aktuelle Version des App Builders stellt einen Parameter namens ViewModel in der Zeilen-API zur Verfügung. Dies ermöglicht den Zugriff auf die Backend-Daten des App Builders und wird beim Upgrade des App Builders nicht garantiert funktionieren. Es wird nicht empfohlen, Code zu schreiben, der auf dieser Eigenschaft basiert.

Site-Widgets

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

Site-Widgets werden ausgeführt, sobald der Browser geladen wird. Dies ermöglicht es, dass der Code so schnell wie möglich ausgeführt wird. Der Code wird asynchron ausgeführt, was bedeutet, dass die Seite nicht wartet, bis der Code ausgeführt wird, um sich selbst darzustellen.

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

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

1. Gehen Sie zu App Workbench > Aussehen & Gefühl > 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 an. Zum Beispiel: Dial Widget
5. Klicken Sie auf Durchsuchen und suchen Sie die Widget-.zip-Datei, die alle erforderlichen Widget-Dateien enthält, wählen Sie sie aus und klicken Sie auf Öffnen
6. Geben Sie eine Dokumentation an, um das Widget zu beschreiben. Hilfetextinformationen, die im IDE für ein Widget angezeigt werden, werden durch den Widget-Datensatz bereitgestellt.
7. Klicken Sie auf Speichern
8. Klicken Sie im Widget-Parameterbereich auf + Parameter und definieren Sie alle erforderlichen Parameter für das Widget
9. Wählen Sie auf der Seite, die Ihr Widget ausführen wird, das Widget aus dem Bereich Widget-Informationen des Control Designers aus und setzen Sie die Werte für Schnittstelle und Aktivmodus
   

API

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

getCurrentPageLocation() - string
Erhält die aktuelle URL der Seite.

getCurrentAuthenticationUserName() - string
Erhält den aktuell angemeldeten Benutzernamen oder null, wenn nicht authentifiziert.

onPageLocationChange(handler: Function(event))
Diese Funktion wird verwendet, um Rückrufe festzulegen, 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 Rückrufe festzulegen, die ausgeführt werden, wenn sich der authentifizierte Benutzer ändert. Gibt den Benutzernamen als Zeichenfolge zurück.

Troubleshooting

App Builder unterstützt Tastenkombinationen, mit denen einige Widget-Bibliotheken möglicherweise in Konflikt stehen. 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 Ihnen, die Unterstützung für Tastenkombinationen für ein bestimmtes HTML-Element und dessen untergeordnete 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 Tastenkombinationen zu ignorieren, fügen Sie diese dem Suffix der CSS-Klasse hinzu. Wenn es mehr als ein Wort gibt, trennen Sie sie im Suffix der CSS-Klasse mit einem 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 bearbeitbar markiert sind:

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