Low-level hooks

Note

Starting from EVA ICS WebEngine React 0.3, all hooks require dependencies. If no dependencies used, specify an empty array ([]).

useEvaStateUpdates

React hook, which automatically switches EVA ICS WebEngine state updates.

It is highly recommended to set WebEngine state updates to false by default, especially for large setups, (see Configuring) and subscribe only to states of items which are currently displayed.

The hook is used in UI layouts where the state updates can be formed as global for all components displayed. For complex block layouts, see: useEvaStateBlock.

Parameters

interface EvaStateUpdatesParams {
  engine?: Eva;
  state_updates: Array<string> | boolean;
  // do not keep WebEngine states for non-subscribed
  clear_existing?: boolean;
  // return previous subscription when the component is unmounted
  // if not set to true, the hook unsubscribes the engine from all events
  keep?: boolean;
  // append subscription to the existing one
  append?: boolean;
}

Usage example

import {
    useEvaStateUpdates,
    useEvaState,
    EvaSubscriptionState, // optional, used by the following example
    ItemValue // optional, used by this example
} from "@eva-ics/webengine-react";

const PageSensors = ({plant}:{plant: string}) => {
  const sub_state = useEvaStateUpdates({
    state_updates: [`sensor:${plant}/#`],
  }, [plant]);

  return (
      <div>Sensors dashboard ({plant})</div>
      <div>Temperature:
          <ItemValue oid={`sensor:${plant}/temp`} digits="2" units="C" />
      </div>
      <div>Humidity:
          <ItemValue oid={`sensor:${plant}/hum`} digits="2" units="%" />
      </div>
  );
}

The current subscription operation state can be optionally parsed and used to e.g. display a loading progress message:

switch (sub_state) {
  case EvaSubscriptionState.Active: // the engine subscription is switched
    return <div>Dashboard</div>;
  case EvaSubscriptionState.Working: // switching in progress
    return <div>Loading...</div>;
  case EvaSubscriptionState.Failed: // switching failed
    return <div>Failed!</div>;
}

useEvaStateBlock

React hook, which automatically registers a EVA ICS WebEngine state block for the current component and its child ones.

It is highly recommended to set WebEngine state updates to false by default, especially for large setups, (see Configuring) and subscribe only to states of items which are currently displayed.

Each state block gets own subscription set which does not interfere neither with the global state subscription nor with other state blocks.

The data, collected by blocks is pushed into the global state map, so all other functions and methods can use it, no matter which block has collected it.

Using state blocks may lead to situations when the same data/events are received from the server multiple times which may produce additional load to front-end applications, so it is recommended to use state blocks only for really complex layouts, where development costs are higher.

Page with blocks

Parameters

interface EvaStateBlockParams {
  name: string;
  state_updates: string[];
  engine?: Eva;
}

Usage example

import {
    useEvaStateBlock,
    useEvaState,
    ItemValue // optional, used by this example
} from "@eva-ics/webengine-react";

useEvaStateBlock({ name: "test", state_updates: [`sensor:${plant}/temp`] }, [plant]);

return (
    <div>Sensors dashboard ({plant})</div>
    <div>Temperature:
        <ItemValue oid={`sensor:${plant}/temp`} digits="2" units="C" />
    </div>
    <div>Humidity:
        <ItemValue oid={`sensor:${plant}/hum`} digits="2" units="%" />
    </div>
);

useEvaState

React hook, which contains state of EVA ICS item. The state is automatically updated in real time.

This is the basic hook to get item states, which is used in the majority of UI components.

Parameters

interface EvaStateParams {
  oid?: string;
  engine?: Eva;
}

Usage example

import { useEvaState } from "@eva-ics/webengine-react";

const MyComponent = () => {
  const state = useEvaState({ oid: "sensor:env/temp" }, []);

  return <span>{state?.value}</span>;
}

useEvaStateBulk

React hook, which contains states of multiple EVA ICS item. The states are automatically updated in real time.

The states are returned as an object, where keys are item OIDs and values are the item states.

Parameters

interface EvaStateBulkParams {
  oid?: Array<string>;
  engine?: Eva;
}

Usage example

import { useEvaStateBulk } from "@eva-ics/webengine-react";

const MyComponent = () => {
 const states = useEvaStateBulk(
     { oid: ["sensor:tests/s1", "sensor:tests/s2", "sensor:tests/s3"] }, []);

 return (
   <>
     {Object.keys(states).map((oid) => {
       return (
         <div key={oid}>
           {oid} = {states[oid].value}
         </div>
       );
     })}
   </>
 );
}

useEvaStateHistory

React hook, which contains historical state of EVA ICS item. The state is automatically updated with the specified interval.

The hook is used in Chart component. It also can be used to output various analytics tables and custom charts.

Parameters

interface EvaStateHistoryParams {
  oid: string | Array<string>;
  timeframe: string | Array<string>;
  update?: number;
  prop?: StateProp;
  fill?: string;
  args?: any;
  update_uninit?: number;
  engine?: Eva;
}

  • timeframe contains a single or multiple time frames (see item.state_history for time frame format). The time frame can be specified as START:END, e.g. to output the data for the previous hour: 2H:1H.

  • update update interval in seconds (default: 1 sec)

  • fill filling interval (see item.state_history)

  • args extra API call arguments

  • update_uninit (seconds) when used standalone with no web-engine HMIApp component and no login.success callback, refresh login status more frequently than update interval set. Use in case of problems when the first hook iteration is skipped.

Note

Time convention used in EVA ICS time-frames to fill data:

  • S for seconds (e.g. 5S for 5 seconds)

  • T for minutes

  • H for hours

  • D for days

  • W for weeks

  • A to get automatic number of records (e.g. 5A for 5 exactly records)

Time convention used in EVA ICS to specify start/end of a timeframe:

  • If there are dedicated parameters for start/end, they are filled separately

  • If there is a single parameter only, it is filled either as START:END or as START only (END is automatically set to the current time)

where values must be:

  • UNIX timestamps only (if a parameter is strictly specified as a number)

  • Date in human-readable format (RFC3339 recommended)

  • Using the same notation as for filling. E.g. setting start=30T sets time-frame start to 30 minutes before now.

START value is always mandatory. If END value is required to be set to the current time, it can be omitted.

Output

interface StateHistoryData {
  data: any;
  error?: EvaError;
}

Usage example

import { useEvaStateHistory } from "@eva-ics/webengine-react";

const MyComponent = () => {
  const state = useEvaStateHistory({
      oid: "sensor:env/temp",
      timeframe: "1D",
      fill: "30A", // get exactly 30 records
      update: 1
  }, []);

  // ...

}

The state.data variable contains item.state_history API call result, which is updated with the specified interval.

In case of API call error, state.error is filled with error information.

useEvaAPICall

React hook, which contains HMI service API call result. The result payload is automatically updated with the specified interval.

Parameters

interface EvaAPICallParams {
  method: string;
  params?: object;
  update?: number;
  engine?: Eva;
}

  • update update interval in seconds (default: 1 sec)

  • update_uninit (seconds) when used standalone with no web-engine HMIApp component and no login.success callback, refresh login status more frequently than update interval set. Use in case of problems when the first hook iteration is skipped.

Output

interface APICallData {
  data: any;
  error?: EvaError;
}

Usage example

import { useEvaAPICall } from "@eva-ics/webengine-react";

const MyComponent = () => {
  const result = useEvaAPICall({
    method: "bus::sim.modbus.sensor1::get",
    update: 1
  }, []);

  let value = result.data?.value;
  return <span>{value}</span>;
}

The result.data variable contains API call result, which is updated with the specified interval.

In case of API call error, result.error is filled with error information.