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

local browser = addonForm:CreateBrowser("BrowserName", "BrowserLabel", "BrowserRibbon", "WebView2"); --Create a browser on the form
 
--Evaluate a script checking if an HtmlElement with the id name exists on the page and if it's value is Addon.
--The HTML that would pass this check would look like <input id="username" value="Addon" />
local response = browser:EvaluateScript("(document.getElementById('username') != null && document.getElementById('username').value == 'Addon')");
 
if (response.Success) then	
	--Do something with the value returned
	if (response.Result == "True") then		
		browser:ExecuteScript("alert('Username set to Addon!')");
	else
		browser:ExecuteScript("alert('Username not set to Addon!')");
	end
else
	LogDebug(response.Message); 
end

Example with arguments

local browser = addonForm:CreateBrowser("BrowserName", "BrowserLabel", "BrowserRibbon", "WebView2"); --Create a browser on the form
 
--Create an anonymous javascript function invoked with params
local addNumbers = [[
	(function(n1, n2) {
		return n1 + n2;
	})
]];
 
local number1 = 5;
local number2 = 2;
local response = catalogSearchForm.Browser:ExecuteScript(addNumbers, { number1, number2 });
--response.Result would be 7
 
--If the HTML page had a javascript function named "addNumbers" that had the same function definition, just pass the javascript function name as a string.
local response = browser:EvaluateScript("addNumbers", { number1, number2 }); --Example assumes a javascript function named addNumbers exists on the current page.

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

local browser = addonForm:CreateBrowser("BrowserName", "BrowserLabel", "BrowserRibbon", "WebView2"); --Create a browser on the form 
browser:ExecuteScript("console.log('The browser has been loaded!')"); --Writes a message to the browser console, visible when the developer tools are opened.
browser:ExecuteScript("alert('Show a javascript popup alert message')"); --Displays an alert - See https://www.w3schools.com/jsref/met_win_alert.asp
 
--Execute a script with arguments
local login = [[
	(function(username, password) {
		var usernameInput = document.getElementById('username');
		var passwordInput = document.getElementById('password');
		var loginInput = document.getElementById('login');
			
		if (!(usernameInput && passwordInput && loginInput)) {
			console.log('Unable to find all three login elements');
		}
			
		usernameInput.value = username;
		passwordInput.value = password;
		loginInput.click();
	})
]];

local username = "jdoe";
local unsecurePassword = "123"; 
browser:ExecuteScript(login, { username, unsecurePassword });

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

local browser = addonForm:CreateBrowser("BrowserName", "BrowserLabel", "BrowserRibbon", "WebView2"); --Create a browser on the form 
browser:Navigate("https://www.atlas-sys.com");

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

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

--Register a title page handler that will call the GoogleLoaded function if the title of the page matches "Google"
browser:RegisterPageHandler("title", "Google", "GoogleLoaded", true); 
 
function GoogleLoaded()
  --The google page was detected via the page handler.
end

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

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

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

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

--Register a custom page handler that will call the ResultsLoaded function
browser:RegisterPageHandler("custom", "AreResultsLoaded", "ResultsLoaded", true); 
 
--Start the page watcher which will check page handlers every 2 seconds for up to 30 seconds. 
browser:StartPageWatcher(2000, 30000);
 
function AreResultsLoaded()
	--Perform logic to check if results are loaded.
	local result = browser:EvaluateScript("(document.getElementById('resultId') != null)");
	return result.Result;	
end
 
function ResultsLoaded()
  --The page has a results section
end

StopPageWatcher

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

Example

--Assume the browser & handlers have already been initialized and that the page watcher was already started.
browser:StopPageWatcher();

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

ExecuteAddonFunction(FunctionName, Parameter1, Parameter2, ...)

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:

window.chrome.webview.hostObjects.sync.atlasAddon.ExecuteAddonFunction(FunctionName, Parameter1, Parameter2, ...)

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:

var atlasAddon = window.chrome.webview.hostObjects.sync.atlasAddon;

After the ‘atlasAddon’ variable is defined, the ExecuteAddonFunction can be called using the variable name as follows:

atlasAddon.ExecuteAddonFunction(FunctionName, Parameter1, Parameter2, ...);

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:

var atlasAddon = window.chrome.webview.hostObjects.sync.atlasAddon;

After the ‘atlasAddon’ variable is defined, the ExecuteAddonFunction can be called using the variable name as follows:

atlasAddon.ExecuteAddonFunction(FunctionName, Parameter1, Parameter2, ...);

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

The following example demonstrates how to use the ExecuteAddonFunction to invoke the scripting system's LogDebug function and log the given message to the Client's log if debug logging is enabled:

window.chrome.webview.hostObjects.sync.atlasAddon.ExecuteAddonFunction("LogDebug", "This log statement originated from an addon browser.");

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

The ExecuteAddonFunction can also return a value. The following example demonstrates how to return the value of an addon’s setting within the WebView2 browser’s scripting environment.

For this example, assume the addon contains a setting named SearchEngineUrl with a value of ‘https://google.com/ ' and also defines the following function GetSettingByName that takes a setting’s name as an argument to return the value of that setting:

function GetSettingByName(settingName)	
        return GetSetting(settingName);
end

To call the GetSettingByName function within the WebView2 browser’s Javascript environment and retrieve the SearchEngineUrl setting’s value, the ExecuteAddonFunction should be used as follows, with the functionName and the settingName passed in as its parameters:

var url = window.chrome.webview.hostObjects.sync.atlasAddon.ExecuteAddonFunction("GetSettingByName", "SearchEngineUrl");

This code will return the value of the SearchEngineUrl setting ( ‘https://google.com/ ') and store it in the ‘url' variable.

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.

Example: Nested ExecuteScript Calls

The following example demonstrates a nested call to ExecuteScript. For this example, assume that two functions using the ExecuteScript command (LogMessageInBrowserConsole and RaiseNestedScriptingError) have been defined for an addon and that addonForm is a WebView2 browser:

function LogMessageInBrowserConsole(message)
	addonForm.Browser:ExecuteScript("console.log('" .. message .. "');");
end
function RaiseNestedScriptingError()
	addonForm.Browser:ExecuteScript('window.chrome.webview.hostObjects.sync.atlasAddon.ExecuteAddonFunction("LogMessageInBrowserConsole", "Reentrancy error");');
end

Calling the RaiseNestedScriptingError function will use the ExecuteScript command to call into the addon’s LogMessageInBrowserConsole function via the scripting bridge. However, when the LogMessageInBrowserConsole function is called, this function will then perform another nested call to the ExecuteScript command, resulting in the error "Nested calls to EvaluateScript or ExecuteScript detected."

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

Related content