Activate Elements Programmatically
State is designed to make the process of integrating data sources to UI components seamless, tying State request state to UI states automatically.
For example adding an State behavior to an input will occur oninput, while a button, will query the server onclick.
Behavior
All the following behaviors can be called using the syntax:
$('.your.element')
.state('behavior name', argumentOne, argumentTwo)
;
| Behavior | Description |
|---|---|
| query | Execute query using existing State settings |
| add url data(url, data) | Adds data to existing templated url and returns full url string |
| get request | Gets promise for current State request |
| abort | Aborts current State request |
| reset | Removes loading and error state from element |
| was cancelled | Returns whether last request was cancelled |
| was failure | Returns whether last request was failure |
| was successful | Returns whether last request was successful |
| was complete | Returns whether last request was completed |
| is disabled | Returns whether element is disabled |
| is mocked | Returns whether element response is mocked |
| is loading | Returns whether element is loading |
| set loading | Sets loading state to element |
| set error | Sets error state to element |
| remove loading | Removes loading state to element |
| remove error | Removes error state to element |
| get event | Gets event that State request will occur on |
| get url encoded value(value) | Returns encodeURIComponent value only if value passed is not already encoded
|
| read cached response(url) | Reads a locally cached response for a URL |
| write cached response(url, response) | Writes a cached response for a URL |
| create cache | Creates new cache, removing all locally cached URLs |
| destroy | Removes State settings from the page and all events |
State
Behavior
| Default | Description | |
|---|---|---|
| automatic | true | Whether possible states should be determined automatically based on type of UI |
| sync | false | When set to true and state is used on multiple elements, state will be synced across all bound elements. |
| flashDuration | 1000 | Default duration to show text when using flash text. |
| context | false | When set to a selector, will use a delegated pattern to bind events from this element. |
Request Settings
| Default | Description | Possible Values | |
|---|---|---|---|
| action | false | Named State action for query, originally specified in $.fn.settings.state | String or false |
| url | false | Templated URL for query, will override specified action | String or false |
| urlData | false | Variables to use for replacement | |
| mockResponse | false | Can be set to a javascript object which will be returned automatically instead of requesting JSON from server | {} or false |
| mockResponseAsync(settings, callback) | false | When specified, this function can be used to retrieve content from a server and return it asynchronously instead of a standard AJAX call. The callback function should return the server response. | function or false |
| method | get | Method for transmitting request to server | post, get |
| dataType | JSON | Expected data type of response | xml, json, jsonp, script, html, text |
| data | {} | POST/GET Data to Send with Request |
Callbacks
| Context | Description | |
|---|---|---|
| beforeSend(settings) | initialized element | Allows modifying settings before request, or cancelling request |
| beforeXHR(xhrObject) | Allows modifying XHR object for request | |
| onRequest(promise, xhr) | state context | Callback that occurs when request is made. Receives both the state success promise and the xhr request promise. |
| onResponse(response) | state context | Allows modifying the server's response before parsed by other callbacks to determine State event success |
| successTest(response) | Determines whether completed JSON response should be treated as successful | |
| onSuccess(response, element, xhr) | state context | Callback after successful response, JSON response must pass successTest |
| onComplete(response, element, xhr) | state context | Callback on request complete regardless of conditions |
| onFailure(response, element) | state context | Callback on failed response, or JSON response that fails successTest |
| onError(errorMessage, element, xhr) | state context | Callback on server error from returned status code, or XHR failure. |
| onAbort(errorMessage, element, xhr) | state context | Callback on abort caused by user clicking a link or manually cancelling request. |
Module
These settings are native to all modules, and define how the component ties content to DOM attributes, and debugging settings for the module.
| Default | Description | |
|---|---|---|
| name | State | Name used in log statements |
| namespace | state | Event namespace. Makes sure module teardown does not effect other events attached to an element. |
| regExp |
regExp : {
required: /\{\$*[A-z0-9]+\}/g,
optional: /\{\/\$*[A-z0-9]+\}/g,
}
|
Regular expressions used for template matching |
| selector |
selector: {
text : false
}
|
Selectors used to find parts of a module |
| className |
className: {
active : 'active',
disabled : 'disabled',
error : 'error',
loading : 'loading',
success : 'success',
warning : 'warning'
}
|
Class names used to determine element state |
| metadata |
metadata: {
promise : 'promise',
storedText : 'stored-text'
}
|
Metadata used to store xhr and response promise |
| silent | false | Silences all console output including error messages, regardless of other debug settings. |
| debug | false | Debug output to console |
| performance | true | Show console.table output with performance metrics |
| verbose | false | Debug output includes all internal behaviors |
| errors |
// errors
error : {
method : 'The method you called is not defined.'
}
|
|