knockout.register
v0.2.4
Published
Enhanced knockout component module
Downloads
46
Readme
knockout.register
knockout.register helps to register component in a simpler and more powerful way.
import eventMixin from './mixin/event';
import style from './btn.css';
import template form './btn.tpl';
export default {
name: 'btn',
props: {
text: {
type: ko.types.String,
required: true
},
type: ko.types.oneOf(
'button',
'submit',
'reset'
)
},
mixin: [
eventMixin
],
methods: {
onClick(vm, ev) {
// 'trigger' mix from eventMixin
this.trigger('click', vm);
}
},
style,
template
};
Usage
Install from NPM:
npm install knockout.register --save
<script src="knockout.3.4.0.js"></script>
<script src="node_modules/knockout.register/dest/knockout.register.js"></script>
Native Component Module
knockout.register named knockout original component module as Native Component Module.
Cite from knockout documentation:
ko.components.register('my-component', {
viewModel: {
createViewModel: function(params, componentInfo) {
// - 'params' is an object whose key/value pairs are the parameters
// passed from the component binding or custom element
// - 'componentInfo.element' is the element the component is being
// injected into. When createViewModel is called, the template has
// already been injected into this element, but isn't yet bound.
// - 'componentInfo.templateNodes' is an array containing any DOM
// nodes that have been supplied to the component. See below.
// Return the desired view model instance, e.g.:
return new MyViewModel(params);
}
},
template: ...
});
Standard Component Module
knockout.register creates a new component module and named it as Standard Component Module.
Options
name
- type:
String
(required)
The name for component and custom element.HTML elements are case-insensitive, so when using component the name need to use their kebab-case equivalents(eg. my-component
).
props
- type:
Object
(default:null
)
A prop is a custom attribute for passing information from parent components.A child component needs to explicity declare the props it expects to receive using this options.
export default {
name: 'child',
props: {
text: ko.types.String
}
};
Then we can pass a plain string to it like so:
<child text="hello"></child>
It is possible for a component to specify requirements for the props it is receiving.If a requirement is not met, the plugin will emit warnings.
<child text="1"></child>
When a prop validation fails, the plugin will produce a console warning(if using the development build).
The validator can be a custom function, native constructors or combination:
export default {
props: {
// basic validator
optionalString: ko.types.String,
optionalNumber: ko.types.Number,
optionalBoolean: ko.types.Boolean,
optionalFunction: ko.types.Function,
optionalObject: ko.types.Object,
optionalArray: ko.types.Array,
optionalDate: ko.types.Date,
optionalRegexp: ko.types.Regexp,
optionalNode: ko.types.Node,
optionalElement: ko.types.Element,
optionalAny: ko.types.any,
optionalUser: ko.types.instanceof(User),
optionalEnum: ko.types.oneOf('button', 'submit', 'reset'),
// basic validator with default
optionalStringWithDefault: ko.types.string, // default: ''
optionalNumberWithDefault: ko.types.number, // default: 0
optionalBooleanWithDefault: ko.types.boolean, // default: false
optionalObjectWithDefault: ko.types.object, // default: {}
optionalArrayWithDefault: ko.types.array, // default: []
optionalFunctionWithDefault: ko.types.function, // default: noop
optionalDateWithDefault: ko.types.date, // default: new Date()
optionalRegExpWithDefault: ko.types.regexp, // default: null
optionalNodeWithDefault: ko.types.node, // default: null
optionalElementWithDefault: ko.types.element, // default: null
// combination validator
optionalObjectWithShape: {
optionalString: ko.types.String,
optionalNumber: ko.types.Number,
optionalBoolean: ko.types.Boolean
},
optionalArrayOfObjectsWithShape: ko.types.arrayOf(
ko.types.shape({
string: ko.types.String,
number: ko.types.Number,
boolean: ko.types.Boolea
})
),
optionalUnion: ko.types.oneOfType(
ko.types.String,
ko.types.Number,
ko.types.Boolean
),
// custom validator
customProp(props, propName) => {
if (/* ... */) {
return true; // valid
} else {
return false // invalid
}
},
// misc
requiredString: {
type: ko.types.String,
required: true
},
stringWithDefaultValue: {
type: ko.types.String,
default: 'default string'
}
}
};
computed
& pureComputed
Putting too much logic into your templates can make them bloated and hard to maintain.You should use a computed property.Why pure?
export default {
name: 'component',
props: {
firstName: String,
lastName: String
},
pureComputed: {
fullName() {
return `${this.firstName()} ${thie.lastName()}`;
}
}
};
mixins
- type:
Array
(default:null
)
A mixin is a methods collection reused in multiply components.The merge stratege is dead simple just copy methods from a mixin to methods
option of target component.
It is possible for a mixin to do something before and after mixing.
export default {
// before mixing
preMix() {
this; // => this keyword refer to view model
},
// after mixing
postMix() {},
// the methods will be copied
on() {},
off() {},
trigger() {}
};
methods
- type:
Object
(default:null
)
Built-in lifecycle and custom methods.The this
keyword refs to building view model in lifecycle methods and not enuse in custom methods.
export default {
methods: {
// vm created
created() {
this.text(); // => ''
this.componentInfo.element; // => null
},
// template compiled and inserted into DOM
ready() {
this.text(); // => ''
this.componentInfo.element; // => element
},
// dispose component and clean up
dispose() {
this._computedObservable.dispose();
this._domElement = null;
this._timeoutHander = null;
},
// custom method
customMethod() {
this; // => not ensure ref to view model all the time
}
}
};
style
- type:
String
(default:''
)
A <style/>
tag which wraps the style string will be created and inserted to <head/>
.
template
- type:
String
(default:'<!-- empty template -->'
)
Knockout will emit error and halt application if template
not specified.This plugin will use a HTML comment string to cheat in registering.
License
MIT © BinRui.Guan