# folder

```javascript
// Get the currently selected folder in the Eagle application
let folder = (await eagle.folder.getSelected())[0];

// Modify properties
folder.name = 'New Folder Name';
folder.description = 'New description...';

// Save changes
await folder.save();
```

{% hint style="success" %}
**🦄 Best Practice:** To ensure data safety, please use the `save()` method provided by the API for data access and modification. Avoid directly modifying the `metadata.json` or any files under the Eagle resource library.
{% endhint %}

## Methods <a href="#z1a5y" id="z1a5y"></a>

## create(options) <a href="#xnzds" id="xnzds"></a>

Create a folder.

* `options` Object
  * `name` string - Folder name
  * `description` string (optional) - Folder description
  * `parent` string (optional) - Parent folder ID; with this parameter, it is equivalent to `createSubfolder(parentId, options)`
* Returns `Promise<folder: Folder>` - Successfully created `folder`

```javascript
let newFolder = await eagle.folder.create({
    name: 'New Folder',
    description: 'Folder\'s description.',
});
```

***

## createSubfolder(parentId, options) <a href="#rys4i" id="rys4i"></a>

Create a subfolder.

* `parentId` string - Parent folder ID
* `options` Object
  * `name` string - Folder name
  * `description` string (optional) - Folder description
* Returns `Promise<folder: Folder>` - Successfully created `folder`

```javascript
let parentFolder = await eagle.folder.getById('folder_id');
let subFolder = await eagle.folder.createSubfolder(parentFolder.id, {
    name: 'Subfolder',
    description: 'Subfolder description.',
});
```

***

## get(options) <a href="#x9nu2" id="x9nu2"></a>

Get folders with specified conditions.

* `options` Object - Query conditions
  * `id` string (optional) - Folder id
  * `ids` string\[] (optional) - Array of folder ids
  * `isSelected` boolean (optional) - Currently selected folders
  * `isRecent` boolean (optional) - Recently accessed folders
* Returns `Promise<folders: Folder[]>` - Query result `folders`

```javascript
// Get the folder corresponding to the specified id
let folders = await eagle.folder.get({
    ids: ['folder_id1', 'folder_id2']
});

// Get currently selected folders in the application
let folders = await eagle.folder.get({
    isSelected: true
});
```

***

## getAll() <a href="#fbdzh" id="fbdzh"></a>

Get all folders.

* Returns `Promise<folders: Folder[]>` - Query result `folders`

```javascript
let folders = await eagle.folder.getAll();
```

***

## getById(folderId) <a href="#sy5fz" id="sy5fz"></a>

Get the folder corresponding to `folderId`.

* `folderId` string - Folder id
* Returns `Promise<folder: Folder>` - Query result `folder`

```javascript
let folder = await eagle.folder.getById('folder_id');
```

***

## getByIds(folderIds) <a href="#n0gjq" id="n0gjq"></a>

Get an array of folders corresponding to `folderIds`.

* `folderIds` string\[] - Array of folder ids
* Returns `Promise<folders: Folder[]>` - Query result `folders`

```javascript
let folders = await eagle.folder.getByIds(['folder_id1', 'folder_id2']);
```

***

## getSelected() <a href="#dsbgj" id="dsbgj"></a>

Get the currently selected folders in the application.

* Returns `Promise<folders: Folder[]>` - `folders`

```javascript
let folders = await eagle.folder.getSelected();
```

***

## getRecents() <a href="#dwsxw" id="dwsxw"></a>

Get the recently used folders.

* Returns `Promise<folders: Folder[]>` - `folders`

```javascript
let folders = await eagle.folder.getRecents();
```

***

## open(folderId) <a href="#gjdst" id="gjdst"></a>

Eagle will open the folder corresponding to `folderId`.

* Returns `Promise<void>`

```javascript
await eagle.folder.open('folder_id');

// Equivalent to
let folder = await eagle.folder.getById('folder_id');
await folder.open();
```

{% hint style="info" %}
Tip: You can also directly call the folder instance's `open()` method to open the folder.
{% endhint %}

***

## Class: Folder <a href="#uezi0" id="uezi0"></a>

An Object type returned by the Folder API `get`, provides modification and save functions.

```javascript
let folder = await eagle.folder.getById('folder_id');

console.log(folder.id);
console.log(folder.name);

folder.name = 'new name';
console.log(folder.name);

await folder.save();
```

{% hint style="success" %}
**🦄 Best Practice:** To ensure data security, please use the `save()` method provided by the Folder instance for data access and modification, and avoid directly modifying the `metadata.json` or any files under the Eagle repository.
{% endhint %}

***

#### Instance Methods <a href="#sihmc" id="sihmc"></a>

### **save()**

Save all modifications.

* Returns `Promise<void>`

```javascript
let folder = await eagle.folder.getById('folder_id');
folder.name = 'New Folder Name';

// Save modifications
await folder.save();
```

***

### **open()**

Eagle will open this folder.

* Returns `Promise<void>`

```javascript
let folder = await eagle.folder.getById('folder_id');
await folder.open();

// Equivalent to
await eagle.folder.open('folder_id');
```

{% hint style="info" %}
Tip: You can also directly call `eagle.folder.open(folderId)` method to open the folder.
{% endhint %}

***

#### Instance Properties <a href="#woenk" id="woenk"></a>

The `Folder` instance includes the following properties:

### **`id` string**

Read-only, folder id.

### **`name` string**

Folder name.

### **`description` string**

Folder description/introduction.

### **`icon` string**

Read-only, folder icon.

### **`iconColor` string**

Folder icon color.

```javascript
let folder = await eagle.folder.getById('folder_id');

// Set folder color to red
folder.iconColor = eagle.folder.IconColor.Red;

// Or use string value directly
folder.iconColor = 'red';

// Save changes
await folder.save();
```

{% hint style="info" %}
Note: This property was read-only before Eagle 4.0 build12 and did not support modification. Starting from Eagle 4.0 build12, this property can be modified.
{% endhint %}

### **`createdAt` Integer**

Read-only, folder creation time (timestamp).

```javascript
let date = new Date(folder.createdAt);
```

### **`parent` string**

Parent folder ID.

```javascript
let folder = await eagle.folder.getById('folder_id');

// Get parent folder ID
console.log(folder.parent);

// Change parent folder (move folder to another parent folder)
folder.parent = 'parent_folder_id';
await folder.save();

// Move to root directory (set to null or undefined)
folder.parent = null;
await folder.save();
```

{% hint style="info" %}
Note: This property was read-only before Eagle 4.0 build12 and did not support modification. Starting from Eagle 4.0 build12, this property can be modified, allowing you to move folders to different parent folders by changing this property.
{% endhint %}

### **`children` Folder\[]**

Read-only, an array of child folders.

```javascript
let children = folder.children;

console.log(children[0]);
await children[0].open();
```

***

## Static Properties <a href="#static-properties" id="static-properties"></a>

### **`IconColor` Object**

Provides predefined folder icon color constants for setting the folder's `iconColor` property.

```javascript
// Available color constants
eagle.folder.IconColor.Red      // 'red'
eagle.folder.IconColor.Orange   // 'orange' 
eagle.folder.IconColor.Yellow   // 'yellow'
eagle.folder.IconColor.Green    // 'green'
eagle.folder.IconColor.Aqua     // 'aqua'
eagle.folder.IconColor.Blue     // 'blue'
eagle.folder.IconColor.Purple   // 'purple'
eagle.folder.IconColor.Pink     // 'pink'
```

**Usage Examples:**

```javascript
let folder = await eagle.folder.getById('folder_id');

// Use color constants to set folder color
folder.iconColor = eagle.folder.IconColor.Blue;
await folder.save();

// Batch set multiple folder colors
let folders = await eagle.folder.getAll();
for (let i = 0; i < folders.length; i++) {
    if (i % 2 === 0) {
        folders[i].iconColor = eagle.folder.IconColor.Green;
    } else {
        folders[i].iconColor = eagle.folder.IconColor.Purple;
    }
    await folders[i].save();
}
```

{% hint style="success" %}
**🦄 Best Practice:** It's recommended to use `eagle.folder.IconColor` constants instead of string values directly for better code hints and type safety.
{% endhint %}

### &#x20;<a href="#nptwx" id="nptwx"></a>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.eagle.cool/plugin-api/api/folder.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.