@bigbinary/neeto-filters-frontend 3.0.3 → 3.0.5

package/README.md

@@ -1,8 +1,13 @@
-# @bigbinary/neeto-filters-frontend
+# neeto-filters-nano
+
+1. [Engine and package installation](./docs/engine-and-package-installation.md)
+2. [Building and releasing](./docs/building-and-releasing.md)
+
+## @bigbinary/neeto-filters-frontend
 
 neetoFilters is the library that manages filters across neeto products.
 
-## Installation
+### Installation
 
 ```bash
 yarn add @bigbinary/neeto-filters-frontend
@@ -16,12 +21,12 @@ command:
 yarn add @bigbinary/neetoui @bigbinary/neeto-icons axios@0.27.2 classnames@2.3.1 dayjs@1.11.1 formik@2.2.0 ramda@0.28.0 react-router-dom@5.3.0 react-router-nav-prompt@0.4.1 react-toastify@9.0.1 yup@0.32.11
 ```
 
-## Usage
+### Usage
 
 neeto-filters-frontend exports 2 components (`Filters` & `Bar`) and 2 functions
 (`buildFiltersFromURL()` & `buildSelectorsFromURL()`).
 
-### 1. `Filters` component
+#### 1. `Filters` component
 
 #### Props
 
@@ -175,7 +180,7 @@ When user selects a value from this dropdown we get that value in the
 `selectors` state. This can be used for further computations outside the
 neeto-filters.
 
-### 2. `Bar` component
+#### 2. `Bar` component
 
 #### Props
 
@@ -198,7 +203,7 @@ All these props must be same as that passed to the `Filters` component. The
 option to save filters as segments will be enabled only when the entity prop is
 passed to the component.
 
-### 3. `Segments` component
+#### 3. `Segments` component
 
 #### Props
 
@@ -212,7 +217,7 @@ set up the neeto-filters-engine with support for Segments, please follow the
 instructions provided in the installation
 [documentation](https://github.com/bigbinary/neeto-filters-engine#installation).
 
-### 3. `buildFiltersFromURL` function
+#### 3. `buildFiltersFromURL` function
 
 - This function takes a list as argument.
 - This list should contains all the filter columns/fields and the value passed
@@ -226,7 +231,7 @@ const [filters, setFilters] = useState(() =>
 );
 ```
 
-### 4. `buildSelectorsFromURL` function
+#### 4. `buildSelectorsFromURL` function
 
 - By `selectors` we mean the filter fields which doesn't have any relation
   (`node`) to a DB table column.
@@ -249,7 +254,7 @@ const [selectors, setSelectors] = useState(() =>
 );
 ```
 
-### 5. `buildFilterColumnsFromFields` function
+#### 5. `buildFilterColumnsFromFields` function
 
 The `buildFilterColumnsFromFields` function is used to generate an array of
 filter columns based on the provided fields (often referred as custom fields)
@@ -285,44 +290,212 @@ const selectedFields = ["name", "age"];
 const filterColumns = buildFilterColumnsFromFields({ fields, selectedFields });
 ```
 
-## Development
+## neeto-filters-engine
 
-Install all the dependencies by executing the following command
+neeto_filters is a Ruby gem that manages filters across neeto products. It
+allows the users to filter entities with respect to its columns, associated
+columns, or custom attributes. It is best used along with the
+[neeto-filters-frontend](https://github.com/bigbinary/neeto-filters-frontend)
+npm package.
 
-```bash
-yarn install
+### Installation
+
+1. Add the following line to your application's Gemfile:
+
+```zsh
+gem "neeto-filters-engine", git: "https://github.com/bigbinary/neeto-filters-engine", branch: "stable"
 ```
 
-Start the development server using the `yarn start` command. In order to run the
-application you need to run the Rails server of the
-[neeto-filters-engine](https://github.com/bigbinary/neeto-filters-engine)'s
-dummy application as well. This is necessary to make sure that all the APIs and
-React Query hooks are working as per the requirement.
+2. Execute the following command:
 
-```bash
-git clone https://github.com/bigbinary/neeto-filters-engine.git
-./test/dummy/bin/setup
-rails server
+```zsh
+bundle install
+```
+
+3. Add the following line to `config/routes.rb` file to mount the engine at
+   `/neeto_filters` route.
+
+```ruby
+mount NeetoFiltersEngine::Engine, at: "/neeto_filters"
+```
+
+4. Add the following line to `models/organization.rb` file.
+
+```ruby
+has_many :segments, class_name: "NeetoFiltersEngine::Segment", dependent: :destroy
+```
+
+5. Execute the following command to generate the migration to generate the
+   `neeto_filters_engine_segments` table. This table stores all the saved
+   segments.
+
+```zsh
+rails g neeto_filters_engine:install
+```
+
+#### Verify that the installation is successful.
+
+- Assume that there is a `users` table with the `User` model associated with it.
+  It a `email` column of type `string` or `text`.
+- Open Rails console and add the following lines:
+
+```ruby
+filters = [
+  {
+    "conditions": [
+      {
+        "node": "email",
+        "label": "Email Address",
+        "type": "text",
+        "rule": "contains",
+        "value": "example",
+        "conditions_join_type": "AND"
+      },
+    ],
+    "group_join_type": "OR"
+  },
+]
+
+User.all.apply_neeto_filters(filters)
 ```
 
-# Building and releasing.
-
-The `@bigbinary/neeto-filters-frontend` package gets published to NPM when we
-merge a PR with `patch`, `minor` or `major` label to the `main` branch. The
-`patch` label is used for bug fixes, `minor` label is used for new features and
-`major` label is used for breaking changes. You can checkout the
-`Create and publish releases` workflow in GitHub Actions to get a live update.
-
-In case if you missed to add the label, you can manually publish the package.
-For that first you need to create a PR to update the version number in the
-`package.json` file and merge it to the `main` branch. After merging the PR, you
-need to create a
-[new github release](https://github.com/bigbinary/neeto-filters-frontend/releases/new)
-from main branch. Whenever a new release is created with a new version number,
-the github actions will automatically publish the built package to npm. You can
-checkout the `Publish to npm` workflow in GitHub Actions to get a live update.
-
-Please note that before publishing the package, you need to verify the
-functionality in some of the neeto web-apps locally using `yalc` package
-manager. The usage of yalc is explained in this video:
-https://youtu.be/QBiYGP0Rhe0
+- If the above lines returns zero or more users, the installation is successful.
+
+### Usage
+
+Here is an example of how to use the `neeto-filters-engine` gem assuming that
+the `users` table has been created.
+
+```rb
+class HomeController < ApplicationController
+  before_action :load_users
+
+  def index
+    @filtered_users = @users.apply_neeto_filters(params[:filters])
+    @total_count = @filtered_users.count
+  end
+
+  private
+
+    def load_users
+      @users = @organization.users
+    end
+end
+```
+
+Note: If you wish to use `select()` method after calling
+`apply_neeto_filters()`, please note to use `reselect()` since neeto-filters
+itself performs a 'select' operation internally.
+
+Here, the param `filters` is a hash with the following structure, where each
+`node` corresponds to a column in the `users` table.
+
+```json
+[
+  {
+    "conditions": [
+      {
+        "node": "email",
+        "label": "Email Address",
+        "type": "text",
+        "rule": "contains",
+        "value": "bigbinary",
+        "conditions_join_type": "AND"
+      },
+      {
+        "node": "timezone",
+        "label": "Timezone",
+        "type": "text",
+        "rule": "is",
+        "value": "Asia/Kolkata",
+        "conditions_join_type": "AND"
+      }
+    ],
+    "group_join_type": "OR"
+  },
+  {
+    "conditions": [
+      {
+        "node": "age",
+        "label": "Age",
+        "type": "number",
+        "rule": "greater_than",
+        "value": "18",
+        "conditions_join_type": "AND"
+      }
+    ],
+    "group_join_type": "AND"
+  }
+]
+```
+
+The gem filters the users based on the conditions in the `filters` param. In
+this case, all the users whose email address contains `bigbinary` in the
+`Asia/Kolkata` timezone or whose age is greater than 18 will be filtered.
+
+### How It Works
+
+#### Base Types
+
+- Base Types refers to the columns that are directly present in the table on
+  which the `apply_neeto_filters` method is called.
+- Refer to this video for an overview of the same.
+
+  https://vimeo.com/724478910/e349e361bd
+
+#### Custom Types
+
+- Some projects will have custom attributes to the tables that will be added or
+  updated dynamically. `NeetoFiltersEngine` can handle these attributes by
+  passing the proper filters to the `apply_neeto_filters` method.
+- The implementation of custom attributes is different for different projects.
+  `NeetoFiltersEngine` is built in the same way as `neetoCRM`. If the custom
+  attributes feature needs to be added to a project where the custom attributes
+  implementation is different, you need to override the
+  `NeetoFiltersEngine::Custom::BaseSearchService` class specifiying the proper
+  join operations.
+- Refer to the below video for an overview of the same.
+
+  https://vimeo.com/724489868/94dfc6cd43
+
+#### Associated Types
+
+- Associated types refer to the the columns that are not directly present in the
+  table on which the `apply_neeto_filters` method is applied. Instead these will
+  be present in another table to which the first table has a foreign key to. For
+  instance, the `deals` table can have an association with the `companies` table
+  and the company name can be displayed in the UI. `NeetoFiltersEngine` can be
+  used to filter these columns by properly specifying the filters.
+- Refer to te below video for an overview of the same.
+
+  https://vimeo.com/724484259/f305257f37
+
+#### Adding a new type
+
+- `NeetoFiltersEngine` provides the following types: `text`, `number`,
+  `single_option`, `multi_option`, `date`, `time`, `datetime`, `date_range`, and
+  `time_range`.
+- Sometimes we need to filter attributes that are not present in the available
+  types. In this case a new type needs to be created.
+- In this case, the type needs to be specified to the NPM package by passing the
+  `type` name and `filters` prop in the list of columns. The corresponding
+  search service must be created in the `app/services/neeto_filters/` folder as
+  well.
+- Refer to te below video for an overview of the same.
+
+  https://vimeo.com/724499299/09e2231780
+
+#### Working with Dates
+
+- Working with dates is tricky due to the involvement of timezones.
+- Refer to the below video for a quick overview of the same.
+
+  https://vimeo.com/724495909/034668f738
+
+## Integrations
+
+| Project        | Routes                                        |
+| -------------- | --------------------------------------------- |
+| neeto-chat-web | /admin/contacts                               |
+| neeto-crm-web  | /deals, /contacts, /companies, /tasks, /mails |
+| neeto-cal-web  | /meetings, /scheduled-meetings                |