Info |
---|
The Chromium Browser is available in ILLiad 9.0 and higher, Aeon v4.0 and higher, and Ares v4.7 and higher. |
The Chromium Browser control manages the display and interaction with a chromium web browser. It allows for direct access to and manipulation of document elements including forms and form elements.
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 ChromiumWebBrowser object being managed by this control.
- Settings: Allows for additional configuration of the chromium web browser.
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.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
local browser = addonForm:CreateBrowser("BrowserName", "BrowserLabel", "BrowserRibbon", "Chromium"); --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.
Anchor | ||||
---|---|---|---|---|
|
Property Name | Type |
---|---|
Message | string |
Success | bool |
Result | object |
EvaluateScript(script)
Executes the javascript code or function name.
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, defined as the following. |
EvaluateScript(script, args)
Executes the javascript code or function name and passes in arguments.
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, defined as the following. |
EvaluateScript(timeout, script)
Executes the javascript code or function name with a timeout.
Parameter Direction | Parameter Name | Parameter Description |
---|---|---|
Input | timeout | The timeout specified in milliseconds. |
Input | script | The javascript code or method name that should be executed. |
Output | javascriptResponse | The result of the script execution as a JavascriptResponse object, defined as the following. |
EvaluateScript(timeout, script, args)
Executes the javascript code or function name and passes in arguments and sets a timeout.
Parameter Direction | Parameter Name | Parameter Description |
---|---|---|
Input | timeout | The timeout specified in milliseconds. |
Input | script | The javascript method 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, defined as the following. |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
local browser = addonForm:CreateBrowser("BrowserName", "BrowserLabel", "BrowserRibbon", "Chromium"); --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 |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
local browser = addonForm:CreateBrowser("BrowserName", "BrowserLabel", "BrowserRibbon", "Chromium"); --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(10000, "addNumbers", { number1, number2 }); --Example uses 10 second timeout and 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 |
---|---|---|
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 |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
local browser = addonForm:CreateBrowser("BrowserName", "BrowserLabel", "BrowserRibbon", "Chromium"); --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 |
---|---|---|
Input | url | The url to navigate to |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
local browser = addonForm:CreateBrowser("BrowserName", "BrowserLabel", "BrowserRibbon", "Chromium"); --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 | ||
---|---|---|---|---|
Input | idType | The type of page handler matching that should be done against the given id.
| ||
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 |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
local browser = addonForm:CreateBrowser("BrowserName", "BrowserLabel", "BrowserRibbon", "Chromium"); --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 it's own window. The developer tools are useful when authoring and debugging an addon that uses the chromium web browser.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
local browser = addonForm:CreateBrowser("BrowserName", "BrowserLabel", "BrowserRibbon", "Chromium"); --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 |
---|---|---|
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 |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
local browser = addonForm:CreateBrowser("BrowserName", "BrowserLabel", "BrowserRibbon", "Chromium"); --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.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
--Assume the browser & handlers have already been initialized and that the page watcher was already started.
browser:StopPageWatcher(); |
Scripting Bridge
The scripting bridge allows for the browser to communicate with the addon system.
ExecuteAddonFunction
The executeAddonFunction is designed to allow javascript on the page to utilize lua functions that are within the addon.
Info | |||||
---|---|---|---|---|---|
Since javascript is case-sensitive, ensure that you call the function exactly as seen below.
|
Parameter | Type | Description |
---|---|---|
functionName | string | The lua function to be called |
args | object[] | The arguments to be passed to the lua function |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
local initializeScript = [[
$(document).on("click", "#importButton", function() {
atlasAddonAsync.executeAddonFunction('Import', { document.getElementById('valueToImport').value }); --call the Import function with the value of the valueToImport element in the web page as a parameter.
});
$(document).on("click", "#replaceButton", function() {
atlasAddonAsync.executeAddonFunction('Replace', { document.getElementById('originalValue').value, document.getElementById('valueToImport').value }); --call the Replace function with the values of the originalValue element and the valueToImport element
});
]];
function Import(newValue)
--Process the import of the newValue
...
end
function Replace(oldValue, newValue)
--Process the replacement
...
end
function Init()
--Assume browser has been created, initialized, and navigated to a site.
--Execute the initialization javascript so that when the buttons are clicked it will trigger the addon functions to be called via the scripting bridge
browser:ExecuteScript(initializeScript);
end |