Creating an Eagle.cool Plugin: A Comprehensive Guide

Eagle.cool (simply Eagle) is a digital asset management app that became extensible in version 4 with a new plugin system (available in Eagle v4 or above). This guide will walk you through everything you need to know to develop a plugin for Eagle – from understanding the plugin structure and available APIs, to building, testing, and publishing your own plugin. We will also include example snippets, best practices, and even a sample prompt you can use with GPT to generate a plugin’s code. Let’s dive in!

Plugin Structure and Organization

An Eagle plugin is essentially a folder (or package) containing specific files that define the plugin’s metadata and functionality. Below is a typical structure for a simple Eagle plugin:

Plugin/                ← Plugin project folder
├─ manifest.json       ← Required manifest with plugin info
├─ logo.png            ← Plugin icon (128×128 PNG)
├─ index.html          ← Main HTML interface (for window/UI plugins)
└─ js/
    └─ plugin.js       ← Main JavaScript code for plugin logic
    

Required Files:

• manifest.json – Every plugin must include this file. It contains the plugin’s metadata such as name, version, unique ID, icon path, and entry points for your code. The manifest also specifies the plugin type configuration. For example, a “window” plugin uses a “main” section to define how to launch its window, whereas a format extension uses a “preview” section instead (more on plugin types below). An example minimal manifest for a window plugin might look like:

{
    "id": "LB5UL2P0Q9FFF",            // unique plugin ID
    "version": "1.0.0",              // version number
    "name": "Hello World",           // plugin name
    "logo": "https://narcolepticnerd.b-cdn.net/logo.png",             // icon file path
    "keywords": ["sample", "demo"],  // search keywords
    "main": {
        "url": "index.html",         // the HTML entry point
        "width": 640,                // window width
        "height": 480               // window height
    }
}
    

Other Required Files:

• logo.png – The plugin’s icon, shown in Eagle’s plugin list and Plugin Center. It should be a 128×128 pixel image (preferably PNG with transparency).
• index.html – The main HTML file for your plugin’s interface or content. When the plugin runs, Eagle will open this HTML in a dedicated window (for Window/Background plugins) or in a panel (for Inspector plugins) or as a viewer (for Format plugins). Your HTML can include any standard web content (HTML/CSS) and should load your plugin’s script.
• js/plugin.js – The main JavaScript file containing the plugin’s logic. This runs in Eagle’s plugin environment (Chromium + Node.js) and has access to Eagle’s plugin API via a global eagle object. In plugin.js you typically attach event handlers and use Eagle’s API to interact with the app.

Plugin Types and Manifest Configuration

Eagle supports four types of plugins, each with a different purpose and slight differences in how you configure them. These types are illustrated below, and understanding them will help you set up the correct fields in your manifest.json.

1. Window Plugin: A plugin that opens a UI window when the user invokes it.
2. Background Service Plugin: A plugin that runs automatically in the background when Eagle launches.
3. Format Extension Plugin: A plugin that extends Eagle’s support for new file formats.
4. Inspector Extension Plugin: A plugin that adds a custom panel in Eagle’s right-hand Inspector sidebar.
    

Using Eagle’s Plugin API (Methods & Capabilities)

Eagle provides a powerful Plugin API for plugins to interact with the application and the user’s library. This API is accessed through the global eagle object in your plugin’s JavaScript. The Eagle plugin environment combines Web APIs (because it’s Chromium-based) and Node.js APIs, plus Eagle’s own APIs. In summary, your plugin can do things like:

• Retrieve data from Eagle: e.g. get the currently selected items, list items in a folder, read tags or folders, etc.
• Modify or add data in Eagle: create new items, update metadata, move items to folders, add tags, etc.
• Control plugin windows and dialogs: adjust your plugin window’s size/position, open dialogs, or show notifications.
• Use system features: The plugin API allows using the clipboard (copy/paste images or text), handling drag-and-drop of files, interacting with the operating system shell (opening a file in an external program, etc.), and more.
• Listen to events: Eagle exposes various events to react to changes, such as eagle.onPluginCreate, eagle.onPluginShow, and eagle.onThemeChanged for UI updates.

Development Workflow: From Setup to Deployment

Developing an Eagle plugin involves a few key stages: setting up your environment, creating the plugin skeleton, coding and testing, then packaging and publishing. Here’s a step-by-step workflow:

1. Setup Eagle and Enable Developer Mode: Make sure you have the Eagle desktop application installed (v4 or above) and enable Developer Mode.
2. Create a New Plugin: Using the “Create Plugin” dialog in Eagle, select the type of plugin you want to create (Window, Background, Format, or Inspector).
3. Run & Inspect the Example Plugin: Test that the plugin loads by clicking it in Eagle’s plugin menu.
4. Open the Plugin in Your Code Editor: Open the plugin folder and edit the files to implement your plugin functionality.
5. Testing & Debugging: Use console logs and DevTools to debug and test the plugin’s functionality.
6. Prepare for Distribution: Once your plugin is working, use Eagle’s “Pack Plugin” feature to package it into an .eagleplugin file for sharing.
7. Publishing (Optional): If you want to share your plugin with others, submit it to the Eagle Plugin Center for distribution.

Examples and Best Practices

Here are a few plugin ideas and examples that align with the different plugin types, along with best practices to follow:

• One-Click Tools (Window Plugin): Examples: an image format converter, a batch image resizer, etc.
• Background Services: Examples: an auto-tagging plugin, cloud sync plugin, etc.
• Format Extensions: Examples: adding support for RAW image formats, 3D model previews, etc.
• Inspector Plugins: Examples: adding EXIF metadata viewers for images, codec information for videos, etc.

Detailed Prompt for GPT (Example)

To spark some inspiration, here is an example of a detailed prompt you could use with GPT to generate a functional Eagle.cool plugin:

Task: Generate the code for an Eagle.cool plugin.

Plugin Type: Window Plugin (opens a UI window when clicked).

Plugin Name: “Bulk Tagger”.

Description/Features: This plugin will allow the user to add a specific tag to all currently selected items in Eagle. When the user clicks the plugin, it should open a window with a text input for the tag name and an "Add Tag" button. On clicking the button, the plugin will use the Eagle API to add that tag to each selected item, then show a confirmation message.

Requirements:
- Provide a manifest.json with appropriate fields (unique id, name "Bulk Tagger", version 1.0.0, an icon reference, etc.). Configure it as a window plugin.
- Provide an index.html that includes a text input and an "Add Tag" button in the body.
- Provide a plugin.js that:
  - Listens for eagle.onPluginCreate to initialize the UI.
  - Attaches an event listener to the "Add Tag" button. When clicked, it reads the tag name from the input field.
  - Uses eagle.item.getSelected() to get all selected items.
  - Uses eagle.tag.addTags(...) to add the specified tag to all those items.
  - Uses eagle.notification.show(...) to notify the user of success.