@frui.ts/views

@frui.ts/views

View discovery

In order to support ViewModel-driven workflow, view discovery is an essential feature. This means that based on a particular view model instance, we should be able to find the proper view and display it.

This feature consists of two parts - view registry that is a list of all available view models and their assigned views, and the View component that makes the lookup and rendering.

To register a view, use the registerView(view, viewModelConstructor, context?) function. If you need to register multiple views for a view model (e.g., main view, side bar, toolbar, etc.), use the context argument.

The View component accepts the following props:

• vm - the actual view model to be displayed
• context - optionally provide value to specify a view to use
• useLifecycle - if set to true, the view will pass lifecycle events (activate, deactivate) to the view model. This is needed only for the top-most root view because all child view models will receive the events from their parent view model.
• fallbackMode - by default, the view throws an error when the appropriate view cannot be found. You can set message or empty to display an error message or empty control instead.

Usage

// loginView.tsx
import { observer } from "mobx-react-lite";
import { registerView } from "@frui.ts/views";

const loginView: React.FunctionComponent<{ vm: LoginViewModel }> = observer(({ vm }) => (
  <TextBox target={vm.credentials} property="login" />
  <TextBox target={vm.credentials} property="password" type="password" />
);

export default registerView(loginView, LoginViewModel);

Let's have RootViewModel as follows:

class RootViewModel extends ConductorSingleChild<LoginViewModel | DataViewModel> {
  ...
}

We can display proper views for the currently active child of the RootViewModel:

// rootView.tsx
...
<aside>
  <View vm={vm.activeChild} context="sidebar" fallbackMode="empty" />
</aside>
<main>
  <View vm={vm.activeChild} />
</main>

BindingComponent

The core component for 2-way binding is BindingComponent, a wrapper around any visual component.

When creating a custom bindable control, you can use the following:

• this.value - contains the value that the control is bound to, use it in the underlying component
• this.setValue(value) - call this and pass the new value when the user changes the value through the underlying component
• this.inheritedProps - contains the props passed to the wrapper except for binding-specific properties, so that you can directly pass it to the underlying component

Example

export class TextBox<TTarget> extends BindingComponent<TTarget, IBindingProps<TTarget>> {
  render() {
    return (
      <Observer>
        {() => (
          <input {...this.inheritedProps} type="text" value={this.value || ""} onChange={this.handleValueChanged} />
        )}
      </Observer>
    );
  }

  @bind
  protected handleValueChanged(e: React.ChangeEvent<HTMLInputElement>) {
    this.setValue(e.target.value);
  }
}

// in view
<TextBox target="{vm.item}" property="firstName" placeholder="First name" />

Changelog

0.15.0

• New package @frui.ts/dataviews with higher-order components for displaying data. Check the readme.
• Added useBinding, getValue, and setValue helper functions to @frui.ts/views. You can use them when implementing functional binding components.
• React and Mobx made peer dependencies
• Router requires root view model on start() instead of the constructor
• Router accepts a navigation adapter on start(), which enables proper cooperation of the two components
• Route name can be string, symbol, or class
• UrlNavigationAdapter requires root view model on start() instead of the constructor
• You can provide custom JSON serializer to FetchApiConnector
• initialize(): Promise<any> | void added to IActivatable (and therefore to IScreen as well)
• ConductorSingleChild requires findNavigationChild to be implemented. You can return undefined, which was the original default, if you don't need navigation to child screens.
• When activating a child of a conductor, it gets at least initialized when the parent is not active
• AutomaticDirtyWatcher can be configured to exclude specified properties
• Check in @frui.ts/bootstrap supports indeterminate state. Enable it by setting the threeState prop. The state id displayed when the bound value is null.
• Check in @frui.ts/bootstrap supports value property so that it can set custom values to the bound property (not only boolean).