ACtl.runInPageCtx

Executes Javascript code in the page context of the tab the script is running in. This allows scripts to use functions and variables defined by the page's own code, which is isolated from the script context. Learn more at Script Isolation.

The code to execute can be given as a function or as a Javascript file.

This function does nothing when called from a background script, as there's no page context in that case.

ACtl.runInPageCtx([args,]func) args Type: Array Default: undefined An array of values to be passed as arguments to the func function. If a single argument is passed, it can be passed as is, without being enclosed in an array.
All values must be JSONable, since they have to be moved between contexts. func Type: Function The function to run. It cannot use closure variables or the ACtl API object since it will run in the page context which is isolated from the script context. However, it can use global variables that exist in the page context. Returns Type: Promise Resolves to: JSONable Returns immediately. The Promise will resolve with func's return value. This value must be JSONable, since it has to be moved between contexts. Throws Type: JSONable Throws any errors thrown by func. Those errors must be JSONable values, since they have to be moved between contexts. This second variant of the function is analogous to ACtl.include, but the code is included in the page context rather than the script context. ACtl.runInPageCtx(fileLocation[,again]) fileLocation Type: string Either a URL, data URI, local path or UNC path of a Javascript file to run in the page context. It can be relative to the script's location (if there is one). It can also contain placeholders such as <desktop>, <documents> and others.

The code in the file won't have access to the ACtl API object. again Type: boolean Default: false If false, the file will be included only if it hasn't been included already in the page context (by any AutoControl script).
If true, the file will always be included. Returns Type: Promise Resolves to: boolean Returns immediately. The Promise will resolve with true once the file has been included and executed or false if the file wasn't included (depending on the again argument). Throws Type: string Error description if fileLocation cannot be accessed. Javascript errors that occur in the file will NOT propagate to the context in which ACtl.runInPageCtx was called.

Examples

If a given webpage uses the jQuery library, we can reuse it in our own code. That way, we avoid loading it again in the script context.


	//Load jQuery Color plugin in the page context
	await ACtl.runInPageCtx('https://code.jquery.com/color/jquery.color-2.1.2.js') ;
	ACtl.runInPageCtx(()=>{
		//we use jQuery here assuming it's already loaded in the page
		$('body').animate({backgroundColor: 'blue'}) ;
	}) ;

We can pass values from the script context to the page context and vice versa:


	let username = await ACtl.var('username') ;
	//Pass `username` to the page context and get a result back
	let result = await ACtl.runInPageCtx(username, user =>{
		//The `logUserIn` function should be defined in the page's code
		return logUserIn(user) ;
	}) ;

We can also run any file from the hard drive:


	await ACtl.runInPageCtx('C:/Projects/My Library/lib.js') ;
	await ACtl.runInPageCtx('<desktop>/unlockRightButton.js') ;

Scripting API Script Isolation Asynchronicity Backgrnd Scripts GUI vs API ACtl.include ACtl.import ACtl.getFile ACtl.saveFile ACtl.saveURL ACtl.openURL ACtl.closeTab ACtl.runInTab ACtl.runInFrames ACtl.runInPageCtx ACtl.getTabInfo ACtl.getTabIds ACtl.TAB_ID ACtl.setTabState ACtl.captureTab ACtl.execAction ACtl.runCommand ACtl.getClipboard ACtl.setClipboard ACtl.expand ACtl.switchState ACtl.var ACtl.pubVar ACtl.on ACtl.off ACtl.sleep ACtl.STOP_CHAIN ACtl.STOP_FULL_SEQ