diff options
author | 2021-08-11 14:59:55 +0000 | |
---|---|---|
committer | 2021-08-11 20:29:55 +0530 | |
commit | 2fd678efd32725a881152af2b2ee5fa64f422dea (patch) | |
tree | 3d158e089ac683ad7a979d23bace07d79bbff354 /docs | |
parent | Fixed eslintrc as root for this folder; Reformatted all files. (diff) | |
download | ferdium-recipes-2fd678efd32725a881152af2b2ee5fa64f422dea.tar.gz ferdium-recipes-2fd678efd32725a881152af2b2ee5fa64f422dea.tar.zst ferdium-recipes-2fd678efd32725a881152af2b2ee5fa64f422dea.zip |
Cleanup all recipes (#605)
* Removed legacy properties that are no longer used:
'author'
'customURL'
'description'
'hostedOnly'
'main'
'openDevTools'
'popup'
'repository'
'serviceName'
'webviewOptions'
'wording'
- Removed entries for if they were the defaults:
'hasCustomUrl'
'hasDirectMessages'
'hasIndirectMessages'
'hasNotificationSound'
'hasTeamId'
'message'
Fixed incorrect 'urlInputSuffix' type.
Added validations for ensuring the above do not creep back in.
Diffstat (limited to 'docs')
-rw-r--r-- | docs/configuration.md | 71 | ||||
-rw-r--r-- | docs/integration.md | 17 |
2 files changed, 37 insertions, 51 deletions
diff --git a/docs/configuration.md b/docs/configuration.md index 923ed19..532a1f7 100644 --- a/docs/configuration.md +++ b/docs/configuration.md | |||
@@ -3,40 +3,34 @@ | |||
3 | A [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). | 3 | A [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 | 4 | ||
5 | ## Table of Contents | 5 | ## Table of Contents |
6 | * [Config flags](#user-content-config-flags) | 6 | |
7 | * [Examples](#user-content-examples) | 7 | - [Integration Config](#integration-config) |
8 | - [Table of Contents](#table-of-contents) | ||
9 | - [Config flags](#config-flags) | ||
10 | - [Example](#example) | ||
8 | 11 | ||
9 | ## Config flags | 12 | ## Config flags |
10 | 13 | ||
11 | `string` **id**<br /> | 14 | `string` **id** _mandatory_<br /> |
12 | Unique identifier name of the plugin. The name of the plugin folder has to be the same. | 15 | Unique identifier name of the plugin. The name of the plugin folder has to be the same. |
13 | 16 | ||
14 | This ID cannot contain any special characters or spaces. | 17 | This ID cannot contain any special characters or spaces. |
15 | 18 | ||
16 | `string` **name**<br /> | 19 | `string` **name** _mandatory_<br /> |
17 | Display name of the service. | 20 | Display name of the service. |
18 | 21 | ||
19 | `string` **version**<br /> | 22 | `string` **version** _mandatory_<br /> |
20 | Version number. Will be used for auto updating the integrations. The version number must be in a semver compatible format: `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`. |
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. | 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. |
22 | 25 | ||
23 | `string` **description**<br /> | ||
24 | Short description about your integration. Not currently used. | ||
25 | |||
26 | `string` **main**<br /> | ||
27 | The plugins main entry point. In our case `index.js`. | ||
28 | |||
29 | `string` **author**<br /> | ||
30 | Author of the integration. Not currently used. | ||
31 | |||
32 | `string` **license**<br /> | 26 | `string` **license**<br /> |
33 | 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/ |
34 | 28 | ||
35 | `string` **repository**<br /> | 29 | `string` **repository**<br /> |
36 | Link to your Github, Gitlab or Bitbucket public repository | 30 | Link to your Github, Gitlab or Bitbucket public repository. Not used in the application, but is very helpful if we need to log bugs or update to newer versions, etc. |
37 | 31 | ||
38 | `object` **config**<br /> | 32 | `object` **config** _mandatory_<br /> |
39 | This is the Ferdi specific integration config. | 33 | This is the Ferdi-specific integration config. |
40 | 34 | ||
41 | * `string` **serviceURL**<br/> | 35 | * `string` **serviceURL**<br/> |
42 | Defines the URL that should be loaded into the Ferdi webview. | 36 | Defines the URL that should be loaded into the Ferdi webview. |
@@ -46,11 +40,13 @@ If you want to load a simple URL like `https://www.messenger.com`, you can simpl | |||
46 | If your service works with custom URLs, just leave this empty. | 40 | If your service works with custom URLs, just leave this empty. |
47 | <br /><br /> | 41 | <br /><br /> |
48 | **Examples** | 42 | **Examples** |
43 | |||
49 | ```json | 44 | ```json |
50 | { | 45 | { |
51 | "serviceURL": "https://www.messenger.com" | 46 | "serviceURL": "https://www.messenger.com" |
52 | } | 47 | } |
53 | ``` | 48 | ``` |
49 | |||
54 | <br /> | 50 | <br /> |
55 | 51 | ||
56 | ```json | 52 | ```json |
@@ -58,35 +54,28 @@ If your service works with custom URLs, just leave this empty. | |||
58 | "serviceURL": "https://{teamId}.slack.com" | 54 | "serviceURL": "https://{teamId}.slack.com" |
59 | } | 55 | } |
60 | ``` | 56 | ``` |
61 | * `boolean` **hasTeamId** _default: true_<br /> | 57 | |
58 | * `boolean` **hasTeamId** _default: false_<br /> | ||
62 | Is this a team based service? If true, the interface to add the service will require a team identifier. e.g. `[teamId]`.slack.com | 59 | Is 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 /> | 60 | * `string` **urlInputPrefix**<br /> |
64 | This 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. _<TeamID>.hipchat.com_ | 61 | This option is only used in combination with `hasTeamId: true` in order to display the value of `urlInputPrefix` before the input for TeamId to make it obvious to the user what input is required from them. Eg. _<TeamID>.hipchat.com_ |
62 | * `string` **urlInputSuffix**<br /> | ||
63 | This 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 them. Eg. _<TeamID>.hipchat.com_ | ||
64 | * `boolean` **hasHostedOption** _default: false_<br /> | ||
65 | If a service can be hosted and has a teamId or customUrl | ||
65 | * `boolean` **hasCustomUrl** _default: false_<br /> | 66 | * `boolean` **hasCustomUrl** _default: false_<br /> |
66 | On premise services like HipChat, Mattermost, ... require a custom URL. This option enables the user to enter a custom URL when adding the service. | 67 | On-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 /> | 68 | * `boolean` **hasNotificationSound** _default: false_<br /> |
68 | Some 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 | Some 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`. |
70 | * `boolean` **hasDirectMessages** _default: true_<br /> | ||
71 | Some services have direct 1x1 messages e.g. a mention or message to every user in a channel (@channel). If this flag is set to `true`, the user can enable/disable if there should be a badge for direct messages. | ||
69 | * `boolean` **hasIndirectMessages** _default: false_<br /> | 72 | * `boolean` **hasIndirectMessages** _default: false_<br /> |
70 | Services 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. | 73 | Services 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 /> | 74 | * `string` **message**<br /> |
72 | Info message that will be displayed in the add/edit service interface. | 75 | Info message that will be displayed in the add/edit service preferences screen. |
76 | * `string` **disablewebsecurity**<br /> | ||
77 | Some services like hangoutschat need the web security disabled. | ||
73 | 78 | ||
74 | ## Example | 79 | ## Example |
75 | ### Mattermost configuration | 80 | |
76 | ```json | 81 | The [mattermost configuration](https://github.com/getferdi/recipes/blob/master/recipes/mattermost/package.json) is a typical example. |
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/integration.md b/docs/integration.md index 360c722..769bde7 100644 --- a/docs/integration.md +++ b/docs/integration.md | |||
@@ -65,16 +65,13 @@ Every recipe needs a specific file structure in order to work as a Ferdi recipe | |||
65 | 65 | ||
66 | ### package.json | 66 | ### package.json |
67 | 67 | ||
68 | The package.json is structured like any other node module and allows to completely configure the service. | 68 | The `package.json` is structured like any other node module and allows to completely configure the service. |
69 | 69 | ||
70 | ```json | 70 | ```json |
71 | { | 71 | { |
72 | "id": "tweetdeck", | 72 | "id": "tweetdeck", |
73 | "name": "Tweetdeck", | 73 | "name": "Tweetdeck", |
74 | "version": "1.0.1", | 74 | "version": "1.0.1", |
75 | "description": "Tweetdeck", | ||
76 | "main": "index.js", | ||
77 | "author": "Stefan Malzner <stefan@adlk.io>", | ||
78 | "license": "MIT", | 75 | "license": "MIT", |
79 | "repository": "https://github.com/meetfranz/recipe-tweetdeck", | 76 | "repository": "https://github.com/meetfranz/recipe-tweetdeck", |
80 | "config": { | 77 | "config": { |
@@ -85,7 +82,7 @@ The package.json is structured like any other node module and allows to complete | |||
85 | 82 | ||
86 | To get more information about all the provided configuration flags, check the [config docs](configuration.md). | 83 | To get more information about all the provided configuration flags, check the [config docs](configuration.md). |
87 | 84 | ||
88 | Please note that the fields `id`, `name`, `version` and `config` and required. | 85 | Please note that the fields `id`, `name`, `version` and `config` are mandatory. |
89 | 86 | ||
90 | ### index.js | 87 | ### index.js |
91 | 88 | ||
@@ -130,7 +127,7 @@ Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_2) AppleWebKit/537.36 (KHTML, like | |||
130 | 127 | ||
131 | Some services may not be compatible with Ferdi adding it's signature to the user agent. | 128 | Some services may not be compatible with Ferdi adding it's signature to the user agent. |
132 | 129 | ||
133 | If you encounter such a service, you remove this signature with the following snippet of code | 130 | If you encounter such a service, please remove this signature with the following snippet of code |
134 | 131 | ||
135 | ```js | 132 | ```js |
136 | overrideUserAgent() { | 133 | overrideUserAgent() { |
@@ -151,7 +148,7 @@ overrideUserAgent() { | |||
151 | 148 | ||
152 | ### webview.js | 149 | ### webview.js |
153 | 150 | ||
154 | The 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()`). | 151 | The `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()`). |
155 | 152 | ||
156 | ```js | 153 | ```js |
157 | // orat.io integration | 154 | // orat.io integration |
@@ -176,17 +173,17 @@ To get more information about the provided functions, check the [API docs](front | |||
176 | 173 | ||
177 | ## Icons | 174 | ## Icons |
178 | 175 | ||
179 | In 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. | 176 | In order to show every service icon crystal clear within the Ferdi UI, we require the icon in .svg (square, 1024x1024px) format. |
180 | 177 | ||
181 | ## Dark Mode | 178 | ## Dark Mode |
182 | 179 | ||
183 | 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. | 180 | 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. |
184 | 181 | ||
185 | Recipe Dark Mode is only supported by Ferdi 5.0.0-beta.19+ | 182 | 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). |
186 | 183 | ||
187 | ## Debugging | 184 | ## Debugging |
188 | 185 | ||
189 | In order to debug your service integration, open Ferdi and use the shortcut `Cmd/Ctrl+Alt+Shift+i` to open the recipes developer tools. | 186 | In order to debug your service integration, open Ferdi and use the shortcut `Cmd/Ctrl+Alt+Shift+I` to open the recipes developer tools. |
190 | 187 | ||
191 | ## Publishing | 188 | ## Publishing |
192 | 189 | ||