- Introduction
- Getting Started
- Initializing the Preferences Service
- Interacting with the Preferences Service from the Main Process
- Interacting with the Preferences Service from the Renderer Process
- Field Types
- Icons
This module provides users of the Electron desktop application development framework with with a simple, consistent interface for managing user preferences. It includes two primary components:
- A GUI interface within which the users of your application can manage their preferences.
- An API for interacting with the service.
Using the API, developers can:
- Define default preferences
- Read / write values on demand
- Define the layout of the preferences window.
To see the library in action, clone this repository and see the demo Electron app that is included within the example folder:
$ git clone https://github.com/tkambler/electron-preferences.git
$ cd electron-preferences
$ npm i
$ npm run example
Within your application's main process, create a new instance of the ElectronPreferences class, as shown below.
const electron = require('electron');
const { app } = electron;
const path = require('path');
const os = require('os');
const ElectronPreferences = require('electron-preferences');
const preferences = new ElectronPreferences({
/**
* Where should preferences be saved?
*/
'dataStore': path.resolve(app.getPath('userData'), 'preferences.json'),
/**
* Default values.
*/
'defaults': {
'notes': {
'folder': path.resolve(os.homedir(), 'Notes')
},
'markdown': {
'auto_format_links': true,
'show_gutter': false
},
'preview': {
'show': true
},
'drawer': {
'show': true
}
},
/**
* If the `onLoad` method is specified, this function will be called immediately after
* preferences are loaded for the first time. The return value of this method will be stored as the
* preferences object.
*/
'onLoad': (preferences) => {
// ...
return preferences;
},
/**
* The preferences window is divided into "sections." Each section has a label, an icon, and one or
* more fields associated with it. Each section should also be given a unique ID.
*/
'sections': [
{
'id': 'about',
'label': 'About You',
/**
* See the list of available icons below.
*/
'icon': 'single-01',
'form': {
'groups': [
{
/**
* Group heading is optional.
*/
'label': 'About You',
'fields': [
{
'label': 'First Name',
'key': 'first_name',
'type': 'text',
/**
* Optional text to be displayed beneath the field.
*/
'help': 'What is your first name?'
},
{
'label': 'Last Name',
'key': 'last_name',
'type': 'text'
},
{
'label': 'Gender',
'key': 'gender',
'type': 'dropdown',
'options': [
{ 'label': 'Male', 'value': 'male' },
{ 'label': 'Female', 'value': 'female' },
{ 'label': 'Unspecified', 'value': 'unspecified' },
]
}
]
}
]
}
},
{
'id': 'notes',
'label': 'Notes',
'icon': 'folder-15',
'form': {
'groups': [
{
'label': 'Stuff',
'fields': [
{
'label': 'Read notes from folder',
'key': 'folder',
'type': 'directory'
},
{
'heading': 'Important Message',
'content': '<p>The quick brown fox jumps over the long white fence. The quick brown fox jumps over the long white fence. The quick brown fox jumps over the long white fence. The quick brown fox jumps over the long white fence.</p>',
'type': 'message'
}
]
}
]
}
},
{
'id': 'space',
'label': 'Other Settings',
'icon': 'spaceship',
'form': {
'groups': [
{
'label': 'Other Settings',
'fields': [
{
'label': 'Phone Number',
'key': 'phone_number',
'type': 'text'
}
]
}
]
}
}
]
});
// Show the preferences window on demand.
preferences.show();
// Get a value from the preferences data store
const myPref = preferences.value('some.nested.key');
// Save a value within the preferences data store
preferences.value('some.nested.key', 'my-value');
const { ipcRenderer, remote } = require('electron');
// Fetch the preferences object
const preferences = ipcRenderer.sendSync('getPreferences');
// Display the preferences window
ipcRenderer.send('showPreferences');
// Listen to the `preferencesUpdated` event to be notified when preferences are changed.
ipcRenderer.on('preferencesUpdated', (e, preferences) => {
console.log('Preferences were updated', preferences);
});
// Instruct the preferences service to update the preferences object from within the renderer.
ipcRenderer.sendSync('setPreferences', { ... });
The library includes built-in support for the following field types:
- Text
- Dropdown
- Message
- Folder selection
Adding support for additional field types if easy, if you're familiar with React. PR's for such additions are welcome.
The following icons come packaged with the library and can be specified when you define the layout of your preferences window.
| Name | Icon |
|---|---|
| archive-2 |  |
| archive-paper |  |
| award-48 |  |
| badge-13 |  |
| bag-09 |  |
| barcode-qr |  |
| bear-2 |  |
| bell-53 |  |
| bookmark-2 |  |
| briefcase-24 |  |
| calendar-60 |  |
| camera-20 |  |
| cart-simple |  |
| chat-46 |  |
| check-circle-07 |  |
| cloud-26 |  |
| compass-05 |  |
| dashboard-level |  |
| diamond |  |
| edit-78 |  |
| email-84 |  |
| eye-19 |  |
| favourite-31 |  |
| flag-points-32 |  |
| flash-21 |  |
| folder-15 |  |
| gift-2 |  |
| grid-45 |  |
| handout |  |
| heart-2 |  |
| home-52 |  |
| image |  |
| key-25 |  |
| layers-3 |  |
| like-2 |  |
| link-72 |  |
| lock-open |  |
| lock |  |
| multiple-11 |  |
| notes |  |
| pencil |  |
| phone-2 |  |
| preferences |  |
| send-2 |  |
| settings-gear-63 |  |
| single-01 |  |
| single-folded-content |  |
| skull-2 |  |
| spaceship |  |
| square-download |  |
| square-upload |  |
| support-16 |  |
| trash-simple |  |
| turtle |  |
| vector |  |
| video-66 |  |
| wallet-43 |  |
| widget |  |
| world |  |
| zoom-2 |  |