knockout-switch-case v2.1.0

SWITCH/CASE bindings for Knockout

Knockout includes only the if and ifnot bindings for control flow. The switch and case bindings provide a flexible and powerful control flow mechanism that can simplify your code.

Let's start with some examples. Here we want to display a different message based on a status value:

<div data-bind="switch: orderStatus">
    <div data-bind="case: 'shipped'">
        Your order has been shipped. Your tracking number is <span data-bind="text: trackingNumber"></span>.
    </div>
    <div data-bind="case: 'pending'">
        Your order is being processed. Please be patient.
    </div>
    <div data-bind="case: 'incomplete'">
        Your order could not be processed. Please go back and complete the missing data.
    </div>
    <div data-bind="case: $default">
        Please call customer service to determine the status of your order.
    </div>
</div>

Here's an equivalent example using source data values:

<div data-bind="switch: true">
    <div data-bind="case: trackingNumber">
        Your order has been shipped. Your tracking number is <span data-bind="text: trackingNumber"></span>.
    </div>
    <div data-bind="case: isReady">
        Your order is being processed. Please be patient.
    </div>
    <div data-bind="casenot: isComplete">
        Your order could not be processed. Please go back and complete the missing data.
    </div>
    <div data-bind="case: $else">
        Your order could not be processed. Please go back and complete the missing data.
    </div>
</div>

A switch block can contain any number of case blocks. No more than one case block will be used. The contents of the remaining blocks will be cleared. Both switch and case take a single parameter. In most cases the values of the two parameters are matched against each other to determine which case block to use. The first block (top-down) to match is used; subsequent blocks are cleared. Here, in detail, is how the values are matched:

1. If the case value is the special value $else or $default, the block is used if no non-default blocks were used. There can be multiple blocks with $else or $default and they can be in any order.
2. If the switch value is boolean (true or false), each case value's "truthiness" is matched against the switch value.
3. If the case value is boolean (and the switch value is not boolean), the case value is used as is. The special variable $value can be used in a case expression to refer to the switch value. The block will be used if the expression is true.
4. If the case value is an array, the block will be used if the switch value matches (strict) an item in the array.
5. Otherwise, the block will be used if the case value matches the switch value (loose comparison).

If you want a block to be used based on the parameter not matching, you can use the casenot binding. This works similarly to case, except that the result of the value matching is reversed.

Here are some more examples. This example demonstrates items 1, 3, 4, and 5 above and uses container-less bindings:

<!-- ko switch: somevalue -->
<!-- ko case: $default -->
    Value doesn't match
<!-- /ko -->
<!-- ko case: 'foo' -->
    Value is foo
<!-- /ko -->
<!-- ko case: 'bar' -->
    Value is bar
<!-- /ko -->
<!-- ko case: ['baz', 'qux'] -->
    Value is either baz or qux
<!-- /ko -->
<!-- ko case: $value.length == 3 -->
    Value is a three-letter word
<!-- /ko -->
<!-- /ko -->

This example demonstrates item 2 (also see the second example above):

<!-- ko switch: isReady -->
    <div data-bind="case: true">You are ready!</div>
    <div data-bind="case: false">You are not ready!</div>
<!-- /ko -->

Controlling visibility instead of inclusion

You can use the case.visible and casenot.visible bindings to conditionally show an element. For example:

<!-- ko switch: true -->
    <p data-bind="case.visible: isReady">You are ready!</p>
    <p data-bind="case.visible: $else">You are not ready!</p>
<!-- /ko -->

Switch shortcut when using Knockout 3.x

When using Knockout 3.0+, you do not need to include the true value for the switch binding. For example:

<!-- ko switch -->
    <!-- ko case: 'abc' -->Value matched<!-- /ko -->
    <!-- ko case: $else -->Value didn't match<!-- /ko -->
<!-- /ko -->

Extending switch/case to control other UI aspects

ko.bindingHandlers.switch.makeCaseHandler can be used to create new bindings that control any UI aspect. It returns a new binding handler object that you should assign to a ko.bindingHandlers property. It takes three parameters:

• binding This is the name of the binding to wrap (case wraps the if binding, for example).
• isNot (optional) If set to true, the new binding will reverse the result of the value matching (like casenot).
• makeValueAccessor (optional) If the wrapped binding needs the value specified in a certain format, you can provide a function that accepts a value parameter and returns a valueAccessor function. The default looks like this: function (value) { return function() { return value } }

License: MIT (http://www.opensource.org/licenses/mit-license.php)

Michael Best https://github.com/mbest mbest@dasya.com