Cascade builds ViewModels with reactive properties to synchronize data. Properties may be marked as observable, so that changes may be watched, or computed, which then watch for changes in related observables. With this, a dynamic tree of data may be built, all which is updated automatically.
Furthermore, any Functional DOM Component which references an observable or computed, will be updated automatically.
Simply use the
@observable decorator, which will automatically detect if the property is a value, an array, or a getter function. Computed values must be declared as a getter, and arrays must be declared with their types. Observable hashes may be created with
Note: Decorators depend on TypeScript. You must set
"experimentalDecorators": truein your
Note: Type detection for arrays depends on the optional package
reflect-metadata. You must also set
"emitDecoratorMetadata": truein your
tsconfig.jsonfile. For IE10 and below, you must also include
es6-shimor similar polyfills. If you don't wish to install polyfills, then you must use
You may also create observable properties directly.
Cascade.createObservableobj: any, property: string, value?: T;Cascade.createObservableArrayobj: any, property: string, value?: Array<T>;Cascade.createObservableHashobj: any, property: string, value?: IHash<T>;Cascade.createComputedobj: any, property: string, definition:T, defer?: boolean, setter?:any;
You may also create the observables as objects. Keep in mind, these are accessed as methods instead of direct usage.
Observablevalue?: T;ObservableArrayvalue?: Array<T>;ObservableHashvalue?: IHash<T>;Computeddefinition:T, defer: boolean = false, thisArg?: any, setter?:any;
Note: Internet Explorer does not support
ObservableHash. It also requires
ObservableArrayvalues to be modified by function calls instead of setters.
In modern browsers which support
Proxyobjects, we can simply modify indexed values with:
viewModel.list = 5;
However, in Internet Explorer, we would need to write:
Functional DOM Components
Cascade.createElementtype: string | Component,props: T,...children: Array<any>: IVirtualNode<any>;
Components may be defined by simply extending the Component class. Any property which references an observable will cause the Component to render any time the observable updates.
Components can then be rendered by either calling
or with JSX by calling
UserView user= /
Note Using JSX requires the options
"reactNamespace": "Cascade"in your
Cascademust also be imported into any
Component and VirtualNode Properties
Components and VirtualNodes have optional props
key for a Component or VirtualNode will improve rendering speeds in certain cases. This is a string, which should be unique to that node within its parent. It is most useful for a set of children which change often, such as arrays or conditional children.
ref: (n: Node) => void
ref callback will receive the resulting
Node whenever the Component or VirtualNode is rendered for the first time. This is useful for directly modifying the
Node after rendering.
Cascade will render directly to any DOM node specified. Simply call
Cascade.rendernode: HTMLElement | string,virtualNode: IVirtualNode<any>: void;
Cascade.renderdocument.getElementById'root',UserView user= /;
Troubleshooting and Optimization
Computed properties subscribe to observables simply by reading them. So any property that is read, will generate a subscription. If you don't want to subscribe, use
Cascade.peek(obj: any, property: string) to read the value without subscribing.
Also, if you need to call methods inside of a computed, those methods may read from observables as well. This behavior may or may not be what you intend. To protect against this, use
Cascade.wrapContext(callback: () => any, thisArg?: any), which will capture any generated subscriptions without actually subscribing to them.
Components manage their subscriptions through the
Component.root computed property. Internally, this calls the
Component.render method, so any observable read while rendering will generate a subscription. In order to reduce re-renders, read observable properites as late as possible. Meaning, it's better to read inside a child component, than inside a parent and then pass the value into the child. This way only the child re-renders when the value is updated.
If a Component or Computed is not correctly updating, there may be more than one copy of Cascade referenced. There must be exactly one copy for subscriptions to be tracked correctly.