Hooks to connect React components to Appframe data objects
npm install @olenbetong/appframe-reactsh
npm install @olenbetong/appframe-react
`
or include the IIFE build in a script
`html
`
Data object context
This package includes a data object context that is useful for binding form
elements and buttons to the current row of the data object.
`
`
The following hooks use the data object from context:
- useDataObject - Returns the data object in context
- useCancelButton - Returns a cancelEdit function used to revert the current
row to saved values
- useDeleteButton - Returns a deleteRow function to delete the current row
(or row at an index given as the first parameter). Will prompt the user with
window.confirm before deleting. Also returns an isDeleting boolean.
- useField(fieldName) - Returns an object with everything needed to bind
form controls to the current row of the data object:
- dataObject: The data object to bind to
- error: Any validation errors when trying to update the record
- value: Current value of the input (if there is en error, the faulty value is
still returned)
- onKeyDown: Keydown event handler that cancels changes when Escape is pressed
- setValue: Function to set the value of the field on the current row
- onChange: For simple components, this property can be passed directly to the
component
- record: The current record
- reset: Cancels changes, and removes any errors
- useRefreshButton - Returns a method to refresh the data object, and a
loading boolean
- useRefreshRowButton - Returns a method to refresh the current row of the
data object, and a loading indicator
- useSaveButton - Returns a method to save changes on the current row of the
data object, and dirty and isSaving booleans
Other hooks
- useCurrentIndex(dataObject) - Returns only the current index
- useCurrentField(dataObject, field) - Returns the value of a field on the
current record. Only re-renders when that field changes
- useCurrentRow(dataObject) - Returns the current record
- useData(dataObject, options) - Returns an array with all records currently
in the data object. If a filter is provided in the options, the data object
will refresh with that filter applied.
- useDataLength(dataObject) - Returns the current number of records in the
data object
- useDataWithFilter(dataObject, filter, type) - Wrapper around useData
kept for backwards compatibility.
- useDirty(dataObject) - Returns a boolean indicating if the current row is
dirty or not
- useError(dataObject) - Returns any loading error message
- useFilter(dataObject, filter, type) - Refreshes data object whenever the
filter changes
- useLoading(dataObject) - Returns a boolean indicating if the data object
is loading or not
- useStatus(dataObject) - Returns booleans indicating if the data object is
saving or deleting records
- usePaging(dataObject) - Returns page, page count and a method to change
the page
- useParameter(dataObject, parameter) - Returns the current value of
parameter
- usePermissions(dataObject) - Returns booleans indicating if the user can
delete, insert or update records
- useDragAndDropUpload({ dataObject }) - Returns drag and drop event
handlers needed to automatically upload files to the data object when dropped
on the element
The above hooks uses the data objects internal state to pass data to the
components. If you do not want to depend on the data objects current row or data
storage, you can use the following hooks. They return data from the data
object's data handler directly, and will not affect the data objects internal
state.
- useFetchData(dataObject, filter) - Returns data matching the filter. If
the filter is set to , data will not be loaded.
- useFetchRecord(dataObject, filter) (alias: useFetchSingle) - Use if the
filter is expected to only return a single row. If multiple rows are returned
from the server, only the first record will be returned to the component.
One hook is also available for procedures.
- useProcedure(procedure, parameters, options) - Returns an object
containing data, execute, isExecuting and error properties. Executes
whenever the procedure or parameters arguments change. execute can be used
to manually execute the procedure again
$3
useData accepts a second options argument. Available options are:
- includeDirty (default true) - Includes currently dirty data in the
dataset. Disable this to optimize if the data is used many places.
$3
#### Getting all state from the data object
This will list all reacords in the data object, and create an editor for the
current row.
`jsx
import {
useCurrentIndex,
useCurrentField,
useCurrentRow,
useData,
useDataLength,
useDirty,
useError,
useLoading,
useStatus,
usePermissions,
useParameter,
} from "@olenbetong/appframe-react";
function MyFunctionComponent(props) {
const currentIndex = useCurrentIndex(dsMyDataObject);
const myRecord = useCurrentRow(dsMyDataObject);
const myField = useCurrentField(dsMyDataObject, "Name");
const myRecords = useData(dsMyDataObject);
const count = useDataLength(dsMyDataObject);
const isDirty = useDirty(dsMyDataObject);
const error = useError(dsMyDataObject);
const isLoading = useLoading(dsMyDataObject);
const { isDeleting, isSaving } = useStatus(dsMyDataObject);
const { allowDelete, allowInsert, allowUpdate } = usePermissions(dsMyDataObject);
const filter = useParameter(dsMyDataObject, "filterString");
return (
{isLoading && }
{error &&
{myRecords.map((record) => (
))}
There are {count} records matching {filter}
);
}
`
Automatically getting data with a given filter.
If you want to conditionally load data, you may set the filter to false.
`jsx
import { useDataWithFilter, useLoading } from "@olenbetong/appframe-react";
function MyComponent({ someId }) {
const isLoading = useLoading(dsMyDataObject);
const data = useDataWithFilter(dsMyDataObject, [SomeID] = ${someId});
return (
{isLoading && }
{data.map((record) => (
))}
);
}
`
#### Getting data from the data source without affecting the data object
If you want to conditionally load data, you may set the filter to false.
The refreshRows method can be used to update only a subset of the current data.
The first parameter is the filter that will be used to fetch data. The second
parameter is the field that will be used to compare fetched data with current
data (defaults to PrimKey). If the refreshRows fetches records that are not in
the current set, they will not be added.
`jsx
import { useFetchData, useFetchRecord } from "@olenbetong/appframe-react";
function MyFunctionComponent(props) {
const { loading, data, refresh, refreshRows } = useFetchData(
dsMyDataObject,
[EntityCategory] = 1,
);
return (
{loading && }
{data.map((item) => (
onRefresh={() => refreshRows([PrimKey] = '${item.PrimKey}')}
/>
))}
);
}
function MyRecordComponent(props) {
const { loading, record, refresh } = useFetchRecord(
dsMyDataObject,
[EntityID] = ${props.id},
);
return (
{loading &&
);
}
`
#### Executing a stored procedure
If 'Parameter', 'OtherParam', 'ThirdParam' are not valid parameters for
'procMyProcedure', they will be removed before executing the procedure. This way
the procedure can be executed even if the actual parameters haven't changed. If
'removeInvalidParameters' isn't set to true, an error will occur instead.
`jsx
import { useProcedure } from "@olenbetong/appframe-react";
function MyComponent() {
const { data, execute, error, isExecuting } = useProcedure(
procMyProcedure,
{
Parameter: "value",
OtherParam: 52,
ThirdParam: "Oh, hai!",
},
{ removeInvalidParameters: true }
);
return (
{error && {error}}
{isExecuting &&
{data && data.length > 0 && data[0].map((record) =>
);
}
`
#### Paging component
`jsx
import { usePaging } from "@olenbetong/appframe-react";
function PagingComponent() {
const { changePage, page, pagecount } = usePaging(dsMyDataObject);
return (
Page {page + 1} of {pageCount}
);
}
``