Haystack React

A set of APIs to make it super simple to create Haystack based applications using React.

This library is built on top of haystack-nclient. and haystack-core.

Installation

The haystack-core and haystack-nclient libraries need to be installed as peer dependencies. Therefore to get started using this library in your project, run the following command...

``
npm install haystack-core haystack-nclient haystack-react
`

If you want to use units then install haystack-units as well...

`
npm install haystack-core haystack-units haystack-nclient haystack-react
`

APIs

Please click here for the API documentation.

Design

$3

If you're unfamiliar with React hooks then click here to read more.

Hooks are being used to make it as easy as possible to create complex applications with React data.

API

$3

In haystack-nclient all network communications is routed through a Client object. Access to the client object and its configuration options is available using the useClient() hook.

This hook uses a React Context called ClientContext. This enables the underlying Client network configuration to be changed independently of UI implementation.

Set up the Client Context high up in your tree of UI components. For example...

`tsx
const client = new Client({
base: new URL(window.location.href),
// Optionally specify a project. This is normally picked up from the browser's current address.
// project: 'demo'
})

// The 'client' object will be picked up by all components and hooks that call useClient() to make a network call.
// This is useful because we can create a UI component that could speak to a variety of origins or projects etc.
const App = (): JSX.Element => {
return (



)
}
`

The client object can be configured differently if the server is not the FIN framework...

`tsx
const client = new Client({
base: new URL(window.location.href),
opsBase: 'haystack',
// Optionally specify a project. This is normally picked up from the browser's current address.
// project: 'demo',
// Optionally prefer Hayson over Zinc...
options: { headers: { accept: HAYSON_MIME_TYPE } },
})

// The 'client' object will be picked up by all components and hooks that call useClient() to make a network call.
// This is useful because we can create a UI component that could speak to a variety of origins or projects etc.
const App = (): JSX.Element => {
return (



)
}
`

Please note, client instances should always be cached wherever possible since they contain all of the state necessary for maintaining and polling watches.

$3

The useReadByFilter hook can be used to make a server side query using a haystack filter.

`tsx
export const GridTable: React.FC = ({filter}) => {
const { grid, isLoading, error } = useReadByFilter(filter)

if (isLoading) {
return

Loading...

}

if (error) {
return

Error: {error.message}

}

return (

{grid.getRows().map(
(row: HDict): JSX.Element => {
return (
key={String(row.get('id')?.value)}
row={row}>
)
}
)}


)
}
`

$3

The useReadByIds hook can be used to make a server side query using record ids.

`tsx
export const GridTable: React.FC = () => {
const { grid, isLoading, error } = useReadByIds([
'@p:demo:r:1eeb15a7-30c88cec',
'@p:demo:r:1eeb1258-8b832ad0',
])

if (isLoading) {
return

Loading...

}

if (error) {
return

Error: {error.message}

}

return (

{grid.getRows().map(
(row: HDict): JSX.Element => {
return (
key={String(row.get('id')?.value)}
row={row}>
)
}
)}


)
}
`

$3

The useEval hook can be used to make server side expression evaluation.

`tsx
export const GridTable: React.FC = ({expr}) => {
const { grid, isLoading, error } = useEval(expr)

if (isLoading) {
return

Loading...

}

if (error) {
return

Error: {error.message}

}

return (

{grid.getRows().map(
(row: HDict): JSX.Element => {
return (
key={String(row.get('id')?.value)}
row={row}>
)
}
)}


)
}
`

$3

This hook is extremely powerful. It handles all of the opening, closing and polling of a watch. All a developer needs to do is specify what live data needs to be watched.

The useWatch hook is used to query and track live data.

- The hook will cause the UI to be updated automatically when new data is retrieved in the watch.
- The watch is automatically closed when the React component is unmounted.
- Watches are smartly collated and polled — additional watches do not make additional poll requests.
- A haystack filter or array of ids can be used to query and watch the live data.

`tsx
export const GridTable: React.FC = () => {
const { grid, isLoading, error } = useWatch({
filter: 'point and curVal',
pollRate: 1,
// or
// ids: ['@p:demo:r:1eeb15a7-30c88cec', '@p:demo:r:1eeb1258-8b832ad0'],
})

if (isLoading) {
return

Loading...

}

if (error) {
return

Error: {error.message}

}

return (

{grid.getRows().map(
(row: HDict): JSX.Element => {
return (
key={String(row.get('id')?.value)}
row={row}>
)
}
)}


)
}
`

$3

This hook allows using the value of a point from an haystack server as a react component state.

- The hook leverages useWatch to retrieve a point live updated data.
- The hook will cause the UI to be updated automatically when an updated value is retrieved.

`tsx
export const SetpointIncrementer: React.FC = () => {
// One-shot reading the first point that matches the filter
const point = useReadByFilter('point and temp and zone and sp').grid[0]

// Using the point
const [pointValue, setPointValue, updatedPoint] = useHaystackPoint(
point
)

return (



)
}
`

$3

This hook allows using the value of a record tag from an haystack server as a react component state.

- The hook leverages useWatch to retrieve the record live updated data.
- The hook will cause the UI to be updated automatically when an updated value is retrieved.

`tsx
export const SetpointPrecisionIncrementer: React.FC = () => {
// One-shot reading the first record that matches the filter
const record = useReadByFilter(
'precision and point and temp and zone and sp'
).grid[0]

// Using its tag
const [precision, setPrecision, updatedRecord] = useHaystackRecordTag(
record,
'precision'
)

return (



)
}
`

$3

This hook allows using a value from an haystack server as a react component state.
This hook should be used when input flexibility is required.
It is meant to abstract how data is actually retrieved/polled/written, enabling at the same time a data driven approach.

It takes a ResolvableDict that contains the record data and a meta tag that indicates how to interact with that record to poll and write an HVal.

Currently a ResolvableDict can indicate one of two resolveType values:

- "point": means that the ResolvableDict passed contains a point data and that the value that needs to be polled and written is the point value.
- "tag": means that the ResolvableDict passed contains a record data and the value that needs to be polled and written is the value of the tag indicated respectively in the "readTag" and "writeTag" tags of the meta dict.

Additional options such as the watch poll interval can be indicated directly inside the ResolvableDict meta.

- The hook leverages useWatch to retrieve the live updated data.
- The hook will cause the UI to be updated automatically when an updated value is retrieved.

`tsx
export const SetpointIncrementer: React.FC = () => {
// One-shot reading the first point that matches the filter
const [point] = useReadByFilter('point and temp and zone and sp').grid

//Adding meta data to the dict (note that this could have already been done server side)
const resolvableDict1 = point
?.newCopy()
.set('meta', { resolveType: 'point' }) as Resolvable

const resolvableDict2 = point?.newCopy().set('meta', {
resolveType: 'tag',
readTag: 'precision',
}) as Resolvable

// The actual state used depends on the metadata in the dict:
const [pointValue, setPointValue] = useResolveHaystackValue(
resolvableDict1
)
const [pointPrecision, setPointPrecision] = useResolveHaystackValue(
resolvableDict2
)

return (



)
}
``