aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorLibravatar Vijay A <avijayr@protonmail.com>2021-05-15 18:45:22 +0530
committerLibravatar Vijay Raghavan Aravamudhan <vraravam@users.noreply.github.com>2021-05-15 19:33:09 +0530
commit882504b4348c795b1fb5f5a6e61542f3cddad02a (patch)
treebf6bed4cf9e6d807d009bba7be92a75e59563c7f /docs
parentHousekeeping: These recipes had been updated for bug fixes since Apr 2020, bu... (diff)
downloadferdium-recipes-882504b4348c795b1fb5f5a6e61542f3cddad02a.tar.gz
ferdium-recipes-882504b4348c795b1fb5f5a6e61542f3cddad02a.tar.zst
ferdium-recipes-882504b4348c795b1fb5f5a6e61542f3cddad02a.zip
Housekeeping: Fixed markdown rule violations.
Diffstat (limited to 'docs')
-rw-r--r--docs/integration.md37
1 files changed, 25 insertions, 12 deletions
diff --git a/docs/integration.md b/docs/integration.md
index 45d3af7..3eb8c1d 100644
--- a/docs/integration.md
+++ b/docs/integration.md
@@ -11,6 +11,7 @@ A Ferdi recipe is basically nothing else than a node module and is currently ini
11> If you want to update an existing recipe, please refer to [updating.md](https://github.com/getferdi/recipes/blob/master/docs/updating.md) instead 11> If you want to update an existing recipe, please refer to [updating.md](https://github.com/getferdi/recipes/blob/master/docs/updating.md) instead
12 12
13## Table of Contents 13## Table of Contents
14
14- [Ferdi Recipe Documentation / Overview](#ferdi-recipe-documentation--overview) 15- [Ferdi Recipe Documentation / Overview](#ferdi-recipe-documentation--overview)
15 - [Table of Contents](#table-of-contents) 16 - [Table of Contents](#table-of-contents)
16 - [Preparing](#preparing) 17 - [Preparing](#preparing)
@@ -25,28 +26,35 @@ A Ferdi recipe is basically nothing else than a node module and is currently ini
25 - [Publishing](#publishing) 26 - [Publishing](#publishing)
26 27
27## Preparing 28## Preparing
29
28You should have basic knowledge of JavaScript - don't worry, you'll really only need some basic commands as we've already prepared the complicated stuff for you. 30You should have basic knowledge of JavaScript - don't worry, you'll really only need some basic commands as we've already prepared the complicated stuff for you.
29 31
30We have also created a nice script that already does 50% of the work for you - yay 🎉. If you want to use this script, please make sure you have NodeJS installed on your system. 32We have also created a nice script that already does 50% of the work for you - yay 🎉. If you want to use this script, please make sure you have NodeJS installed on your system.
31 33
32## Create a recipe 34## Create a recipe
35
331. Fork this repository on GitHub. You can do this by clicking the "Fork" button in the top right corner 361. Fork this repository on GitHub. You can do this by clicking the "Fork" button in the top right corner
342. Clone your forked repository. Normally, you can do this by running `git clone https://github.com/<Your GitHub Username>/recipes.git` in your terminal. You may also use a Git GUI or the GitHub Website for this. 372. Clone your forked repository. Normally, you can do this by running `git clone https://github.com/<Your GitHub Username>/recipes.git` in your terminal. You may also use a Git GUI or the GitHub Website for this.
352. (Optional, if you want to use our creation script) Install its dependencies via the terminal: 383. (Optional, if you want to use our creation script) Install its dependencies via the terminal:
39
36```Bash 40```Bash
37npm install 41npm install
38``` 42```
393. You can now run our automatic recipe wizard that creates and opens the new recipe for you: 43
444. You can now run our automatic recipe wizard that creates and opens the new recipe for you:
45
40```Bash 46```Bash
41# Make sure you are still in the repository's folder 47# Make sure you are still in the repository's folder
42npm run create "Service Name" 48npm run create "Service Name"
43``` 49```
50
44Replace `Service Name` with the name of your service, e.g. `npm run create "Google Hangouts"`. 51Replace `Service Name` with the name of your service, e.g. `npm run create "Google Hangouts"`.
45This 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. 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.
464. Reload Ferdi (`CMD/CTRL + SHIFT + R`) in order for it to register the new recipe 535. Reload Ferdi (`CMD/CTRL + SHIFT + R`) in order for it to register the new recipe
475. You can now develop your recipe as described below. Please continue down below with "[Publishing](#Publishing)" after you are done creating your recipe. 546. You can now develop your recipe as described below. Please continue down below with "[Publishing](#Publishing)" after you are done creating your recipe.
48 55
49## Recipe structure 56## Recipe structure
57
50Every recipe needs a specific file structure in order to work as a Ferdi recipe 58Every recipe needs a specific file structure in order to work as a Ferdi recipe
51 59
52* icon.svg - Icon for the service in SVG form (must be square) 60* icon.svg - Icon for the service in SVG form (must be square)
@@ -57,6 +65,7 @@ Every recipe needs a specific file structure in order to work as a Ferdi recipe
57* darkmode.css - CSS File that gets included when dark mode is activated 65* darkmode.css - CSS File that gets included when dark mode is activated
58 66
59### package.json 67### package.json
68
60The package.json is structured like any other node module and allows to completely configure the service. 69The package.json is structured like any other node module and allows to completely configure the service.
61 70
62```json 71```json
@@ -79,8 +88,8 @@ To get more information about all the provided configuration flags, check the [c
79 88
80Please note that the fields `id`, `name`, `version` and `config` and required. 89Please note that the fields `id`, `name`, `version` and `config` and required.
81 90
82
83### index.js 91### index.js
92
84This 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 Ferdi Class:
85 94
86```js 95```js
@@ -88,6 +97,7 @@ module.exports = Ferdi => Ferdi;
88``` 97```
89 98
90If 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
91```js 101```js
92// RocketChat integration 102// RocketChat integration
93module.exports = Ferdi => class RocketChat extends Ferdi { 103module.exports = Ferdi => class RocketChat extends Ferdi {
@@ -113,10 +123,9 @@ module.exports = Ferdi => class RocketChat extends Ferdi {
113 123
114`validateServer` needs to return a [`Promise`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise), otherwise validation will fail. 124`validateServer` needs to return a [`Promise`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise), otherwise validation will fail.
115 125
116
117
118By default, Ferdi's user agent looks like this: 126By default, Ferdi's user agent looks like this:
119``` 127
128```text
120Mozilla/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) 129Mozilla/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)
121``` 130```
122 131
@@ -124,7 +133,7 @@ Some services may not be compatible with Ferdi adding it's signature to the user
124 133
125If you encounter such a service, you remove this signature with the following snippet of code 134If you encounter such a service, you remove this signature with the following snippet of code
126 135
127``` 136```js
128overrideUserAgent() { 137overrideUserAgent() {
129 return window.navigator.userAgent.replace( 138 return window.navigator.userAgent.replace(
130 /(Ferdi|Electron)\/\S+ \([^)]+\)/g, 139 /(Ferdi|Electron)\/\S+ \([^)]+\)/g,
@@ -135,15 +144,15 @@ overrideUserAgent() {
135 144
136If you want to change the user agent to a different one, you can simply return the String for the new user agent: 145If you want to change the user agent to a different one, you can simply return the String for the new user agent:
137 146
138``` 147```js
139overrideUserAgent() { 148overrideUserAgent() {
140 return "Mozilla/2.02Gold (Win95; I)"; 149 return "Mozilla/2.02Gold (Win95; I)";
141} 150}
142``` 151```
143 152
144### webview.js 153### webview.js
145The 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()`) and inject CSS files (`Ferdi.injectCSS()`).
146 154
155The 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()`) and inject CSS files (`Ferdi.injectCSS()`).
147 156
148```js 157```js
149// orat.io integration 158// orat.io integration
@@ -167,19 +176,23 @@ module.exports = (Ferdi) => {
167To get more information about the provided functions, check the [API docs](frontend_api.md). 176To get more information about the provided functions, check the [API docs](frontend_api.md).
168 177
169## Icons 178## Icons
179
170In order to show every service icon crystal clear within the Ferdi UI, we require the icon in both .svg (square) and .png (square, 1024x1024px) formats. 180In order to show every service icon crystal clear within the Ferdi UI, we require the icon in both .svg (square) and .png (square, 1024x1024px) formats.
171 181
172## Dark Mode 182## Dark Mode
183
173You 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. 184You 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.
174 185
175Recipe Dark Mode is only supported by Ferdi 5.0.0-beta.19+ 186Recipe Dark Mode is only supported by Ferdi 5.0.0-beta.19+
176 187
177## Debugging 188## Debugging
189
178In order to debug your service integration, open Ferdi and use the shortcut `Cmd/Ctrl+Alt+Shift+i` to open the recipes developer tools. 190In order to debug your service integration, open Ferdi and use the shortcut `Cmd/Ctrl+Alt+Shift+i` to open the recipes developer tools.
179 191
180## Publishing 192## Publishing
193
181Ferdi uses its recipe repository at <https://github.com/getferdi/recipes> to publish recipes to all clients. 194Ferdi uses its recipe repository at <https://github.com/getferdi/recipes> to publish recipes to all clients.
182 195
183Publishing 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). 196Publishing 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).
184 197
185Simply 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. \ No newline at end of file 198Simply 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.