Class: SC.browser

This object contains information about the browser environment SproutCore is running in. This includes the following properties:

Note: User agent sniffing does not provide guaranteed results and spoofing may affect the accuracy. Therefore, as a general rule, it is much better to rely on the browser's verified capabilities in SC.platform. But if you must write browser specific code, understand that SC.browser does an exceptional job at identifying the current browser.

Based on the unit test samples, the most stable browser properties appear to be engine and engineVersion.

Defined in: browser.js

Since:
Version 1.0

Field Summary

Class Methods

Field Detail

Deprecated: Version 1.7. Use browser.version.
SC.browser.chrome String
SC.browser.classPrefix String
The prefix of browser specific properties on this platform.
SC.browser.countryCode String
SC.browser.cssPrefix String
The prefix of browser specific CSS properties on this platform.
Deprecated: Version 1.7. Use browser.name. See SC.BROWSER for possible values.
SC.browser.current String
SC.browser.device SC.DEVICE|SC.BROWSER.unknown
SC.browser.domPrefix String
The prefix of browser specific methods on this platform.
SC.browser.engine SC.ENGINE|SC.BROWSER.unknown
SC.browser.engineVersion String
Deprecated: Version 1.7. Use browser.version.
SC.browser.iPadSafari String
Deprecated: Version 1.7. Use browser.version.
SC.browser.iPhoneSafari String
Deprecated: Version 1.7. Use browser.version.
SC.browser.iPodSafari String
Deprecated: Version 1.7. Use browser.os === SC.OS.android or browser.name === SC.BROWSER.android or browser.device === SC.DEVICE.android.
SC.browser.isAndroid Boolean
Deprecated: Version 1.7. Use browser.name === SC.BROWSER.chrome.
SC.browser.isChrome Boolean
Deprecated: Version 1.7. Use browser.engine === SC.ENGINE.trident.
SC.browser.isIE Boolean
Deprecated: Version 1.7. Use browser.compare(browser.version, '8') <= 0.
SC.browser.isIE8OrLower Boolean
Deprecated: Version 1.7. Use browser.os === SC.OS.ios.
SC.browser.isiOS Boolean
Deprecated: Version 1.7. Use SC.platform.standalone.
SC.browser.isiOSHomeScreen Boolean
Deprecated: Version 1.7. Use browser.device === SC.DEVICE.ipad.
SC.browser.isiPad Boolean
Deprecated: Version 1.7. Use browser.device === SC.DEVICE.ipad && browser.name === SC.BROWSER.safari
SC.browser.isiPadSafari Boolean
Deprecated: Version 1.7. Use browser.device === SC.DEVICE.iphone.
SC.browser.isiPhone Boolean
Deprecated: Version 1.7. Use browser.device === SC.DEVICE.iphone && browser.name === SC.BROWSER.safari
SC.browser.isiPhoneSafari Boolean
Deprecated: Version 1.7. Use browser.device === SC.DEVICE.ipod.
SC.browser.isiPod Boolean
Deprecated: Version 1.7. Use browser.device === SC.DEVICE.ipod && browser.name === SC.BROWSER.safari
SC.browser.isiPodSafari Boolean
Deprecated: Version 1.7. Use browser.os === SC.OS.mac && browser.compare(browser.osVersion, '10.7') == 0
SC.browser.isLion Boolean
Deprecated: Version 1.7. Use browser.os === SC.OS.mac.
SC.browser.isMac Boolean
Deprecated: Version 1.7. Use browser.name === SC.BROWSER.safari && browser.os === SC.OS.ios
SC.browser.isMobileSafari Boolean
Deprecated: Version 1.7. Use browser.name === SC.BROWSER.firefox or browser.engine === SC.ENGINE.gecko.
SC.browser.isMozilla Boolean
Deprecated: Version 1.7. Use browser.name === SC.BROWSER.opera.
SC.browser.isOpera Boolean
Deprecated: Version 1.7. Use browser.name === SC.BROWSER.safari && browser.os === SC.OS.mac.
SC.browser.isSafari Boolean
Deprecated: Version 1.7. Use browser.engine === SC.ENGINE.webkit.
SC.browser.isWebkit Boolean
Deprecated: Version 1.7. Use browser.os === SC.OS.win.
SC.browser.isWindows Boolean
SC.browser.language String
Deprecated: Version 1.7. Use browser.version.
SC.browser.mobileSafari String
Deprecated: Version 1.7. Use browser.version or browser.engineVersion.
SC.browser.mozilla String
Deprecated: Version 1.7. Use browser.version or browser.engineVersion.
SC.browser.msie String
SC.browser.name SC.BROWSER|SC.BROWSER.unknown
Deprecated: Version 1.7. Use browser.version or browser.engineVersion.
SC.browser.opera String
SC.browser.os SC.OS|SC.BROWSER.unknown
SC.browser.osVersion String
Deprecated: Version 1.7. Use browser.version.
SC.browser.safari String
SC.browser.version String
Deprecated: Version 1.7. Use browser.engineVersion.
SC.browser.webkit String

Class Method Detail

compare(version, other)

Version Strings should not be compared against Numbers. For example, the version "1.20" is greater than "1.2" and less than "1.200", but as Numbers, they are all 1.2.

Pass in one of the browser versions: SC.browser.version, SC.browser.engineVersion or SC.browser.osVersion and a String to compare against. The function will split each version on the decimals and compare the parts numerically.

Examples:

SC.browser.compare('1.20', '1.2') == 18 SC.browser.compare('1.08', '1.8') == 0 SC.browser.compare('1.1.1', '1.1.004') == -3


Defined in: browser.js.
Parameters:
version String
One of SC.browser.version, SC.browser.engineVersion or SC.browser.osVersion
other String
The version to compare against.
Returns:
Number
The difference between the versions at the first difference.
experimentalCSSNameFor(standardCSSName, testValue)

This method returns safe CSS attribute names for current and future browsers.

Using browser specific CSS prefixes is a risky coding practice. With sufficient testing, you may be able to match attributes across today's most popular browsers, but this is a lot of work and not future proof. For instance, if a browser drops the prefix and supports the standard CSS name, your code will suddenly stop working. This happens ALL the time!

Instead, use SC.browser.experimentalCSSNameFor(standardCSSName), which will test support for the standard CSS name and if not found will try the prefixed version with the current browser's prefix appended.

Note: the proper CSS name is only determined once per standard CSS name tested and then cached. Therefore, calling experimentalCSSNameFor repeatedly has no performance detriment.

For example,

var boxShadowCSS = SC.browser.experimentalCSSNameFor('box-shadow'),
  el = document.createElement('div');

// `boxShadowCSS` may be "box-shadow", "-webkit-box-shadow", "-ms-box-shadow", etc. depending on the current browser.
el.style.cssText = boxShadowCSS + " rgb(0,0,0) 0px 3px 5px";

Improving deduction

Occasionally a browser will appear to support a style, but will fail to actually accept a value. In order to ensure that the style doesn't just exist but is also usable, you can provide an optional testValue that will be used to verify that the detected style is usable.


Defined in: browser.js.
Parameters:
standardCSSName string
The standard name of the experimental CSS attribute as it should be un-prefixed (ex. box-shadow).
testValue String Optional
A value to temporarily assign to the style to ensure support.
Returns:
string
Future-proof CSS name for use in the current browser or SC.UNSUPPORTED if no style support found.
experimentalNameFor(target, standardName, testValue)

This simple method allows you to more safely use experimental properties and methods in current and future browsers.

Using browser specific methods and properties is a risky coding practice. With sufficient testing, you may be able to match prefixes to today's browsers, but this is prone to error and not future proof. For instance, if a property becomes standard and the browser drops the prefix, your code could suddenly stop working.

Instead, use SC.browser.experimentalNameFor(target, standardName), which will check the existence of the standard name on the target and if not found will try different camel-cased versions of the name with the current browser's prefix appended.

If it is still not found, SC.UNSUPPORTED will be returned, allowing you a chance to recover from the lack of browser support.

Note that experimentalNameFor is not really meant for determining browser support, only to ensure that using browser prefixed properties and methods is safe. Instead, SC.platform provides several properties that can be used to determine support for a certain platform feature, which should be used before calling experimentalNameFor to safely use the feature.

For example,

// Checks for IndexedDB support first on the current platform.
if (SC.platform.supportsIndexedDB) {
  var db = window.indexedDB,
    // Example return values: 'getDatabaseNames', 'webkitGetDatabaseNames', 'MozGetDatabaseNames', SC.UNSUPPORTED.
    getNamesMethod = SC.browser.experimentalNameFor(db, 'getDatabaseNames'),
    names;

    if (getNamesMethod === SC.UNSUPPORTED) {
      // Work without it.
    } else {
      names = db[getNamesMethod](...);
    }
} else {
  // Work without it.
}

Improving deduction

Occasionally a target will appear to support a property, but will fail to actually accept a value. In order to ensure that the property doesn't just exist but is also usable, you can provide an optional testValue that will be temporarily assigned to the target to verify that the detected property is usable.


Defined in: browser.js.
Parameters:
target Object
The target for the method.
standardName String
The standard name of the property or method we wish to check on the target.
testValue String Optional
A value to temporarily assign to the property.
Returns:
string
The name of the property or method on the target or SC.UNSUPPORTED if no method found.
experimentalStyleNameFor(standardStyleName, testValue)

This method returns safe style names for current and future browsers.

Using browser specific style prefixes is a risky coding practice. With sufficient testing, you may be able to match styles across today's most popular browsers, but this is a lot of work and not future proof. For instance, if a browser drops the prefix and supports the standard style name, your code will suddenly stop working. This happens ALL the time!

Instead, use SC.browser.experimentalStyleNameFor(standardStyleName), which will test support for the standard style name and if not found will try the prefixed version with the current browser's prefix appended.

Note: the proper style name is only determined once per standard style name tested and then cached. Therefore, calling experimentalStyleNameFor repeatedly has no performance detriment.

For example,

var boxShadowName = SC.browser.experimentalStyleNameFor('boxShadow'),
  el = document.createElement('div');

// `boxShadowName` may be "boxShadow", "WebkitBoxShadow", "msBoxShadow", etc. depending on the browser support.
el.style[boxShadowName] = "rgb(0,0,0) 0px 3px 5px";

Improving deduction

Occasionally a browser will appear to support a style, but will fail to actually accept a value. In order to ensure that the style doesn't just exist but is also usable, you can provide an optional testValue that will be used to verify that the detected style is usable.


Defined in: browser.js.
Parameters:
standardStyleName string
The standard name of the experimental style as it should be un-prefixed. This is the DOM property name, which is camel-cased (ex. boxShadow)
testValue String Optional
A value to temporarily assign to the style to ensure support.
Returns:
string
Future-proof style name for use in the current browser or SC.UNSUPPORTED if no style support found.
Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:20 GMT-0600 (CST)