Add wrappers to optionally convert incoming data

Wrappers can be added as a third argument to WebChannel
constructors or by explicitly calling addConverter.
They can be added by supplying their name or by supplying
a function. If the function is not applicable it must return
undefined to proceed to to the next wrapper.

Data is transmitted as JSON when sent over the WebChannel.
Because JSON does not have a date, type QDateTime objects are sent
as ISO 8601 text strings. The "Date" converter converts such
strings to ECMAScript Date objects.

Fixes: QTBUG-98490
Change-Id: I83bb7476b50838359db5b981f500871142fa41f0
Reviewed-by: Arno Rehn <a.rehn@menlosystems.com>

1 files changed, 10 insertions, 1 deletions

diff --git a/src/webchannel/doc/src/javascript.qdoc b/src/webchannel/doc/src/javascript.qdoc
index d36476e..0657953 100644
--- a/src/webchannel/doc/src/javascript.qdoc
+++ b/src/webchannel/doc/src/javascript.qdoc
@@ -14,7 +14,8 @@
     can load the file via \c qrc:///qtwebchannel/qwebchannel.js. For external clients, you
     need to copy the file to your web server. Then instantiate a QWebChannel object and pass
     it a transport object and a callback function, which will be invoked once the
-    initialization of the channel finishes and the published objects become available.
+    initialization of the channel finishes and the published objects become available. An optional
+    third argument contains an array of converter wrapper functions or a single one.
 
     The transport object implements a minimal message passing interface. It should be an object
     with a \c send() function, which takes a stringified JSON message and transmits it to the
@@ -27,6 +28,14 @@
     socket's \c onopen handler. Take a look at the \l{Qt WebChannel Standalone Example} to see how
     this is done.
 
+    A converter wrapper function is either a string with the name of a built-in converter or a
+    user supplied function that takes the object to process as an argument and returns the
+    resultant type or undefined if the function does not apply. If undefined is returned the next
+    converter is processed. If there are no converters that returns a value other than undefined,
+    processing proceeds as normal. "Date" is the only currently built-in converter function. It
+    takes a string with an ISO 8601 date and returns a new Date object if the syntax is right and
+    the date is valid.
+
     \section1 Interacting with QObjects
 
     Once the callback passed to the QWebChannel object is invoked, the channel has finished