A modern library for creating user interfaces.
npm install cascade@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 @hash.
"experimentalDecorators": true in your tsconfig.json file.
typescript
class User {
@observable firstName: string = '';
@observable lastName: string = '';
@observable get fullName() {
return this.firstName + ' ' + this.lastName;
}
@observable list: number[] = [1, 2, 3, 4];
@array array: number[] = [5, 6, 7, 8];
@hash hash: {} = {
'property': 'value'
};
}
`
> Note: Type detection for arrays depends on the optional package reflect-metadata. You must also set "emitDecoratorMetadata": true in your tsconfig.json file. For IE10 and below, you must also include es6-shim or similar polyfills. If you don't wish to install polyfills, then you must use @array instead of @observable.
$3
You may also create observable properties directly.
`typescript
Cascade.createObservable(obj: any, property: string, value?: T);
Cascade.createObservableArray(obj: any, property: string, value?: Array);
Cascade.createObservableHash(obj: any, property: string, value?: IHash);
Cascade.createComputed(obj: any, property: string, definition: (n?: T) => T, defer?: boolean, setter?: (n: T) => any);
`
You may also create the observables as objects. Keep in mind, these are accessed as methods instead of direct usage.
`typescript
Observable(value?: T);
ObservableArray(value?: Array);
ObservableHash(value?: IHash);
Computed(definition: (n?: T) => T, defer: boolean = false, thisArg?: any, setter?: (n: T) => any);
`
> Note: Internet Explorer does not support ObservableHash. It also requires ObservableArray values to be modified by function calls instead of setters.
>
> In modern browsers which support Proxy objects, we can simply modify indexed values with:
>
> viewModel.list[4] = 5;
>
> However, in Internet Explorer, we would need to write:
>
> viewModel.list.set(4, 5);
Functional DOM Components
Cascade uses either JSX or direct JavaScript calls to create a Virtual Dom. These Virtual Nodes can then be rendered into DOM Nodes for display.
`typescript
Cascade.createElement(
type: string | Component,
props: T,
...children: Array
): IVirtualNode;
`
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.
`typescript
interface IUserViewProps {
user: User;
}
class UserView extends Component {
render() {
return (
{this.props.user.fullName}
);
}
}
`
$3
Components can then be rendered by either calling
`typescript
Cascade.createElement(UserView, { user: User });
`
or with JSX by calling
`typescript
`
> Note Using JSX requires the options "jsx": "react" and "reactNamespace": "Cascade" in your tsconfig.json file. Cascade must also be imported into any .jsx or .tsx file.
$3
Components and VirtualNodes have optional props
key: string
Specifying a 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
A 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.
Rendering
Cascade will render directly to any DOM node specified. Simply call
`typescript
Cascade.render(
node: HTMLElement | string,
virtualNode: IVirtualNode
): void;
`
For example
`typescript
Cascade.render(
document.getElementById('root'),
);
`
Troubleshooting and Optimization
$3
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.
$3
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.