<< Prev | - Up - | Next >> |
QHTML displays the user interface using an Internet browser. So far all examples started a browser locally :
{{QHTML.build toplevel(label(value:"Hello world"))} show}
This is a facility of QHTML, not a limitation. QHTML windows can be connected to Internet browsers in many different ways, so that the user interface can be in a remote location from the QHTML running site.
The connection between QHTML and an Internet browser requires :
An Oz application listening to a socket that will accept connections from outer world.
A web page that loads the QHTML Java applet. This applet connects to the socket of the Oz application to create a communication stream between the browser and the QHTML window. This Java applet is distributed with the sources of QHTML, or by the QHTML internal web server. The web page that loads this applet can be automatically created by QHTML.
QHTML sends JavaScript commands to be executed at the browser side. Dynamic HTML is used to configure and interact with the browser.
The show
method of a QHTML toplevel
widget is a shortcut to start a local Internet browser and make it load the Java applet that will connect to the QHTML window.
Note that the Java applet must be configured so that it knows where it must connect, eg it needs to know the ip adress and port number of the listening socket of the Oz application.
To avoid the requirement of a web server, QHTML has a simplified web server built in that can serve the starting page and Java applet required by itself to work. This web server can automatically configure the served files to match the ip and port selected for the connection. A web page can be created to redirect (change the page displayed inside) the browser to the URL of the QHTML web server. This page can be placed anywhere, including public web servers, to create an entry point with a fixed URL to the QHTML application.
QHTML windows at the Oz side can live indifferently connected or not to an Internet browser. This is a simplification for the application development as the developer has not to worry of the connection state of the window, at least most of the time. Note that under some circonstances, QHTML might return QHTML.undefined
when asked for some state of the user interface (that is mainly but not limited to get
method calls). QHTML applications should always expect this return value and take proper actions accordingly (ignore the return value and discard the operation, try again later, log an error, ...) Note that the same command might successively return QHTML.undefined
and the expected value under some (rare) circumstances. Note that QHTML might return QHTML.undefined
even if it is correctly connected to a browser. The rule of thumb is : QHTML always returns the asked value if it was able to determine it, otherwise it returns QHTML.undefined
. Possible cause where QHTML cannot determine the asked value (not exhaustive) : the browser returned undefined
or another error code; a disconnection was detected after the value was asked to the browser, but before it answered to QHTML; a state with no default that was never set to any value and QHTML is not connected to a browser; a state that only the browser can know the value and QHTML is not connected to a browser.
QHTML windows can be successively connected to different browsers. One QHTML window can be connected to zero or one browser window at a time. The state of the window is monitored by QHTML so that its state persists from connection to connection. However for effeciency reasons, this monitoring cannot be garanteed to be acurate in all situations. For example, if the browser crashes, it is the last known by QHTML state of widgets that will be used when building the user interface upon a new connection.
There are two types of server QHTML can create:
QHTML connection server: the Java applet connects to this server. A communication object is created at the Oz side by the QHTML connection server for a bidirectional communication between the Oz process and the Internet Browser. A QHTML window can be connected to that browser by : {QHTMLWindow connect(ComObj)}
where QHTMLWindow
is a window object built by QHTML.build
, and ComObj
is the communication object corresponding to the Internet Browser.
Web server: provides the index page and the QHTML java applet to the Internet Browser.
QHTML server management procedures:
fun{QHTML.startServer P}
: starts a QHTML connection server on a free port and returns its number. P
is a one parameter procedure that is called each time a connection is created by the server. This procedure parameter is the communication object to the Internet Browser. For example P
could be :
proc{$ ComObj}
Window={QHTML.build someDescription}
in
{Window connect(ComObj)}
end
proc{QHTML.startServerOnPort N P}
: same as above, but force the use of the port number N
.
proc{QHTML.stopServer N}
: stops the connection server that uses the port number N
.
fun{QHTML.startWebServer N}
: starts a web server on a free port and returns its number. The Java applet is configured to use the port number N
, eg the port returned by QHTML.startServer
, or the one specfied by QHTML.startServerOnPort
.
proc{QHTML.startWebServerOnPort N M}
: same as above, but force the use of the port number M
for this server.
proc{QHTML.stopWebServer M}
: stops the web server that uses the port number M
.
proc{QHTML.startAll P N M}
: shortcut to start a connection server on port N
that uses the connection procedure P
and a web server on port M
with one command.
proc{QHTML.startAllHTMLEntryFilename P F}
: starts a connection server that uses the connection procedure P
and a web server. A redirector web page is created and saved to the file F
. This is the simplest way to make a QHTML application available from a computer that has no fixed web address : upload the file F
to a web server to make it available from a fixed URL each time you run the application, and use that adress to use the application from an Internet Browser.
<< Prev | - Up - | Next >> |