The WebView2 Browser is available when creating addons instead of having to use Internet Explorer or Chromium. This enhancement is currently available for use with all versions of the Aeon Client v5.2 or later, ILLiad Client v9.2.4 or later, and Ares Client v5.0.9 or later. To use the WebView2 browser for any pre-existing addons, they will need to be re-written to include the properties mentioned below since there is not an easy way to toggle for the new supported browser.

The WebView2 Browser control manages the display and interaction with a Microsoft Edge WebView2 web browser. It allows for direct access to and manipulation of document elements including forms and form elements.

The WebView2 browser updates itself via Windows Update, removing the need to update the version of the browser through new ILLiad/Ares/Aeon releases as is the case with the embedded Chromium browser. Due to these enhancements, and due to Microsoft’s end of support for Internet Explorer, Atlas strongly encourages addon developers to use WebView2 when creating Client addons.

Creating an Addon with Dual Chromium/WebView2 Support

The WebView2 browser support has been added to Aeon 5.2, ILLiad Client v9.2.4, and Ares Client v5.0.9 and is not available for use with any prior versions of Atlas software. Therefore, it is recommended that when updating or creating an addon that uses the WebView2 browser, support for Chromium is also included in the addon code to make that addon backward compatible with previous software versions.

Doing so will ensure that only one version of the addon will need to be maintained instead of having to maintain two separate versions (i.e., one version using Chromium and one version using WebView2). Click to expand the section below for instructions on implementing dual Chromium/WebView2 support in your addon.

Instructions for implementing dual Chromium/WebView2 support

The following code shows how to define a WebView2Enabled function that will return the value ‘true’ if WebView2 support is available for the version of the software running the addon, and ‘false’ otherwise:

function WebView2Enabled()
    return AddonInfo.Browsers ~= nil and AddonInfo.Browsers.WebView2 ~= nil and AddonInfo.Browsers.WebView2 == true;
end

Once this function is defined, it can then be used to create a WebView2 browser if the function returns the value ‘true’ and a Chromium browser if the function returns the value ‘false’:

 if (WebView2Enabled()) then
        form.Browser = form.Form:CreateBrowser(Name, Label, RibbonPageName, "WebView2");
    else
        form.Browser = form.Form:CreateBrowser(Name, Label, RibbonPageName, "Chromium");
    end

Properties

Address: The URL of the current page.
FieldName: A string representing the name of the control. This can be used for retrieving the control.
Label: A string representing the label that should be displayed beside the field on the form.
LabelVisible: A boolean value representing whether or not the label should be displayed.
TypeName: A string representing the full name of the control type.
WebBrowser: The underlying WebView2 object being managed by this control.

Methods

CheckHandlerQueue

Forces an immediate check of the page handler queue. This is primarily used when JavaScript and AJAX enabled pages perform updates that do not require an actual page change in the browser, but need to be detected and checked by the browser.

Example

local browser = addonForm:CreateBrowser("BrowserName", "BrowserLabel", "BrowserRibbon", "WebView2"); --Create a browser on the form 
browser:CheckHandlerQueue(); --Check the page handlers

EvaluateScript

Executes JavaScript and returns the result. There are multiple EvaluateScript method signatures taking different arguments.

JavaScript Response Object

The output type of all EvaluateScript methods is defined as the following. See the examples below making use of the JavaScript response object.

Property Name	Type

Property Name	Type
Message	string
Success	bool
Result	string If the JavaScript executed is intended to return a complex object, it will be returned as a JSON string. JSON strings can be deserialized back into complex objects using the JsonParser class available here.

EvaluateScript(script)

Executes the JavaScript code or function name.

Parameter Direction	Parameter Name	Parameter Description

Parameter Direction	Parameter Name	Parameter Description
Input	script	The JavaScript code or javascript method name on the page that should be executed.
Output	javascriptResponse	The result of the script execution as a JavascriptResponse object.

EvaluateScript(script, args)

Executes the JavaScript code or function name and passes in arguments.

Parameter Direction	Parameter Name	Parameter Description

Parameter Direction	Parameter Name	Parameter Description
Input	script	The javascript method name on the page that should be executed.
Input	args	The arguments passed to the javascript method.
Output	javascriptResponse	The result of the script execution as a JavascriptResponse object.

Example using script only

Example with arguments

ExecuteScript

Executes the supplied JavaScript code asynchronously in the context of the browser.

Parameter Direction	Parameter Name	Parameter Description

Parameter Direction	Parameter Name	Parameter Description
Input	script	The JavaScript code or javascript function name that should be executed.
Input - Optional	arguments	The arguments to be passed as params to the method

Example

Navigate

Attempts to load the specified URL into the browser.

Parameter Direction	Parameter Name	Parameter Description

Parameter Direction	Parameter Name	Parameter Description
Input	url	The URL to navigate to The URL must begin with “http://” or “https://”

Example

RegisterPageHandler

Registers a new page handler for use in detecting when pages that have automated actions associated with them are loaded and alerting the addon script to respond to the page load.

Parameter Direction	Parameter Name	Parameter Description

Parameter Direction	Parameter Name	Parameter Description
Input	idType	The type of page handler matching that should be done against the given id. A detailed description of the page handler types and how each works is listed in the Page Handlers section.
Input	id	The id to match against
Input	handlerName	The name of the Lua method that should be called when the page handler is invoked
Input	critical	Whether or not the page handler is considered a critical page handler, which should exist outside of the normal queue and should be checked every time the the system checks for a page match

Example

ShowDevTools

Open developer tools in its own window. The developer tools are useful when authoring and debugging an addon that uses the Edge/WebView2 web browser.

Example

StartPageWatcher

Starts the page watcher, which will check the page handler queue (and critical page handlers) at an interval defined by checkInterval. If no match is found when the maxWatchTime is reached, the handler will stop. This is primarily used on pages that use AJAX or other similar methods to make dynamic changes to the page content without actually causing the page to fully change. In these cases, a page watcher can be started before performing an action that will cause a page update so that the new page state can be checked.

Parameter Direction	Parameter Name	Parameter Description

Parameter Direction	Parameter Name	Parameter Description
Input	checkInterval	The interval, in milliseconds, that the page handler queue should be checked
Input	maxWatchTime	The maximum amount of time,in milliseconds, the page watcher should run before stopping

Example

StopPageWatcher

Stops the page watcher so that it will not perform any more checks on the page handler queue.

Example

Scripting Bridge

The scripting bridge is an object in the WebView2 browser's Javascript environment that allows you to access the addon scripting system from the WebView2 browser. The scripting bridge object can be referenced from the browser using the window.chrome.webview.hostObjects.sync.atlasAddon object.

ExecuteAddonFunction

The scripting bridge only has one function: ExecuteAddonFunction. This allows you to execute a Lua function with the WebView2 browser's Javascript, such as built-in functions like LogDebug or functions defined in the addon itself. The signature of the function is

Parameter	Type	Description

Parameter	Type	Description
FunctionName	string	The name of the lua function to be called
Parameter1, Parameter2, etc.	-	The parameters are optional and are only needed when appropriate for the function being called.

Format for ExcuteAddonFunction Call

The function can be called using the following format:

Tip: Due to the length of the function call, if you're making frequent use of the scripting bridge, consider defining a variable that points to it for later use, for example: After the ‘atlasAddon’ variable is defined, the ExecuteAddonFunction can be called using the variable name as follows:

Tip: Due to the length of the function call, if you're making frequent use of the scripting bridge, consider defining a variable that points to it for later use, for example: After the ‘atlasAddon’ variable is defined, the ExecuteAddonFunction can be called using the variable name as follows:

Example: Calling the Lua system's built-in LogDebug function

Example: Calling a Lua function defined by the addon to return an addon setting value

Warning: Avoid Nested Calls to ExecuteScript

The WebView2 browser’s ExecuteScript command does not support reentrancy, meaning that a call to ExecuteScript that leads to another nested call to ExecuteScript will return an error. Be careful to avoid nested calls to ExecuteScript when using the ExecuteAddonFunction to make function calls in the browser’s Javascript environment.

Atlas Addons

WebView2 Browser

Creating an Addon with Dual Chromium/WebView2 Support

Instructions for implementing dual Chromium/WebView2 support

Properties

Methods

CheckHandlerQueue

Example

EvaluateScript

JavaScript Response Object

EvaluateScript(script)

EvaluateScript(script, args)

Example using script only

Example with arguments

ExecuteScript

Example

Navigate

Example

RegisterPageHandler

Example

ShowDevTools

Example

StartPageWatcher

Example

StopPageWatcher

Example

Scripting Bridge

ExecuteAddonFunction

Format for ExcuteAddonFunction Call

Example: Calling the Lua system's built-in LogDebug function

Example: Calling a Lua function defined by the addon to return an addon setting value

Warning: Avoid Nested Calls to ExecuteScript

Example: Nested ExecuteScript Calls