aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorLibravatar vantezzen <hello@vantezzen.io>2020-03-08 11:10:17 +0100
committerLibravatar vantezzen <hello@vantezzen.io>2020-03-08 11:10:17 +0100
commit9d715597a600710c20f75412d3dcd8cdb7b3c39e (patch)
tree65ab812834d486aaccf35e2a31a7a628a7100422
parentRevert to using the standart file comparison function (diff)
downloadferdi-recipes-9d715597a600710c20f75412d3dcd8cdb7b3c39e.tar.gz
ferdi-recipes-9d715597a600710c20f75412d3dcd8cdb7b3c39e.tar.zst
ferdi-recipes-9d715597a600710c20f75412d3dcd8cdb7b3c39e.zip
Add documentation
-rw-r--r--README.md18
-rw-r--r--docs/README.md7
-rw-r--r--docs/backend_api.md90
-rw-r--r--docs/configuration.md92
-rw-r--r--docs/frontend_api.md169
-rw-r--r--docs/integration.md148
6 files changed, 508 insertions, 16 deletions
diff --git a/README.md b/README.md
index 895663f..3bc7a84 100644
--- a/README.md
+++ b/README.md
@@ -3,19 +3,5 @@ Recipes for Ferdi.
3 3
4Copyright on these recipes is on their original creators. 4Copyright on these recipes is on their original creators.
5 5
6## Adding your own recipes 6## Creating and adding your own recipes
7After creating your own recipe using [Franz's guide](https://github.com/meetfranz/plugins/blob/master/docs/integration.md) you can add them to this repository. 7Please refer to our documentation at https://github.com/getferdi/recipes/blob/master/docs/integration.md. \ No newline at end of file
8
91. Copy your recipe files into `scripts/recipe_src`
102. Open a terminal at `scripts/`
113. Run `yarn install` to install all dependencies
124. Run `yarn package` to package your new recipe
135. Create a PR to <https://github.com/getferdi/recipes> with your new changes
14
15## Importing recipes from GitHub
16If you've uploaded your recipe to GitHub, you can easily import it into the Ferdi recipe repository using the `add_github` script:
17
181. Open a terminal at `scripts/`
192. Run `yarn install` to install all dependencies
203. Run `yarn github [GitHub URL]`, e.g. `yarn github https://github.com/vantezzen/franz-recipe-standardnotes`, to add your new recipe
214. Create a PR to <https://github.com/getferdi/recipes> with your new changes \ No newline at end of file
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..689ecd5
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,7 @@
1# Ferdi Integration Documentation
2Create your own [Ferdi](https://getferdi.com) service integration within a few minutes.
3
4* [Overview / How to create a Ferdi integration](integration.md)
5* [Configuration (package.json)](configuration.md)
6* [Frontend API (webview.js)](frontend_api.md)
7* [Backend API (index.js)](backend_api.md)
diff --git a/docs/backend_api.md b/docs/backend_api.md
new file mode 100644
index 0000000..dfc9f22
--- /dev/null
+++ b/docs/backend_api.md
@@ -0,0 +1,90 @@
1# Backend API
2
3Provides a set of helper functions to integrate the recipe into [Ferdi](https://getferdi.com).
4
5## Ferdi Backend Class Methods
6* [validateUrl](#user-content-validateurl)
7* [overrideUserAgent](#user-content-overrideuseragent)
8
9## Events
10* [webview events](#user-content-events)
11
12### validateUrl(URL)
13Validate if the given URL is a valid service instance.
14
15#### Arguments
161. `string` URL
17
18#### Returns
19[`Promise`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise)
20
21#### Usage
22
23```js
24// RocketChat integration
25module.exports = Ferdi => class RocketChat extends Ferdi {
26 async validateUrl(url) {
27 try {
28 const resp = await window.fetch(`${url}/api/info`, {
29 method: 'GET',
30 headers: {
31 'Content-Type': 'application/json',
32 },
33 });
34 const data = await resp.json();
35
36 return Object.hasOwnProperty.call(data, 'version');
37 } catch (err) {
38 console.error(err);
39 }
40
41 return false;
42 }
43};
44```
45
46### overrideUserAgent()
47Validate if the given URL is a valid service instance.
48
49#### Returns
50`Boolean`
51
52#### Usage
53
54```js
55// Discord integration
56module.exports = Ferdi => class Discord extends Ferdi {
57 overrideUserAgent() {
58 const useragent = window.navigator.userAgent;
59
60 // Quick and dirty hackfix
61 const parts = useragent.split('(KHTML, like Gecko)');
62
63 return parts.join('(KHTML, like Gecko) discord/0.0.248').replace('Electron', 'Discord').replace('Ferdi', 'Discord');
64 }
65};
66
67```
68
69### Events
70Ferdi recipes can hook into the [electron webview events](https://electron.atom.io/docs/api/webview-tag/#dom-events) to trigger custom functions.
71
72This is necessary for services like TweetDeck where custom URL forwarding is needed during login.
73
74#### Usage
75```js
76module.exports = Ferdi => class Tweetdeck extends Ferdi {
77 events = {
78 'did-get-redirect-request': '_redirectFix',
79 }
80
81 _redirectFix(event) {
82 if (event.newURL !== undefined && event.oldURL !== undefined && event.isMainFrame) {
83 if (event.isMainFrame) {
84 setTimeout(() => this.send('redirect-url', event.newURL), 100);
85 event.preventDefault();
86 }
87 }
88 }
89};
90```
diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 0000000..923ed19
--- /dev/null
+++ b/docs/configuration.md
@@ -0,0 +1,92 @@
1# Integration Config
2
3A [Ferdi](https://getferdi.com) 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
5## Table of Contents
6* [Config flags](#user-content-config-flags)
7* [Examples](#user-content-examples)
8
9## Config flags
10
11`string` **id**<br />
12Unique identifier name of the plugin. The name of the plugin folder has to be the same.
13
14This ID cannot contain any special characters or spaces.
15
16`string` **name**<br />
17Display name of the service.
18
19`string` **version**<br />
20Version number. Will be used for auto updating the integrations. The version number must be in a semver compatible format: `1.0.0`.
21**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.
22
23`string` **description**<br />
24Short description about your integration. Not currently used.
25
26`string` **main**<br />
27The plugins main entry point. In our case `index.js`.
28
29`string` **author**<br />
30Author of the integration. Not currently used.
31
32`string` **license**<br />
33The license of the integration. We prefer MIT, but here is a list of all the available SPDX licenses http://spdx.org/licenses/
34
35`string` **repository**<br />
36Link to your Github, Gitlab or Bitbucket public repository
37
38`object` **config**<br />
39This is the Ferdi specific integration config.
40
41* `string` **serviceURL**<br/>
42Defines the URL that should be loaded into the Ferdi webview.
43<br /><br />
44If 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`.
45<br /><br />
46If your service works with custom URLs, just leave this empty.
47<br /><br />
48**Examples**
49```json
50{
51 "serviceURL": "https://www.messenger.com"
52}
53```
54<br />
55
56```json
57{
58 "serviceURL": "https://{teamId}.slack.com"
59}
60```
61* `boolean` **hasTeamId** _default: true_<br />
62Is this a team based service? If true, the interface to add the service will require a team identifier. e.g. `[teamId]`.slack.com
63* `boolean` **urlInputSuffix**<br />
64This option is only used in combination with `hasTeamId: true` in order to display the value of `urlInputSuffix` after the input for TeamId to make it obvious to the user what input is required from him. Eg. _&lt;TeamID&gt;.hipchat.com_
65* `boolean` **hasCustomUrl** _default: false_<br />
66On premise services like HipChat, Mattermost, ... require a custom URL. This option enables the user to enter a custom URL when adding the service.
67* `boolean` **hasNotificationSound** _default: false_<br />
68Some services provide their own notification sound. In order to avoid multiple sounds when the user receives a message set this to `true`. If the service has no built in notification sound set this to `false`.
69* `boolean` **hasIndirectMessages** _default: false_<br />
70Services like Slack or HipChat have direct messages e.g. a mention or message to every user in a channel (@channel) and indirect messages e.g. general discussion in a channel. If this flag is set to `true`, the user can enable/disable if there should be a badge for indirect messages.
71* `string` **message**<br />
72Info message that will be displayed in the add/edit service interface.
73
74## Example
75### Mattermost configuration
76```json
77{
78 "id": "mattermost",
79 "name": "Mattermost",
80 "version": "1.0.0",
81 "description": "Mattermost",
82 "main": "index.js",
83 "author": "Stefan Malzner <stefan@adlk.io>",
84 "license": "MIT",
85 "repository": "https://github.com/meetFerdi/recipe-mattermost",
86 "config": {
87 "hasNotificationSound": true,
88 "hasIndirectMessages": true,
89 "hasCustomUrl": true
90 }
91}
92```
diff --git a/docs/frontend_api.md b/docs/frontend_api.md
new file mode 100644
index 0000000..c1d35ce
--- /dev/null
+++ b/docs/frontend_api.md
@@ -0,0 +1,169 @@
1# Frontend API
2
3Provides a set of helper functions to integrate the service into [Ferdi](https://getferdi.com).
4
5## Ferdi Class Methods
6* [setBadge](#user-content-setbadge)
7* [injectCSS](#user-content-injectcss)
8* [loop](#user-content-loop)
9* [onNotify](#user-content-onnotify)
10* [handleDarkMode](#user-content-handleDarkMode)
11
12### setBadge(directMessages, [indirectMessages])
13Sets the unread message badge
14
15#### Arguments
161. `int` directMessages
17 * sets the count of direct messages eg. Slack direct mentions, or a message to @channel
182. `int` indirectMessages (optional)
19 * Set a badge that defines there are new messages but they do not involve me directly to me eg. in a channel
20
21#### Usage
22
23```js
24Ferdi.setBadge(4, 2);
25
26// or
27
28Ferdi.setBadge(3);
29```
30
31### injectCSS(pathToCssFile)
32Injects the contents of one or more CSS files into the current webview
33
34#### Arguments
351. `string` cssFile
36 * CSS files that should be injected. This must be an absolute path to the file
37
38#### Usage
39
40```js
41const path = require('path');
42
43// inject a single css file
44Ferdi.injectCSS(path.join(__dirname, 'style.css'));
45
46// inject multiple css files
47const globalStyles = path.join(__dirname, 'global.css');
48const focusModeStyles = path.join(__dirname, 'focusmode.css');
49
50Ferdi.injectCSS(globalStyles, focusModeStyles);
51```
52
53### loop(action)
54Runs an action every X milliseconds (Ferdi default is currently 1s)
55
56#### Arguments
571. `function` action
58
59#### Usage
60
61```js
62// slack integration
63const path = require('path');
64
65module.exports = (Ferdi) => {
66 const getMessages = () => {
67 const directMessages = $('.unread_highlights, .unread_highlight').not('.hidden').length;
68 const indirectMessages = $('.unread').length - directMessages;
69
70 Ferdi.setBadge(directMessages, indirectMessages);
71 }
72
73 Ferdi.loop(getMessages);
74
75 Ferdi.injectCSS(path.join(__dirname, 'style.css'));
76}
77```
78
79### onNotify(fn)
80Runs `fn` on every notification created by the service before sending them to the host (Useful if you want to update information of the notification before showing it to the user)
81
82#### Arguments
831. `function` fn
84
85#### Usage
86
87```js
88// messenger integration
89module.exports = (Ferdi) => {
90 const getMessages = function getMessages() {
91 let count = document.querySelectorAll('._5fx8:not(._569x),._1ht3:not(._569x)').length;
92 const messageRequestsElement = document.querySelector('._5nxf');
93 if (messageRequestsElement) {
94 count += parseInt(messageRequestsElement.innerHTML, 10);
95 }
96
97 Ferdi.setBadge(count);
98 };
99
100 Ferdi.loop(getMessages);
101
102 Ferdi.onNotify(notification => {
103
104 if (typeof notification.title !== 'string') {
105 notification.title = ((notification.title.props || {}).content || [])[0] || 'Messenger';
106 }
107
108 return notification;
109
110 });
111};
112```
113
114### handleDarkMode(callback)
115You can use a `darkmode.css` to automatically get the service into a dark theme. If your service already supports its own dark mode (e.g. Reddit and YouTube have build-in dark modes) you can use a custom dark mode handler instead.
116
117This handler should take the nesessary steps to (de-)activate dark mode on the page, e.g. by clicking a button or flipping a switch.
118
119Ferdi 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.
120
121#### Arguments
1221. `function` callback
123
124#### Callback function arguments
1251. `boolean` isEnabled: Is Dark Mode currently enabled?
1262. `object` helpers: Helper functions that you can use in your function:
127 `enableDarkMode` - Enable DarkReader
128 `injectDarkModeStyle` - Inject darkmode.css
129 `removeDarkModeStyle` - Remove service's darkmode.css
130 `disableDarkMode` - Disable DarkReader
131 `isDarkModeStyleInjected` - Function that returns true if darkmode.css is injected into the page
132
133#### Usage
134```JavaScript
135// Handler that works for Reddit
136Ferdi.handleDarkMode((isEnabled, helpers) => {
137 // Open dropdown menu if not already open
138 const menu = document.querySelector('#USER_DROPDOWN_ID');
139 if (menu.getAttribute('aria-expanded') === 'false') {
140 menu.click();
141 }
142
143 setTimeout(() => {
144 // Check if service is already in right mode
145 const btn = document.querySelector('[role=menu] button button');
146 const checked = btn.getAttribute('aria-checked') === 'true';
147
148 if ((checked && !isEnabled) || (!checked && isEnabled)) {
149 // Click the button to switch between modes
150 btn.click();
151 }
152 }, 50);
153});
154
155// --- or ---
156
157// Helper that activates DarkReader and injects your darkmode.css at the same time
158Ferdi.handleDarkMode((isEnabled, helpers) => {
159 if (isEnabled) {
160 helpers.enableDarkMode();
161 if (!helpers.isDarkModeStyleInjected()) {
162 helpers.injectDarkModeStyle();
163 }
164 } else {
165 helpers.disableDarkMode();
166 helpers.removeDarkModeStyle();
167 }
168})
169``` \ No newline at end of file
diff --git a/docs/integration.md b/docs/integration.md
new file mode 100644
index 0000000..ddfc35c
--- /dev/null
+++ b/docs/integration.md
@@ -0,0 +1,148 @@
1# Ferdi Recipe Documentation / Overview
2
3A 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.
4
5Recipes 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.
6
7## Table of Contents
8* [Installation](#user-content-installation)
9* [Plugin structure](#user-content-recipe-structure)
10* [Configuration (package.json)](#user-content-packagejson)
11* [Backend (index.js)](#user-content-indexjs)
12* [Frontend (webview.js)](#user-content-webviewjs)
13* [Icons](#user-content-icons)
14* [Dark Mode](#user-content-dark-mode)
15* [Debugging](#user-content-debugging)
16* [Deployment](#user-content-deployment)
17
18## Installation
191. To install a new recipe for testing, download the recipe folder e.g `whatsapp` or simply create an empty one with the name of your new recipe (we recommend using a recipe like `whatsapp` as a template though).
202. Open the development Ferdi Plugins folder on your machine (note that the `dev` directory may not exist yet, and you must create it):
21 * Mac: `~/Library/Application Support/Ferdi/recipes/dev/`
22 * Windows: `%appdata%/Ferdi/recipes/dev/`
23 * Linux: `~/.config/Ferdi/recipes/dev`
243. Copy the recipe folder into this folder
254. Reload Ferdi (`CMD/CTRL + SHIFT + R`)
26
27## Recipe structure
28Every recipe needs a specific file structure in order to work as a Ferdi recipe
29
30* icon.svg - Icon for the service in SVG form
31* icon.png - Icon for the service in PNG form (1024x1024px)
32* index.js - Backend script, this script is NOT included in the service webview but only in Ferdi itself
33* package.json - Information about the recipe
34* webview.js - Frontend script, this script is injected into the service itself but still has access to all NodeJS APIs
35* darkmode.css - CSS File that gets included when dark mode is activated
36
37### package.json
38The package.json is structured like any other node module and allows to completely configure the service.
39
40```json
41{
42 "id": "tweetdeck",
43 "name": "Tweetdeck",
44 "version": "1.0.1",
45 "description": "Tweetdeck",
46 "main": "index.js",
47 "author": "Stefan Malzner <stefan@adlk.io>",
48 "license": "MIT",
49 "repository": "https://github.com/meetfranz/recipe-tweetdeck",
50 "config": {
51 "serviceURL": "https://tweetdeck.twitter.com/"
52 }
53}
54```
55
56To get more information about all the provided configuration flags, check the [config docs](configuration.md).
57
58Please note that the fields `id`, `name`, `version` and `config` and required.
59
60
61### index.js
62This 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:
63
64```js
65module.exports = Ferdi => Ferdi;
66```
67
68If 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`
69```js
70// RocketChat integration
71module.exports = Ferdi => class RocketChat extends Ferdi {
72 async validateUrl(url) {
73 try {
74 const resp = await window.fetch(`${url}/api/info`, {
75 method: 'GET',
76 headers: {
77 'Content-Type': 'application/json',
78 },
79 });
80 const data = await resp.json();
81
82 return Object.hasOwnProperty.call(data, 'version');
83 } catch (err) {
84 console.error(err);
85 }
86
87 return false;
88 }
89};
90```
91
92`validateServer` needs to return a [`Promise`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise), otherwise validation will fail.
93
94### webview.js
95The 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()`).
96
97
98```js
99// orat.io integration
100module.exports = (Ferdi) => {
101 function getMessages() {
102 let direct = 0;
103 let indirect = 0;
104 const FerdiData = document.querySelector('#FerdiMessages').dataset;
105 if (FerdiData) {
106 direct = FerdiData.direct;
107 indirect = FerdiData.indirect;
108 }
109
110 Ferdi.setBadge(direct, indirect);
111 }
112
113 Ferdi.loop(getMessages);
114}
115```
116
117To get more information about the provided functions, check the [API docs](frontend_api.md).
118
119### Icons
120In order to show every service icon crystal clear within the Ferdi UI, we require a .svg and .png in 1024x1024px.
121
122### Dark Mode
123You 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.
124
125Recipe Dark Mode is only supported by Ferdi 5.0.0-beta.19+
126
127### Debugging
128In order to debug your service integration, open Ferdi and use the shortcut `Cmd/Ctrl+Alt+Shift+i` to open the recipes developer tools.
129
130### Publishing
131Ferdi uses its recipe repository at <https://github.com/getferdi/recipes> to publish recipes to all clients.
132
133To add your own recipe to the repository:
134- If you already uploaded the recipe to GitHub:
135 1. Fork https://github.com/getferdi/recipes and clone it to your computer
136 2. Open a terminal in the `scripts/` folder of that repository
137 3. Run `yarn install` to install all dependencies
138 4. Run `yarn github [GitHub URL]`, e.g. `yarn github https://github.com/vantezzen/franz-recipe-standardnotes`, to add your new recipe
139 5. Create a PR to <https://github.com/getferdi/recipes> with your new changes
140
141- If you don't have it uploaded it GitHub:
142 ℹ️ We recommend uploading your recipes to GitHub before adding them to provide a platform for users to report issues.
143 1. Fork https://github.com/getferdi/recipes and clone it to your computer
144 2. Copy your recipe files into `scripts/recipe_src`
145 3. Open a terminal at `scripts/`
146 4. Run `yarn install` to install all dependencies
147 5. Run `yarn package` to package your new recipe
148 6. Create a PR to <https://github.com/getferdi/recipes> with your new changes