config Class
Config object that contains all of the configuration options for
this YUI
instance.
This object is supplied by the implementer when instantiating YUI. Some properties have default values if they are not supplied by the implementer.
This object should not be updated directly because some values are cached. Use
applyConfig()
to update the config object on a YUI instance that has already
been configured.
Index
Properties
- 2in3
- aliases
- base
- bootstrap
- cacheUse deprecated
- combine
- comboBase
- core
- cssAttributes
- dateFormat deprecated
- debug
- delayUntil
- doc
- errorFn
- fetchCSS
- filter
- filters
- force
- gallery
- global
- groups
- ignore
- injected
- insertBefore
- jsAttributes
- lang
- loaderPath
- loadErrorFn
- locale deprecated
- logExclude
- logFn
- logInclude
- logLevel
- modules
- pollInterval
- purgethreshold
- requireRegistration
- root
- skin
- throwFail
- timeout
- useBrowserConsole
- useHistoryHTML5
- useNativeES5
- useNativeJSONParse
- useNativeJSONStringify
- win
- windowResizeDelay
- yui2
Properties
2in3
String
Revision number of YUI 2in3 modules that should be used when loading YUI 2in3.
Default: "4"
aliases
Object
Aliases are dynamic groups of modules that can be used as shortcuts.
Example:
YUI({
aliases: {
davglass: [ 'node', 'yql', 'dd' ],
mine: [ 'davglass', 'autocomplete']
}
}).use('mine', function (Y) {
// Node, YQL, DD & AutoComplete available here.
});
base
String
Base directory for dynamic loading.
bootstrap
Boolean
If true
(the default), YUI will "bootstrap" the YUI Loader and module metadata
if they're needed to load additional dependencies and aren't already available.
Setting this to false
will prevent YUI from automatically loading the Loader
and module metadata, so you will need to manually ensure that they're available
or handle dependency resolution yourself.
Default: true
cacheUse
Boolean
deprecated
Cache serviced use() requests.
Default: true
combine
Boolean
If true
, YUI will use a combo handler to load multiple modules in as few
requests as possible.
The YUI CDN (which YUI uses by default) supports combo handling, but other
servers may not. If the server from which you're loading YUI does not support
combo handling, set this to false
.
Providing a value for the base
config property will cause combine
to default
to false
instead of true
.
Default: true
comboBase
String
Base URL for a dynamic combo handler. This will be used to make combo-handled
module requests if combine
is set to `true.
Default: "http://yui.yahooapis.com/combo?"
core
Array
A list of modules that defines the YUI core (overrides the default list).
Default: ['get', 'features', 'intl-base', 'yui-log', 'yui-later', 'loader-base', 'loader-rollup', 'loader-yui3']
cssAttributes
Object
Object hash containing attributes to add to dynamically added <link>
nodes.
dateFormat
String
deprecated
Default date format.
debug
Boolean
If true
, Y.log()
messages will be written to the browser's debug console
when available and when useBrowserConsole
is also true
.
Default: true
delayUntil
Object | String
Delay the use
callback until a specific event has passed (load
, domready
, contentready
or available
)
Example:
You can use load
or domready
strings by default:
YUI({
delayUntil: 'domready'
}, function (Y) {
// This will not execute until 'domeready' occurs.
});
Or you can delay until a node is available (with available
or contentready
):
YUI({
delayUntil: {
event: 'available',
args : '#foo'
}
}, function (Y) {
// This will not execute until a node matching the selector "#foo" is
// available in the DOM.
});
doc
Document
The browser document
object associated with this YUI instance's win
object.
When running in Node.js, this property is undefined
, since there is no
document
object.
errorFn
Function
Callback to execute when Y.error()
is called. It receives the error message
and a JavaScript error object if one was provided.
This function is executed with the YUI instance as its this
object.
Returning true
from this function will prevent an exception from being thrown.
Sub-properties:
-
msg
StringError message
-
[err]
Object optionalError object (if one was provided).
fetchCSS
Boolean | String
If true
, YUI will attempt to load CSS dependencies and skins. Set this to
false
to prevent YUI from loading any CSS, or set it to the string "force"
to force CSS dependencies to be loaded even if their associated JS modules are
already loaded.
Default: true
filter
Object | String
Filter to apply to module urls. This filter will modify the default path for all modules.
The default path for the YUI library is the minified version of the files (e.g., event-min.js). The filter property can be a predefined filter or a custom filter. The valid predefined filters are:
- debug: Loads debug versions of modules (e.g., event-debug.js).
- raw: Loads raw, non-minified versions of modules without debug logging (e.g., event.js).
You can also define a custom filter, which must be an object literal containing a search regular expression and a replacement string:
myFilter: {
searchExp : "-min\\.js",
replaceStr: "-debug.js"
}
filters
Object
Hash of per-component filter specifications. If specified for a given component,
this overrides the global filter
config.
Example:
YUI({
modules: {
'foo': './foo.js',
'bar': './bar.js',
'baz': './baz.js'
},
filters: {
'foo': {
searchExp: '.js',
replaceStr: '-coverage.js'
}
}
}).use('foo', 'bar', 'baz', function (Y) {
// foo-coverage.js is loaded
// bar.js is loaded
// baz.js is loaded
});
force
String
Array of module names that should always be loaded when required, even if already present on the page.
gallery
String
Default gallery version used to build gallery module urls.
global
Object
Reference to the global object for this execution context.
In a browser, this is the current window
object. In Node.js, this is the
Node.js global
object.
groups
Object
A hash of module group definitions.
For each group you can specify a list of modules and the base path and combo spec to use when dynamically loading the modules.
Example:
groups: {
yui2: {
// specify whether or not this group has a combo service
combine: true,
// The comboSeperator to use with this group's combo handler
comboSep: ';',
// The maxURLLength for this server
maxURLLength: 500,
// the base path for non-combo paths
base: 'http://yui.yahooapis.com/2.8.0r4/build/',
// the path to the combo service
comboBase: 'http://yui.yahooapis.com/combo?',
// a fragment to prepend to the path attribute when
// when building combo urls
root: '2.8.0r4/build/',
// the module definitions
modules: {
yui2_yde: {
path: "yahoo-dom-event/yahoo-dom-event.js"
},
yui2_anim: {
path: "animation/animation.js",
requires: ['yui2_yde']
}
}
}
}
ignore
String
Array of module names that should never be dynamically loaded.
injected
Boolean
When the YUI seed file is dynamically loaded after the window.onload
event has
fired, set this to true
to tell YUI that it shouldn't wait for window.onload
to occur.
This ensures that components that rely on window.onload
and the domready
custom event will work as expected even when YUI is dynamically injected.
Default: false
insertBefore
HTMLElement | String
DOM element or id that should be used as the insertion point for dynamically
added <script>
and <link>
nodes.
jsAttributes
Object
Object hash containing attributes to add to dynamically added <script>
nodes.
lang
String | String
A list of languages to use in order of preference.
This list is matched against the list of available languages in modules that the YUI instance uses to determine the best possible localization of language sensitive modules.
Languages are represented using BCP 47 language tags, such as "en-GB" for English as used in the United Kingdom, or "zh-Hans-CN" for simplified Chinese as used in China. The list may be provided as a comma-separated string or as an array.
loaderPath
String
Path to the Loader JS file, relative to the base
path.
This is used to dynamically bootstrap the Loader when it's needed and isn't yet available.
Default: "loader/loader-min.js"
loadErrorFn
Function
A callback to execute when Loader fails to load one or more resources.
This could be because of a script load failure. It could also be because a
module fails to register itself when the requireRegistration
config is true
.
If this function is defined, the use()
callback will only be called when the
loader succeeds. Otherwise, use()
will always executes unless there was a
JavaScript error when attaching a module.
locale
String
deprecated
Default locale.
logExclude
Object
A hash of log sources that should be not be logged. If specified, all sources will be logged except those on this list.
logFn
Function
Alternate console log function that should be used in environments without a
supported native console. This function is executed with the YUI instance as its
this
object.
logInclude
Object
A hash of log sources that should be logged. If specified, only messages from these sources will be logged. Others will be discarded.
logLevel
String
The minimum log level to log messages for. Log levels are defined incrementally. Messages greater than or equal to the level specified will be shown. All others will be discarded. The order of log levels in increasing priority is:
debug
info
warn
error
Default: 'debug'
modules
Object
A hash of module definitions to add to the list of available YUI modules. These
modules can then be dynamically loaded via the use()
method.
This is a hash in which keys are module names and values are objects containing module metadata.
See Loader.addModule()
for the supported module metadata fields. Also see
groups
, which provides a way to configure the base and combo spec for a set of
modules.
Example:
modules: {
mymod1: {
requires: ['node'],
fullpath: '/mymod1/mymod1.js'
},
mymod2: {
requires: ['mymod1'],
fullpath: '/mymod2/mymod2.js'
},
mymod3: '/js/mymod3.js',
mycssmod: '/css/mycssmod.css'
}
purgethreshold
Number
The number of dynamic <script>
nodes to insert by default before automatically
removing them when loading scripts.
This applies only to script nodes because removing the node will not make the evaluated script unavailable. Dynamic CSS nodes are not auto purged, because removing a linked style sheet will also remove the style definitions.
Default: 20
requireRegistration
Boolean
If true
, Loader will expect all loaded scripts to be first-class YUI modules
that register themselves with the YUI global, and will trigger a failure if a
loaded script does not register a YUI module.
Default: false
root
String
Root path to prepend to each module path when creating a combo-handled request.
This is updated for each YUI release to point to a specific version of the library; for example: "3.8.0/build/".
skin
Object
Skin configuration and customizations.
Sub-properties:
-
[defaultSkin='sam']
String optionalDefault skin name. This skin will be applied automatically to skinnable components if not overridden by a component-specific skin name.
-
[base='assets/skins/']
String optionalDefault base path for a skin, relative to Loader's
base
path. -
[overrides]
Object optionalComponent-specific skin name overrides. Specify a component name as the key and, as the value, a string or array of strings for a skin or skins that should be loaded for that component instead of the
defaultSkin
.
throwFail
Boolean
If true
, Y.error()
will generate or re-throw a JavaScript error. Otherwise,
errors are merely logged silently.
Default: true
timeout
Number
Timeout in milliseconds before a dynamic JS or CSS request will be considered a failure. If not set, no timeout will be enforced.
useBrowserConsole
Boolean
Log messages to the browser console if debug
is true
and the browser has a
supported console.
Default: true
useHistoryHTML5
Boolean
<p> If <code>true</code>, the <code>Y.History</code> alias will always point to <code>Y.HistoryHTML5</code> when the history-html5 module is loaded, even if the current browser doesn't support HTML5 history. </p>
<p> If <code>false</code>, the <code>Y.History</code> alias will always point to <code>Y.HistoryHash</code> when the history-hash module is loaded, even if the current browser supports HTML5 history. </p>
<p> If neither <code>true</code> nor <code>false</code>, the <code>Y.History</code> alias will point to the best available history adapter that the browser supports. This is the default behavior. </p>
useNativeES5
Boolean
Whether or not YUI should use native ES5 functionality when available for
features like Y.Array.each()
, Y.Object()
, etc.
When false
, YUI will always use its own fallback implementations instead of
relying on ES5 functionality, even when ES5 functionality is available.
Default: true
useNativeJSONParse
Boolean
Leverage native JSON parse if the browser has a native implementation. In general, this is a good idea. See the Known Issues section in the JSON user guide for caveats. The default value is true for browsers with native JSON support.
Default: true
useNativeJSONStringify
Boolean
Leverage native JSON stringify if the browser has a native implementation. In general, this is a good idea. See the Known Issues section in the JSON user guide for caveats. The default value is true for browsers with native JSON support.
Default: true
win
Window
The browser window or frame that this YUI instance should operate in.
When running in Node.js, this property is undefined
, since there is no
window
object. Use global
to get a reference to the global object that will
work in both browsers and Node.js.
windowResizeDelay
Number
Delay in milliseconds to wait after a window resize
event before firing the
event. If another resize
event occurs before this delay has elapsed, the
delay will start over to ensure that resize
events are throttled.
Default: 40
yui2
String
Default YUI 2 version used to build YUI 2 module urls.
This is used for intrinsic YUI 2 support via the 2in3 project. Also see the
2in3
config for pulling different revisions of the wrapped YUI 2 modules.
Default: "2.9.0"