. Provide multiple anchor elements if you want to render multiple sockets (each one in its own table). * You may specify an anchor element for displaying notifications, by assigning id="notify_". By default, the notification anchor is added as the last element to the tag at the time when the first state is propagated to the HTML page. * Labels are automatically retrieved from the UCH, and displayed within the table structure. The language for the labels is set as "lang" attribute of the element. * Socket constants do not show up in the user interface. * Sample files: sample-tv_tuner-autogenerate.html, controller.html. Instructions for index.html & controller.html: Run the provided index.html file, retrieving it from the UCH (http://[::1]/UCH/clients/webclient/index.html). This will provide you with a list of sockets that are currently offered by the UCH. Click on any of them, and it will automatically build the user interface for it. Internally, this is done by launching controller.html with two query arguments of socket=socketName and targetId=targetId, e.g. http://[::1]/UCH/clients/webclient/controller.html?socket=http://res.i2home.org/tv/tv_tuner.uisocket&targetId="target-ABC" (not URI encoded here for simplicity). 3.2 HTML template mode In this mode, an HTML template is custom-designed for one or multiple UI sockets and prepared for operation with the UCH. This allows for custom-designed interactive control web pages, possibly including advanced graphics and JavaScript widgets. Notes for HTML template mode: * Provide a list of sockets as the first argument to org_myurc_webclient_init. The webclient code will open a session with every socket on the list, and will provide updates for pertaining values. * For any interactive HTML element, you should write your own handler for setting socket values, as follows: - Setting the value of a socket element: org_myurc_webclient_setValue(socketPath, value) whereby socketPath is the full path of a socket element consisting of: socket name + "#" + path. Example: org_myurc_webclient_setValue("http://res.myurc.org/tv#/powerMode", "ON") See sample-tv_tuner.html, sample-tv_tuner_ac.html. - As an alternative, you can use session objects directly. See sample-tv_tuner_ac2.html. * For receiving updates (including notifications) from UCH: - Write a global function onpostvalue(path, thisValue, session), and dispatch suitable rendering actions from there. (You may want to use a switch statement on the path.) See sample-tv_tuner.html, sample-tv_tuner_ac.html, sample-postvalue.html. - As an alternative, you can assign ".val" identifiers to associated HTML elements. See sample-postvalue2.html. * You can have label resources displayed by marking the corresponding HTML element with id="socketName#path.lab". The language for the labels is determined through the "lang" attribute of the element. Example: for the label of the socket. * Dimensional socket elements can only be used if their indices are known before runtime and coded into the id's of the HTML template. Example: id="/setId[0]/varId". * Hint: It is recommended to write empty nodes with beginning and closing tag (e.g. ) rather than using the shortcut . Problems have been observed using the shortcut notation. * Overall sample files: sample-tv_tuner.html, sample-tv_tuner2.html, sample-tv_tuner_ac.html, sample-tv_tuner_ac2.html, sample-requestvalue.html, sample-postvalue.html, sample-postvalue2.html. 4. JavaScript Integration in HTML File Error exceptions may be thrown by the webclient software. If thrown, the current runtime context may not be functioning anymore, and the program should be exited. You should catch potential runtime exception thrown by org_myurc_webclient_init. You should define an init() and a finalize() function in your HTML file, and call them when the document is loaded and unloaded, respectively: ... See also sample files, e.g. sample-tv_tuner.html, Note: Only include the file org_myurc_urchttp_test.js for debugging and testing. Do not include it when running in a production environment since it significantly increases load time for the browser." 5. Naming restrictions The following restrictions apply in general (for both modes of operation). * On element identifiers in socket description: - must not contain "/", "[", "]" and "#". - must not end with ".val", ".inv" or ".lab". - must not be "invoke", "state" or "ttc". * On index values used in paths at runtime: - must not contain "/", "[", "]" and "#". - must not be "invoke", "state" or "ttc". * Although theroretically encoding and decoding should be working properly, problems have been experienced with using any of the following special characters as part of socket elements paths: "&", "<", ">", '"', "'". It is not recommended to use them. * Values as items in a uis:csvlist must not contain the comma character ",". * Namespaces in Socket Description (SD) and external XML Schema Definition (XSD) documents: - Elements and attributes from the uis and xsd namespaces must be used without a namespace prefix. Declare the default namespace on the element, and the element, respectively. - Namespace prefixes for external types must be declared on the root element (either or ) with an 'xmlns:[prefix]' attribute. For every namespace prefix defined for external types, there must be a schema location specified on the root element, with the 'xsi:schemaLocation' attribute - use the prefix 'xsi' literally. - For type names in XSD type definitions, the following namespace prefixes have to be used literally: uis: http://myurc.org/ns/uisocketdesc xsd: http://www.w3.org/2001/XMLSchema Prefixes may be freely chosen for other namespaces identifying external types. 6. Extensions to the standard * Resources for SD-external types have to be specified with eltRef="[targetNamespace][typeName]", with: - [targetNamespace] being the value of the 'targetNamespace' attribute on the root element of the corresponding XML schema definition. - [typeName] being the value of the 'name' attribute on the corresponding type definition node ( or ). 7. Current Limitations * Tested with Firefox and Internet Explorer 7 only. * Values are displayed as literal values, and not as value-specific labels (exceptions see below). * All variable values have to be edited in input boxes, with the following exceptions: - If the variable has type "xsd:boolean", a checkbox is used. - If the variable has an enumeration type whose definition is included in the socket description, or whose definition is contained in an XSD file that is directly linked (via xsi:schemaLocation) from the SD, it will be displayed as combobox with labels for the values, if available. - If the variable has a closed selection, it will be displayed as combobox with labels for the values, if available. However, if the variable has a closed selection and has an enumeration type, the enumeration type is ignored. * External resources ("localAt") are not supported. * The options of a combobox are not updated if its dynamic selection set changes. * Timeout inside notification not supported. * User is requested to confirm every notification, including those that do not need explicit acknowledgement. * All variables are editable (have input boxes), whether currently writeable or not. * Removal of indices (for dimensional sets, variables and commands) supported for paths with given indices only. * If multiple sockets exist with the same name, only one of them can be open at a time. * Commands of type uis:voidCommand that have no parameters will not show up in the webclient page since the UCH does not send any pertaining path (on state or parameters) to the URC-HTTP client on a GetValues or GetUpdates request. * For complex sockets, the browser may take very long to generate the HTML user interface. An "unresponsive script" warning may be shown by Firefox. 8. TODOs * Make validate with http://validator.w3.org * Session forwarding * Session abort from target * Timeout variables/constants for notifications * Let the user confirm only those notifications that require explicit user acknowledgment. * Optional asynchronous Ajax (now only synchronous) * See "TODO" marks in code for further improvements