ko.plus is a collection of extensions to KnockoutJs that add to the core library.
Get the ko.plus package from NuGet.
Install-Package ko.plus
You can also user bower
bower install ko.plus
..and NPM
npm install ko.plus
ko.command creates a representation of a command that exposes isRunning, failed and other observable properties to allow binding to command state.
The created commands can be invoked directly (as you would a normal function) and as such can be bound to the click handler.
They support both synchronous and asynchronous implementation code, and expose done, fail and always methods to allow continuations.
function ViewModel() {
this.doSomething = ko.command(function() {
return $.get("...");
})
.done(function(data) {
//do something with the response
})
.fail(function(error) {
//handle the error
});
}The state properties can be bound in the UI:
<span data-bind="visible: doSomething.isRunning">Loading...</span>
<span data-bind="visible: doSomething.failed">Something went wrong!</span>The action function can be specified as the single parameter passed to ko.command or as the action property on an options object passed into the function.
ko.command(function() { /*...*/ });
//or
ko.command({
action: function() { /*...*/ })
});An optional canExecute function can be specified to determine whether or not a command can currently be executed.
function ViewModel() {
this.doSomething = ko.command({
action: function() {
return $.get("...");
},
canExecute: function() {
//validation logic
return true;
}
});
}Note: the function passed as canExecute will be wrapped in a ko.computed, so if it uses other observable properties it will automatically be updated.
If you need to manually inform a command that the value of canExecute has changed then you can call the canExecuteHasMutated function, which will force a reevaluation.
The context option sets the context in which the callbacks and action functions will be executed.
function ViewModel() {
this.url = "...";
this.doSomething = ko.command({
action: function() {
return $.get(this.url);
},
context: this
});
}An observable that indicates whether or not the command is currently running.
A computed observable that indicates whether or not the command is currently able to execute.
An observable that indicates whether or not the last invocation of the command failed.
Attach a callback that will be invoked when the command completes successfully.
Attach a callback that will be invoked when the command fails.
Attach a callback that will be invoked when the command either completes successfully or fails.
ko.editable creates an extendion of ko.observable with some additional properties to aid in beginning, cancelling and committing changes.
ko.editableArray does the same for instances of ko.observableArray.
function ViewModel() {
this.value = ko.editable(123);
}
var instance = new ViewModel();
//instance.value -> 123
instance.value.beginEdit();
instance.value(456);
//instance.value -> 456
instance.value.cancelEdit();
//instance.value -> 123An observable property that indicates whether or not the editable is currently in edit mode.
Puts the editable into edit mode.
Takes the editable out of edit mode, commiting any changes.
Takes the editable out of edit mode and reverts to value at the point when beginEdit was called.
Without changing edit state, reverts back through historically committed values for this editable until it reaches the original value.
ko.makeEditable adds to the functionality of ko.editable and ko.editableArray (which only apply to single properties) and expands to allow object graphs to be editable.
This works by appending beginEdit, cancelEdit, endEdit and rollback methods to the target object that will visit all child properties and, if they are editable, invoke the appropriate function.
The function will be applied recursively to:
- immediate child properties that are editable (whether instances of
ko.editableor other editable view models) - any editable objects found in child arrays (either editable arrays or normal)
function ViewModel() {
this.property1 = ko.editable();
this.property2 = ko.editable();
this.arrayProperty = ko.editableArray([
ko.editable(),
ko.editable()
]);
ko.editable.makeEditable(this);
}
var instance = new ViewModel();
instance.beginEdit();
instance.property1.isEditing(); // -> true
instance.property2.isEditing(); // -> true
instance.property1.isEditing(); // -> trueAn observable property that indicates whether or not the editable is currently in edit mode.
Puts the editable and all child editables into edit mode.
Takes the editable and all child editables out of edit mode, commiting any changes.
Takes the editable and all child editables out of edit mode and reverts to value at the point when beginEdit was called.
Without changing edit state, reverts back through historically committed values for this editable until it reaches the original value for all child editables.
The loadingWhen custom binding handler replaces the contents of a container element with a loading placeholder when the bound value is truthy.
<div data-bind="loadingWhen: someAction.isRunning">
<p>This will content will be replaced when someAction.isRunning</p>
</div>The loading element is automatically assigned the .loader class (defined in ko.plus.css).
The loaderClass property specifies what additional class will be assigned to the loading element that sets the loading spinner.
The default option is loader-dark (grey spinner on a transparent background), and the default ko.plus.css stylesheet contains a loader-white option (white spinner on a transparent background).
Non-default loader classes can also be assigned.
Whilst primarily designed for container elements (div, ul, etc.) the loadingWhen binding will also work with elements that directly contain text (button, a, etc.).
By default the loading spinner will overlay itself over the text in these scenarios. For a slightly better appearance, try setting a specific background colour on the element to "hide" the text content. For example, if you have a elements on a white background you could use the following:
/* CSS */
a > .loader { background-color: white; }<!-- HTML -->
<body>
<!-- "Click Me" will be hidden by the white background whilst command is running -->
<a href="#" data-bind="click: command, loadingWhen: command.isRunning">Click Me</a>
</body>Important note: don't change the background-image - this is needed to display the loading spinner.
The command custom binding handler applies the following bindings for a ko.command instance specified through the valueAccessor:
clickbound to the commandloadingWhenbound tocommand.isRunningenablebound tocommand.canExecute
<button data-bind="command: someAction">Do Something</button>The sortable extender attaches sorting behaviour to the target observable array
var source = ko.observableArray([5, 3, 1, 2]).extend({ sortable: true });
// --> source() === [1, 2, 3, 5]Sorting is live (i.e. any changes to the key, direction or source list will result in re-sorting) and properties are exposed to control the sort behaviour.
The parameters for the extender accept an optional key and a descending flag
The key parameter can be left blank (causing the default JS sort to be applied) or can specify a property or property path to be evaluated.
The property path can contain either normal or observable nested parameters. For example, given a list of these objects
{
id: 1,
name: ko.observable('name'),
children: ko.observableArray(),
nested: {
nestedProperty: ko.observable('value')
}
}...any of the following sort paths are valid:
idsorts by the rootidpropertynamesorts by thenameproperty and reacts to changeschildren.lengthsorts by the number of items in thechildrencollectionnested.nestedPropertysorts by the nested property value
Multiple sort keys can be specified by setting the key property to a comma separated list. e.g.
ko.observableArray().extend({
sortable: {
key: 'property1, nested.property.two'
}
});Spaces between items are automatically trimmed.
Determines whether or not the sorting should be reversed
Sort using the specificed locale. A string with a BCP 47 language tag.
Observable property that exposes the current sort key. Changing this will change the sorting immediately
Observable property that determines whether or not the sorting is reversed. Changing this will change the sorting immediately
A helper function that sets the sortKey property to the specified value and toggles sortDescending if the same key is already set
var source = ko.observableArray().extend({
sortable: {
key: 'id',
descending: false
}
});
// source.sortKey() === 'id'
// source.sortDescending() === false
source.setSortKey('id');
// source.sortKey() === 'id'
// source.sortDescending() === true
source.setSortKey('name');
// source.sortKey() === 'name'
// source.sortDescending() === falseko.plus provides a binding handler to assist in the display of sorted elements: sortBy.
<th data-bind="sortBy: { source: sourceCollection, key: 'sort.key' }"></th>This handler attaches a click event handler to the element and injects a child caret element that displays the current direction of sort.