Difference between revisions of "GM.getValue"

From GreaseSpot Wiki
Jump to navigationJump to search
m (Arantius moved page GM getValue to GM.getValue)
(Update for 4.0)
Line 1: Line 1:
{{DISPLAYTITLE:GM_getValue}}
== Description ==
== Description ==


This method retrieves a value that was set with [[GM_setValue]].
This method retrieves a value that was set with [[GM.setValue]].
See [[GM_setValue]] for details on the storage of these values.
See [[GM.setValue]] for details on the storage of these values.
 
Compatibility: [[Version_history#0.3_beta|Greasemonkey 0.3b+]]


== Syntax ==
== Syntax ==


{{Function|GM_getValue|name, default}}
{{Function|GM_getValue|name, default}}
Compatibility: [[Version_history#4.0_2|Greasemonkey 4.0+]]


=== Arguments ===
=== Arguments ===


; <code>name</code>
; <code>name</code>
: <code>String</code> The property name to get. See [[GM_setValue#Arguments|GM_setValue]] for details.
: <code>String</code> The property name to get. See [[GM.setValue#Arguments|GM.setValue]] for details.
; <code>default</code>
; <code>default</code>
: Optional. Any value to be returned, when no value has previously been set.
: Optional. The default value to be returned when none has previously been set.


=== Returns ===
=== Returns ===
A [[Promise]], rejected in case of error and otherwise resolved with:


; When this <code>name</code> has been set
; When this <code>name</code> has been set
Line 32: Line 32:
Retrieving the value associated with the name 'foo':
Retrieving the value associated with the name 'foo':
<pre class='sample'>
<pre class='sample'>
//outputs either the value associated to foo, else undefined
console.log(await GM.getValue("foo"));  
 
GM_log(GM_getValue("foo"));  
</pre>
</pre>


Line 42: Line 40:
//  associated with the name timezoneOffset is found in storage
//  associated with the name timezoneOffset is found in storage


GM_log(GM_getValue("timezoneOffset", -5));  
console.log(await GM.getValue("timezoneOffset", -5));  
</pre>
</pre>


Line 55: Line 53:
//  Also Note the default value is in quotes (thus a string) rather than an object literal
//  Also Note the default value is in quotes (thus a string) rather than an object literal


var storedObject = JSON.parse( GM_getValue("foo", "{}") );  
var storedObject = JSON.parse(await GM.getValue("foo", "{}"));  


if(!storedObject) {
if (!storedObject) {
   //JSON.parse() should never return any value that type-casts to false, assume there is an  
   //JSON.parse() should never return any value that type-casts to false, assume there is an  
   //  error in the input string
   //  error in the input string
   GM_log('Error! JSON.parse failed - The stored value for "foo" is likely to be corrupted.');
   console.warn('Error! JSON.parse failed - The stored value for "foo" is likely to be corrupted.');
   throw;
   throw;
}
}
Line 67: Line 65:
== See Also ==
== See Also ==


* [[GM_setValue]]
* [[GM.setValue]]
* [[GM_deleteValue]]
* [[GM.deleteValue]]
* [[GM_listValues]]
* [[GM.listValues]]


[[Category:API_Reference|G]]
[[Category:API_Reference|G]]

Revision as of 10:26, 3 November 2017

Description

This method retrieves a value that was set with GM.setValue. See GM.setValue for details on the storage of these values.

Syntax

function GM_getValue( name, default )

Compatibility: Greasemonkey 4.0+

Arguments

name
String The property name to get. See GM.setValue for details.
default
Optional. The default value to be returned when none has previously been set.

Returns

A Promise, rejected in case of error and otherwise resolved with:

When this name has been set
String, Integer or Boolean as previously set
When this name has not been set, and default is provided
The value passed as default
When this name has not been set, and default is not provided
undefined

Examples

Retrieving the value associated with the name 'foo':

console.log(await GM.getValue("foo")); 

Retrieving the value associated with the name 'timezoneOffset' with a default value defined:

//GM_getValue() returns the value -5 (integer) if no value 
//   associated with the name timezoneOffset is found in storage

console.log(await GM.getValue("timezoneOffset", -5)); 


A more complex example:

If you have used JSON.stringify to place an object into storage, JSON.parse shall be used to convert it back from a string to a Javascript Object.

//Note that if the value associated with foo is an invalid
//   JSON string, JSON.parse will fail.
//   Also Note the default value is in quotes (thus a string) rather than an object literal

var storedObject = JSON.parse(await GM.getValue("foo", "{}")); 

if (!storedObject) {
  //JSON.parse() should never return any value that type-casts to false, assume there is an 
  //   error in the input string
  console.warn('Error! JSON.parse failed - The stored value for "foo" is likely to be corrupted.');
  throw;
}

See Also