@j2inn/haystack-react v2.0.6
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-client. and haystack-core.
Installation
The haystack-core and haystack-client libraries need to be installed as peer dependencies. Therefore to get started using this library in your project, run the following command...
npm install @j2inn/haystack-core @j2inn/haystack-client @j2inn/haystack-react
If you want to use units then install haystack-units as well...
npm install @j2inn/haystack-core @j2inn/haystack-units @j2inn/haystack-client @j2inn/haystack-react
Design
Hooks
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
Client Context
In haystack-client 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...
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 (
<ClientContext.Provider value={client}>
<MyFancyUi/>
</ClientContext.Provider>
)
}
The client object needs to be set up slightly differently for FINx...
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 (
<ClientContext.Provider value={client}>
<MyFancyUi/>
</ClientContext.Provider>
)
}
Please note, client instances should always be cached wherever possible since they contain all of the state necessary for maintaining and polling watches.
useReadByFilter
The useReadByFilter
hook can be used to make a server side query using a haystack filter.
export const GridTable: React.FC<filter: string}> = ({filter}) => {
const { grid, isLoading, error } = useReadByFilter(filter)
if (isLoading) {
return <h1>Loading...</h1>
}
if (error) {
return <h1>Error: {error.message}</h1>
}
return (
<table>
<thead>
<tr>
<Header key='id' name='id' displayName='Id' />
<Header key='navName' name='navName' displayName='Name' />
<Header key='curVal' name='curVal' displayName='Value' />
</tr>
</thead>
<tbody>
{grid.getRows().map(
(row: HDict): JSX.Element => {
return (
<Row
key={String(row.get<HRef>('id')?.value)}
row={row}></Row>
)
}
)}
</tbody>
</table>
)
}
useReadByIds
The useReadByIds
hook can be used to make a server side query using record ids.
export const GridTable: React.FC = () => {
const { grid, isLoading, error } = useReadByIds([
'@p:demo:r:1eeb15a7-30c88cec',
'@p:demo:r:1eeb1258-8b832ad0',
])
if (isLoading) {
return <h1>Loading...</h1>
}
if (error) {
return <h1>Error: {error.message}</h1>
}
return (
<table>
<thead>
<tr>
<Header key='id' name='id' displayName='Id' />
<Header key='navName' name='navName' displayName='Name' />
<Header key='curVal' name='curVal' displayName='Value' />
</tr>
</thead>
<tbody>
{grid.getRows().map(
(row: HDict): JSX.Element => {
return (
<Row
key={String(row.get<HRef>('id')?.value)}
row={row}></Row>
)
}
)}
</tbody>
</table>
)
}
useEval
The useEval
hook can be used to make server side expression evaluation.
export const GridTable: React.FC<expr: string}> = ({expr}) => {
const { grid, isLoading, error } = useEval(expr)
if (isLoading) {
return <h1>Loading...</h1>
}
if (error) {
return <h1>Error: {error.message}</h1>
}
return (
<table>
<thead>
<tr>
<Header key='id' name='id' displayName='Id' />
<Header key='navName' name='navName' displayName='Name' />
<Header key='curVal' name='curVal' displayName='Value' />
</tr>
</thead>
<tbody>
{grid.getRows().map(
(row: HDict): JSX.Element => {
return (
<Row
key={String(row.get<HRef>('id')?.value)}
row={row}></Row>
)
}
)}
</tbody>
</table>
)
}
useWatch
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.
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 <h1>Loading...</h1>
}
if (error) {
return <h1>Error: {error.message}</h1>
}
return (
<table>
<thead>
<tr>
<Header key='id' name='id' displayName='Id' />
<Header key='navName' name='navName' displayName='Name' />
<Header key='curVal' name='curVal' displayName='Value' />
</tr>
</thead>
<tbody>
{grid.getRows().map(
(row: HDict): JSX.Element => {
return (
<Row
key={String(row.get<HRef>('id')?.value)}
row={row}></Row>
)
}
)}
</tbody>
</table>
)
}
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago