WithEndpoint

This Hook allows for the creation of interactive GUI elements (such as buttons) that automatically connect to an Odin Control endpoint. It can handle events automatically to send specified data (as a PUT request) to that specified adapter, to a specific path.

Use of this hook creates a new, custom element (a Higher Order Component), that can then be used multiple times as required, with different endpoints and paths for each iteration if required.

Warning

Do not create the new component within a React component. Creation of WithEndpoint wrapped components should be done outside of the component itself, at the same level as the import statements

Note

In most projects, this will be used with a Bootstrap Button, Form.Control or DropdownButton, but any other component with a value property and some sort of event handling (such as onClick or onSelect) should work. If a custom component is created that needs to be wrapped by this hook, ensure these properties, at minimum, are present.

If the component is a textbox or other such input, and uses the enter event_type (which is the default), then the background colour of that component will be changed when the value within that component does not match the value of it's parameter within the Endpoint, to highlight to a user that a change has been made that has not been submitted.

If the value of the parameter within the endpoint is changed by other means (for instance, some other input modified it, or a periodically updating Endpoint changes it), then the displayed value of that component will also update, unless the user has modified the value so that it already didn't match the Endpoint.

The component will perform rudimentary validation before submitting a value to the Adapter, checking any available metadata to ensure that the value is of the expected type, and is not outside of any permitted value. Should this validation fail, the component will throw an error and will not perform the HTTP PUT request.

Properties

Important

Because the hook creates an element, the properties listed below should be passed to the instance of the element, rather than to the initial hook. Any properties passed to the instance that are not listed below will be passed through to the underlying component, allowing them to function as originally intended.

import { WithEndpoint } from 'odin-react';

Name	Type	Default	Description
endpoint	AdapterEndpoint		Required the AdapterEndpoint object that the component should use for the HTTP requests.
fullpath	string		Required the path to the value on the Adapter's param tree to read/write.
value	JSON		If specified, the component will send this value on PUT requests rather than any value from the component itself. If not specified, the value defaults to the value from the Endpoint, until the user makes any changes.
event_type	"select" | "click" | "enter"	"enter"	Sets the behaviour of the component, specifying what kind of event will trigger a PUT request. enter: triggers on a keyPress event for the Enter key (if the shift key was not also held) select: triggers on a onSelect event. Mainly for dropdown menus. click: triggers on an onClick event. Useful for buttons and other clickable Components.
min	number		Sets the minimum value permitted, assuming the value is a number. If not specified, the component will default to either the metadata's minimum value, or will not set a limit.
max	number		Sets the maximum value permitted, assuming the value is a number. If not specified, the component will default to either the metadata's maximum value, or will not set a limit.
disabled	boolean		if specified, will disable the component when this value is true. If not specified, the component will disable itself when the Endpoint is awaiting a response or if the metadata has set the value as ReadOnly.
pre_method	Function		If set, the component will run this function prior to sending the PUT request.
pre_args	Array<Any>		The arguments to pass to the pre_method, should any be required.
post_method	Function		If set, the component will run this function after receiving a response from the PUT request and merging that data into the Endpoint's local data object.
post_args	Array<Any>		The arguments to pass to the post_method, should any be required.
dif_color	CSSProperties.backgroundColor	"var(--bs-highlight-bg)"	The colour to highlight a textbox or other component using the "enter" event_type when the value displayed by the component is different to the one the Endpoint has for the same parameter. Used to highlight when a user has changed a value in a component, but not yet submitted that change to the Adapter.

Example

//create the component at the top level of the file, in the same scope as any import statements.
const EndpointButton = WithEndpoint(Button);
const EndpointInput = WithEndpoint(Form.Control);

...

export const ExamplePage = () => {

return (
    <EndpointButton endpoint={exampleEndpoint} event_type="click" fullpath="test" value={42}>
        Trigger
    </EndpointButton>
    //note the "type" property is not one specified, and so gets passed down to the internal component. In this instance, it is there to tell the input component what kind of input it is.
    <EndpointInput endpoint={exampleEndpoint} fullpath="values/number" type="number"/>
)

}