@bigbinary/neeto-folders-frontend NPM

neeto-folders-nano

The neeto-folders-nano acts as the source of truth for the new nano's structure, configs, data etc.

Development with Host Application
- Engine
  - Installation
  - Usage
- Frontend package
Instructions for Publishing

Development with Host Application

Engine

Installation

Add this line to your application's Gemfile:

 source "NEETO_GEM_SERVER_URL" do
   # ..existing gems

   gem 'neeto-folders-engine'
 end

And then execute:
```
bundle install
```
Add required migrations in the db/migrate folder. Run the following commands to copy the migrations from the engine to the host application.
```
bundle exec rails neeto_folders_engine:install:migrations
bundle exec rails db:migrate
```

Usage

Define the folder model in your application by extending the NeetoFoldersEngine::Folder base class. Below is the sample code in NeetoRecord that defines a RecordingFolder model by extending the NeetoFoldersEngine::Folder to manage recordings.
```
class RecordingFolder < NeetoFoldersEngine::Folder
  has_many :recordings, -> { unscope(where: :deleted_at) }, foreign_key: :folder_id, dependent: :nullify
```
NeetoFoldersEngine also expects a instance method items to be defined in the extended class. This enables the NeetoFoldersEngine to keep track of the count of items in the folder. Below is a sample code from NeetoRecord.
```
def items
  recordings
end
```
Include the NeetoFoldersEngine::Folderable in the model which should belong to a folder. Order of include is important. Include Folderable after Deletable from neeto-commons-backend to allow Folderable to override the soft_delete method.
```
include NeetoFoldersEngine::Folderable
```
NeetoFoldersEngine also exposes a controller class NeetoFoldersEngine::FoldersController with index, show, create, update, destroy, bulk_update, bulk_destroy, and reorder actions to manage folders. The host application can extend this class to manage their folders. Make sure the routes are properly configured to direct to these actions.
Similar to the RecordingFolder < NeetoFoldersEngine::Folder, the NeetoFoldersEngine::FoldersController base controller expects a folders method to be defined in the extended class that allows the controller to target folder instances that belongs to a particular type. Given below is sample definition in NeetoRecord which extracts recording folders that should be managed by the extended controller.
```
class Api::V1::FoldersController < NeetoFoldersEngine::FoldersController

  private

    def folders
      @_folders ||= @organization.recording_folders.includes(:recordings)
    end
  end
```

Frontend package

Installation

Add the neeto-folders-frontend package to the package.json
```
yarn add @bigbinary/neeto-folders-frontend
```

Instructions for development

Check the Frontend package development guide for step-by-step instructions to develop the frontend package.

Usage

neeto-folders-frontend exports a set of components, hooks, utils and constants to be integrated in the host application.

Most of the above exports accepts a configuration object with certain properties. Given below is the structure of default config object. You can pass your own config object as argument or props to customize behaviors that suits the host product. Define this constant in a constant file and customize certain properties such as params as necessary.

{

  type: "FOLDER", // A unique type key for query keys.
  maxDepth: 2, // Maximum allowed depth for folder tree
  folderPath: "/folders/:folderId", // Path for handling URL redirections and params matching.
  invalidationKeys: [], // For invalidation purposes. Keys in this array will be invalidated along with folders.
  reorderMode: "rearrange", // If reorder pane should mount in positional `reorder` mode or simple `rearrange` mode.
// Taxonomy
  labels: {
    folder: t("common.folder"),
    folders: t("common.folders"),
    items: t("common.items"),
    items: t("common.items"),
  }
  params: {}, // Params to be passed to APIs along with other params. Can be used for sorting and similar.
  api: { // Folder CRUD methods.
    fetch: noop,
    get: noop,
    create: noop,
    update: noop,
    destroy: noop,
    bulkUpdate: noop,
    bulkDestroy: noop,
  }
}

Components

import * as components from "@bigbinary/neeto-folders-frontend/components";

FoldersContext: This component renders all alerts and panes related to folders. Make sure this component is included in some part of your application.
Props:
- config: A config object to customize the folders behavior.
Sample usage:
```
import { FoldersContext } from "@bigbinary/neeto-folders-frontend/components";
// ....
<FoldersContext config={foldersConfig}>
  <ApplicationComponent>
</FoldersContext>
```
FoldersTree: This component renders the folders in tree a tree structure.
Props:
- config: A config object to customize the folders behavior.
Sample usage:
```
import { FoldersTree } from "@bigbinary/neeto-folders-frontend/components";
// ....
<FoldersTree config={foldersConfig} />;
```
FoldersList: Component renders list of folders. If no folder is selected/active, renders list of root folders. If inside a selected folder, renders list of sub-folders. The active folder is identified based on the param in the URL that matches the folderPath in the config object.
Props:
- config: A config object to customize the folders behavior.
- selection: An array of folder ids indicating id of selected folders for bulk selection.
- onSelect: Callback triggered when checkbox is selected for a folder item for bulk selection.
Sample usage:
```
import { FoldersList } from "@bigbinary/neeto-folders-frontend/components";
// ....
<FoldersList
  config={foldersConfig}
  onSelect={onSelectFolder}
  selection={folderSelection}
/>;
```
MoveToFoldersPane: This component can be used in host applications to move items to a folder. Component renders current list of folders in pane with radio buttons and invokes callbacks for folder selections.
Props:
- isOpen: Boolean value that controls pane visibility.
- item: An item object that is to be moved to the folder.
- config: A config object to customize the folders behavior.
- submitButtonProps: Pane "Submit" button overrides.
- cancelButtonProps: Pane "Cancel" button overrides.
- removeButtonProps: Pane "Remove from folder" button overrides. Note that the button will be hidden unless the onRemove prop is supplied.
- onSubmit(folderId): Callback invoked with id of selected folder on submit.
- onClose(): Callback invoked when the pane is closed.
- onRemove(): Callback invoked when the Remove from folder button is pressed. Note that the button will be hidden unless this prop is supplied.
- onSelect: Callback triggered when checkbox is selected for a folder item for bulk selection.
Sample usage:
```
import { MoveToFoldersPane } from "@bigbinary/neeto-folders-frontend/components";
// ....
<MoveToFoldersPane
  item={itemToMove}
  onSelect={onSelectFolder}
  selection={folderSelection}
/>;
```

Hooks

import * as hooks from "@bigbinary/neeto-folders-frontend/hooks";

useFolders(config): Hook that return the data for all folders in tree structure.
Arguments:
- config: A config object to customize the folders behavior.
Returns:
- isLoading: true when data is being fetched for active folder. false otherwise.
- folders: Data of all folders of given type in tree structure.
useFolder(config): Hook that return the data related to current active folder based on URL param.
Arguments:
- config: A config object to customize the folders behavior.
Returns:
- isLoading: true when data is being fetched for active folder. false otherwise.
- folderId: SID of the current active folder based on URL param.
- folder: Data of the current folder if exists.
useFolderActions(config): Hook that return a set of callbacks to trigger actions from host application.
Arguments:
- config: A config object to customize the folders behavior.
Returns:
- isPending: true when action is in progress. false otherwise.
- onAdd(): Initiates the folder create action.
- onEdit(folder): Initiates the folder edit action. Accepts folder data as argument.
- onMove(folder): Initiates the folder edit action. Accepts folder data as argument.
- onDelete(folder): Initiates the folders delete action. Accepts folder data as argument.
- onReorder(): Initiates the reorder folder action. Opens the "Reorder" pane.

Utils

import * as utils from "@bigbinary/neeto-folders-frontend/utils";

pathToFolder(folders, folderId):
Arguments:
- folders: Folders data in tree structure, returned by the useFolders hook.
- folderId: Target folder id.
Returns an flattened array of folders from root folder to current folder with id folderId. Useful for showing breadcrumbs and similar.

Constants

import * as constants from "@bigbinary/neeto-folders-frontend/constants";

QUERY_KEYS: Use query keys to target React Query actions such as invalidations.
- [QUERY_KEYS.FOLDERS]: Targets every query related to folders.
- [QUERY_KEYS.FOLDERS, config.folderType]: Targets every query related to folders of particular type.
- [QUERY_KEYS.FOLDERS, config.folderType, QUERY_KEYS.LIST]: Targets folders list.
- [QUERY_KEYS.FOLDERS, config.folderType, QUERY_KEYS.DETAILS, folderId]: Target folder details of a folder with id folderId