aboutsummaryrefslogtreecommitdiffstats
path: root/docs/integration.md
diff options
context:
space:
mode:
authorLibravatar Vijay A <vraravam@users.noreply.github.com>2022-04-18 06:51:50 -0500
committerLibravatar Vijay A <vraravam@users.noreply.github.com>2022-04-18 06:51:50 -0500
commit18801ed0c02627e87639dc0848cab44dacc18be2 (patch)
tree15e56ba66c68bf7b4594e6c9fdef44e037b4be31 /docs/integration.md
parentRemove deprecated webPreference flag (diff)
downloadferdium-recipes-18801ed0c02627e87639dc0848cab44dacc18be2.tar.gz
ferdium-recipes-18801ed0c02627e87639dc0848cab44dacc18be2.tar.zst
ferdium-recipes-18801ed0c02627e87639dc0848cab44dacc18be2.zip
Rebranded from 'ferdi' to 'ferdium' (companion changes for the main repo PR #2)
Diffstat (limited to 'docs/integration.md')
-rw-r--r--docs/integration.md58
1 files changed, 29 insertions, 29 deletions
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
3Recipes 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. 3Recipes 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
5A 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. 5A 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
51Replace `Service Name` with the name of your service, e.g. `pnpm run create "Google Hangouts"`. 51Replace `Service Name` with the name of your service, e.g. `pnpm run create "Google Hangouts"`.
52This 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. 52This 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
545. (Mandatory) Please run the following step before raising a PR: 545. (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
62Every recipe needs a specific file structure in order to work as a Ferdi recipe 62Every 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
93This 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: 93This 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
96module.exports = Ferdi => Ferdi; 96module.exports = Ferdium => Ferdium;
97``` 97```
98 98
99If 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` 99If 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
103module.exports = Ferdi => 103module.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
127By default, Ferdi's user agent looks like this: 127By default, Ferdium's user agent looks like this:
128 128
129```text 129```text
130Mozilla/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) 130Mozilla/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
133Some services may not be compatible with Ferdi adding it's signature to the user agent. 133Some services may not be compatible with Ferdium adding it's signature to the user agent.
134 134
135If you encounter such a service, please remove this signature with the following snippet of code 135If you encounter such a service, please remove this signature with the following snippet of code
136 136
137```js 137```js
138overrideUserAgent() { 138overrideUserAgent() {
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
156The 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()`). 156The 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
160module.exports = Ferdi => { 160module.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
201In order to show every service icon crystal clear within the Ferdi UI, we require the icon in .svg (square, 1024x1024px) format. 201In 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
205You 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. 205You 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
207Recipe 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). 207Recipe 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
211In order to debug your service integration, open Ferdi and use the shortcut `Cmd/Ctrl+Alt+Shift+I` to open the recipes developer tools. 211In 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
215Ferdi uses its recipe repository at <https://github.com/ferdium/ferdium-recipes> to publish recipes to all clients. 215Ferdium uses its recipe repository at <https://github.com/ferdium/ferdium-recipes> to publish recipes to all clients.
216 216
217Publishing 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). 217Publishing 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
219Simply 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. 219Simply 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.