AutoControl Control your browser your way Forum               Install now from theChrome Web Store


Runs Javascript code in the context of other tabs and all embeded documents in those tabs.
Embedded documents are specified by the following HTML elements:
<frame>, <iframe>, <embed>, <object>.

In other words, this function runs code in the top frame as well as all subframes at any nesting depth.
In contrast, ACtl.runInTabs runs code only in the top frame of each tab. Therefore, the following call:
ACtl.runInTab(tabSpec, args, func)
is functionally equivalent to:
ACtl.runInFrames(tabSpec, {depth: 0}, args, func)
Limitation: This function cannot run code in protected pages.
ACtl.runInFrames(tabSpec,frameFilter[,args],func) tabSpec Type: TabSpec One or more tabs in which to run func. It can be either a tab ID, a filter object, a tab-selection name or an array combining all that. Full details at Tab Specifier.
The code given by func runs concurrently on each frame of each tab, not sequentially.
Therefore, errors thrown in one frame don't prevent the execution of the code in any other frame.
Limitation: Tabs containing protected pages will be omitted from the list. i.e. no attemp to run func will be made for those tabs.
frameFilter Type: Object An object with zero or more of the following properties. Each property represents a condition. func will run only in the frames that satisfy all conditions.
A condition can be a number or string for an exact match or a RegExp for a pattern match.
If the object is empty or has no valid conditions, func will run in all frames.
depthnumberNesting depth of the frame. The top frame has depth zero.
minDepthnumberMinimum nesting depth of the frame.
maxDepthnumberMaximum nesting depth of the frame.
hrefstring | RegExpThe URL of the frame.
protocolstring | RegExpThe protocol of the frame.
hostnamestring | RegExpThe host name of the frame.
portstring | RegExpThe port of the frame.
pathnamestring | RegExpThe path of the frame.
searchstring | RegExpThe query string of the frame.
hashstring | RegExpThe fragment of the frame.
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 in each frame. This function cannot use closure variables since it will run in a different browsing context. However, it can still use global variables that exist in the frame in which it will run. Returns Type: Promise Resolves to: Array Returns immediately. The Promise will resolve to an array containing the return value of func for each frame in which it ran (minus frames containing protected pages). These values must be JSONable, since they have to be moved between contexts. Throws Type: JSONable Error description if tabSpec, frameFilter or func are invalid values.
This function also rethrows any errors thrown by func. Only the first error that occurs in any of the frames is rethrown.
The error value must be JSONable, since it has to be moved between contexts.


Get the URL, width and height of all frames in the current tab.

	let framesData = await ACtl.runInFrames('#currentTab', {minDepth: 1}, ()=>{
		return [location.href, window.innerWidth, window.innerHeight] ;
	}) ;
	console.log(framesData) ;

Navigate to about:blank all frames at depth 2 (i.e. frames inside frames).

	await ACtl.runInFrames('#currentTab', {depth: 2}, ()=>{
		window.location = 'about:blank' ;
	}) ;

Scroll down 100px all frames with a domain terminated in

	await ACtl.runInFrames('#currentTab', {hostname: /\.example\.com$/}, ()=>{
		window.scrollBy({top:100, behavior:'smooth'}) ;
	}) ;

Submit a login form in a frame at depth 2 whose path contains the string loginForm.
Then wait for the frame to finish loading.

	let username = 'John' ;
	let password = '123456' ;
	let frameFilter = {pathname: /loginForm/, depth: 2} ;
	await ACtl.runInFrames(ACtl.TAB_ID, frameFilter, [username, password], (user, pass)=>{
		document.querySelector('#username').value = user ;
		document.querySelector('#password').value = pass ;
		document.querySelector('#submit').click() ;		
	}) ;
	await ACtl.on('tabLoadEnd', ACtl.TAB_ID) ;
	alert('We are in!!') ;
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.sleep ACtl.STOP_CHAIN ACtl.STOP_FULL_SEQ