uhtml (HTML Widget)

The uhtml widget is a field-level widget in a form component that renders HTML code (including HTML, CSS, and JavaScript) or displays a web page (when the field value is a URL prefixed by an ampersand (&www.mysite.com/doc/index.html). Uniface provides a logical widget called HTML, which is mapped to uhtml.

For more information, see Specifying a Widget for a Field or Entity.

Description

The uhtml widget enables you to embed HTML 5 or a complete web page in a Uniface form and have the Uniface application interact with them. Using widget operations and interactive triggers, you can create a rich, interactive experience that is suitable for many purposes, such as embedding application help, adding social media interactions, or embedding your own limited web browser in the application.

Although the uhtml widget can display external URLs, this can be problematic for both usability (for example, links that take the user away from the intended page) and security.

Important: When using the uhtml widget to display external web sites or web pages, you are responsible for ensuring the security of the application. For more information, see Web Security Guidelines.

Restrictions

The uhtml widget makes use of HTML rendering and JavaScript execution provided by the Chromium Embedded Framework (CEF3). Additional functionality may be inherited from Chromium, but it can be changed or removed without notice, and is not maintained or supported by Uniface.

For the current version of CEF3 used by Uniface, see the Platform Availability Matrix.

For information about functionality provided in the CEF3 project, consult the chromiumembedded and CEF forum web sites.

Note the following:

• Uniface sends content as UTF8. If the content contains the charset meta tag, it should also be set to UTF8 to ensure that browser displays the data correctly.
• With the exception of Gold key combinations that use the plus + key in the numeric keypad, keyboard input is passed to the widget rather than being handled by Uniface. This is because the HTML and JavaScript inside the page may do their own keyboard processing. To define a list of keys that Uniface, rather than the widget, should handle, set the UnifaceKeys property. For more information, see Gold and Tab Keys in the HTML Widget.
• The uhtml widget performs SSL certificate checks, and will not display a requested URL if the common name of the certificate does not match the server name. You must ensure that valid certificates are available on the local machine, either in the browser or as Trusted Root Certification Authority on Windows.
• Running the uhtml widget automatically switches the Data Execution Protection Policy (DEP) on, which may affect the ability of Uniface to run (older) third-party components such as OCX controls and COM components. For more information, see Data Execution Protection.
• The performance of a form that contains many uhtml widgets may suffer because of the number of rendering engines that must be started. To improve performance, you can adjust the number of renderers that can stay active and be reused by setting the CefRendererCache initialization setting. For more information, see CefRendererCache.

Gold and Tab Keys in the HTML Widget

In the uhtml widget, most keyboard input is handled by the widget's embedded renderer rather than by Uniface. As a result:

• Gold key combinations are intercepted and handled as Uniface keys, when the plus + key in the numeric keypad is used as the Gold key. All other keystrokes are passed on to the widget for handling. For example, Gold+M will display the message frame, but Ctrl+M will not.
• Tab and (Shift+Tab) keys are used to navigate to HTML elements that can have focus. This in contrast to other Uniface widgets, where the Tab key is used to navigate between Uniface fields. Tab and Shift-Tab navigate to the next or previous field in the following circumstances:
  • When the HTML element with focus is the last one in the HTML (based on tab index), and the user tries to move the focus to the next element on the page, the ^NEXT_FIELD macro is executed.
  • When the HTML element with focus is the first one in the HTML (based on tab index), and the user tries to set focus to the previous element (usually by pressing Shift+Tab), the ^PREV_FIELD macro is executed.

If you want the widget to accept the Ctrl key combinations to activate Uniface macros and structure editor functions, you can use the UnifaceKeys property to define the keys that should be redirected. You can also add the Tab key to navigate between fields. For more information, see Uniface Keys (UnifaceKeys) .

HTML Values

By default, the field value is rendered as HTML code, so "some text" is treated as if it were "<html><body>some text</body></html>". The value could also be an HTML snippet, a complete web page, or JavaScript. For example:

operation exec
F_HTML = "<H2>Uniface Web Sites</h2> <ul>%\
  <li>uniface.info</li>%\
  <li>www.uniface.com</li>%\
  <li>training.uniface.com</li> %\
</ul>"
edit
end

Tip: The line continuation marker ensures that a long string is readable but correctly interpreted by Uniface.

URL Values

To display a web page in the widget, the value must be a URL, prefixed by an ampersand (&). For example, to load a URL:

F_HTML = "&unifaceinfo.com/docs/1000/Uniface_Library_HTML/ulibrary/aboutUniface.html"

The value is rendered as if it werehttp:/unifaceinfo.com/docs/1000/Uniface_Library_HTML/ulibrary/aboutUniface.html. At run time the specified web page is loaded into the widget.

F_HTML = "&file://page.html"

Widget Properties

Triggers

• trigger loadError
• All other triggers are user-defined, and only if Use Extended Triggers is true.

The uhtml widget also supports widget operations for manipulating widget content without changing the field value. See Widget Operations.

Widget Operations

The uhtml widget has widget operations that can be called in ProcScript to manipulate the contents of the HTML widget, without changing the field's value. To call these functions, clear the Use Field Value property (UseFieldValue=false) and use the following ProcScript instruction:

$fieldhandle(Field)->$widgetoperation(WidgetOperation,Params)

For more information, see $widgetoperation .

Executing a JavaScript Function in the HTML Widget

The content of the HTML widget can include JavaScript functions. These can be accessed from ProcScript using:

$fieldhandle(Field)->$widgetoperation("JS:Function",Params)

For example, the HTML widget contains the following JavaScript, which displays some provided text:

<script language=�?javascript�?>
function addText(id, text) {
    document.getElementById(id).innerHTML = text;
}
</script>

In ProcScript, you can execute this code as follows:

$fieldhandle(F_HTML)->$widgetoperation("JS:addText", "status", "In progress")

Defining and Calling Interactive Triggers

The HTML widget supports user-defined interactive triggers that can be called from JavaScript in the widget content. This is possible only if the Use Extended Triggers property is selected (ExtendedTriggers=true). In this case, you can write JavaScript functions that call these triggers by addressing the window.unifaceTriggers JavaScript object.

Note:  Calls to interactive triggers are asynchronous, so you cannot define interactive triggers with OUT or INOUT parameters, or return values.

For example, you can define a trigger with one parameter:

trigger selectColor
params
  string pColor : IN 
endparams
   ... <do something>
end

For example, to call the interactive trigger selectColor with one parameter, the widget could contain the following JavaScript:

<script language="javascript">
window.unifaceTriggers('selectColor', 'red');
</script>