# @onaio/drill-down-table > DrillDownTable Latest version **1.0.6** (published 2021-05-12) · Apache-2.0 license · 0 weekly downloads ## Install ```sh npm install @onaio/drill-down-table pnpm add @onaio/drill-down-table yarn add @onaio/drill-down-table bun add @onaio/drill-down-table ``` ## Health **Score 20/100 (F)** — status: abandoned. Positive: has types; no vulnerabilities. Warnings: low downloads; no esm support. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 1.0.6 | | Published | 2021-05-12 | | First published | 2019-03-13 | | Weekly downloads | 0 | | License | Apache-2.0 | | TypeScript types | bundled | | Module format | CommonJS | | Dependencies | 2 | | Unpacked size | 62.9 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 11 | | Author | Ona Engineering | | Maintainers | onaio | ## Links - npm: https://www.npmjs.com/package/@onaio/drill-down-table - Repository: https://github.com/onaio/js-tools - Homepage: https://github.com/onaio/js-tools#readme - Issues: https://github.com/onaio/js-tools/issues - npm.io page: https://npm.io/package/@onaio/drill-down-table ## Dependencies (2) - [reactstrap](https://npm.io/package/reactstrap.md) ^8.4.1 - [react-table](https://npm.io/package/react-table.md) ^7.0.6 ## Recent versions - 1.0.6 (latest) — 2021-05-12 - 1.0.5 — 2021-01-07 - 1.0.4 — 2020-09-15 - 1.0.3 — 2020-08-20 - 1.0.2 — 2020-06-17 - 1.0.1 — 2020-06-05 - 0.0.21 — 2019-09-24 - 0.0.20 — 2019-07-17 - 0.0.17 — 2019-04-11 - 0.0.16 — 2019-03-29 - 0.0.11 — 2019-03-21 - 0.0.10 — 2019-03-21 - 0.0.9 — 2019-03-18 - 0.0.8 — 2019-03-18 - 0.0.7 — 2019-03-18 - … 4 more at https://npm.io/package/@onaio/drill-down-table/versions ## README # DrillDownTable DrillDownTable is a bootstrap-based [higher order component](https://reactjs.org/docs/higher-order-components.html) that works with [React Table](https://github.com/tannerlinsley/react-table). It makes use of the following hooks from react-table: - useSortBy - usePagination - useResizeColumns - useFlexLayout ## Installation ```sh yarn add @onaio/drill-down-table ``` You can opt to use the default styles by adding this to your component's file ```ts import '@onaio/drill-down-table/dist/table.css'; ``` ## Displaying Hierarchical Data DrillDownTable was made to let you easily display hierarchically structured data in nice tables that allow you to drill down through the hierarchical levels of the data. ### Data structure We expect the hierarchical data to be structured as expected in the [adjacency list model](https://en.wikipedia.org/wiki/Adjacency_list). i.e. each record in the data will have a pointer to its parent, like so: ```sh id | parent_id | name ------+-----------+---------------- 3954 | | Siavonga 2939 | | Chadiza 2962 | 2939 | Sinalo 2957 | 3954 | Mkumbuzi 2946 | 2962 | SNL_1 2958 | 2962 | SNL_2 2956 | 2962 | SNL_3 2959 | 2957 | MKU_1 2951 | 2957 | MKU_2 2950 | 2939 | Chanida Border 2947 | 2939 | Chanjobwe ``` Of course in javascript this same data will be represented as a list of objects, something like: ```js data = [ { id: 1, name: 'District A', parent_id: null, spray_coverage: '80%', spray_effectiveness: '80%' }, { id: 4, name: 'HFC 1', parent_id: 1, spray_coverage: '70%', spray_effectiveness: '90%' } ]; ``` ### WithHeaders As you know, you absolutely need to define `columns` when working with React Table. DrillDownTable includes a `columnsFromObject` util that can be used to create columns from your objects ### The props These are: #### columns && data _Required_ these 2 props should be structured as defined by react-table. #### identifierField _Optional_(`string` = `id`) Which field in the data represents the unique identifier for a row of data? This is optional, but if you do not define it then the default is set to `id`. #### parentIdentifierField _Optional_(`string` = `parent_id`) Which field in the data represents the unique identifier of the parent of a row of data? This is optional, but if you do not define it then the default is set to `parent_id`. #### rootParentId This defines the value of the `parentIdentifierField` on the highest hierarchy level of your data. This is commonly something like `null` or `''` or `0`. Basically it defines the first hierarchical level that you want to show on your `DrillDownTable`. This is also optional and defaults to `null`. #### linkerField _Optional_(`string` | `undefined` = `undefined`) When the table is rendered, you can click anywhere on a row to drill down to the next level of the hierarchy. However, you may want to display some kind of indication that it is possible to drill down on a row of data. The `linkerField` prop allows you to define which field should have this indicator. By default this is set to the `id` field. #### CellComponent This is a component responsible for rendering the cell in which the `linkerField` (above) is found. By default it just adds a caret to show if you can drill down on a row of data or not. However you can supply your own component that renders whatever else you may want - for example instead of a caret you may want to show a link. Have a look at [`DropDownCell`](src/helpers/DropDownCell.tsx) for an example of how this component might look at. #### extraCellProps This is an object that represents extra props to be given to the `CellComponent` (above). #### useDrillDown _Optional_(`boolean` = `true`) By default `DrillDownTable` allows you to click on any row to drill-down to the next hierarchical level of data. This is achieved by adding a custom onClick handler to the cells that render the linker field. To switch this off and have the table render as a normal table, set `useDrillDown` to `false`. #### renderInTopFilterBar _Optional_(`(prop) => ReactNode` | `undefined` = `undefined`) add a section immediately above table for filter components, through a render prop #### renderInBottomFilterBar _Optional_(`(prop) => ReactNode` | `undefined` = `undefined`) add a section immediately below table for filter components, through a render prop #### nullDataComponent _Optional_(`() => React.ReacNode` = ``) A renderProp that renders a custom component when data is an empty array. #### loading _Optional_(`boolean` = `false`) A boolean switch that makes the table render a custom #### loadingComponent _Optional_(`React.ElementType` = ``) A custom component that should be rendered when loading is true. #### getTdProps _optional_(`(cell: Cell) => Dictionary` | `undefined` = `undefined`) Use this to pass in a custom prop getter for the table cell elements. While the default for this is undefined, the table component does make use of a customTdProps getter that attaches a onClick handler that effects drilling down, This handler is only used when `useDrillDown = true` and `getTdProps` is undefined, otherwise if `getTdProps` is propped in then the component uses that as the click handler #### paginate _optional_(`boolean` = `true`) Tells the component if should paginate the data. setting this to false will have the component show all of its data as a single page. #### resize _optional_(`boolean` = `true`) Make table columns resizeable. #### hasChildren _Optional_ This is a function that returns a `boolean` indicating whether or not a row of data has children i.e. should you be able to drill down using the given row? A sample `hasChildren` function looks like so: ```ts export function hasChildrenFunc( cellObject: Cell, parentIdList: Array, idField: string | number = ID ) { return parentIdList.includes(cellObject.row.original[idField]); } ``` #### drillDownFilter **Optional** A custom function to override how the hierarchy is decided. ### Code examples Simplest example: ```tsx import { DrillDownTable, columnsFromObjects } from '@onaio/drill-down-table/'; const props = { columns: columnsFromObjects(data), data }; ; ``` Define `location` as the column where the drill-down caret will be displayed ```tsx import { DrillDownTable, columnsFromObjects } from '@onaio/drill-down-table/'; const props = { columns: columnsFromObjects(data), data, linkerField: 'location' }; ; ``` Supply columns as a prop. ```tsx import { DrillDownTable } from '@onaio/drill-down-table/'; const columns = [ { Header: 'Name', accessor: 'location' }, { Header: 'Spray Coverage', accessor: 'spray_coverage' } ]; const props = { columns, data, linkerField: 'location' }; ; ``` Turn off clicking on a row to drill-down i.e. . ```tsx import { DrillDownTable, columnsFromObjects } from '@onaio/drill-down-table/'; const props = { columns: columnsFromObjects(data), data, linkerField: 'location', useDrillDown: false }; ; ``` Use a custom `CellComponent` and `extraCellProps`. ```tsx interface NewCellComponentProps extends DropDownCellProps { urlPath: string; caret: string; } const NewCellComponent: React.ElementType = (props: NewCellComponentProps) => { const { cellValue, hasChildren, urlPath, caret } = props; return (
{hasChildren ? ( {cellValue} {caret} ) : ( cellValue )}
); }; const props = { columns: columnsFromObjects(data), CellComponent: NewCellComponent, data, extraCellProps: { urlPath: 'http://example.com', caret: + } }; ; ``` Use custom `hasChildren` ```tsx import { DrillDownTable, columnsFromObjects } from '@onaio/drill-down-table/'; const props = { columns: columnsFromObjects(data), data: data, hasChildren: (item, parents, idfield) => item.original[idfield] === 10 }; ; ``` Adding global filter components like pagination ```tsx // write the pagination component const CustomPagination = (props) => { return <>{/* pagination JSX */} } // create a render prop that takes the [TableInstance properties](https://github.com/tannerlinsley/react-table/blob/master/docs/api/useTable.md#instance-properties) adds custom properties and passes them to the CustomPagination component const customRenderInFilterBar = (tableProps: RenderFiltersInBarOptions) => { return (
{customRenderPagination(tableProps)}
); }; let props: Dictionary = { columns: columnsFromObjects(jurisdictions), data: jurisdictions, useDrillDown: true, renderInTopFilterBar: customRenderInFilterBar, linkerField: 'name', rootParentId: '', renderInBottomFilterBar: customRenderInFilterBar }; ); ``` --- _Source: https://npm.io/package/@onaio/drill-down-table · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._