Setting up Configuration for Your Plugin

This guide will help you correctly add configuration to your plugin.

Setup

To enable configuration in your plugin, ensure that your setup.json file is correctly structured. The config field must be set to either an object (for configurations) or false (for no configuration), as shown below:

{
  "id": "example",
  "version": "1.0.0",
  "config": {
    "search": ["value-1", "value-2"]
  },
  "multiple_choice": false,
  "name": "Example Plugin",
  "description": "This is an example plugin. Notice that the config value is set to an object.",
  "logo": "https://example.com/logo.png",
  "api_url": "https://example.com/api"
}

Making Your Configuration Effective

For your configuration to take effect, the setup.json file should be accessible at a URL structured as follows: https://pluginurl.com/:config/setup.json, where :config is replaced by your actual configuration details. The configuration can be passed in various formats, such as a Base64-encoded string, a boolean, or other encoded values.

For instance, if you are scraping two sites, you could allow users to select which one to scrape in the configuration.

The configuration object should look like this:

{
  "search": ["value-1", "value-2"]
}

The values in the array are then appended to the search/:os/ before the :query url param, forming a URL like: https://pluginurl.com/search/:os/value-1/value-2/query

No Configuration Page Required

If your plugin doesn’t require a configuration page, set the config field to false:

{
  "id": "example",
  "version": "1.0.0",
  "config": false,
  "multiple_choice": false,
  "name": "Example Plugin",
  "description": "This is an example plugin. The config value is set to false, indicating no configuration page.",
  "logo": "https://example.com/logo.png",
  "api_url": "https://example.com/api"
}

Example

Assume you are scraping two sites: https://example.com/ and https://httpbin.org/, referred to as “1” and “2” respectively. If you want users to retrieve results only from example.com, the setup.json would be accessible at https://pluginurl.com/1/setup.json.

Handling Other Endpoints

To handle configuration on additional endpoints, ensure that your server incorporates the configuration data directly in the endpoint URL, one level before the .json extension, as follows: https://pluginurl.com/search/Windows/:config/results.json.

Configuration Page

Most plugins will benefit from a configuration page, where users can customize their plugin settings. After the user selects their preferred settings, the server should generate a fully configured setup.json that users can copy and paste into Falkor.

Although not mandatory, we highly recommend setting up the configuration page at the /configure endpoint or the root endpoint / for accessibility and ease of use.