|
| 1 | +# react-edit - Inline editing utilities for React |
| 2 | + |
| 3 | +`react-edit` provides a set of inline editing related utilities for React. The library comes with a couple of basic editors and you can implement your own as long as you follow the same interface (`value`, `onValue` props). |
| 4 | + |
| 5 | +## API |
| 6 | + |
| 7 | +The `edit` transform has been designed to allow inline editing. It expects you to define how to manipulate the state. it also expects you to pass an editor. |
| 8 | + |
| 9 | +**Example:** |
| 10 | + |
| 11 | +```jsx |
| 12 | +... |
| 13 | +import cloneDeep from 'lodash/cloneDeep'; |
| 14 | +import findIndex from 'lodash/findIndex'; |
| 15 | +import * as edit from 'react-edit'; |
| 16 | + |
| 17 | +... |
| 18 | + |
| 19 | +// Define how to manipulate rows through edit. |
| 20 | +const editable = edit.edit({ |
| 21 | + // Determine whether the current cell is being edited or not. |
| 22 | + isEditing: ({ columnIndex, rowData }) => columnIndex === rowData.editing, |
| 23 | + |
| 24 | + // The user requested activation, mark the current cell as edited. |
| 25 | + // IMPORTANT! If you stash the rows at this.state.rows, DON'T |
| 26 | + // mutate it as that will break Table.Body optimization check. |
| 27 | + // |
| 28 | + // You also have access to `event` here. |
| 29 | + onActivate: ({ columnIndex, rowData, event }) => { |
| 30 | + event.stopPropagation(); |
| 31 | + |
| 32 | + const index = findIndex(this.state.rows, { id: rowData.id }); |
| 33 | + const rows = cloneDeep(this.state.rows); |
| 34 | + |
| 35 | + rows[index].editing = columnIndex; |
| 36 | + |
| 37 | + this.setState({ rows }); |
| 38 | + }, |
| 39 | + |
| 40 | + // Capture the value when the user has finished and update |
| 41 | + // application state. |
| 42 | + onValue: ({ value, rowData, property }) => { |
| 43 | + const index = findIndex(this.state.rows, { id: rowData.id }); |
| 44 | + const rows = cloneDeep(this.state.rows); |
| 45 | + |
| 46 | + rows[index][property] = value; |
| 47 | + rows[index].editing = false; |
| 48 | + |
| 49 | + this.setState({ rows }); |
| 50 | + }, |
| 51 | + |
| 52 | + // It's possible to shape the value passed to the editor. See |
| 53 | + // the Excel example for a concrete example. |
| 54 | + // getEditedValue: v => v.value |
| 55 | + |
| 56 | + // If you want to change default value/onValue, you can do it through |
| 57 | + // editingProps: { value: 'value', onValue: 'onValue' } |
| 58 | + |
| 59 | + // In case you want to trigger activation using something else than |
| 60 | + // onClick, adjust it like this: |
| 61 | + // activateEvent: 'onDoubleClick' |
| 62 | +}); |
| 63 | + |
| 64 | +... |
| 65 | + |
| 66 | +// Wrap within an element and render. |
| 67 | +React.createElement('div', editable(edit.input())( |
| 68 | + value, { columnIndex, rowData }, { ... custom props ... } |
| 69 | +), (value, extraParameters, props) => ({ |
| 70 | + children: <div>{value}</div> |
| 71 | +})); |
| 72 | + |
| 73 | +// Or in JSX |
| 74 | +<div {...editable(edit.input())(...)} /> |
| 75 | +``` |
| 76 | + |
| 77 | +## Editing Interface |
| 78 | + |
| 79 | +An editor should follow the following interface: |
| 80 | + |
| 81 | +* `({ value, onValue, extraParameters }) => <React element>` |
| 82 | + |
| 83 | +It will receive the current `value` and is expected to emit the result through `onValue` upon completion. You can capture row data, property name, and such through `extraParameters`. |
| 84 | + |
| 85 | +## Editors |
| 86 | + |
| 87 | +`react-edit` provides a few editors by default: |
| 88 | + |
| 89 | +* `edit.boolean({ props: <props> })` - If the initial value is true, allows setting to false and vice versa. Demo value defaults to false always |
| 90 | +* `edit.dropdown({ options: [[<value>, <name>]], props: <props> })` - The dropdown expects an array of value-name object pairs and emits the selected one. |
| 91 | +* `edit.input({ props: <props> })` - A wrapper for a regular input. |
| 92 | + |
| 93 | +## Writing a Custom Editor |
| 94 | + |
| 95 | +If you want to implement a custom editor, you should accept `value` and `onValue` prop pair. The former will contain the current value and `onValue` should return a new one. It can be convenient to curry your editor so that you can pass custom `props` to it easily. Consider the following example. |
| 96 | + |
| 97 | +```jsx |
| 98 | +/* |
| 99 | +import React from 'react'; |
| 100 | +*/ |
| 101 | + |
| 102 | +const boolean = ({ props } = {}) => { |
| 103 | + const Boolean = ({ value, onValue }) => ( |
| 104 | + <div {...props}> |
| 105 | + <button |
| 106 | + disabled={value} |
| 107 | + onClick={() => onValue(true)} |
| 108 | + >✓ |
| 109 | + </button> |
| 110 | + <button |
| 111 | + disabled={!value} |
| 112 | + onClick={() => onValue(false)} |
| 113 | + >✗ |
| 114 | + </button> |
| 115 | + </div> |
| 116 | + ); |
| 117 | + Boolean.propTypes = { |
| 118 | + value: React.PropTypes.any, |
| 119 | + onClick: React.PropTypes.func, |
| 120 | + onValue: React.PropTypes.func |
| 121 | + }; |
| 122 | + |
| 123 | + return Boolean; |
| 124 | +}; |
| 125 | + |
| 126 | +const Boolean = boolean({ style: { |
| 127 | + backgroundColor: '#ddd' |
| 128 | +}}); |
| 129 | + |
| 130 | +<Boolean value onValue={v => alert(`You chose ${v}`)} /> |
| 131 | +``` |
| 132 | + |
| 133 | +## License |
| 134 | + |
| 135 | +MIT. See LICENSE for details. |
| 136 | + |
0 commit comments