@j2inn/haystack-react

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>
	)
}