@alekna/react-data-browser v1.1.11
The problem
It's time consuming to build your own table functionality when you want something unique or have more specific use case than table components that already exist.
This solution
DataBrowser component will provide common functionalities like checkbox, client side sorting, filtering, visible / offset columns and much more for your individual table components...
NOTE: The original use case of this component is to build flexbox tables, however the API is powerful and flexible enough to build things like grids as well.
Table of Contents
Installation
This module is distributed via npm which is bundled with node and
should be installed as one of your project's dependencies:
npm install --save @alekna/react-data-browserThis package also depends on
reactandprop-types. Please make sure you have those installed as well.
Usage
NOTE: DataBrowser component will not provide any styles, only the functionality. Styles used in the examples are only for better visualization for what could be achieved using this component.
import React from 'react';
import { render } from 'react-dom';
import DataBrowser from 'react-data-browser';
render(
<DataBrowser columns={[]}>{() => <div />}</DataBrowser>,
document.getElementById('root'),
);This package exposes <DataBrowser />, withDataBrowser() components and getObjectPropertyByString() function.
<DataBrowser /> doesn't render anything itself, it just calls the render function and renders that "Use a render prop!"!
<DataBrowser>{props => <div>/* your JSX here! */</div>}</DataBrowser>.
getObjectPropertyByString() is a function that helps to access nested properties on an object by string.
Usage: getObjectPropertyByString(object, 'object.property.that.you.want.to.access')
Basic Props
This is the list of props that you should know about. There are some advanced props below as well.
children
function({})| required
This is called with an object. Read more about the properties of this object in the section "Children Function".
initialSort
Object<{ dir: string, sortField: string }>optional
sets an initial sort order.
columns
Array<{ label: string, sortField: string, isLocked: boolean }>| required
Accepts an array of objects with any values you need + 3 values that are used by the component. label key will hold the label for the field, sortField will have to match data key name that you want to display from remote source. isLocked key will add isLocked props to the visibleColumns.
viewsAvailable
Array<string>| optional | defaults to 'LIST_VIEW', 'GRID_VIEW'
you can provide available views to your component and you will be able to toggle them later.
totalItems
number | optional
totalItems is required if you have a sorting functionality on your table. It will help for the selectAllCheckbox to determin weather all items are selected or not.
initialChecked
Array<string>| optional
Takes in an array of ids if you need to set initial checkedItems items.
initialColumnFlex
Array<>| optional | defaults to '0 0 25%', '1 1 35%', '0 0 20%', '0 0 20%'
columnFlex has a default layout, if you'd like to overwrite it you can provide initialColumnFlex with an array of flex values you required or an array of arrays with flex values.
stateReducer
function(state: object, changes: object)| optional
🚨 This is a really handy power feature 🚨
This function will be called each time react-data-browser sets its internal state
(or calls your onStateChange handler for control props). It allows you to
modify the state change that will take place which can give you fine grain
control over how the component interacts with user updates without having to
use Control Props. It gives you the current state and the
state that will be set, and you return the state that you want to set.
state: The full current state of react-data-browser.changes: These are the properties that are about to change. This also has atypeproperty which you can learn more about in thestateChangeTypessection.
const ui = (
<DataBrowser stateReducer={stateReducer}>{/* your callback */}</DataBrowser>
);
function stateReducer(state, changes) {
switch (changes.type) {
default:
return changes;
}
}Advanced Props
visibleColumns
Array<string>| defaults to generated visibleColumns
viewType
string| defaults to 'LIST_VIEW'
selectAllCheckboxState
boolean| defaults to false
currentSort
object| defaults to currentSort: { dir: '', sortField: '' }
checkedItems
Array<>| control prop
state that holds selected item ids
viewsAvailable
Array<>| defaults to internal implementation
switchViewType
function(props: object)| defaults to internal implementation
accepts view type string from viewsAvailable controlled prop
switchColumns
function(props: object)| defaults to internal implementation
will accept an object with params from and to. Providing sortFields columns will be replaced from - to.
checkboxState
function(props: string)| defaults to internal implementation
will check weather item is checkedItems or not. Returns boolean
offsetColumns
function()| defaults to internal implementation
will return offset columns with additional prop 'visible' if that column is already displayed.
checkboxToggle
function(props: string)| defaults to internal implementation
will accept item id and toggle the checkbox for that item
onSelection
function(props: object)| defaults to internal implementation
function for 'select all checkbox'.
toggleSort
function(props: object)| defaults to internal implementation
takes in sortField and toggles asc | dsc on it
changeSortDirection
function(props: object)| defaults to internal implementation
changes sort direction, will accept an object with {dir: string}
defaultSortMethod
function()| defaults to internal implementation
default sort method for client side sort implementation
sortData
function()| defaults to internal implementation
will accept sortField and dir
onStateChange
function(changes: object, stateAndHelpers: object)| optional, no useful default
This function is called anytime the internal state changes. This can be useful if you're using react-data-browser as a "controlled" component, where you manage some or all of the state and then pass it as props, rather than letting react-data-browser control all its state itself. The parameters both take the shape of internal state but differ slightly.
changes: These are the properties that actually have changed since the last state change. This also has atypeproperty which you can learn more about in thestateChangeTypessection.stateAndHelpers: This is the exact same thing yourchildrenfunction is called with (see Children Function)
Tip: This function will be called any time any state is changed. The best way to determine whether any particular state was changed, you can use
changes.hasOwnProperty('propName').
class App extends React.Component {
state = { rows: [] };
onStateChange = (action, { defaultSortMethod }) => {
if (action.type === '__sort_data__') {
this.setState(state => ({
rows: sort(defaultSortMethod, state.rows),
}));
}
};
render() {
<DataBrowser onStateChange={this.onStateChange}>
{/* your callback */}
</DataBrowser>;
}
}stateChangeTypes
There are a few props that expose changes to state
(onStateChange and stateReducer).
For you to make the most of these APIs, it's important for you to understand
why state is being changed. To accomplish this, there's a type property on the
changes object you get. This type corresponds to a
DataBrowser.stateChangeTypes property. If you want to see what change types
are available, run this in your app:
console.log(Object.keys(DataBrowser.stateChangeTypes));Children Function
This is where you render whatever you want to based on the state of react-data-browser.
You use it like so:
const ui = (
<DataBrowser>{props => <div>{/* more jsx here */}</div>}</DataBrowser>
);LICENSE
MIT