Configuration Options
Relevant source files
The following files were used as context for generating this wiki page:
The Ghostbird add-on provides a dedicated options page for users to configure its behavior. This system allows customization of connection settings for the GhostText server and other operational parameters. The configuration is managed through a standard WebExtension options UI, ensuring a consistent user experience within Thunderbird.
Settings are persisted using browser.storage.local and are read by the background script when initiating a connection. The architecture follows a typical pattern where the UI, logic, and storage are decoupled.
Sources: doc/design.md:100-106, manifest_template.json:52-54
Options Architecture
The configuration system is composed of three main parts: the UI page (options.html), the logic script (options.js), and the browser's storage API for persistence. The background script (background.js) consumes these settings.
Sources: doc/design.md:96-106
Component Interaction
The following diagram illustrates the relationship between the components involved in managing configuration options.
This diagram shows that the user interacts with options.html, which uses options.js to manage settings in browser.storage.local. The main background.js script then reads these settings to configure its behavior.
Sources: doc/design.md:15-43, manifest_template.json:50-54
Data Flow for Saving Settings
When a user modifies and saves a setting, the options.js script handles the persistence and provides feedback.
This sequence shows the process of saving settings, which is facilitated by the webext-options-sync library, as indicated by its inclusion in the project's dependencies.
Sources: doc/design.md:100-106, package.json:67, ext/options.css:45-49
Options UI
The user interface for configuration is defined in ext/options.html. It is a simple HTML document that provides a form for user input.
Sources: ext/options.html
UI Structure
The page consists of a <ghostbird-options> custom element which contains a <form>. The form includes input fields for each configurable option.
<!-- Source: ext/options.html:7-29 -->
<ghostbird-options>
<form>
<label for="serverPort"></label>
<label>
<input
id="serverPort"
name="serverPort"
type="number"
min="1"
max="65535"
size="4"
required
>
</label>
<label for="enableNotifications"></label>
<label>
<input
id="enableNotifications"
name="enableNotifications"
type="checkbox"
>
</label>
<span></span>
<span
><input type="reset"></span
>
</form>
<div class="progress"></div>
</ghostbird-options>
The styling for this page is provided by ext/options.css, which imports standard Thunderbird in-content styles to maintain a consistent look and feel. It also defines styles for the form layout and feedback messages like "Saved" or "Error".
Sources: ext/options.html:1-29, ext/options.css:1-58
Available Options
The following options are available on the configuration page:
| Option | UI Element | Name Attribute | Type | Description |
|---|---|---|---|---|
| Server Port | Number Input | serverPort | number | The port number on localhost where the GhostText server is listening. The default is 4001. |
| Enable Notifications | Checkbox | enableNotifications | boolean | Toggles whether to show system notifications for events like connection success or failure. |
Sources: ext/options.html:11-25, doc/design.md:105-106, README.md:120
Integration with Thunderbird
The options page is registered with Thunderbird through the manifest_template.json file. The options_ui key specifies the HTML file to be used, making it accessible from the add-on's entry in Thunderbird's Add-on Manager.
// Source: manifest_template.json:52-54
"options_ui": {
"page": "options.html"
},
This is the standard mechanism for WebExtensions to provide a configuration interface.
Sources: manifest_template.json:52-54
Other Configuration
While the options page covers runtime settings, some composition behavior is configured directly within Thunderbird's own settings. For instance, switching between HTML and Plain Text composition is managed via Account Settings > Composition & Addressing, not within the Ghostbird options page. This setting determines the format of the content that Ghostbird will handle.
Sources: doc/faq.md:41-61