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
• Usage
• Basic Props
  • children
  • initialSort
  • columns
  • viewsAvailable
  • totalItems
  • initialChecked
  • initialColumnFlex
  • stateReducer
• Advanced Props
  • visibleColumns
  • viewType
  • selectAllCheckboxState
  • currentSort
  • checkedItems
  • viewsAvailable
  • switchViewType
  • switchColumns
  • checkboxState
  • offsetColumns
  • checkboxToggle
  • onSelection
  • toggleSort
  • changeSortDirection
  • defaultSortMethod
  • sortData
  • onStateChange
• stateChangeTypes
• Children Function
• LICENSE

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 react-data-browser

This package also depends on react and prop-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.

Try it out in the browser

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 a type property which you can learn more about in the stateChangeTypes section.

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 a type property which you can learn more about in the stateChangeTypes section.
• stateAndHelpers: This is the exact same thing your children function 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