{"id":13580718,"url":"https://github.com/ddanninger/electron-angular-preferences","last_synced_at":"2025-04-06T02:32:37.181Z","repository":{"id":57221505,"uuid":"180641522","full_name":"ddanninger/electron-angular-preferences","owner":"ddanninger","description":"Electron extendable preference window build in angular 7","archived":false,"fork":false,"pushed_at":"2019-05-10T12:47:23.000Z","size":1664,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-24T00:43:36.448Z","etag":null,"topics":["angular","electron","electron-preferences","preferences"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ddanninger.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-04-10T18:33:14.000Z","updated_at":"2022-05-23T06:13:48.000Z","dependencies_parsed_at":"2022-08-29T01:51:04.988Z","dependency_job_id":null,"html_url":"https://github.com/ddanninger/electron-angular-preferences","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddanninger%2Felectron-angular-preferences","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddanninger%2Felectron-angular-preferences/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddanninger%2Felectron-angular-preferences/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddanninger%2Felectron-angular-preferences/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ddanninger","download_url":"https://codeload.github.com/ddanninger/electron-angular-preferences/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223233221,"owners_count":17110621,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["angular","electron","electron-preferences","preferences"],"created_at":"2024-08-01T15:01:54.501Z","updated_at":"2024-11-05T19:33:11.713Z","avatar_url":"https://github.com/ddanninger.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# Electron Angular Preferences\n\n- [Introduction](#introduction)\n- [Getting Started](#getting-started)\n- [Initializing the Preferences Service](#initializing-the-preferences-service)\n- [Interacting with the Preferences Service from the Main Process](#interacting-with-the-preferences-service-from-the-main-process)\n- [Interacting with the Preferences Service from the Renderer Process](#interacting-with-the-preferences-service-from-the-renderer-process)\n- [Field Types](#field-types)\n- [Icons](#icons)\n\n## Inspiration \u0026 Base code\n\nThank you to -\u003e [Electron Preferences](https://github.com/tkambler/electron-preferences) for the inspiration \u0026 base structure\n\n## Introduction\n\nProvides [Electron](https://electronjs.org/) developers with with a simple, consistent interface for managing user preferences. It includes two primary components:\n\n- A GUI interface within which the users of your application can manage their preferences.\n- An API for interacting with the service.\n\nUsing the API, developers can:\n\n- Define default preferences\n- Create custom validations\n- Read / write values on demand\n- Define the layout of the preferences window.\n\nTo see the library in action, clone this repository and see the demo application that is included within the `example` folder:\n\n    $ git clone https://github.com/ddanninger/electron-angular-preferences.git\n    $ cd electron-angular-preferences\n    $ npm i --no-optional\n    $ npm run build\n    $ npm run example\n\n## Getting Started\n\n### Initializing the Preferences Service\n\nInstall with\n\n```\nnpm install electron-angular-preferences\n```\n\nWithin your application's main process, create a new instance of the `ElectronPreferences` class, as shown below. [preferences.js](https://github.com/ddanninger/electron-angular-preferences/blob/master/example/preferences.js)\n\n```\nconst electron = require('electron');\nconst app = electron.app;\nconst path = require('path');\nconst os = require('os');\nconst ElectronPreferences = require('electron-angular-preferences');\n\nconst preferences = new ElectronPreferences({\n    /**\n     * Where should preferences be saved?\n     */\n    dataStore: path.resolve(app.getPath('userData'), 'preferences.json'),\n    /**\n     * Default values.\n     */\n    defaults: {\n        'notes': {\n            'folder': path.resolve(os.homedir(), 'Notes')\n        },\n        'markdown': {\n            'auto_format_links': true,\n            'show_gutter': false\n        },\n        'preview': {\n            'show': true\n        },\n        'drawer': {\n            'show': true\n        }\n    },\n    /**\n     * If the `onLoad` method is specified, this function will be called immediately after\n     * preferences are loaded for the first time. The return value of this method will be stored as the\n     * preferences object.\n     */\n    onLoad: (preferences) =\u003e {\n        // ...\n        return preferences;\n    },\n    /**\n     * Extend the BrowserWindow of the Preference Window\n     */\n     window: {\n         'icon': 'path-to-icon.png'\n     },\n     /**\n     * Custom validators (value: string) =\u003e {}\n     * value is the filled value\n     */\n     validators: {\n     validate_me: val =\u003e {\n            if (val === 'test') {\n                return true;\n            }\n            return false;\n        }\n     },\n    /**\n    * Angular Validation Mechanism\n    */\n    validationOn: 'submit', // blur | submit | null or do not set empty for default behaviour\n    /**\n    * Actions to call for buttons ( e.g usecase you want to implement a \"Test Connection\" button)\n    * (form: []) =\u003e {} will return the group of the button , with the values of all form fields in this group\n    */\n    actions: {\n        btn_action: form =\u003e {\n            return 'This message will be shown inline';\n        }\n    },\n    /**\n     * The preferences window is divided into sections. Each section has a label, an icon, and one or\n     * more fields associated with it. Each section should also be given a unique ID.\n     */\n    sections: [\n    {\n      name: 'about',\n      label: 'About You',\n      icon: 'globe',\n      form: {\n        groups: [\n          {\n            label: 'About You',\n            fields: [\n              {\n                label: 'Validate me',\n                name: 'validate_me',\n                type: 'text',\n                help: 'field must be \"test\"',\n                validator: 'validate_me',\n                errorMessage: 'Field value is not \"test\"!'\n              },\n              {\n                label: 'First Name',\n                name: 'first_name',\n                type: 'text',\n                help: 'What is your first name?'\n              },\n              {\n                label: 'Last Name',\n                name: 'last_name',\n                type: 'text',\n                help: 'What is your last name?'\n              },\n              {\n                label: 'Gender',\n                name: 'gender',\n                type: 'dropdown',\n                options: [\n                  { label: 'Male', value: 'male' },\n                  { label: 'Female', value: 'female' },\n                  { label: 'Unspecified', value: 'unspecified' }\n                ],\n                help: 'What is your gender?'\n              },\n              {\n                label: 'Age',\n                name: 'age',\n                type: 'text',\n                inputType: 'number'\n              },\n              {\n                label: 'Which of the following foods do you like?',\n                name: 'foods',\n                type: 'checkbox',\n                options: [\n                  { label: 'Ice Cream', value: 'ice_cream' },\n                  { label: 'Carrots', value: 'carrots' },\n                  { label: 'Cake', value: 'cake' },\n                  { label: 'Spinach', value: 'spinach' }\n                ],\n                help: 'Select one or more foods that you like.'\n              }\n            ]\n          }\n        ]\n      }\n    },\n    {\n      name: 'notes',\n      label: 'Notes',\n      icon: 'certificate',\n      form: {\n        groups: [\n          {\n            label: 'Stuff',\n            fields: [\n              {\n                label: 'Read notes from folder',\n                name: 'folder',\n                type: 'directory',\n                help: 'The location where your notes will be stored.'\n              },\n              {\n                heading: 'Important Message',\n                content:\n                  '\u003cp\u003eThe 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.\u003c/p\u003e',\n                type: 'message'\n              }\n            ]\n          }\n        ]\n      }\n    },\n    {\n      name: 'space',\n      label: 'Other Settings',\n      icon: 'folder',\n      form: {\n        groups: [\n          {\n            label: 'Other Settings',\n            fields: [\n              {\n                label: 'Enable',\n                name: 'enable_debug',\n                type: 'boolean',\n                help: 'Do you want to enable the debug mode?'\n              },\n              {\n                label: 'Test button',\n                name: 'button',\n                type: 'button',\n                action: 'btn_action',\n                help: 'Click me to do something'\n              },\n              {\n                label: 'Phone Number',\n                name: 'phone_number',\n                type: 'text',\n                help: 'What is your phone number?'\n              },\n              {\n                label: 'Foo or Bar?',\n                name: 'foobar',\n                type: 'radio',\n                options: [\n                  { label: 'Foo', value: 'foo' },\n                  { label: 'Bar', value: 'bar' },\n                  { label: 'FooBar', value: 'foobar' }\n                ],\n                help: 'Foo? Bar?'\n              }\n            ]\n          }\n        ]\n      }\n    }\n  ]\n});\n```\n\n### Interacting with the Preferences Service from the Main Process\n\n```\n// Show the preferences window on demand.\npreferences.show();\n\n// Get a value from the preferences data store\nconst myPref = preferences.value('some.nested.key');\n\n// Save a value within the preferences data store\npreferences.value('some.nested.key', 'my-value');\n\n// Subscribing to preference changes.\npreferences.on('save', (preferences) =\u003e {\n    console.log(`Preferences were saved.`, JSON.stringify(preferences, null, 4));\n});\n```\n\n### Interacting with the Preferences Service from the Renderer Process\n\n```\nconst { ipcRenderer, remote } = require('electron');\n\n// Fetch the preferences object\nconst preferences = ipcRenderer.sendSync('getPreferences');\n\n// Display the preferences window\nipcRenderer.send('showPreferences');\n\n// Listen to the `preferencesUpdated` event to be notified when preferences are changed.\nipcRenderer.on('preferencesUpdated', (e, preferences) =\u003e {\n    console.log('Preferences were updated', preferences);\n});\n\n// Instruct the preferences service to update the preferences object from within the renderer.\nipcRenderer.sendSync('setPreferences', { ... });\n```\n\n## Actions\n\nDefining actions via the action attribute\nAn action can return either a string or an object \n\n```{ message: string, color: string }``` \n\nwhere color stands for the text color.\n\n### Observable Actions\n\nObservable action names should end with $\n\n```\nbtn_actionObject$: form =\u003e {\n  const domain = form.domain;\n  return interval(1000).pipe(\n    take(1),\n    switchMap(() =\u003e from(ping.promise.probe(domain))),\n    map(({ alive, avg }) =\u003e {\n      if (!alive) {\n        return { message: `I couldnt ping ${domain}`, color: 'red' };\n      }\n      return { message: `I pinged ${domain} and avg=${avg}`, color: 'green' };\n    })\n  );\n}\n```\n\n### Usecases\n\ne.g you want to implement a test connection button to validate if the domain is reachable\n\n## Field Types\n\nThe library includes built-in support for the following field types:\n\n- Text ( text )\n- Dropdown ( dropdown )\n- Message ( message )\n- Folder selection ( directory )\n- Checkbox ( checkbox )\n- Radio ( radio )\n- Switch ( boolean )\n- Spinner Button ( spinner-button )\n- Button ( button )\n- Shortcut ( shortcut )\n\n## Icons\n\n[Font Awesome 5](https://fontawesome.com/icons?d=\u0026s=solid\u0026m=free) Free, Solid icons can be used\n\n## Known issues\n\n- Validators and Action buttons still need some testing and improvements\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fddanninger%2Felectron-angular-preferences","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fddanninger%2Felectron-angular-preferences","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fddanninger%2Felectron-angular-preferences/lists"}