diff options
-rw-r--r-- | .github/ISSUE_TEMPLATE/recipe_request.md | 5 | ||||
-rw-r--r-- | .github/PULL_REQUEST_TEMPLATE/add_recipe.md | 7 | ||||
-rw-r--r-- | README.md | 7 | ||||
-rw-r--r-- | docs/integration.md | 37 |
4 files changed, 37 insertions, 19 deletions
diff --git a/.github/ISSUE_TEMPLATE/recipe_request.md b/.github/ISSUE_TEMPLATE/recipe_request.md index c32ea1a..65bf7a9 100644 --- a/.github/ISSUE_TEMPLATE/recipe_request.md +++ b/.github/ISSUE_TEMPLATE/recipe_request.md | |||
@@ -18,13 +18,12 @@ If there is no repository on GitHub you can also create one yourself - this ofte | |||
18 | IF YOU ARE NOT FAMILIAR WITH JAVASCRIPT: Please still search for a recipe using the guide above and add it to your request. | 18 | IF YOU ARE NOT FAMILIAR WITH JAVASCRIPT: Please still search for a recipe using the guide above and add it to your request. |
19 | --> | 19 | --> |
20 | 20 | ||
21 | |||
22 | <!-- Please complete the following form to create your recipe request: --> | 21 | <!-- Please complete the following form to create your recipe request: --> |
23 | Name of the service (e.g. WhatsApp): | 22 | Name of the service (e.g. WhatsApp): |
24 | URL of the service (e.g. whatsapp.com): | 23 | URL of the service (e.g. whatsapp.com): |
25 | 24 | ||
26 | GitHub URL to a recipe <!-- (optional but highly recommended. Please look at the intructions above) -->: https://github.com/... | 25 | GitHub URL to a recipe <!-- (optional but highly recommended. Please look at the intructions above) -->: https://github.com/... |
27 | 26 | ||
28 | Features you want implemented (optional): | 27 | Features you want implemented (optional): |
29 | <!-- In this list you can write features you want this service to support, e.g. Notification support --> | 28 | <!-- In this list you can write features you want this service to support, e.g. Notification support --> |
30 | - | 29 | - |
diff --git a/.github/PULL_REQUEST_TEMPLATE/add_recipe.md b/.github/PULL_REQUEST_TEMPLATE/add_recipe.md index 6cc42b4..052fde4 100644 --- a/.github/PULL_REQUEST_TEMPLATE/add_recipe.md +++ b/.github/PULL_REQUEST_TEMPLATE/add_recipe.md | |||
@@ -2,7 +2,9 @@ | |||
2 | Thank you for taking the time to create a recipe for Ferdi. | 2 | Thank you for taking the time to create a recipe for Ferdi. |
3 | Please complete the following form so we can add your new recipe | 3 | Please complete the following form so we can add your new recipe |
4 | --> | 4 | --> |
5 | |||
5 | ## Adding new recipe | 6 | ## Adding new recipe |
7 | |||
6 | Service: [Service your new recipe is for] | 8 | Service: [Service your new recipe is for] |
7 | 9 | ||
8 | URL: [URL to your service] | 10 | URL: [URL to your service] |
@@ -10,7 +12,8 @@ URL: [URL to your service] | |||
10 | Service ID: [What ID does your recipe use?] | 12 | Service ID: [What ID does your recipe use?] |
11 | 13 | ||
12 | ### Terminal output | 14 | ### Terminal output |
13 | ``` | 15 | |
16 | ```bash | ||
14 | [Output of your terminal when you ran yarn package] | 17 | [Output of your terminal when you ran yarn package] |
15 | ``` | 18 | ``` |
16 | 19 | ||
@@ -19,4 +22,4 @@ Service ID: [What ID does your recipe use?] | |||
19 | - [ ] I am the original creator of this package | 22 | - [ ] I am the original creator of this package |
20 | - [ ] My recipe has been tested to work inside Ferdi | 23 | - [ ] My recipe has been tested to work inside Ferdi |
21 | 24 | ||
22 | <!-- Here you can write anything else you want to tell us. --> | 25 | <!-- Here you can write anything else you want to tell us. --> |
@@ -11,12 +11,15 @@ Official Recipe repository for Ferdi with over 100 recipes. | |||
11 | Copyright on these recipes is on their original creators - please look at `recipes/<id>/package.json` for information about the original creator and license. This is simply a curation of those recipes so we can include them into Ferdi. | 11 | Copyright on these recipes is on their original creators - please look at `recipes/<id>/package.json` for information about the original creator and license. This is simply a curation of those recipes so we can include them into Ferdi. |
12 | 12 | ||
13 | ## What are "Recipes"? | 13 | ## What are "Recipes"? |
14 | |||
14 | Recipes are small scripts that are responsible for providing the connection between your services (e.g. WhatsApp, GMail or Slack) and Ferdi. It provides Ferdi information like the number of current notifications, handles enabling dark mode and may otherwise improve your experience with the service. | 15 | Recipes are small scripts that are responsible for providing the connection between your services (e.g. WhatsApp, GMail or Slack) and Ferdi. It provides Ferdi information like the number of current notifications, handles enabling dark mode and may otherwise improve your experience with the service. |
15 | 16 | ||
16 | Each time you create a new service inside Ferdi, Ferdi will automatically install and execute the recipe associated with that service. | 17 | Each time you create a new service inside Ferdi, Ferdi will automatically install and execute the recipe associated with that service. |
17 | 18 | ||
18 | ## Creating and adding your own recipes | 19 | ## Creating and adding your own recipes |
19 | Please refer to our documentation at https://github.com/getferdi/recipes/blob/master/docs/integration.md. | 20 | |
21 | Please refer to our [documentation](docs/integration.md) | ||
20 | 22 | ||
21 | ## Minifying images | 23 | ## Minifying images |
22 | Please run `npm run minify-images` to optimize images | 24 | |
25 | Please run `npm run minify-images` to optimize images before you commit or raise PRs into this repository | ||
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 | |||
28 | You 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. | 30 | You 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 | ||
30 | We 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. | 32 | We 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 | |||
33 | 1. Fork this repository on GitHub. You can do this by clicking the "Fork" button in the top right corner | 36 | 1. Fork this repository on GitHub. You can do this by clicking the "Fork" button in the top right corner |
34 | 2. 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. | 37 | 2. 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. |
35 | 2. (Optional, if you want to use our creation script) Install its dependencies via the terminal: | 38 | 3. (Optional, if you want to use our creation script) Install its dependencies via the terminal: |
39 | |||
36 | ```Bash | 40 | ```Bash |
37 | npm install | 41 | npm install |
38 | ``` | 42 | ``` |
39 | 3. You can now run our automatic recipe wizard that creates and opens the new recipe for you: | 43 | |
44 | 4. 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 |
42 | npm run create "Service Name" | 48 | npm run create "Service Name" |
43 | ``` | 49 | ``` |
50 | |||
44 | Replace `Service Name` with the name of your service, e.g. `npm run create "Google Hangouts"`. | 51 | Replace `Service Name` with the name of your service, e.g. `npm run create "Google Hangouts"`. |
45 | 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. | 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. |
46 | 4. Reload Ferdi (`CMD/CTRL + SHIFT + R`) in order for it to register the new recipe | 53 | 5. Reload Ferdi (`CMD/CTRL + SHIFT + R`) in order for it to register the new recipe |
47 | 5. You can now develop your recipe as described below. Please continue down below with "[Publishing](#Publishing)" after you are done creating your recipe. | 54 | 6. 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 | |||
50 | Every recipe needs a specific file structure in order to work as a Ferdi recipe | 58 | Every 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 | |||
60 | The package.json is structured like any other node module and allows to completely configure the service. | 69 | The 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 | ||
80 | Please note that the fields `id`, `name`, `version` and `config` and required. | 89 | Please note that the fields `id`, `name`, `version` and `config` and required. |
81 | 90 | ||
82 | |||
83 | ### index.js | 91 | ### index.js |
92 | |||
84 | 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 Ferdi Class: |
85 | 94 | ||
86 | ```js | 95 | ```js |
@@ -88,6 +97,7 @@ module.exports = Ferdi => Ferdi; | |||
88 | ``` | 97 | ``` |
89 | 98 | ||
90 | 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 | |||
91 | ```js | 101 | ```js |
92 | // RocketChat integration | 102 | // RocketChat integration |
93 | module.exports = Ferdi => class RocketChat extends Ferdi { | 103 | module.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 | |||
118 | By default, Ferdi's user agent looks like this: | 126 | By default, Ferdi's user agent looks like this: |
119 | ``` | 127 | |
128 | ```text | ||
120 | 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) | 129 | 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) |
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 | ||
125 | If you encounter such a service, you remove this signature with the following snippet of code | 134 | If you encounter such a service, you remove this signature with the following snippet of code |
126 | 135 | ||
127 | ``` | 136 | ```js |
128 | overrideUserAgent() { | 137 | overrideUserAgent() { |
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 | ||
136 | If you want to change the user agent to a different one, you can simply return the String for the new user agent: | 145 | If 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 |
139 | overrideUserAgent() { | 148 | overrideUserAgent() { |
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 |
145 | 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()`). | ||
146 | 154 | ||
155 | 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()`). | ||
147 | 156 | ||
148 | ```js | 157 | ```js |
149 | // orat.io integration | 158 | // orat.io integration |
@@ -167,19 +176,23 @@ module.exports = (Ferdi) => { | |||
167 | To get more information about the provided functions, check the [API docs](frontend_api.md). | 176 | To get more information about the provided functions, check the [API docs](frontend_api.md). |
168 | 177 | ||
169 | ## Icons | 178 | ## Icons |
179 | |||
170 | 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. | 180 | 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. |
171 | 181 | ||
172 | ## Dark Mode | 182 | ## Dark Mode |
183 | |||
173 | 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 | 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. |
174 | 185 | ||
175 | Recipe Dark Mode is only supported by Ferdi 5.0.0-beta.19+ | 186 | Recipe Dark Mode is only supported by Ferdi 5.0.0-beta.19+ |
176 | 187 | ||
177 | ## Debugging | 188 | ## Debugging |
189 | |||
178 | 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 | In 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 | |||
181 | Ferdi uses its recipe repository at <https://github.com/getferdi/recipes> to publish recipes to all clients. | 194 | Ferdi uses its recipe repository at <https://github.com/getferdi/recipes> to publish recipes to all clients. |
182 | 195 | ||
183 | 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). | 196 | 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). |
184 | 197 | ||
185 | 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. \ No newline at end of file | 198 | 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. |