neeto-folders-nano

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

Contents

1. Development with Host Application
   • Engine
     • Installation
     • Usage
   • Frontend package
     • Installation
     • Instructions for development
     • Usage
2. Instructions for Publishing

Development with Host Application

Engine

Installation

1. Add this line to your application's Gemfile:

    source "NEETO_GEM_SERVER_URL" do
      # ..existing gems
   
      gem 'neeto-folders-engine'
    end

2. And then execute:

   bundle install

3. Add required migrations in the db/migrate folder. Run the following commands to copy the migrations from the engine to the host application.

   rails g neeto_folders_engine:install
   bundle exec rails db:migrate

Usage

1. 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

2. 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

3. 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

1. 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,
  },
  folderActions: { getMoreActions: (node) => [...], getAddActions: (node) => [...] },
  itemActions: { getMoreActions: (node) => [...], getAddActions: (node) => [...] }
}

Components

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

1. 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>

2. 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} />;

3. 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}
   />;

4. MoveToFolderPane: 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 { MoveToFolderPane } from "@bigbinary/neeto-folders-frontend/components";
   // ....
   <MoveToFolderPane
     item={itemToMove}
     onSelect={onSelectFolder}
     selection={folderSelection}
   />;

5. AddEditPane: This component can be used in host applications to add or edit folders.

   Props:

   • config: A config object to customize the folders behavior.

   • onClose(): Callback invoked when the pane is closed.

   • folderSid: It is optional. The SID of the parent folder where new folder should be created. If not provided, uses the active folder from URL.

   • setFocusField: Ref callback to set focus on the name input field when pane opens.

   Sample usage:

   import { AddEditPane } from "@bigbinary/neeto-folders-frontend/components";
   // ....
   <AddEditPane
     {...{ setFocusField, onClose }}
     config={foldersConfig}
     folderSid={selectedFolderSid}
   />;

Hooks

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

1. 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.

2. 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.

3. 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";

1. 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";

1. 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

Instructions for Publishing

Consult the building and releasing packages guide for details on how to publish.