diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/backend_api.md | 22 | ||||
-rw-r--r-- | docs/configuration.md | 8 | ||||
-rw-r--r-- | docs/frontend_api.md | 56 | ||||
-rw-r--r-- | docs/integration.md | 58 | ||||
-rw-r--r-- | docs/updating.md | 10 |
5 files changed, 77 insertions, 77 deletions
diff --git a/docs/backend_api.md b/docs/backend_api.md index a9d29ac..a46927b 100644 --- a/docs/backend_api.md +++ b/docs/backend_api.md | |||
@@ -1,8 +1,8 @@ | |||
1 | # Backend API | 1 | # Backend API |
2 | 2 | ||
3 | Provides a set of helper functions to integrate the recipe into [Ferdi](https://ferdium.org). | 3 | Provides a set of helper functions to integrate the recipe into [Ferdium](https://ferdium.org). |
4 | 4 | ||
5 | ## Ferdi Backend Class Methods | 5 | ## Ferdium Backend Class Methods |
6 | 6 | ||
7 | * [validateUrl](#validateurl) | 7 | * [validateUrl](#validateurl) |
8 | * [overrideUserAgent](#overrideuseragent) | 8 | * [overrideUserAgent](#overrideuseragent) |
@@ -29,7 +29,7 @@ Validate if the given URL is a valid service instance. | |||
29 | 29 | ||
30 | ```js | 30 | ```js |
31 | // RocketChat integration | 31 | // RocketChat integration |
32 | module.exports = Ferdi => class RocketChat extends Ferdi { | 32 | module.exports = Ferdium => class RocketChat extends Ferdium { |
33 | async validateUrl(url) { | 33 | async validateUrl(url) { |
34 | try { | 34 | try { |
35 | const resp = await window.fetch(`${url}/api/info`, { | 35 | const resp = await window.fetch(`${url}/api/info`, { |
@@ -61,11 +61,11 @@ Override the user agent used inside the service webview. | |||
61 | #### Usage | 61 | #### Usage |
62 | 62 | ||
63 | ```js | 63 | ```js |
64 | module.exports = Ferdi => class Discord extends Ferdi { | 64 | module.exports = Ferdium => class Discord extends Ferdium { |
65 | overrideUserAgent() { | 65 | overrideUserAgent() { |
66 | // Remove Ferdi's signature from the user agent | 66 | // Remove Ferdium's signature from the user agent |
67 | return window.navigator.userAgent.replace( | 67 | return window.navigator.userAgent.replace( |
68 | /(Ferdi|Electron)\/\S+ \([^)]+\)/g, | 68 | /(Ferdium|Electron)\/\S+ \([^)]+\)/g, |
69 | "" | 69 | "" |
70 | ); | 70 | ); |
71 | } | 71 | } |
@@ -73,7 +73,7 @@ module.exports = Ferdi => class Discord extends Ferdi { | |||
73 | ``` | 73 | ``` |
74 | 74 | ||
75 | ```js | 75 | ```js |
76 | module.exports = Ferdi => class Example extends Ferdi { | 76 | module.exports = Ferdium => class Example extends Ferdium { |
77 | overrideUserAgent() { | 77 | overrideUserAgent() { |
78 | // Use a completely different user agent | 78 | // Use a completely different user agent |
79 | return "Mozilla/2.02Gold (Win95; I)"; | 79 | return "Mozilla/2.02Gold (Win95; I)"; |
@@ -98,7 +98,7 @@ Valid URL patterns can be referred from [here](https://www.electronjs.org/docs/a | |||
98 | 98 | ||
99 | ```js | 99 | ```js |
100 | // Hangouts Chat integration | 100 | // Hangouts Chat integration |
101 | module.exports = Ferdi => class HangoutsChat extends Ferdi { | 101 | module.exports = Ferdium => class HangoutsChat extends Ferdium { |
102 | modifyRequestHeaders() { | 102 | modifyRequestHeaders() { |
103 | return [{ | 103 | return [{ |
104 | // Adding an origin header for all http requests from this recipe | 104 | // Adding an origin header for all http requests from this recipe |
@@ -123,7 +123,7 @@ Specify an array of known hosts from where certificates can be issued for this s | |||
123 | 123 | ||
124 | ```js | 124 | ```js |
125 | // msteams Chat integration | 125 | // msteams Chat integration |
126 | module.exports = Ferdi => class MicrosoftTeams extends Ferdi { | 126 | module.exports = Ferdium => class MicrosoftTeams extends Ferdium { |
127 | knownCertificateHosts() { | 127 | knownCertificateHosts() { |
128 | return [ | 128 | return [ |
129 | 'aka.ms', | 129 | 'aka.ms', |
@@ -152,14 +152,14 @@ module.exports = Ferdi => class MicrosoftTeams extends Ferdi { | |||
152 | 152 | ||
153 | ### Events | 153 | ### Events |
154 | 154 | ||
155 | Ferdi recipes can hook into the [electron webview events](https://electron.atom.io/docs/api/webview-tag/#dom-events) to trigger custom functions. | 155 | Ferdium recipes can hook into the [electron webview events](https://electron.atom.io/docs/api/webview-tag/#dom-events) to trigger custom functions. |
156 | 156 | ||
157 | This is necessary for services like TweetDeck where custom URL forwarding is needed during login. | 157 | This is necessary for services like TweetDeck where custom URL forwarding is needed during login. |
158 | 158 | ||
159 | #### Usage | 159 | #### Usage |
160 | 160 | ||
161 | ```js | 161 | ```js |
162 | module.exports = Ferdi => class Tweetdeck extends Ferdi { | 162 | module.exports = Ferdium => class Tweetdeck extends Ferdium { |
163 | events = { | 163 | events = { |
164 | 'did-get-redirect-request': '_redirectFix', | 164 | 'did-get-redirect-request': '_redirectFix', |
165 | } | 165 | } |
diff --git a/docs/configuration.md b/docs/configuration.md index a53c99d..8dff91b 100644 --- a/docs/configuration.md +++ b/docs/configuration.md | |||
@@ -1,6 +1,6 @@ | |||
1 | # Integration Config | 1 | # Integration Config |
2 | 2 | ||
3 | A [Ferdi](https://ferdium.org) recipe is a node module. In order to learn more about node modules and their configuration check the official [Node.js documentation](https://nodejs.org/api/modules.html) / [npm package.json documentation](https://docs.npmjs.com/files/package.json). | 3 | A [Ferdium](https://ferdium.org) recipe is a node module. In order to learn more about node modules and their configuration check the official [Node.js documentation](https://nodejs.org/api/modules.html) / [npm package.json documentation](https://docs.npmjs.com/files/package.json). |
4 | 4 | ||
5 | ## Table of Contents | 5 | ## Table of Contents |
6 | 6 | ||
@@ -21,7 +21,7 @@ Display name of the service. | |||
21 | 21 | ||
22 | `string` **version** _mandatory_<br /> | 22 | `string` **version** _mandatory_<br /> |
23 | Version number. Will be used for auto updating the integrations. The version number must be in a semver compatible format: eg `1.0.0`. | 23 | Version number. Will be used for auto updating the integrations. The version number must be in a semver compatible format: eg `1.0.0`. |
24 | **important:** the version will be used to figure out if a new recipe update should be deployed to the user. If you make changes to a recipe, **always** increase the version number or Ferdi won't update your recipe. | 24 | **important:** the version will be used to figure out if a new recipe update should be deployed to the user. If you make changes to a recipe, **always** increase the version number or Ferdium won't update your recipe. |
25 | 25 | ||
26 | `string` **license**<br /> | 26 | `string` **license**<br /> |
27 | The license of the integration. We prefer MIT, but here is a list of all the available SPDX licenses http://spdx.org/licenses/ | 27 | The license of the integration. We prefer MIT, but here is a list of all the available SPDX licenses http://spdx.org/licenses/ |
@@ -33,10 +33,10 @@ Link to your Github, Gitlab or Bitbucket public repository. Not used in the appl | |||
33 | The list of alternate names that this recipe can be called | 33 | The list of alternate names that this recipe can be called |
34 | 34 | ||
35 | `object` **config** _mandatory_<br /> | 35 | `object` **config** _mandatory_<br /> |
36 | This is the Ferdi-specific integration config. | 36 | This is the Ferdium-specific integration config. |
37 | 37 | ||
38 | * `string` **serviceURL**<br/> | 38 | * `string` **serviceURL**<br/> |
39 | Defines the URL that should be loaded into the Ferdi webview. | 39 | Defines the URL that should be loaded into the Ferdium webview. |
40 | <br /><br /> | 40 | <br /><br /> |
41 | If you want to load a simple URL like `https://www.messenger.com`, you can simply define it via the `serviceURL` parameter. If your service URL is team based, e.g. Slack or HipChat you can use `https://{teamId}.slack.com`. | 41 | If you want to load a simple URL like `https://www.messenger.com`, you can simply define it via the `serviceURL` parameter. If your service URL is team based, e.g. Slack or HipChat you can use `https://{teamId}.slack.com`. |
42 | <br /><br /> | 42 | <br /><br /> |
diff --git a/docs/frontend_api.md b/docs/frontend_api.md index 35b0918..af9acf8 100644 --- a/docs/frontend_api.md +++ b/docs/frontend_api.md | |||
@@ -1,5 +1,5 @@ | |||
1 | - [Frontend API](#frontend-api) | 1 | - [Frontend API](#frontend-api) |
2 | - [Ferdi Class Methods](#ferdi-class-methods) | 2 | - [Ferdium Class Methods](#ferdium-class-methods) |
3 | - [setBadge(directMessages, [indirectMessages])](#setbadgedirectmessages-indirectmessages) | 3 | - [setBadge(directMessages, [indirectMessages])](#setbadgedirectmessages-indirectmessages) |
4 | - [Arguments](#arguments) | 4 | - [Arguments](#arguments) |
5 | - [Usage](#usage) | 5 | - [Usage](#usage) |
@@ -35,9 +35,9 @@ | |||
35 | 35 | ||
36 | # Frontend API | 36 | # Frontend API |
37 | 37 | ||
38 | Provides a set of helper functions to integrate the service into [Ferdi](https://ferdium.org). | 38 | Provides a set of helper functions to integrate the service into [Ferdium](https://ferdium.org). |
39 | 39 | ||
40 | ## Ferdi Class Methods | 40 | ## Ferdium Class Methods |
41 | 41 | ||
42 | ### setBadge(directMessages, [indirectMessages]) | 42 | ### setBadge(directMessages, [indirectMessages]) |
43 | 43 | ||
@@ -56,11 +56,11 @@ Sets the unread message badge | |||
56 | #### Usage | 56 | #### Usage |
57 | 57 | ||
58 | ```js | 58 | ```js |
59 | Ferdi.setBadge(4, 2); | 59 | Ferdium.setBadge(4, 2); |
60 | 60 | ||
61 | // or | 61 | // or |
62 | 62 | ||
63 | Ferdi.setBadge(3); | 63 | Ferdium.setBadge(3); |
64 | ``` | 64 | ``` |
65 | 65 | ||
66 | ### setDialogTitle(title) | 66 | ### setDialogTitle(title) |
@@ -76,7 +76,7 @@ Sets the active dialog title to the app title | |||
76 | #### Usage | 76 | #### Usage |
77 | 77 | ||
78 | ```js | 78 | ```js |
79 | Ferdi.setDialogTitle('Dialog title'); | 79 | Ferdium.setDialogTitle('Dialog title'); |
80 | ``` | 80 | ``` |
81 | 81 | ||
82 | ### injectCSS(pathToCssFile) | 82 | ### injectCSS(pathToCssFile) |
@@ -95,20 +95,20 @@ Injects the contents of one or more CSS files into the current webview | |||
95 | const path = require('path'); | 95 | const path = require('path'); |
96 | 96 | ||
97 | // inject a single css file | 97 | // inject a single css file |
98 | Ferdi.injectCSS(path.join(__dirname, 'style.css')); | 98 | Ferdium.injectCSS(path.join(__dirname, 'style.css')); |
99 | 99 | ||
100 | // inject multiple css files | 100 | // inject multiple css files |
101 | const globalStyles = path.join(__dirname, 'global.css'); | 101 | const globalStyles = path.join(__dirname, 'global.css'); |
102 | const focusModeStyles = path.join(__dirname, 'focusmode.css'); | 102 | const focusModeStyles = path.join(__dirname, 'focusmode.css'); |
103 | 103 | ||
104 | Ferdi.injectCSS(globalStyles, focusModeStyles); | 104 | Ferdium.injectCSS(globalStyles, focusModeStyles); |
105 | ``` | 105 | ``` |
106 | 106 | ||
107 | ### injectJSUnsafe(pathToJsFile) | 107 | ### injectJSUnsafe(pathToJsFile) |
108 | 108 | ||
109 | Injects the contents of one or more JavaScript files into the current webview without context isolation | 109 | Injects the contents of one or more JavaScript files into the current webview without context isolation |
110 | 110 | ||
111 | Ferdi uses context isolation to prevent services from accessing Node.js APIs in the webview. | 111 | Ferdium uses context isolation to prevent services from accessing Node.js APIs in the webview. |
112 | If you want to expose objects to the service (eg. via the `window` object) or interact with the Javascript loaded by the service you must do so from a script injected with this method. | 112 | If you want to expose objects to the service (eg. via the `window` object) or interact with the Javascript loaded by the service you must do so from a script injected with this method. |
113 | Trying to overwrite properties of the `window` object or other objects or trying to interact with the Javascript loaded by the service from `webview.js` will fail due to context isolation. | 113 | Trying to overwrite properties of the `window` object or other objects or trying to interact with the Javascript loaded by the service from `webview.js` will fail due to context isolation. |
114 | 114 | ||
@@ -126,18 +126,18 @@ The code is executed as if part of the body of a Javascript function, ie. you sh | |||
126 | const path = require('path'); | 126 | const path = require('path'); |
127 | 127 | ||
128 | // inject a single css file | 128 | // inject a single css file |
129 | Ferdi.injectJSUnsafe(path.join(__dirname, 'webview-unsafe.js')); | 129 | Ferdium.injectJSUnsafe(path.join(__dirname, 'webview-unsafe.js')); |
130 | 130 | ||
131 | // inject multiple css files | 131 | // inject multiple css files |
132 | const globalScripts = path.join(__dirname, 'global.js); | 132 | const globalScripts = path.join(__dirname, 'global.js); |
133 | const focusModeScripts = path.join(__dirname, 'focusmode.js); | 133 | const focusModeScripts = path.join(__dirname, 'focusmode.js); |
134 | 134 | ||
135 | Ferdi.injectCSS(globalScripts, focusModeScripts); | 135 | Ferdium.injectCSS(globalScripts, focusModeScripts); |
136 | ``` | 136 | ``` |
137 | 137 | ||
138 | ### loop(action) | 138 | ### loop(action) |
139 | 139 | ||
140 | Runs an action every X milliseconds (Ferdi default is currently 1s) | 140 | Runs an action every X milliseconds (Ferdium default is currently 1s) |
141 | 141 | ||
142 | #### Arguments | 142 | #### Arguments |
143 | 143 | ||
@@ -149,19 +149,19 @@ Runs an action every X milliseconds (Ferdi default is currently 1s) | |||
149 | // slack integration | 149 | // slack integration |
150 | const path = require('path'); | 150 | const path = require('path'); |
151 | 151 | ||
152 | module.exports = Ferdi => { | 152 | module.exports = Ferdium => { |
153 | const getMessages = () => { | 153 | const getMessages = () => { |
154 | const directMessages = $('.unread_highlights, .unread_highlight').not( | 154 | const directMessages = $('.unread_highlights, .unread_highlight').not( |
155 | '.hidden', | 155 | '.hidden', |
156 | ).length; | 156 | ).length; |
157 | const indirectMessages = $('.unread').length - directMessages; | 157 | const indirectMessages = $('.unread').length - directMessages; |
158 | 158 | ||
159 | Ferdi.setBadge(directMessages, indirectMessages); | 159 | Ferdium.setBadge(directMessages, indirectMessages); |
160 | }; | 160 | }; |
161 | 161 | ||
162 | Ferdi.loop(getMessages); | 162 | Ferdium.loop(getMessages); |
163 | 163 | ||
164 | Ferdi.injectCSS(path.join(__dirname, 'style.css')); | 164 | Ferdium.injectCSS(path.join(__dirname, 'style.css')); |
165 | }; | 165 | }; |
166 | ``` | 166 | ``` |
167 | 167 | ||
@@ -177,22 +177,22 @@ Runs `fn` on every notification created by the service before sending them to th | |||
177 | 177 | ||
178 | ```js | 178 | ```js |
179 | // messenger integration | 179 | // messenger integration |
180 | module.exports = Ferdi => { | 180 | module.exports = Ferdium => { |
181 | const getMessages = () => { | 181 | const getMessages = () => { |
182 | let count = document.querySelectorAll( | 182 | let count = document.querySelectorAll( |
183 | '._5fx8:not(._569x),._1ht3:not(._569x)', | 183 | '._5fx8:not(._569x),._1ht3:not(._569x)', |
184 | ).length; | 184 | ).length; |
185 | const messageRequestsElement = document.querySelector('._5nxf'); | 185 | const messageRequestsElement = document.querySelector('._5nxf'); |
186 | if (messageRequestsElement) { | 186 | if (messageRequestsElement) { |
187 | count += Ferdi.safeParseInt(messageRequestsElement.textContent); | 187 | count += Ferdium.safeParseInt(messageRequestsElement.textContent); |
188 | } | 188 | } |
189 | 189 | ||
190 | Ferdi.setBadge(count); | 190 | Ferdium.setBadge(count); |
191 | }; | 191 | }; |
192 | 192 | ||
193 | Ferdi.loop(getMessages); | 193 | Ferdium.loop(getMessages); |
194 | 194 | ||
195 | Ferdi.onNotify(notification => { | 195 | Ferdium.onNotify(notification => { |
196 | if (typeof notification.title !== 'string') { | 196 | if (typeof notification.title !== 'string') { |
197 | notification.title = | 197 | notification.title = |
198 | ((notification.title.props || {}).content || [])[0] || 'Messenger'; | 198 | ((notification.title.props || {}).content || [])[0] || 'Messenger'; |
@@ -209,7 +209,7 @@ You can use a `darkmode.css` to automatically get the service into a dark theme. | |||
209 | 209 | ||
210 | This handler should take the necessary steps to (de-)activate dark mode on the page, e.g. by clicking a button or flipping a switch. | 210 | This handler should take the necessary steps to (de-)activate dark mode on the page, e.g. by clicking a button or flipping a switch. |
211 | 211 | ||
212 | Ferdi won't activate DarkReader or inject `darkmode.css` if the recipe has defined a custom handler. If you still need to do this, you can use the `injectDarkModeStyle` or `enableDarkMode` function provided as the second argument. | 212 | Ferdium won't activate DarkReader or inject `darkmode.css` if the recipe has defined a custom handler. If you still need to do this, you can use the `injectDarkModeStyle` or `enableDarkMode` function provided as the second argument. |
213 | 213 | ||
214 | #### Arguments | 214 | #### Arguments |
215 | 215 | ||
@@ -229,7 +229,7 @@ Ferdi won't activate DarkReader or inject `darkmode.css` if the recipe has defin | |||
229 | 229 | ||
230 | ```JavaScript | 230 | ```JavaScript |
231 | // Handler that works for Reddit | 231 | // Handler that works for Reddit |
232 | Ferdi.handleDarkMode((isEnabled, helpers) => { | 232 | Ferdium.handleDarkMode((isEnabled, helpers) => { |
233 | // Open dropdown menu if not already open | 233 | // Open dropdown menu if not already open |
234 | const menu = document.querySelector('#USER_DROPDOWN_ID'); | 234 | const menu = document.querySelector('#USER_DROPDOWN_ID'); |
235 | if (menu.getAttribute('aria-expanded') === 'false') { | 235 | if (menu.getAttribute('aria-expanded') === 'false') { |
@@ -251,7 +251,7 @@ Ferdi.handleDarkMode((isEnabled, helpers) => { | |||
251 | // --- or --- | 251 | // --- or --- |
252 | 252 | ||
253 | // Helper that activates DarkReader and injects your darkmode.css at the same time | 253 | // Helper that activates DarkReader and injects your darkmode.css at the same time |
254 | Ferdi.handleDarkMode((isEnabled, helpers) => { | 254 | Ferdium.handleDarkMode((isEnabled, helpers) => { |
255 | if (isEnabled) { | 255 | if (isEnabled) { |
256 | helpers.enableDarkMode(); | 256 | helpers.enableDarkMode(); |
257 | if (!helpers.isDarkModeStyleInjected()) { | 257 | if (!helpers.isDarkModeStyleInjected()) { |
@@ -276,7 +276,7 @@ While exiting/closing/disabling the service, if you want to clear the local stor | |||
276 | #### Usage | 276 | #### Usage |
277 | 277 | ||
278 | ```JavaScript | 278 | ```JavaScript |
279 | Ferdi.clearStorageData(settings.id, { | 279 | Ferdium.clearStorageData(settings.id, { |
280 | storages: [ | 280 | storages: [ |
281 | 'appcache', | 281 | 'appcache', |
282 | 'serviceworkers', | 282 | 'serviceworkers', |
@@ -302,12 +302,12 @@ A utility method that can be used to safely parse the text content (handles null | |||
302 | #### Usage | 302 | #### Usage |
303 | 303 | ||
304 | ```JavaScript | 304 | ```JavaScript |
305 | Ferdi.safeParseInt(mySelector.innerText) | 305 | Ferdium.safeParseInt(mySelector.innerText) |
306 | ``` | 306 | ``` |
307 | 307 | ||
308 | ### setDialogTitle(title) | 308 | ### setDialogTitle(title) |
309 | 309 | ||
310 | When you want to set the title of the Ferdi window (while this service is active or in focus), you can use this function | 310 | When you want to set the title of the Ferdium window (while this service is active or in focus), you can use this function |
311 | 311 | ||
312 | #### Arguments | 312 | #### Arguments |
313 | 313 | ||
@@ -316,5 +316,5 @@ When you want to set the title of the Ferdi window (while this service is active | |||
316 | #### Usage | 316 | #### Usage |
317 | 317 | ||
318 | ```JavaScript | 318 | ```JavaScript |
319 | Ferdi.setDialogTitle(element ? element.textContent : null); | 319 | Ferdium.setDialogTitle(element ? element.textContent : null); |
320 | ``` | 320 | ``` |
diff --git a/docs/integration.md b/docs/integration.md index 1115454..d0b1460 100644 --- a/docs/integration.md +++ b/docs/integration.md | |||
@@ -1,10 +1,10 @@ | |||
1 | # Ferdi Recipe Documentation / Overview | 1 | # Ferdium Recipe Documentation / Overview |
2 | 2 | ||
3 | Recipes are responsible for providing the connection between the service itself (e.g. WhatsApp) and Ferdi, providing information like the number of current notifications or handling dark mode. | 3 | Recipes are responsible for providing the connection between the service itself (e.g. WhatsApp) and Ferdium, providing information like the number of current notifications or handling dark mode. |
4 | 4 | ||
5 | A Ferdi recipe is basically nothing else than a node module and is currently initialized on `dom-ready`. You access all of the [electron](http://electron.atom.io) modules as well. | 5 | A Ferdium recipe is basically nothing else than a node module and is currently initialized on `dom-ready`. You access all of the [electron](http://electron.atom.io) modules as well. |
6 | 6 | ||
7 | > âšī¸ New to Ferdi recipes and Electron? Then we recommend you read Jake Lee's ["Super simple guide to adding a new Ferdi service recipe"](https://blog.jakelee.co.uk/super-simple-guide-to-adding-a-new-ferdi-service-recipe/) which gives you an easy step-by-step guide on how to create and publish your recipe! | 7 | > âšī¸ New to Ferdium recipes and Electron? Then we recommend you read Jake Lee's ["Super simple guide to adding a new Ferdium service recipe"](https://blog.jakelee.co.uk/super-simple-guide-to-adding-a-new-ferdium-service-recipe/) which gives you an easy step-by-step guide on how to create and publish your recipe! |
8 | 8 | ||
9 | > âšī¸ If you have any problems packaging your recipes, if you are inexperienced with the tools used or have any other problems, we are here to help! Just open a new issue at https://github.com/ferdium/ferdium-recipes/issues/new and we can help you develop, test and publish your recipe | 9 | > âšī¸ If you have any problems packaging your recipes, if you are inexperienced with the tools used or have any other problems, we are here to help! Just open a new issue at https://github.com/ferdium/ferdium-recipes/issues/new and we can help you develop, test and publish your recipe |
10 | 10 | ||
@@ -12,7 +12,7 @@ A Ferdi recipe is basically nothing else than a node module and is currently ini | |||
12 | 12 | ||
13 | ## Table of Contents | 13 | ## Table of Contents |
14 | 14 | ||
15 | - [Ferdi Recipe Documentation / Overview](#ferdi-recipe-documentation--overview) | 15 | - [Ferdium Recipe Documentation / Overview](#ferdium-recipe-documentation--overview) |
16 | - [Table of Contents](#table-of-contents) | 16 | - [Table of Contents](#table-of-contents) |
17 | - [Preparing](#preparing) | 17 | - [Preparing](#preparing) |
18 | - [Create a recipe](#create-a-recipe) | 18 | - [Create a recipe](#create-a-recipe) |
@@ -49,7 +49,7 @@ pnpm run create "Service Name" | |||
49 | ``` | 49 | ``` |
50 | 50 | ||
51 | Replace `Service Name` with the name of your service, e.g. `pnpm run create "Google Hangouts"`. | 51 | Replace `Service Name` with the name of your service, e.g. `pnpm run create "Google Hangouts"`. |
52 | This command will automatically create the development recipe in the correct folder, prepares it for your service and opens the new recipe in your file explorer or Finder. 5. Reload Ferdi (`CMD/CTRL + SHIFT + R`) in order for it to register the new recipe 6. You can now develop your recipe as described below. Please continue down below with "[Publishing](#Publishing)" after you are done creating your recipe. | 52 | This command will automatically create the development recipe in the correct folder, prepares it for your service and opens the new recipe in your file explorer or Finder. 5. Reload Ferdium (`CMD/CTRL + SHIFT + R`) in order for it to register the new recipe 6. You can now develop your recipe as described below. Please continue down below with "[Publishing](#Publishing)" after you are done creating your recipe. |
53 | 53 | ||
54 | 5. (Mandatory) Please run the following step before raising a PR: | 54 | 5. (Mandatory) Please run the following step before raising a PR: |
55 | ```Bash | 55 | ```Bash |
@@ -59,10 +59,10 @@ Fix any issues that are reported. | |||
59 | 59 | ||
60 | ## Recipe structure | 60 | ## Recipe structure |
61 | 61 | ||
62 | Every recipe needs a specific file structure in order to work as a Ferdi recipe | 62 | Every recipe needs a specific file structure in order to work as a Ferdium recipe |
63 | 63 | ||
64 | - icon.svg - Icon for the service in SVG form (must be square) | 64 | - icon.svg - Icon for the service in SVG form (must be square) |
65 | - index.js - Backend script, this script is NOT included in the service webview but only in Ferdi itself | 65 | - index.js - Backend script, this script is NOT included in the service webview but only in Ferdium itself |
66 | - package.json - Information about the recipe | 66 | - package.json - Information about the recipe |
67 | - webview.js - Optional frontend script, this script is injected into the service itself but still has access to all NodeJS APIs | 67 | - webview.js - Optional frontend script, this script is injected into the service itself but still has access to all NodeJS APIs |
68 | - darkmode.css - CSS File that gets included when dark mode is activated | 68 | - darkmode.css - CSS File that gets included when dark mode is activated |
@@ -75,7 +75,7 @@ The `package.json` is structured like any other node module and allows to comple | |||
75 | { | 75 | { |
76 | "id": "tweetdeck", | 76 | "id": "tweetdeck", |
77 | "name": "Tweetdeck", | 77 | "name": "Tweetdeck", |
78 | "version": "1.0.1", | 78 | "version": "1.0.0", |
79 | "license": "MIT", | 79 | "license": "MIT", |
80 | "repository": "https://github.com/meetfranz/recipe-tweetdeck", | 80 | "repository": "https://github.com/meetfranz/recipe-tweetdeck", |
81 | "config": { | 81 | "config": { |
@@ -90,18 +90,18 @@ Please note that the fields `id`, `name`, `version` and `config` are mandatory. | |||
90 | 90 | ||
91 | ### index.js | 91 | ### index.js |
92 | 92 | ||
93 | This is your "backend" code. Right now the options are very limited and most of the services don't need a custom handling here. If your service is relatively straight forward and has a static URL eg. _messenger.com_, _`[TEAMID]`.slack.com_ or _web.skype.com_ all you need to do to return the Ferdi Class: | 93 | This is your "backend" code. Right now the options are very limited and most of the services don't need a custom handling here. If your service is relatively straight forward and has a static URL eg. _messenger.com_, _`[TEAMID]`.slack.com_ or _web.skype.com_ all you need to do to return the Ferdium Class: |
94 | 94 | ||
95 | ```js | 95 | ```js |
96 | module.exports = Ferdi => Ferdi; | 96 | module.exports = Ferdium => Ferdium; |
97 | ``` | 97 | ``` |
98 | 98 | ||
99 | If your service can be hosted on custom servers, you can validate the given URL to detect if it's your server and not e.g. google.com. To enable validation you can override the function `validateServer` | 99 | If your service can be hosted on custom servers, you can validate the given URL to detect if it's your server and not e.g. google.com. To enable validation you can override the function `validateServer` |
100 | 100 | ||
101 | ```js | 101 | ```js |
102 | // RocketChat integration | 102 | // RocketChat integration |
103 | module.exports = Ferdi => | 103 | module.exports = Ferdium => |
104 | class RocketChat extends Ferdi { | 104 | class RocketChat extends Ferdium { |
105 | async validateUrl(url) { | 105 | async validateUrl(url) { |
106 | try { | 106 | try { |
107 | const resp = await window.fetch(`${url}/api/info`, { | 107 | const resp = await window.fetch(`${url}/api/info`, { |
@@ -124,20 +124,20 @@ module.exports = Ferdi => | |||
124 | 124 | ||
125 | `validateServer` needs to return a [`Promise`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise), otherwise validation will fail. | 125 | `validateServer` needs to return a [`Promise`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise), otherwise validation will fail. |
126 | 126 | ||
127 | By default, Ferdi's user agent looks like this: | 127 | By default, Ferdium's user agent looks like this: |
128 | 128 | ||
129 | ```text | 129 | ```text |
130 | Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.141 Safari/537.36 Ferdi/5.4.4-beta.3 (Electron 8.1.1) | 130 | Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.141 Safari/537.36 Ferdium/5.4.4-beta.3 (Electron 8.1.1) |
131 | ``` | 131 | ``` |
132 | 132 | ||
133 | Some services may not be compatible with Ferdi adding it's signature to the user agent. | 133 | Some services may not be compatible with Ferdium adding it's signature to the user agent. |
134 | 134 | ||
135 | If you encounter such a service, please remove this signature with the following snippet of code | 135 | If you encounter such a service, please remove this signature with the following snippet of code |
136 | 136 | ||
137 | ```js | 137 | ```js |
138 | overrideUserAgent() { | 138 | overrideUserAgent() { |
139 | return window.navigator.userAgent.replace( | 139 | return window.navigator.userAgent.replace( |
140 | /(Ferdi|Electron)\/\S+ \([^)]+\)/g, | 140 | /(Ferdium|Electron)\/\S+ \([^)]+\)/g, |
141 | "" | 141 | "" |
142 | ); | 142 | ); |
143 | } | 143 | } |
@@ -153,11 +153,11 @@ overrideUserAgent() { | |||
153 | 153 | ||
154 | ### webview.js | 154 | ### webview.js |
155 | 155 | ||
156 | The optional `webview.js` is the actual script that will be loaded into the webview. Here you can do whatever you want to do in order perfectly integrate the service into Ferdi. For convenience, we have provided a very simple set of functions to set unread message badges (`Ferdi.setBadge()`), set active dialog title (`Ferdi.setDialogTitle()`) and inject CSS files (`Ferdi.injectCSS()`). | 156 | The optional `webview.js` is the actual script that will be loaded into the webview. Here you can do whatever you want to do in order perfectly integrate the service into Ferdium. For convenience, we have provided a very simple set of functions to set unread message badges (`Ferdium.setBadge()`), set active dialog title (`Ferdium.setDialogTitle()`) and inject CSS files (`Ferdium.injectCSS()`). |
157 | 157 | ||
158 | ```js | 158 | ```js |
159 | // telegram integration | 159 | // telegram integration |
160 | module.exports = Ferdi => { | 160 | module.exports = Ferdium => { |
161 | const getMessages = () => { | 161 | const getMessages = () => { |
162 | let direct = 0; | 162 | let direct = 0; |
163 | let indirect = 0; | 163 | let indirect = 0; |
@@ -165,7 +165,7 @@ module.exports = Ferdi => { | |||
165 | for (const element of elements) { | 165 | for (const element of elements) { |
166 | const subtitleBadge = element.querySelector('.dialog-subtitle-badge'); | 166 | const subtitleBadge = element.querySelector('.dialog-subtitle-badge'); |
167 | if (subtitleBadge) { | 167 | if (subtitleBadge) { |
168 | const parsedValue = Ferdi.safeParseInt(subtitleBadge.textContent); | 168 | const parsedValue = Ferdium.safeParseInt(subtitleBadge.textContent); |
169 | if (element.dataset.peerId > 0) { | 169 | if (element.dataset.peerId > 0) { |
170 | direct += parsedValue; | 170 | direct += parsedValue; |
171 | } else { | 171 | } else { |
@@ -174,13 +174,13 @@ module.exports = Ferdi => { | |||
174 | } | 174 | } |
175 | } | 175 | } |
176 | 176 | ||
177 | Ferdi.setBadge(direct, indirect); | 177 | Ferdium.setBadge(direct, indirect); |
178 | }; | 178 | }; |
179 | 179 | ||
180 | const getActiveDialogTitle = () => { | 180 | const getActiveDialogTitle = () => { |
181 | const element = document.querySelector('.top .peer-title'); | 181 | const element = document.querySelector('.top .peer-title'); |
182 | 182 | ||
183 | Ferdi.setDialogTitle(element ? element.textContent : ''); | 183 | Ferdium.setDialogTitle(element ? element.textContent : ''); |
184 | }; | 184 | }; |
185 | 185 | ||
186 | const loopFunc = () => { | 186 | const loopFunc = () => { |
@@ -188,9 +188,9 @@ module.exports = Ferdi => { | |||
188 | getActiveDialogTitle(); | 188 | getActiveDialogTitle(); |
189 | }; | 189 | }; |
190 | 190 | ||
191 | Ferdi.loop(loopFunc); | 191 | Ferdium.loop(loopFunc); |
192 | 192 | ||
193 | Ferdi.injectCSS(_path.default.join(__dirname, 'service.css')); | 193 | Ferdium.injectCSS(_path.default.join(__dirname, 'service.css')); |
194 | }; | 194 | }; |
195 | ``` | 195 | ``` |
196 | 196 | ||
@@ -198,22 +198,22 @@ To get more information about the provided functions, check the [API docs](front | |||
198 | 198 | ||
199 | ## Icons | 199 | ## Icons |
200 | 200 | ||
201 | In order to show every service icon crystal clear within the Ferdi UI, we require the icon in .svg (square, 1024x1024px) format. | 201 | In order to show every service icon crystal clear within the Ferdium UI, we require the icon in .svg (square, 1024x1024px) format. |
202 | 202 | ||
203 | ## Dark Mode | 203 | ## Dark Mode |
204 | 204 | ||
205 | You can provide a custom Dark Mode Theme for your recipes just by putting the `darkmode.css` into your recipe folder. Once the `darkmode.css` exists, you can enable the Dark Mode in your service settings. | 205 | You can provide a custom Dark Mode Theme for your recipes just by putting the `darkmode.css` into your recipe folder. Once the `darkmode.css` exists, you can enable the Dark Mode in your service settings. |
206 | 206 | ||
207 | Recipe Dark Mode is only supported by Ferdi 5.0.0-beta.19+. Even then, certain services do not allow clients like Ferdi to override these styles (an example of this is google calendar). | 207 | Recipe Dark Mode is only supported by Ferdium 5.0.0-beta.19+. Even then, certain services do not allow clients like Ferdium to override these styles (an example of this is google calendar). |
208 | 208 | ||
209 | ## Debugging | 209 | ## Debugging |
210 | 210 | ||
211 | In order to debug your service integration, open Ferdi and use the shortcut `Cmd/Ctrl+Alt+Shift+I` to open the recipes developer tools. | 211 | In order to debug your service integration, open Ferdium and use the shortcut `Cmd/Ctrl+Alt+Shift+I` to open the recipes developer tools. |
212 | 212 | ||
213 | ## Publishing | 213 | ## Publishing |
214 | 214 | ||
215 | Ferdi uses its recipe repository at <https://github.com/ferdium/ferdium-recipes> to publish recipes to all clients. | 215 | Ferdium uses its recipe repository at <https://github.com/ferdium/ferdium-recipes> to publish recipes to all clients. |
216 | 216 | ||
217 | Publishing your recipes to Ferdi is super easy! When you used our recipe creation script, we have created a folder for your recipe inside Ferdi's internal folders (the one that got automatically opened after you ran our script). | 217 | Publishing your recipes to Ferdium is super easy! When you used our recipe creation script, we have created a folder for your recipe inside Ferdium's internal folders (the one that got automatically opened after you ran our script). |
218 | 218 | ||
219 | Simply copy that whole folder into the repositories "recipes" folder. You'll now need to push your changes to Git and create a Pull Request from your fork repository to our repository using the GitHub website. | 219 | Simply copy that whole folder into the repositories "recipes" folder. You'll now need to push your changes to Git and create a Pull Request from your fork repository to our repository using the GitHub website. |
diff --git a/docs/updating.md b/docs/updating.md index f840f50..b5d35c3 100644 --- a/docs/updating.md +++ b/docs/updating.md | |||
@@ -4,16 +4,16 @@ If you want to improve or update an existing recipe, please follow this guide. | |||
4 | 4 | ||
5 | ## 1. Implement your updates | 5 | ## 1. Implement your updates |
6 | 6 | ||
7 | We highly suggest that you implement and test your updates to the recipe inside Ferdi before implementing them into the recipe repository. This will save you time on debugging and repackaging the recipe later. | 7 | We highly suggest that you implement and test your updates to the recipe inside Ferdium before implementing them into the recipe repository. This will save you time on debugging and repackaging the recipe later. |
8 | 8 | ||
9 | You can find the recipe source Ferdi uses at: | 9 | You can find the recipe source Ferdium uses at: |
10 | * Mac: `~/Library/Application Support/Ferdium/recipes/<recipe id>/` | 10 | * Mac: `~/Library/Application Support/Ferdium/recipes/<recipe id>/` |
11 | * Windows: `%appdata%/Ferdium/recipes/<recipe id>/` | 11 | * Windows: `%appdata%/Ferdium/recipes/<recipe id>/` |
12 | * Linux: `~/.config/Ferdium/recipes/<recipe id>` | 12 | * Linux: `~/.config/Ferdium/recipes/<recipe id>` |
13 | 13 | ||
14 | > If you can't find the recipe's folder, please make sure that you have created a service inside Ferdi with that recipe - otherwise Ferdi will not load it into the folder | 14 | > If you can't find the recipe's folder, please make sure that you have created a service inside Ferdium with that recipe - otherwise Ferdium will not load it into the folder |
15 | 15 | ||
16 | After changing the files in that folder, you can reload the service inside Ferdi using `CTRL/CMD + R`. | 16 | After changing the files in that folder, you can reload the service inside Ferdium using `CTRL/CMD + R`. |
17 | 17 | ||
18 | ## 2. Setting up the recipe repository | 18 | ## 2. Setting up the recipe repository |
19 | 19 | ||
@@ -27,7 +27,7 @@ Simply add your changes to the recipe inside this repository. | |||
27 | 27 | ||
28 | You'll need to increase the version number inside recipe's `package.json`. | 28 | You'll need to increase the version number inside recipe's `package.json`. |
29 | 29 | ||
30 | Ferdi uses this version to determine if it should update the local copy of the recipe. If you do not increase the version number, no Ferdi user will get your updated recipe đ | 30 | Ferdium uses this version to determine if it should update the local copy of the recipe. If you do not increase the version number, no Ferdium user will get your updated recipe đ |
31 | 31 | ||
32 | ## 5. Running the validation checks | 32 | ## 5. Running the validation checks |
33 | 33 | ||