Add documentation for TableList component

graylog2-web-interface/src/components/common/TableList.jsx

@@ -7,15 +7,49 @@ import { Col, ListGroup, ListGroupItem, Row } from 'react-bootstrap';
 import { Input } from 'components/bootstrap';
 import { TypeAheadDataFilter } from 'components/common';
 
+/**
+ * Component that renders a list of items in a table-like structure. The list
+ * also includes a filter input that can be used to search for specific
+ * items or elements matching a string.
+ *
+ * The component can render action elements for each item, and also for
+ * performing bulk-operation. In that second case, action elements will
+ * appear in the header once the user selects more than one item by clicking
+ * in the checkboxes next to them.
+ */
 const TableList = React.createClass({
   propTypes: {
+    /** Specifies key to use as item ID. */
     idKey: PropTypes.string,
+    /** Specifies a key to use as item title. */
     titleKey: PropTypes.string,
+    /** Specifies key to use as item description. */
     descriptionKey: PropTypes.string,
+    /** Object keys to use for filtering. Use an empty array to disable filtering. */
     filterKeys: PropTypes.arrayOf(PropTypes.string).isRequired,
+    /** Label to use next to the filter input. */
     filterLabel: PropTypes.string,
+    /**
+     * Immutable List of objects to display in the list. Objects are expected
+     * to have an ID (`idKey` prop), a title (`title` prop), and an optional
+     * description (`descriptionKey` prop).
+     */
     items: PropTypes.instanceOf(Immutable.List).isRequired,
+    /**
+     * Function that generates react elements to render in the header.
+     * Those elements are meant to display actions that affect more than one
+     * item in the list, so they will only be displayed when more than one
+     * item is checked.
+     * The function receives a list of IDs corresponding to all selected
+     * elements as argument.
+     */
     headerActionsFactory: PropTypes.func,
+    /**
+     * Function that generates react elements to render for each item.
+     * Those elements are meant to display actions that affect that specific
+     * item.
+     * The function will receive the whole item object as an argument.
+     */
     itemActionsFactory: PropTypes.func,
   },
   getDefaultProps() {

graylog2-web-interface/src/components/common/TableList.md

@@ -0,0 +1,61 @@
+```js
+const createReactClass = require('create-react-class');
+const Immutable = require('immutable');
+const Button = require('react-bootstrap').Button;
+
+const TableListExample = createReactClass({
+  getInitialState() {
+    return {
+      items: Immutable.List([
+        { id: '1', title: 'One', secret_key: 'uno', description: 'First number' },
+        { id: '2', title: 'Two', secret_key: 'dos', description: 'Second number' },
+        { id: '3', title: 'Three', secret_key: 'tres', description: 'Third number' },
+        { id: '4', title: 'Four', secret_key: 'cuatro', description: 'Fourth number' },
+        { id: '5', title: 'Five', secret_key: 'cinco', description: 'Fifth number' },
+      ]),
+    };
+  },
+
+  action(text) {
+    return () => {
+      alert(`This is an action for "${text}"`);
+    };
+  },
+
+  headerActionsFactory(selectedNumbers) {
+    return (
+      <div className="pull-right" style={{ marginTop: 10 }}>
+        <Button bsStyle="info"
+                bsSize="xsmall"
+                onClick={this.action(selectedNumbers.join(', '))}>
+          Bulk-operation
+        </Button>
+      </div>
+    );
+  },
+
+  itemActionsFactory(selectedNumber) {
+    return (
+      <Button bsStyle="primary"
+              bsSize="xsmall"
+              onClick={this.action(JSON.stringify(selectedNumber))}>
+        Do something
+      </Button>
+    );
+  },
+
+  render() {
+    const { items } = this.state;
+
+    return (
+      <TableList items={items}
+                 filterKeys={['title', 'secret_key']}
+                 filterLabel=""
+                 headerActionsFactory={this.headerActionsFactory}
+                 itemActionsFactory={this.itemActionsFactory} />
+    );
+  },
+});
+
+<TableListExample />
+```