From 821408056f32962d3d5b86e91c9571ce1b1cff9d Mon Sep 17 00:00:00 2001
From: John Knox <jknox@fb.com>
Date: Wed, 1 May 2019 08:25:41 -0700
Subject: [PATCH] Add Searching and Filtering page

Summary: I can't take credit for this, I found it in the internal wiki. Have just modernised it and made it public.

Reviewed By: danielbuechele

Differential Revision: D15165547

fbshipit-source-id: d59344aa6ad47be6ab32b88abcdfc14a7d20c775
---
 docs/extending/search-and-filter.md | 68 +++++++++++++++++++++++++++++
 website/i18n/en.json                |  3 ++
 website/sidebars.json               |  1 +
 3 files changed, 72 insertions(+)
 create mode 100644 docs/extending/search-and-filter.md

diff --git a/docs/extending/search-and-filter.md b/docs/extending/search-and-filter.md
new file mode 100644
index 000000000..e35f6ab29
--- /dev/null
+++ b/docs/extending/search-and-filter.md
@@ -0,0 +1,68 @@
+---
+id: search-and-filter
+title: Searching and Filtering
+---
+
+## Adding Search and Filter capabilities to your plugin
+Many plugins need the ability to make their content search and filterable. Flipper provides a component for this use-case called `Searchable`. This is a higher-order-component that can be used to wrap any table, list, generic react-component and adds Flippers search bar on top of it.
+
+We differentiate between search and filter, but both functionalities are provided by the `Searchable` component. Search is a custom string entered by the user. Filters can not be added by the user directly, but are added programmatically from within your plugin.
+
+### Filters
+Every filter has a key and a value. The key represents an attribute of the items you are filtering, and the value is the value that is compared with the items to see if the attribute matches. As an example, if you were filtering rows of a table, the a filter key would be the id of a column.
+
+There are two different types of filters:
+
+**include/exclude filters**: An arbitrary string that must (or must not) be included in the filterable item.
+
+**enum**: Allows the user to select one or more from a set of values, using a dropdown.
+
+### Higher Order Component
+The `Searchable()` function adds three props to a React component:
+
+`addFilter: (filter: Filter) => void`
+
+Function allowing the component to add filters.
+
+`searchTerm: string`
+
+The search term entered into the searchbar by the user.
+
+`filters: Array<Filter>`
+
+The list of filters that are currently applied
+
+
+#### Example
+```
+import type {SearchableProps} from 'sonar';
+import {Searchable} from 'sonar';
+
+class MyPluginTable extends Component<{
+  ...SearchableProps
+}> {
+  getRows() {
+    const {rows, searchTerm, filters} = this.props;
+    return rows.filter(row => {
+      // filter rows for searchTerm and applied filters
+    });
+  }
+
+  addFilter () {
+    this.props.addFilter({
+      type: 'include',
+      key: '...',
+      value: '...',
+    });
+  }
+
+  render() {
+    return <div>
+      <Button onClick={this.addFilter}>Filter</Button>
+      <Table rows={this.getRows()} />
+    </div>
+  }
+}
+
+export default SearchableTable = Searchable(MyPluginTable);
+```
diff --git a/website/i18n/en.json b/website/i18n/en.json
index dacb1704e..6fbe32d10 100644
--- a/website/i18n/en.json
+++ b/website/i18n/en.json
@@ -37,6 +37,9 @@
       "extending/new-clients": {
         "title": "Implementing a Flipper Client"
       },
+      "extending/search-and-filter": {
+        "title": "Searching and Filtering"
+      },
       "extending/send-data": {
         "title": "Sending Data to Plugins"
       },
diff --git a/website/sidebars.json b/website/sidebars.json
index 77fb89487..ffac3ac2b 100644
--- a/website/sidebars.json
+++ b/website/sidebars.json
@@ -39,6 +39,7 @@
       "extending/styling-components",
       "extending/create-plugin",
       "extending/send-data",
+      "extending/search-and-filter",
       "extending/error-handling",
       "extending/testing"
     ],