# Jodit Finder

Enhanced file browser for Jodit with many additional features and improved interface.

## Advantages

- Dark and light themes, switchable from the interface.
- Ability to change file browser settings directly in the interface.
- Folders in a tree view.
- Ability to add an image, file, or folder to the Favorites section.
- Navigation history with buttons: home, forward, and back.
- 5 tile display modes: very small, small, default, large, and very large.
- Display mode as compact labels and icons.
- Folders inside the items section like in Explorer. You can hide the tree section.
- Partial loading with infinite scrolling.
- Quick preview of images.
- Preview of office documents.
- Moving files and folders with Cut/Paste in the context menu.

## Usage with Jodit

```js
const jodit = Jodit.make('#editor', {
    filebrowser: {
        ajax: {
            url: 'https://xdsoft.net/jodit/finder/'
        },
        uploader: {
            url: 'https://xdsoft.net/jodit/finder/?action=fileUpload'
        }
    }
});

jodit.filebrowser.open((images) => {
    console.log('Selected:', images);
}, true); // true - show only images
```

The entire [list of settings](/jodit/docs/classes/config.Config.html#filebrowser) is available just like in the [free version](/jodit/docs/modules/modules_file_browser.html)

## Usage without Jodit

```js
const fb = new Jodit.modules.FileBrowserPro({
    ajax: {
        url: 'https://xdsoft.net/jodit/finder/'
    },
    uploader: {
        url: 'https://xdsoft.net/jodit/finder/?action=fileUpload'
    }
});

fb.open((images) => {
    console.log('Selected:', images);
}, true); // true - show only images
```

## Options

### view

- Type: String
- Default: `null`
- Possible values: "tiles", "list", "compact"

Default display mode of the file list. The mode the user picks in the interface
is stored in `localStorage` (see `saveStateInStorage.storeView`) and wins over
this option on the next open. To force the configured mode on every open,
disable the view persistence:

```js
Jodit.make('#editor', {
    filebrowser: {
        view: 'list',
        saveStateInStorage: {
            storeView: false
        }
    }
});
```

### previewOfficeURL

- Type: String
- Default: "https://view.officeapps.live.com/op/view.aspx?src="

URL for opening office documents in the preview window in an iframe.

```js
Jodit.make('#editor', {
    filebrowser: {
        previewOfficeURL: "https://view.officeapps.live.com/op/view.aspx?src="
    }
});
```

### buttons

- Type: Array
- Default: 
```js
[
    'filebrowser.home',
    'filebrowser.previous',
    'filebrowser.next',
    '|',
    'filebrowser.upload',
    'filebrowser.new-folder',
    'filebrowser.remove',
    'filebrowser.update',
    'filebrowser.select',
    'filebrowser.edit',
    '|',
    'filebrowser.preview',
    'about'
]
```

Array of buttons for the file browser toolbar.

```js
Jodit.make('#editor', {
    filebrowser: {
        buttons: [
            'filebrowser.home',
            'filebrowser.upload',
            'filebrowser.remove',
            'filebrowser.update',
            'filebrowser.select'
        ]
    }
});
```

### sort

- Type: Boolean
- Default: false

Enables or disables sorting of files and folders.

```js
Jodit.make('#editor', {
    filebrowser: {
        sort: true
    }
});
```

### pixelOffsetLoadNewChunk

- Type: Number
- Default: 300

Pixel offset for loading a new chunk during infinite scrolling.

```js
Jodit.make('#editor', {
    filebrowser: {
        pixelOffsetLoadNewChunk: 500
    }
});
```

### width

- Type: Number
- Default: 800

Width of the file browser window.

```js
Jodit.make('#editor', {
    filebrowser: {
        width: 1000
    }
});
```

### height

- Type: Number
- Default: 400

Height of the file browser window.

```js
Jodit.make('#editor', {
    filebrowser: {
        height: 600
    }
});
```

### maxWidth

- Type: Number
- Default: Not set

Maximum width of the file browser window.

```js
Jodit.make('#editor', {
    filebrowser: {
        maxWidth: 1200
    }
});
```

## State Settings

The following settings can be changed through the file browser interface:

### theme

- Type: String
- Default: "default"
- Possible values: "default", "dark"

File browser theme.

### showSideBar

- Type: Boolean
- Default: true

Show or hide the sidebar.

### showFavorites

- Type: Boolean
- Default: true

Show or hide the favorites section.

### showSettings

- Type: Boolean
- Default: false

Show or hide settings.

### showPreview

- Type: Boolean
- Default: false

Show or hide preview.

### withFolders

- Type: Boolean
- Default: true

Show folders together with files in the main list.

### foldersPosition

- Type: String
- Default: "bottom"
- Possible values: "top", "bottom", "default"

Position of folders in the file list.

### tileSize

- Type: String
- Default: "default"
- Possible values: "xsmall", "small", "default", "large", "xlarge"

Size of tiles in tile display mode.

## Moving and copying files and folders (Cut / Copy / Paste)

Right-click a file or folder and choose **Cut** or **Copy**, then paste it:

- via the context menu of the target folder (in the tree or in the list),
- via the context menu of the source root,
- via the context menu of an **empty spot** of the file list (pastes into the
  currently opened folder),
- or with the **Paste** toolbar button, which appears as soon as the
  clipboard is not empty and pastes into the current folder.

Multi-select works: all selected files are cut/copied together. Cut items are
shown dimmed until they are pasted; a cut clipboard works once, a copied one
can be pasted repeatedly (the server resolves name clashes with a ` (N)`
suffix, so copying into the same folder duplicates the item).

- The actions are shown only when the connector allows them
  (`allowFileMove` / `allowFolderMove` / `allowFileCopy` / `allowFolderCopy`
  in the `permissions` answer, or `permissionsPresets`).
- Move uses the `fileMove`/`folderMove` connector actions; copy uses
  `fileCopy`/`folderCopy` (supported by the official Node and PHP
  connectors).
- Items can only be moved/copied within the same source; a folder can not be
  pasted into itself or its own subtree.
- Programmatic API: the events `cut.filebrowser`, `copy.filebrowser` and
  `paste.filebrowser`, the `state.clipboard` array and the
  `canPaste(target)` / `getPasteTarget()` methods of `FileBrowserPro`.

```js
const fb = jodit.filebrowser;
fb.e.fire('cut.filebrowser'); // cut current selection
fb.e.fire('copy.filebrowser'); // copy current selection
fb.e.fire('paste.filebrowser', { path: 'documents', sourceName: 'default' });
```

## API Reference

### IFileBrowserStatePro

Extended state interface for the Pro file browser, inheriting from `IFileBrowserState`.

```typescript
interface IFileBrowserStatePro extends IFileBrowserState {
    /** Current theme of the file browser */
    theme: string;

    /** Callback function triggered when files are selected */
    onSelectCallBack: Nullable<(data: IFileBrowserCallBackData) => void>;

    /** Whether to show the sidebar */
    showSideBar: boolean;

    /** Whether to show the settings panel */
    showSettings: boolean;

    /** Whether to show the favorites section */
    showFavorites: boolean;

    /** Whether to show the preview panel */
    showPreview: boolean;

    /** Index of the last selected item */
    lastSelectedIndex: number;

    /** Whether to display folders in the main file list */
    withFolders: boolean;

    /** Position of folders in the file list */
    foldersPosition: 'top' | 'bottom' | 'default';

    /** Current progress value (0-100) for loading operations */
    progress: number;

    /** Information message to display */
    info: string;

    /** Additional metadata information */
    metaInfo: Nullable<IDictionary>;

    /** Size of tiles in tile display mode */
    tileSize: 'xsmall' | 'small' | 'default' | 'large' | 'xlarge';

    /** Array of favorite files and folders */
    favorites: IFileBrowserState['activeElements'];

    /** Tree structure for folder navigation */
    tree: IFileBrowserTreeItemPro[];
}
```

### IFileBrowserOptionsPro

Extended options interface for the Pro file browser, combining multiple option interfaces.

```typescript
interface IFileBrowserOptionsPro extends IFileBrowserOptions, IDialogOptions, IViewOptionsPro {
    /** Toolbar buttons configuration (alias for buttons) */
    toolbarButtons: IFileBrowserOptions['buttons'];

    /** Maximum width of the file browser window */
    maxWidth: number;

    /** URL for previewing office documents */
    previewOfficeURL: string;

    /** License key for the Pro version */
    license: string;
}
```

### IFileBrowserTreeItemPro

Interface for tree items in the folder navigation tree.

```typescript
interface IFileBrowserTreeItemPro {
    /** Type of the tree item */
    type: 'file' | 'directory' | 'source';

    /** Name of the item */
    name: string;

    /** Display title (optional, defaults to name) */
    title?: string;

    /** Whether the tree item is collapsed */
    isCollapsed?: boolean;

    /** Whether the tree item is currently active/selected */
    isActive?: boolean;

    /** Full path to the item */
    path: string;

    /** Name of the source/server this item belongs to */
    sourceName: string;

    /** Child items (for directories) */
    children: IFileBrowserTreeItemPro[];
}
```

### IFileBrowserPro

Main interface for the Pro file browser instance.

```typescript
interface IFileBrowserPro extends IFileBrowser<IFileBrowserOptionsPro> {
    /** Observable state object */
    readonly state: IFileBrowserStatePro & IObservable;

    /** Persistent storage manager for user preferences */
    readonly persistent: PersistentStore;

    /** Loading state manager for async operations */
    readonly loadingManager: LoadingManager;

    /** State management utilities */
    readonly stateManager: StateManager;

    /** Navigation history manager */
    readonly historyManager: IHistoryManager;

    /** Context menu manager */
    readonly contextMenuManager: ContextMenuManager;

    /** Main UI panel component */
    readonly panel: UIBrowserPanel;

    /** Whether the current clipboard can be pasted into the target folder */
    canPaste(target: IFinderPasteTarget): boolean;

    /** The currently opened folder as a paste target */
    getPasteTarget(): IFinderPasteTarget;
}
```

### IFinderClipboardItem

Interface for an item in the finder clipboard (`state.clipboard`).

```typescript
interface IFinderClipboardItem {
    /** How the item was placed into the clipboard */
    mode: 'cut' | 'copy';

    /** Kind of the item */
    type: 'file' | 'folder';

    /** Full relative path (including the item name) inside the source */
    from: string;

    /** Name of the item */
    name: string;

    /** Name of the source the item belongs to */
    sourceName: string;
}
```

### IHistoryManager

Interface for managing navigation history within the file browser.

```typescript
interface IHistoryManager {
    /** Check if there's a next item in history */
    canNext(): boolean;

    /** Check if there's a previous item in history */
    canPrevious(): boolean;

    /** Add a new item to history */
    push(item: IHistoryItem): void;

    /** Navigate to the next item in history */
    next(): void;

    /** Navigate to the previous item in history */
    previous(): void;

    /** Update the current history item with latest state */
    updateCurrent(): void;
}
```

### IHistoryItem

Interface for individual history items stored by the history manager.

```typescript
interface IHistoryItem {
    /** Current path when this history item was created */
    currentPath: IFileBrowserStatePro['currentPath'];

    /** Current source when this history item was created */
    currentSource: IFileBrowserStatePro['currentSource'];

    /** Tree state when this history item was created */
    tree: IFileBrowserStatePro['tree'];

    /** Elements state when this history item was created */
    elements: IFileBrowserStatePro['elements'];
}
```

## Examples

### Basic Usage

```js
const jodit = Jodit.make('#editor', {
    extraPlugins: ['finder'],
    filebrowser: {
        ajax: {
            url: 'https://xdsoft.net/jodit/finder/'
        },
        uploader: {
            url: 'https://xdsoft.net/jodit/finder/?action=fileUpload'
        }
    }
});

// Open file browser
jodit.filebrowser.open((files) => {
    console.log('Selected:', files);
});
```

### Configuring Size and Appearance

```js
const jodit = Jodit.make('#editor', {
    extraPlugins: ['finder'],
    filebrowser: {
        width: 1000,
        height: 600,
        theme: 'dark',
        tileSize: 'large',
        buttons: [
            'filebrowser.home',
            'filebrowser.upload',
            'filebrowser.new-folder',
            'filebrowser.remove',
            'filebrowser.select'
        ]
    }
});
```

### Configuring Office Document Preview

```js
const jodit = Jodit.make('#editor', {
    extraPlugins: ['finder'],
    filebrowser: {
        previewOfficeURL: "https://docs.google.com/viewer?embedded=true&url="
    }
});
```

### Usage without Jodit

```js
// Create a file browser instance
const fb = new Jodit.modules.FileBrowserPro({
    ajax: {
        url: 'https://xdsoft.net/jodit/finder/'
    },
    uploader: {
        url: 'https://xdsoft.net/jodit/finder/?action=fileUpload'
    },
    width: 1000,
    height: 600,
    theme: 'dark'
});

// Open the file browser
fb.open((files) => {
    // Process selected files
    if (files.length) {
        const fileUrls = files.map(file => file.fileURL);
        console.log('Selected files:', fileUrls);
    }
});
```

### Programmatic State Management

```js
const jodit = Jodit.make('#editor', {
    extraPlugins: ['finder']
});

// Open file browser
jodit.filebrowser.open((files) => {
    console.log('Selected:', files);
});

// Change state programmatically
jodit.filebrowser.state.theme = 'dark';
jodit.filebrowser.state.tileSize = 'large';
jodit.filebrowser.state.showSideBar = false;