knobjs

A component library for knockout.js to build skinnable UIs with ease.

Knobjs is a component library based on knockoutjs. The main goal of the lib is to ease the way of creating skinnable / themed UIs. The components communicate through ko.observables. Other than knockout, its dependency is superdata which is a general data layer which can be used with any client-side frameworks.

knob-button

This is one of the most basic components in knobjs. It works like you would expect it from a button. If you click on it, something will be triggered. This is why most of the components in knobjs are using this element. Each components where some kind of changes should be triggered by a click are implemented with knob-buttons.

$3

Param | Type | Required | Default value | Description
--- |--- |--- |--- |---
variation | string | No | "default" | The variation of the button. See the style section.
label | string | Partially ** | | The text which will be written on the button.
iconLeft | string | Partially ** | | The id of the icon on the left of the label.
iconRight | string | Partially ** | | The id of the icon on the right of the label
icon | string | Partially ** | | This is a synonim for iconLeft.
click | function | No | | This is the callback which will be called on click.

** At least one of these params has to be given, otherwise an error will be thrown. It's because you probably don't want to create a totally empty button.

$3

``html




`

knob-toggleSwitch

This switch component is used for enabling or disabling features. If you click on it, you toggle the value property associated with the component.

$3

Param | Type | Required | Default value | Description
--- |--- |--- |--- |---
value | ko.observable(boolean) | Yes | ko.observalble(false) | With this observable, you can set the default state of the switch button.
variation | string | No | | By giving "square" value to variation, the component can be set to have rectangular button.

$3

`html




`




knob-notification

If you place this component somewhere in your html code, knob attaches an object called notifications to its interface. It doesn't need params like other components, You can use it like this:

`html

`
After that, you can call the following 4 functions in javascript code

`js
window.knob.notifications.showError("Error text", 1111)
window.knob.notifications.showWarning("Warning text", 1111)
window.knob.notifications.showSuccess("Succes text", 1111)
window.knob.notifications.showLoading("Loading text", 1111)
`
They all have 2 parameters, the text to show, and the time to live in ms. After the given time the notifications will disappear.
The notifications will have position: absolute, and top: 0 css parameters on them.




knob-input

This is the other most basic component in knobjs. It's just a simple input, but you can style it in the knob way.

$3

Param | Type | Required | Default value | Description
--- |--- |--- |--- |---
variation | string | No | "default" | The variation of the button. See the style section.
type | string | No | "text" | The type of the input. (Eg.: 'password')
value | ko.observable | Yes | | This is the observable in which the value will be written. If you want to use the value of the input, then you must give it as a parameter.
hasFocus | ko.observable (boolean) | No | ko.observable (false) | With this observable, you can programmatically set the focus to this input.

You can use "primary" variation instead of "default" in order to use a style depending on primary color. In this case, default state's fill color and border-color will be the primary color. Hover and active states will use darkened or lightened primary colors depending whether primary color is a dark color or not.

$3


`html


`

knob-radio

This component is built on top of the knob-button component and it implements a radio button behaviour. This means that you can select one of it's elements and only one element can be selected from the group. Since it is composed from knob-button elements, you can add icons and labels to it's elements.

$3

Param | Type | Required | Default value | Description
--- |--- |--- |--- |---
group | string | Yes | | This value will indicate in which group the buttons will be. You can connect multiple knob-radios by putting them into the same group.
selected | ko.observable | No | | The selected element will be put into this observable.
selectedIdx | ko.observable (number) | No | | The selected index will be written into this observable. Also, you can set the default selection by giving a value to this observable.
items | Array | Yes | | You can configure the buttons within the component, so every parameter which you can pass to buttons are valid in this array. Also, there is an extra value parameter.

$3


`html


`

knob-dropdown

This component is also composed of knob-buttons. Therefore every element can have it's icon and label. It also can have an icon on the right, which is usually a caret pointing down to indicate the options will be visible if you click on it. In a sense, it's very similar to the knob-radio element.

$3

Param | Type | Required | Default value | Description
--- |--- |--- |--- |---
selected | ko.observable | Yes | | The selected element. This is not visible in the dropdown list.
rightIcon | string | No | | The icon on the right of the selected element. Should be a caret to indicate that something will appear on the bottom if you click on it.
items | Array or ko.observableArray | Yes | | The items in the dropdown. They are configured just like buttons and they also can have a value property.
selectedIdx | number or ko.observable | No | 0 | The selected index. If it's an observable, is it possible to get or set selected index after creating component

You can give ko.observableArray as items parameter. This way you can change dropdown's items after creating component by setting value of observableArray to other items array. It throws error if given new value is invalid (each element of array value should contain label and/or icon property).

If you give an observable as selectedIdx parameter, you can change selected item after creating component by setting value of selectedIdx observable. If given selectedIdx value is not a valid index, it will be changed to 0.

If an item is selected or its position changes caused by setting items observableArray's value, selectedIdx observable will be automatically refreshed to the new selected index.

$3


`html


`

Example for giving ko.observableArray() as items parameter can be found in ./examples/knob.html and ./examples/knob.js

knob-inline-text-editor

It's a quite common task to edit a short text. This component has one major boolean state variable, the editMode. If the edit mode is false, then the text value is shown as a text node and there is an edit button next to it. If you click on the edit mode, then it's replaced with a knob-input and a save and a cancel button. The save and cancel functionality can be triggered with pressing enter and the esc key.

$3

Param | Type | Required | Default value | Description
--- |--- |--- |--- |---
value | ko.observable | Yes | | The initial value is read from this observable and the changes will be written back to it. (Only if you save the changes.)

$3


`html


`

knob-items-per-page

This component is used in the knob-paged-list component. It's basically responsible for calculating the actual number of pages based on the number of items and the items per page value. This value is selected from a dropdown list.

$3

Param | Type | Required | Default value | Description
--- |--- |--- |--- |---
numOfItems | ko.observable (number) | Yes | | The number of items in a result set.
itemsPerPage | ko.observable (number) | Yes | | The number of items on a page.
numOfPages | ko.observable (number) | Yes | | The calculated number of pages, which are based on the previous two values.
itemsPerPageList | Array | Yes | | The available numbers of items which will show up in the dropdown.

$3


`html


`

knob-pagination

This component is used by the knob-paged-list as well. It's very tightly bound with the knob-items-per-page. Basically if you pass the same numOfPages ko.observable to the two components, then they will smoothly function together.

$3

Param | Type | Required | Default value | Description
--- |--- |--- |--- |---
numOfPages | ko.observable | Yes | | You can set the total number of pages with this property. The page selector items will be generated based on this variable.
currentPage | ko.observable | Yes | ko.observable(0) | The selected page's value will be written into this ko.observable
afterHead | number | No | 2 | The number of page selectors to be visible at the beginning of the list.
beforeTail | number | No | 2 | The number of page selectors to be visible at the end of the list.
beforeCurrent | number | No | 2 | The number of page selectors to be visible before the currently selected item.
afterCurrent | number | No | 2 | The number of page selectors to be visible after the currently selected element.

$3


`html


`

knob-paged-list

An easily configurable general paged list with which you can list any kind of data. You can create project lists, galleries or anything related to listing by using this module. The child template can be anything of this component depending on the data you want to show in the list.

The main dependency of the module is superdata's store module.

$3

Param | Type | Required | Default value | Description
--- |--- |--- |--- |---
store | superdata.store | Yes | | A store instance from superdata. Every data reading and writing goes through this module.
search | string | Yes | | The field's name based on which the filtering should work.
sort | Array | Yes | | The field names based on which the you want to have a sorting option.

$3


`html


`




knob-tabs

With the knob-tabs component, you can easily create tabbed user interfaces. This component is special in the sense that it works only if you add knob-tab components as child components. The params of the knob-tab components will be applied to a knob-radio component, which will be responsible for selecting the visible tab.
You can change easily the tab orientation, with only one css selector.
Now available:
* knob-tab-orient--left-top
* knob-tab-orient--top-left
* knob-tab-orient--top-center
* knob-tab-orient--top-right

$3

Param | Type | Required | Default value | Description
--- |--- |--- |--- |---
defaultTab | number | No | 0 | You can set the default selected tab by giving the zero-based index of it.
variation | string | No | "tab" | Possible values: "tab", "tab-transparent"

Also, the knob-tab child elements has to have at least one of the following parameters:
- label
- icon (a synonim for leftIcon)
- leftIcon
- rightIcon

Variation "tab-transparent" displays tab panels with transparent backgound.

$3


` html


content1


content2


content3


`

knob-modal

With this component, you can easily create a modal window.

$3

Param | Type | Required | Default value | Description
--- |--- |--- |--- |---
variation | string | Yes | "modalHead" | The variation of the button in modal header section.
title | string | No | "text" | Header text in the header element.
icon | string | No | "text" | The icon on the left of the header element.
visible | ko.observable (boolean) | Yes | | This is the observable in which the show / hide the modal.

$3

` html

Content text

`

knob-modal - alert

With this component, you can easily create a modal - alert window.

$3

Param | Type | Required | Default value | Description
--- | --- | --- | --- | ---
title | string | No | "" | Header text in the header element.
icon | string | No | "" | The id of the icon on the left of the header element.
message | string | Yes | | The message shown.
okLabel | string | Yes | | The label on the button.
visible | ko.observable (boolean) | Yes | | This is the observable in which the show / hide the modal.
callback | function | Yes | | The callback function to be executed on pressing the button button.

$3

` html


`

knob-modal - confirm

With this component, you can easily create a confirm dialog.

$3

Param | Type | Required | Default value | Description
--- |--- |--- |--- |---
title | string | No | "" | Header text in the header element.
icon | string | No | "" | The icon on the left of the header element.
visible | ko.observable (boolean) | Yes | false | This is the observable in which the show / hide the modal.
message | string | Yes | | Content message in the confirm modal window content section.
okLabel | string | Yes | | The label of the ok button.
cancelLabel | string | Yes | | The label of the cancel button.
callback | function | Yes | | This function will be called when the user clicks on the ok or cancel button. If the ok was clicked, then the param of it will be true, otherwise false.

$3


` html


`

knob-notification

With this component, you can easily create a notification bar - info, success, warning and error statements.

$3

Param | Type | Required | Default value | Description
--- |--- |--- |--- |---
variation | string | No | "" | Header text in the header element.
message | string | No | "" | Header text in the header element.
icon | string | No | "" | The icon on the left of the header element.
visible | ko.observable (boolean) | Yes | false | This is the observable in which the show / hide the modal.

$3


` html


`




Styling knob components

You can use simply themes, and color sets. Defines the color, and use them in any module.

$3

`javascript
knob.init({
theme: "default",
colorSet: {
primary: "#2199e8",
secondary: "#777",

info: {
text: "#00529b",
background: "#bde5f8"
},
success: {
text: "#4f8a10",
background: "#dff2bf"
},
warning: {
text: "#9f6000",
background: "#feefb3"
},
error: {
text: "#d8000c",
background: "#ffbaba"
},

white: "#fff",

lightGray: "#e6e6e6",
mediumGray: "#cacaca",
darkGray: "#8a8a8a",

black: "#000",
transparent: "transparent"
}
});
`

knob-js uses the tinycolor2 npm package to the lighten and darken colors. Here is the example, hover state is lighten, active state is darken:

$3


`javascript
"default": {
"default": {
"backgroundColor": theme.secondary,
"borderColor": theme.secondary,
"color": theme.black,
"fill": theme.black
},
"hover": {
"backgroundColor": tinycolor(theme.success.background).lighten().toString(),
"borderColor": tinycolor(theme.success.background).lighten().toString()
},
"active": {
"backgroundColor": tinycolor(theme.success.background).darken().toString(),
"borderColor": tinycolor(theme.success.background).darken().toString()
},
"disabled": {
"backgroundColor": theme.mediumGray,
"color": theme.lightGray,
"fill": theme.lightGray
}
}

`

Icons and localization

You can add two extra parameters when you init knob, with which you can customize the icons and the labels in the components. The first is the icons, which should be an object, the secont is the labels property, which also should be an object.

$3

Param | Type | Required | Default value | Description
--- |--- |--- |--- |---
config.icons.search | string | No | "#icon-search" | The search icon in the paged list component.
config.icons.sort.asc | string | No | "#icon-sort-asc" | The icon of the ascending sort.
config.icons.sort.desc | string | No | "#icon-sort-desc" | The icon of the descending sort.
config.icons.dropdown | string | No | "#icon-expand-more" | The icon on the right hand side in dropdowns.
config.icons.loading | string | No | "#icon-loading" | The loading icon. It is alwas spinned!
config.icons.pagination.first | string | No | "#icon-first-page" | The icon of the last page button in the pagination.
config.icons.pagination.prev | string | No | "#icon-chervon-left" | The icon of the prev button in the pagination.
config.icons.pagination.next | string | No | "#icon-chervon-right" | The icon of the next button in the pagination.
config.icons.pagination.last | string | No | "#icon-last-page" | The icon of the last page button in the paginagion.
config.labels.noResults | string | No | "No results" | The string which will be displayed if the query in a list returns with an empty set.

$3

`javascript
knob.init({
theme: "default",
colorSet: {
primary: "#2199e8",
secondary: "#777",

info: {
text: "#00529b",
background: "#bde5f8"
},
success: {
text: "#4f8a10",
background: "#dff2bf"
},
warning: {
text: "#9f6000",
background: "#feefb3"
},
error: {
text: "#d8000c",
background: "#ffbaba"
},

white: "#fff",

lightGray: "#e6e6e6",
mediumGray: "#cacaca",
darkGray: "#8a8a8a",

black: "#000",
transparent: "transparent"
},
icons: {
search: "#icon-search",
sort: {
asc: "#icon-sort-asc",
desc: "#icon-sort-desc"
},
dropdown: "#icon-expand-more",
loading: "#icon-loading",
pagination: {
first: "#icon-first-page",
prev: "#icon-chevron-left",
last: "#icon-chevron-right",
next: "#icon-last-page"
}
},
labels: {
noResults: "No results"
}
});
`

knob-checkbox

Checkbox component in knobjs. It has two state: checked (marked by a tick) or unchecked (marked by a cross). It's value is it's state (boolean). You can style it by giving icons object as parameter.

$3

Param | Type | Required | Default value | Description
--- |--- |--- |--- |---
value | ko.observable | Yes | | This is the observable in which the value will be written. If you want to use the value of the checkbox, then you must give it as a parameter.
icons | object | No | { tick: icons.tick, cross: icons.cross } | You can set custon icons belonging to checked and unchecked states

$3


`html


`

##knob-numericinput

A numeric stepper component. It's built up from two knob-buttons and a knob-input, the buttons are able to increase or decrease the input's value. Holding one of the buttons make the value change faster to a cap.

$3

Param | Type | Required | Default value | Description
--- |--- |--- |--- |---
value | ko.observable | Yes | | The value of the input, it should store a number as an inital value.
minValue | number | Yes | | The minimum value the input can reach.
maxValue | number | Yes | | The maxmimum value the input can reach.
step | number | Yes | | The amount the input can be decreased or increased with when clicking once.
prefix | string | No | | String before the input's value.
postfix | string | No | | String appended before the input's value.
minTimeout | number | No | 50 | The miminum of the refresh rate when holding one of the buttons.
timeoutDecrement | number | No | 100 | Specifies how fast the value will refresh.
baseTimeout | number | No | 500 | Refresh rate in the beginning.
layoutArrangement | string | No* | "back" | Specifies the button placements.

*Only "back", "split" or "front" values are viable. No value means "back" by default. Otherwise an exception is thrown.

$3


` html


``

Additional features

$3

You can set a background color for body of the HTML document by setting background property in theme parameter passed to knob's init function.