ACtl.var

Gets, sets and deletes variables on permanent storage. These variables are private to each script, i.e. they are isolated from the variables of other scripts.

A script can always access its private variables regarless of which page it's running in, even if multiple instances of the script are running on different pages or in the background at the same time.

The maximum size of each variable is only limited by the available disk space.

Use ACtl.pubVar instead, to work with variables that are common to all scripts.

With two arguments, the function sets or deletes a variable. ACtl.var(namePath,value) namePath Type: string The name of the variable to set. All unicode characters are permitted.

It can also be a dot-separated list of property names, e.g. 'prop1.prop2.prop3', in which case the value will be set in a nested property.

i.e. {prop1: {prop2: {prop3: value}}}. If the nested objects don't exist, they will be created. value Type: JSONable The value to save. It must be a JSONable value. If undefined or null is passed, the variable will be deleted. Returns Type: Promise Resolves to: undefined Returns immediately. The Promise will resolve when the variable has been set or deleted. Throws Type: string Error description if the variable could not be set for lack of disk space or some other uncommon problem reported by the browser. With one string argument, the function gets the value of a variable. ACtl.var(namePath) namePath Type: string The name of the variable to get. It can also be a dot-separated list of property names, e.g. 'prop1.prop2.prop3', in which case the value will be read from the appropriate nested object. i.e. {prop1: {prop2: {prop3: value}}}. Returns Type: Promise Resolves to: JSONable Returns immediately. The Promise will resolve with the value of the variable, which will always be a JSONable value. If the variable or nested property doesn't exist, the promise will resolve with undefined. With one object argument, the function will set each name-value pair in the object. ACtl.var(nameValuePairs) nameValuePairs Type: Object | Array An Object or Array with name-value pairs. For example:


							{
								variable1: [1, 2, 3, 4, 5],
								prop1: {prop2: {} }, 
								'prop1.prop2.prop3': null,
							}


							[
								['variable1', [1, 2, 3, 4, 5] ],
								['prop1', {prop2: {} } ],
								['prop1.prop2.prop3', null ],
							]

This is identical to calling ACtl.var(name,value) once for each name-value pair, but faster when used on a large amount of variables since storage is read and written only once. Returns Type: Promise Resolves to: undefined Returns immediately. The Promise will resolve when all name-value pairs have been set or deleted. Throws Type: string Error description if nameValuePairs doesn't contain name-value pairs or if the variables could not be set due to lack of disk space or some other uncommon problem reported by the browser. With no arguments, the function gives all private variables. ACtl.var() Returns Type: Promise Resolves to: Object Returns immediately. The Promise will resolve with an Object of name-value pairs containing all private variables of the calling script.

This object is direclty iterable with a for...of loop (standard Objects are not). See example below.

Examples

Create and modify object variables in-place.


	//Create the `data` variable as an object
	await ACtl.var('data', {prop1: 'value 1'}) ;
	//Add to it a property `prop2` as a sub object
	await ACtl.var('data.prop2.prop3', 'value 2') ;
	//Get the value of property `prop1` in that object
	let prop1 = await ACtl.var('data.prop1') ;
	//Show that value
	alert('data.prop1 = ' + prop1 ) ;
	//Delete `prop1` from the object
	await ACtl.var('data.prop1', null) ;

Get and set variables in bulk.


	//Set several variables in one call
	await ACtl.var({
		variable1: 1.234E5,
		variable2: ['1', 2, {3: 'four'}],
		variable3: false,
		variable4: 'value 4',
	}) ;
	//Get all existing variables
	let allVars = await ACtl.var() ;
	//Iterate the name-value pairs in the object
	for( let [varName, value] of allVars ){
		console.log(varName, value) ;
	}

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