Knockstrap is binding library for Knockout.js, which provides binding to Twitter Bootstrap widgets

Features

• Using Bootstrap widgets via data-bind attribute
• Supports dynamicaly changing parameters and data of widgets via observables
• Supports Knockout templates for such widgets, as modal or popover
• Supports using of third party template engines
• Provides default templates for such widgets, as modal, for typical using
• Provides string template engine, which allows to use javascript strings as templates

Usage

If you have all dependencies, you only need to include knockstrap.min.js or knockstrap.js to your pages:

<script src="../path/to/knockstrap.min.js"></script>

<script src="https://cdn.jsdelivr.net/npm/knockstrap@1.4.1/build/knockstrap.js"></script>

Also you can install it via npm, bower or nuget.

Dependencies

• Knockout.js (>=2.3.0)
• jQuery (Any compatible with Bootstrap 3 version)
• Bootstrap 3 (CSS and JavaScript)

Binding to Bootstrap tooltip

Examples

Html markup

<div>
    Lorem ipsum dolor sit amet, <a data-bind="tooltip: { title: 'Tooltip example' }">consectetur</a> adipiscing elit. 
    Vestibulum nec pharetra eros. Sed luctus vitae ligula 
    <a data-bind="tooltip: { title: tooltipTitle, placement: tooltipPlacement }">viverra</a> porttitor. 
    Vestibulum porttitor egestas lacus.
</div>
    
<!-- ... -->

<input type="text" data-bind="value: title, valueUpdate: 'afterkeydown'" />
<div>
    <input type="radio" name="tooltipPlacement" value="left" data-bind="checked: placement" />
    Left
    <input type="radio" name="tooltipPlacement" value="right" data-bind="checked: placement" />
    Right
    <input type="radio" name="tooltipPlacement" value="top" data-bind="checked: placement" />
    Top
    <input type="radio" name="tooltipPlacement" value="bottom" data-bind="checked: placement" />
    Bottom
</div>

View model

function TooltipExampleViewModel() {
    this.tooltipTitle = ko.observable('Observable title');
    this.tooltipPlacement = ko.observable('left');
}

Options

Binding to Bootstrap popover. Supports custom templates with observables for popover content

Examples

Html markup

<button class="btn btn-primary" data-bind="popover: { 
        options: { title: 'Popover with template', placement: 'top' }, 
        template: popoverTemplate, 
        data: { text: 'First template' } 
    }">Click</button>

<button class="btn" data-bind="click: switchTemplates">Switch templates</button>

<button class="btn btn-primary" data-bind="popover: { 
        options: { title: 'Focus', content: 'Focus popover', trigger: 'focus', placement: 'bottom' } 
    }">Focus</button>

<button class="btn btn-primary" data-bind="popover: { 
        options: { title: 'Hover', content: 'Hover popover', trigger: 'hover' } 
    }">Hover</button>
        
<script type="text/html" id="firstPopoverTemplate">
    <button class="close pull-right" type="button" data-dismiss="popover">×</button>
    <p data-bind="text: text"></p>
</script>

<script type="text/html" id="secondPopoverTemplate">
    <p>Second template</p>
</script>

View model

function PopoverExampleViewModel() {
    var self = this;
    
    self.popoverTemplate = ko.observable('firstPopoverTemplate');
    self.switchTemplates = function() {
        self.popoverTemplate() === 'firstPopoverTemplate' 
                                    ? self.popoverTemplate('secondPopoverTemplate') 
                                    : self.popoverTemplate('firstPopoverTemplate');
    };
}

Options

All of the options can be observables (besides trigger, see details), also option's object can be observable too

Short notation

If you don't need use template, you can use short notation of binding, which uses only option object.

Binding to Bootstrap alert widget. This binding can be used with virtual elements. Supports custom templates with observables

Examples

Html markup

<div data-bind="alert: { message: message, type: type }"></div>

<div data-bind="alert: { message: 'Using custom alert template', template: 'alertExampleTemplate', type: 'danger' }"></div>

<!-- ko alert: { message: 'Using virtual root element', type: 'success' } -->
<!-- /ko -->

<script type="text/html" id="alertExampleTemplate">
    <p data-bind="text: message"></p>
    <button class="btn btn-primary" data-dismiss="alert">Close</button>
</script>

View model

function AlertExampleViewModel() {
    this.type = ko.observable('info');
    
    this.message = ko.observable('Alert message');
}

Options

All of the options can be observables.

Binding to Bootstrap modal widget.

Examples

Html markup

<button class="btn btn-primary" data-bind="click: show">Show modal</button>

<div class="btn-group form-group" data-toggle="buttons" data-bind="radio: modalSize">
    <label class="btn btn-default">
        <input type="radio" name="modalSizing" value="" />
        None
    </label>
    <label class="btn btn-default">
        <input type="radio" name="modalSizing" value="modal-lg" />
        Large
    </label>
    <label class="btn btn-default">
        <input type="radio" name="modalSizing" value="modal-sm" />
        Small
    </label>
</div>

<div data-bind="modal: {
    visible: modalVisible,
    dialogCss: modalSize,
    header: { data: { label: headerLabel } },
    body: { name: bodyTemplate, data: bodyData },
    footer: { data: { action: switchTemplates, closeLabel: 'Custom text', primaryLabel: 'Change body template' } }
}"></div>

<script type="text/html" id="firstModalTemplate">
    <p data-bind="text: text"></p>
    <div class="form-group">
        <label data-bind="text: label"></label>
        <input type="text" data-bind="value: label, valueUpdate: 'afterkeydown'" class="form-control" />
    </div>
</script>

<script type="text/html" id="secondModalTemplate">
    <p data-bind="text: text"></p>
    <p data-bind="text: simpleLabel"></p>
</script>

View model

function ModalExampleViewModel() {

    var self = this;

    var firstTemplateData = {
        text: 'First template',
        label: ko.observable('Observable label')
    };

    var secondTemplateData = {
        text: 'Second template',
        simpleLabel: 'Simple text label'
    };

    self.modalVisible = ko.observable(false);

    self.show = function() {
        self.modalVisible(true);
    };

    self.headerLabel = ko.observable('Some header text');
    self.bodyTemplate = ko.observable('firstModalTemplate');
    self.bodyData = ko.computed(function() {
        return self.bodyTemplate() === 'firstModalTemplate' ? firstTemplateData : secondTemplateData;
    });

    self.okText = ko.observable();

    self.switchTemplates = function() {
        self.bodyTemplate() === 'firstModalTemplate' 
                            ? self.bodyTemplate('secondModalTemplate') 
                            : self.bodyTemplate('firstModalTemplate');
    };
        
    self.modalSize = ko.observable('modal-lg');
}

Options

All of the options can be observables.

Default values

Default values for modal binding located in ko.bindingHandlers.modal.defaults object. It contains default css and attributes for root element of modal and default values for header, body and footer. Can be changed before ko.applyBindigs() is called.

defaults: {
    css: 'modal fade',
    attributes: {
        role: 'dialog'  
    },

    events: {
        shown: 'shown.bs.modal',
        hidden: 'hidden.bs.modal'
    },

    headerTemplate: {
        name: 'modalHeader',
        templateEngine: ko.stringTemplateEngine.instance
    },

    bodyTemplate: {
        name: 'modalBody',
        templateEngine: ko.stringTemplateEngine.instance
    },

    footerTemplate: {
        name: 'modalFooter',
        templateEngine: ko.stringTemplateEngine.instance,
        data: {
            closeLabel: 'Close',
            primaryLabel: 'Ok'
        }
    }
}

Binding to Bootatrap progress bar

Examples

Html markup

<div data-bind="progress: { value: value, type: type, text: text, textHidden: textHidden, animated: animated, striped: striped }"></div>

View model

function ProgressExampleViewModel() {
    this.value = ko.observable(50);

    this.animated = ko.observable();

    this.striped = ko.observable();

    this.type = ko.observable('info');

    this.text = ko.observable('Complete');

    this.textHidden = ko.observable(true);
}

Options

All of the options can be observables.

Short notation

Examples

If you only need use progress value, you can use short notation of binding, which uses only number as model.

Html markup

<div data-bind="progress: progress"></div>

View model

function ProgressExampleViewModel() {
    //...

    this.progress = ko.observable(20);
}

Options

Stacked progress bars

Examples

If you need use multiple bars into the same .progress to stack them, you can pass array of options objects to binding:

Html markup

<div data-bind="progress: progressBars"></div>

View model

function ProgressExampleViewModel() {
    this.firstBar = {
        value: ko.observable(50),
        animated: ko.observable(),
        striped: ko.observable(),
        type: ko.observable('warning'),
        text: ko.observable('Complete'),
        textHidden: ko.observable(true)
    };

    this.secondBar = ko.observable(20);

    this.progressBars = ko.observableArray([
        this.firstBar,
        this.secondBar
    ]);
}

Options

Default values

Default values for progress binding located in ko.bindingHandlers.progress.defaults object. It contains default css for root element of progress-bar and default values for its options. Can be changed before ko.applyBindigs() is called.

defaults: {
    css: 'progress',
    text: '',
    textHidden: true,
    striped: false,
    type: '',
    animated: false
}

Toggle buttons

Binding to Bootstrap toggle button.

Examples

Html markup

<button class="btn btn-info" data-bind="toggle: isToggled">Toggle button</button>

Viem model

function ButtonsExampleViewModel() {
    //...

    this.isToggled = ko.observable(false);
}

Options

Radio buttons

Two-way binding to Bootstrap radio buttons. Default Knockout checked binding doesn't work with Bootstrap's buttons, so you can use this binding

Examples

Html markup

<div class="btn-group form-group" data-toggle="buttons" data-bind="radio: radioValue">
    <label class="btn btn-primary">
        <input type="radio" name="options" value="A" />
        A
    </label>
    <label class="btn btn-primary">
        <input type="radio" name="options" value="B" />
        B
    </label>
    <label class="btn btn-primary">
        <input type="radio" name="options" value="C" />
        C
    </label>
</div>

View model

function ButtonsExampleViewModel() {
    //...

    this.radioValue = ko.observable();
}

Options

Checkbox buttons

Two-way binding to Bootstrap checkbox buttons. Default Knockout checked binding doesn't work with Bootstrap's buttons, so you can use this binding

Examples

Html markup

<div class="btn-group form-group" data-toggle="buttons" data-bind="checkbox: checkboxArray">
    <label class="btn btn-primary">
        <input type="checkbox" value="A" />
        A
    </label>
    <label class="btn btn-primary">
        <input type="checkbox" value="B" />
        B
    </label>
    <label class="btn btn-primary">
        <input type="checkbox" value="C" />
        C
    </label>
</div>

<div class="btn-group form-group" data-toggle="buttons">
    <label class="btn btn-primary">
        <input type="checkbox" data-bind="checkbox: checkboxValueA" />
        A
    </label>
    <label class="btn btn-primary">
        <input type="checkbox" data-bind="checkbox: checkboxValueB" />
        B
    </label>
</div>

View model

function ButtonsExampleViewModel() {
    //...

    this.checkboxArray = ko.observableArray();
        
    this.checkboxValueA = ko.observable(true);
        
    this.checkboxValueB = ko.observable(false);
}

Options

Binding to Bootstrap Carousrel widget

Examples

With default templates and options:

Html markup

<div data-bind="carousel: { content: { data: itemsFirst } }"></div>

View model

function CarouselExampleViewModel() {
    // ...

    self.itemsFirst = ko.observableArray([
        {
            src: 'holder.js/900x200/text:First image',
            alt: 'First image',
            content: 'First caption'
        }, {
            src: 'holder.js/900x200/text:Second image',
            alt: 'Second image',
            content: 'Second caption'
        }, {
            src: 'holder.js/900x200/text:Third image',
            alt: 'Third image',
            content: 'Third caption'
        }
    ]);
}

Carousel with custom item template:

Html markup

<div data-bind="carousel: { content: { name: 'carouselItemTemplate', data: itemsSecond } }"></div>
            
<script type="text/html" id="Script1">
    <h4 data-bind="text: primary"></h4>
    <p data-bind="text: secondary"></p>
</script>

View model

function CarouselExampleViewModel() {
    // ...

    self.itemsSecond = ko.observableArray([
        {
            src: 'holder.js/900x270/text:First image',
            alt: 'First image',
            primary: 'First caption',
            secondary: 'First subcaption'
        }, {
            src: 'holder.js/900x270/text:Second image',
            alt: 'Second image',
            primary: 'Second caption',
            secondary: 'Second subcaption'
        }, {
            src: 'holder.js/900x270/text:Third image',
            alt: 'Third image',
            primary: 'Third caption',
            secondary: 'Third subcaption'
        }
    ]);
}       

Options

Default values

Default values for carousel binding located in ko.bindingHandlers.carousel.defaults object. It contains default css for root element of carousel and default values for controls, indicators and item templtates. Can be changed before ko.applyBindigs() is called.

defaults: {
    css: 'carousel slide',

    controlsTemplate: {
        name: 'carouselControls',
        templateEngine: ko.stringTemplateEngine.instance,
        dataConverter: function(value) {
            return {
                id: ko.computed(function() {
                    return '#' + ko.unwrap(value.id);
                })
            };
        }
    },
        
    indicatorsTemplate: {
        name: 'carouselIndicators',
        templateEngine: ko.stringTemplateEngine.instance,
        dataConverter: function(value) {
            return {
                id: ko.computed(function() {
                    return '#' + ko.unwrap(value.id);
                }),
                    
                items: value.content.data
            };
        }
    }, 
        
    itemTemplate: {
        name: 'carouselContent',
        templateEngine: ko.stringTemplateEngine.instance,

        converter: function (item) {
            return item;
        }
    }
}

Binding to Bootstrap pagination component.

Examples

Html markup

<div data-bind="pagination: { currentPage: page, totalCount: total, maxPages: maxPages, directions: directions, boundary: boundary, text: text }"></div>

View model

function PaginationExampleViewModel() {
    this.page = ko.observable(1);
    this.total = ko.observable(100);
    this.maxPages = ko.observable(5);
    this.directions = ko.observable(true);
    this.boundary = ko.observable(true);
    this.text = {
        first: ko.observable('First'),
        last: ko.observable('Last'),
        back: ko.observable('«'),
        forward: ko.observable('»')
    };
}

Options

All of the options can be observables.

Binding to Bootstrap pager component.

Examples

Html markup

<div data-bind="pager: { currentPage: page, totalCount: total, isAligned: aligned, text: text }"></div>

View model

function PagerExampleViewModel() {
    this.page = ko.observable(1);
    this.total = ko.observable(100);
    this.aligned = ko.observable(false);
    this.text = {
        back: ko.observable('←'),
        forward: ko.observable('→')
    };
}

Options

All of the options can be observables.

This binding adds or removes one or more CSS classes to the associated DOM element. Can be used, when you need to use Knockout css binding with static and dynamic classes simultaneously. In this case, you may use css binding for static classes and class binding for dynamic classes.

Examples

Html markup

<p class="class-example-text" data-bind="class: className">
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum nec pharetra eros.
    Sed luctus vitae ligula viverra porttitor. Vestibulum porttitor egestas lacus.
</p>
<div class="btn-group form-group" data-toggle="buttons" data-bind="radio: className">
    <label class="btn btn-primary">
    <input type="radio" name="options" value="bg-primary" />
        bg-primary
    </label>
    <label class="btn btn-primary">
    <input type="radio" name="options" value="bg-success" />
        bg-success
    </label>
    <label class="btn btn-primary">
    <input type="radio" name="options" value="bg-danger" />
        bg-danger
    </label>
</div>

View model

function ClassExampleViewModel() {
    this.className = ko.observable('bg-primary');
}

Options

Knockstrap provides implementation of Knockout-compatible stringTemplateEngine, which can use strings as html templates.

For developers, constructor of engine available via ko.stringTemplateEngine. Also it contains instance property, so it isn't necessary to create your own. It can be used everywhere, where Knockout's nativeTemplateEngine is acceptable.

Template engine contains storage of templates, which is shared between all instances.

API

stringTemplateEngine contains:

Examples

Html markup

<p>String template engine:</p>
<p data-bind="template: { name: 'demo', templateEngine: ko.stringTemplateEngine.instance }"></p>
<p>Native template engine:</p>
<p data-bind="template: { name: 'demo' }"></p>
            
<script id="demo" type="text/html">
    <span>It's a <strong>native template engine</strong>!</span>
</script>

View model

var ste = ko.stringTemplateEngine.instance;

ste.addTemplate('demo', '<span>It\'s a <strong>string template engine</strong>!</span>');