WebView EWO JavaScript Schnittstelle

Die WebView EWO JavaScript Schnittstelle ist eine bidirektionale Kommunikationsschnittstelle zwischen JavaScript und Control. Sie ermöglicht einen Datenaustausch zwischen dem WebView EWO, dem UI und Control.

Vorraussetzungen

Folgende Vorraussetzungen müssen erfüllt sein um die JavaScript Schnittstelle des WebView EWOs verwenden zu können:

  • Eine gültige WinCC OA Lizenz
  • Ein aktiver WebServer auf den Ihr Projekt zugreifen kann. Für die Verwendung des WinCC OA Webservers kann z.B. ein neuer CTRL Manager mit dem Parameter "webclient_http.ctl" gestartet werden.
  • Die JavaScript Kompatibilität des WebView EWOS kann mittels der Testseite "kangax.github.io/compat-table" geprüft werden.

Konfiguration

Die JavaScript Schnittstelle kann innerhalb des WebView EWO verwendet werden. Dieses erlaubt mittels der Funktion loadSnippet eine entsprechend aufgebaute HTML Seite zu laden in welcher JavaScript Code hinterlegt und ausgeführt werden kann. Durch den Aufruf mit loadSnippet() steht die Bibliothek oaJsApi zur Verfügung.

Diese HTML Datei muss bestimmte Kriterien erfüllen::

  • JavaScript Code muss in korrekt geformten <Script> Tags eingebunden werden.
  • Es können alle herkömmlichen HTML Elemente verwendet werden
  • Die Datei darf keine <html> <body> oder <header> Tags enthalten.
  • Die Datei muss mit ".html" enden.

Ein entsprechendes Beispiel finden Sie unter WebView EWO - JavaScript Interface Examples oder innerhalb des JavaScript Demo Panels.

Anmerkung:

Bitte beachten Sie, dass bei Verwendung von loadSnippet der url Parameter des EWOs nicht mehr verwendet wird.

Verwendung innerhalb des ULC UX

Für die Verwendung von JavaScript Code innerhalb der Client Seite des ULC UX muss die EWO Eigenschaft ulcClientSideWidget aktiviert werden. Dies erlaubt es dem Browser den JavaScript Code des EWos herunterzuladen und lokal anstelle der Serverseite auszuführen.

Dadurch kann eine Reduktion der Last des Servers sowie die Verwendung der JavaScript Engine des Browsers ermöglicht werden. Zusätzlich kann , wenn möglich, die Kommunikation zwischen mehreren Clientseitigen EWOs ohne einen Zugriff auf den WebServer erfolgen wodurch auch eine Reduktion der Netzwerkauslaustung erreicht werden kann sollten keine Daten vom Server erforderlich sein.

VORSICHT:

Bei Verwendung der JavaScript Schnittstelle innerhalb des ULC UX (die Kombination aus loadSnippet() and ulcClientSideWidget = true) ermöglicht der WebSocket den lokalen Zugriff auf die oaJsApi welche potentiell verwendet werden könnte um, z.B. Datenpunktwerte direkt über die Entwickler Konsole des Web Browsers zu manipulieren.

Anmerkung:

Bitte beachten SIe, dass beim EInsatz von ulcClientSideWidget = true der Code auf dem Client ausgeführt wird und die Lokalisierung (Zeit, Zeitzone, Sprache, etc.) sich auf die Informationen des Clients bezieht.

JavaScript Schnittstelle

Um Ihre Projektdaten innerhalb von JavaScript zu adressieren steht innerhalb des WebView EWOs die oaJsApi JavaScript Bibliothek zur Verfügung. Diese wird automatisch geladen wenn ein JavaScript Snippet mit der WebView EWO Funktion loadSnippet geladen wird. Die entsprechenden Funktionen der Bibliothek können anschließend innerhalb des JavaScript Codes mittels oaJsApi.<Funktionsname> aufgerufen werden.

Die oaJsApi Bibliothek bietet ein bestimmtes Set an Funktionen an, welche innerhalb der API Dokumentation beschrieben sind.

Hinweise

Folgende Hinweise sollten bei der Verwendung der JavaScript Schnittstelle beachtet werden:

  • Es wird empfohlen bei Datenpunkt Funktionen die übertragenen Elemente zusammenzuzufassen und mittels eines Funktionsaufrufs abzuarbeiten anstelle eines einzelnen Aufrufs je Datenpunkt. Dieses Vorgehen erlaubt einen signifikant höheren Durchsatz an Datenpunktwerten. Dieses Vorgehen trifft auch auf die native CTRL Implementierungen zu, aber für JavaScript sind die Auswirkungen signifikant höher.
  • Um den Fehler "Values were discarded" beim Senden vieler Aufrufe der toCtrl Funktion zu vermeiden kann der Wert des Config Eintrages [general]ctrlMaxPendings erhöht werden, z.B. "ctrlMaxPendings = 10000".
  • Bei Verwendung des ULC UX, einem oder mehreren aktivierten ulcClientSideWidgets und vieler Requests in kurzer Zeit kann es zu einer maximalen Auslastung der Bandbreite kommen was dazu führt, dass die normale Abarbeitung der ULC UX Kommunikation beeinflusst wird.
  • Die Werte "Infinity", "Negative Infinity" und "Not-A-Number"(NaN) werden durch die JavaScript Schnittestelle nicht unterstützt. Diese werden automatisch durch den Wert "null" ersetzt oder ein Konvertierungsfehler wird ausgelöst.

Einschränkungen

Folgende Einschränkungen müssen bei der Verwendung der JavaScript Schnittstelle beachtet werden:

  • Die JavaScript Schnittstelle ist nicht für die Verwendung mit der Mobile UI Applikation oder dem ULC UX verfügbar. Die Unterstützung der WebView EWO JavaScript Schnittstelle für diese Plattformen wird erst in einem späteren Release des Produkts zur Verfügung stehen,.
  • Die Datentypen bit32 und bit64 müssen als Bit String angegeben werden, z.B. "1010101011" anstelle von 683 oder "0x2AB".
  • Der Datentyp "blob" kann nicht direkt verwendet werden. Eine manuelle Encodierung ist erforderlich, siehe "Encodierung des BLOB Datentyps"
  • Der Wert "null" wird nicht durch die JavaScript Schnittstelle unterstützt.

Schnittstellen Demonstations Panel

Eine Demonstration und Getting Started Beispiele für die JavaScript Schnittstelle können unter /panels/examples/html/js/ gefunden werden.

Mapping der Datentypen

Folgende Mappings werden zwischen den Datentypen von CTRL und JavaScript intern angewandt:

CTRL Datentyp JavaScript Datentyp Erlaubte Wertebereiche
blob string -
bool bool true oder false
float number -1.79769e+308 to +1.79769e+308
uint number 0 to +4.294.967.295
int number -2.147.483.648 to +2.147.483.647
long number -9.007.199.254.740.992 (JavaScript: Number.MIN_SAFE_INT) bis +9.007.199.254.740.991 (JavaScript: Number.MAX_SAFE_INT)
ulong number 0 bis +9.007.199.254.740.991 (JavaScript: Number.MAX_SAFE_INT)
string string -
char number 0-255
time string
anytype
mixed
dyn_string array
dyn_int array
dyn_float array
mapping object
bit32 string 0 to +4.294.967.295; Muss als bitstring angegeben werden.
bit64 string 0 to +18.446.744.073.709.551.615; Muss als bitstring angegeben werden.
shape string Name des Shape
dpidentifier string -
langString string String der momentanen Sprache.

Encodierung des BLOB Datentyps

Durch technische Einschränkungen ist eine direkte Übergabe zwischen Control und JavaScript für den Datentyp blob nicht möglich. Um trotzdem mit blobs arbeiten zu können müssen diese manuell als Base64 encodiert werden.

Anmerkung:

Für Datenpunktelemente des Typs "blob" ist diese Encodierung nicht zusätzlich erforderlich.

Beispiel

Diese Beispiel-Implementierung zeigt wie eine Encodierung/Decodierung der blobs umgesetzt werden kann.

CTRL

mapping getOutArgsObject()
{
  blob blob0="01000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F";
  blob blob1="02000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F";
  dyn_string blobArray = new dyn_string(base64Encode(blob0));
  dynAppend(blobArray,base64Encode(blob1));

  mapping outArgsObject = makeMapping(
  "blob", base64Encode(blob0),
  "blobList", blobArray);

  return outArgsObject;
}

JavaScript:

function msgReceived(arg)
{
  var decoded = window.atob(arg.blob);
  var decoded1 = window.atob(arg.blobList[0]);
}