Component Hooks

VertiGIS Studio Web provides a number of React hooks to ease development of custom components bound to models. These hooks make it simple to follow the recommended observable properties pattern for model interactions within your functional components.

useWatchAndRerender

Watches an object for changes in one or more properties of a component model and triggers a re-render of the component.

The Problem

In VertiGIS Studio Web, component models provide a way to decouple components from data source concerns and app interactions. However, they raise the issue of consistency - how can a component stay up to date with changes in the data of the underlying model? E.g. how does the React component know when to re-render?

The Solution

VertiGIS Studio Web components solve this problem by providing a way to update the UI when the data in the underlying model changes using a React hook called useWatchAndRerender. The component render lifecycle is as follows:

1. The initial data is pulled from the model and rendered.
2. The component starts to watch for changes to the specified properties on the model by using the useWatchAndRerender React hook.
3. The value of the watched property in the model changes. In the example below it changes as a result of a button click.
4. The hook that is watching the property value for changes causes the component to re-render with the new property value.

import { useWatchAndRerender } from "@vertigis/web/ui";
import Typography from "@vertigis/web/ui/Typography";
import React from "react";
import { LayoutElement } from "@vertigis/web/components";
import Button from "@vertigis/web/ui/Button";

export default function CustomComponent(props) {
    const { model } = props;

    // Start watching for changes to the hidden property on the model
    useWatchAndRerender(model, "hidden");

    return (
        <LayoutElement {...props}>
            {/* Change the underlying model to trigger a re-render */}
            {model.hidden && (
                <Button onClick={() => (model.hidden = false)}>
                    Show Me
                </Button>
            )}
            {!model.hidden && (
                <div>
                    <Typography variant="h1">BOO!</Typography>
                    <Button onClick={() => (model.hidden = true)}>
                        Hide Me
                    </Button>
                </div>
            )}
        </LayoutElement>
    );
}

The role of the "watch" functions for a component with respect to model data is similar to the role of the useState and useEffect functions with respect to the local state data. The useWatchAndRenderer function essentially defines a model property as state your component's presentation is dependent upon, much like useState, while leaving you the responsibility to update the underlying component when appropriate. The useWatch function defines a dependency on a model property, while leaving you to define what side effects are required, much like useEffect.

useWatchCollectionAndRerender

Watches a collection for change events and triggers a re-render. Conceptually equivalent to useWatchAndRerender but specifically for Collection objects.

useWatch

Watches an object for changes in one or more properties and triggers a callback.

useSubscribeAndRerender

Subscribes to an event and triggers a re-render.

useSubscribe

Subscribes to an event and triggers a callback.