Description
State allows you to do things like
- Tie loading state to AJAX requests
- Tie text to different states, so for example having a button go from 'Follow to Followed to Unfollow' on hover depending on its current state
- Tie multiple elements state to each other, for example, automatically having all `follow` buttons activate on a page after a successfully activating one button.
- Give activate/deactivate test functions which give criteria to allow or reject an item 'activating'
- Handle correctly removing/adding class names signifying states without having to have garbled 'addClass' 'removeClass' sprinkled over your site
Simple activate example
// immediately activates element
$('.my.button')
.state('activate')
;
// activates element on click
$('.my.button')
.state()
;
API example
// typically you'd define all your templated urls in one config file
$.fn.api.settings.api.follow = '/follow/{id}/'
$('.foo.button')
.api({ action: 'follow' })
.state({
onActivate: function() {
$(this).state('flash text');
},
text: {
inactive : 'Follow',
active : 'Followed',
deactivate : 'Unfollow',
flash : 'Added follower!'
}
})
;
Text example
// Changes button between Follow and Following
$('.follow.button')
.state({
text: {
inactive : 'Follow',
active : 'Following'
}
})
;
// Changes text on activation and hover
// The hover text is different when active and inactive
$('.vote.button')
.state({
text: {
inactive : 'Vote',
activate : 'Cast Vote',
active : 'Voted',
deactivate: 'Remove Vote'
}
})
;
Behaviors
All the following behaviors can be called using the syntax:
$('.your.element')
.state('behavior name', argumentOne, argumentTwo)
;
| Behavior | Description |
|---|---|
| is active | Returns whether element state is active |
| is inactive | Returns whether element state is inactive |
| is state(type) | Checks the element for specific state, given by a string name |
| is enabled | Returns whether element is enabled |
| is disabled | Returns whether element is disabled |
| is loading | Returns whether element is loading |
| is textEnabled | Returns whether element is capable to show text which could be changed by states |
| is button | Returns whether element is a button |
| is input | Returns whether element is an input |
| is progress | Returns whether element is a progress |
| allows(state) | Checks if a specific state, given by a string name, is currently allowed to be changed |
| allow(state) | Allows change of element state, given by a string name |
| disallow(state) | Disallows change of element state, given by a string name |
| activate | Sets element to active state |
| deactivate | Sets element to inactive state |
| enable | Sets element as enabled |
| disable | Sets element as disabled |
| set state(state) | Sets a specific state, given by a string name |
| remove state(state) | Removes a specific state, given by a string name |
| change state | Toggles between active/inactive state immediatly without any checks |
| toggle state | Toggles between active/inactive state but checks if element is active and uses a possible attached api |
| flash text(text, duration, callback) | Changes the elements text for an optional given amount of time. After that, reverts the text to the previous value and optionally calls a given callback function |
| refresh | Refreshes cached selectors |
| destroy | Removes State settings from the element and all events |
Settings
| Setting | 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. |
| filter |
filter: {
text: '.loading, .disabled',
active: '.disabled',
}
|
Selector filter to recognize element states which cannot be changed |
| context | false | When set to a selector, will use a delegated pattern to bind events from this element. |
| states |
states: {
active: true,
disabled: true,
error: true,
loading: true,
success: true,
warning: true
}
|
Default states. When set to false those are disallowed for a change. |
| text |
text: {
disabled: false,
flash: false,
hover: false,
active: false,
inactive: false,
activate: false,
deactivate: false
}
|
State texts for relevant elements like button. Provide strings here when needed. |
Callbacks
Callbacks specify a function to occur after a specific behavior.
| Setting | Context | Description |
|---|---|---|
| activateTest | initialized element | Called before a state is activated. Return false to cancel state activation |
| deactivateTest | initialized element | Called before a state is deactivated. Return false to cancel state deactivation |
| onActivate | initialized element | Called when state was activated |
| onDeactivate | initialized element | Called when state was deactivated |
| onChange | initialized element | Called after a state has changed |
DOM Settings
DOM settings specify how this module should interface with the DOM
| Setting | Default | Description |
|---|---|---|
| namespace | state | Event namespace. Makes sure module teardown does not effect other events attached to an element. |
| 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 text changes |
Debug Settings
Debug settings controls debug output to the console
These settings are native to all modules, and define how the component ties content to DOM attributes, and debugging settings for the module.
| Setting | Default | Description |
|---|---|---|
| name | State | Name used in log statements |
| 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.'
}
|
|