diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/frontend_api.md | 69 |
1 files changed, 47 insertions, 22 deletions
diff --git a/docs/frontend_api.md b/docs/frontend_api.md index cceda9c..aa1070b 100644 --- a/docs/frontend_api.md +++ b/docs/frontend_api.md | |||
@@ -3,20 +3,26 @@ | |||
3 | Provides a set of helper functions to integrate the service into [Ferdi](https://getferdi.com). | 3 | Provides a set of helper functions to integrate the service into [Ferdi](https://getferdi.com). |
4 | 4 | ||
5 | ## Ferdi Class Methods | 5 | ## Ferdi Class Methods |
6 | * [setBadge](#user-content-setbadge) | 6 | |
7 | * [injectCSS](#user-content-injectcss) | 7 | - [setBadge](#user-content-setbadge) |
8 | * [loop](#user-content-loop) | 8 | - [injectCSS](#user-content-injectcss) |
9 | * [onNotify](#user-content-onnotify) | 9 | - [loop](#user-content-loop) |
10 | * [handleDarkMode](#user-content-handleDarkMode) | 10 | - [onNotify](#user-content-onnotify) |
11 | - [handleDarkMode](#user-content-handleDarkMode) | ||
11 | 12 | ||
12 | ### setBadge(directMessages, [indirectMessages]) | 13 | ### setBadge(directMessages, [indirectMessages]) |
14 | |||
13 | Sets the unread message badge | 15 | Sets the unread message badge |
14 | 16 | ||
15 | #### Arguments | 17 | #### Arguments |
18 | |||
16 | 1. `int` directMessages | 19 | 1. `int` directMessages |
17 | * sets the count of direct messages eg. Slack direct mentions, or a message to @channel | 20 | |
21 | - sets the count of direct messages eg. Slack direct mentions, or a message to @channel | ||
22 | |||
18 | 2. `int` indirectMessages (optional) | 23 | 2. `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 | 24 | |
25 | - Set a badge that defines there are new messages but they do not involve me directly to me eg. in a channel | ||
20 | 26 | ||
21 | #### Usage | 27 | #### Usage |
22 | 28 | ||
@@ -29,11 +35,14 @@ Ferdi.setBadge(3); | |||
29 | ``` | 35 | ``` |
30 | 36 | ||
31 | ### injectCSS(pathToCssFile) | 37 | ### injectCSS(pathToCssFile) |
38 | |||
32 | Injects the contents of one or more CSS files into the current webview | 39 | Injects the contents of one or more CSS files into the current webview |
33 | 40 | ||
34 | #### Arguments | 41 | #### Arguments |
42 | |||
35 | 1. `string` cssFile | 43 | 1. `string` cssFile |
36 | * CSS files that should be injected. This must be an absolute path to the file | 44 | |
45 | - CSS files that should be injected. This must be an absolute path to the file | ||
37 | 46 | ||
38 | #### Usage | 47 | #### Usage |
39 | 48 | ||
@@ -51,6 +60,7 @@ Ferdi.injectCSS(globalStyles, focusModeStyles); | |||
51 | ``` | 60 | ``` |
52 | 61 | ||
53 | ### injectJSUnsafe(pathToJsFile) | 62 | ### injectJSUnsafe(pathToJsFile) |
63 | |||
54 | Injects the contents of one or more JavaScript files into the current webview without context isolation | 64 | Injects the contents of one or more JavaScript files into the current webview without context isolation |
55 | 65 | ||
56 | Ferdi uses context isolation to prevent services from accessing Node.js APIs in the webview. | 66 | Ferdi uses context isolation to prevent services from accessing Node.js APIs in the webview. |
@@ -60,8 +70,10 @@ Trying to overwrite properties of the `window` object or other objects or trying | |||
60 | The code is executed as if part of the body of a Javascript function, ie. you should modify the `window` object explicitly to expose objects in the global scope. | 70 | The code is executed as if part of the body of a Javascript function, ie. you should modify the `window` object explicitly to expose objects in the global scope. |
61 | 71 | ||
62 | #### Arguments | 72 | #### Arguments |
73 | |||
63 | 1. `string` jsFile | 74 | 1. `string` jsFile |
64 | * JavaScript files that should be injected. This must be an absolute path to the file | 75 | |
76 | - JavaScript files that should be injected. This must be an absolute path to the file | ||
65 | 77 | ||
66 | #### Usage | 78 | #### Usage |
67 | 79 | ||
@@ -79,9 +91,11 @@ Ferdi.injectCSS(globalScripts, focusModeScripts); | |||
79 | ``` | 91 | ``` |
80 | 92 | ||
81 | ### loop(action) | 93 | ### loop(action) |
94 | |||
82 | Runs an action every X milliseconds (Ferdi default is currently 1s) | 95 | Runs an action every X milliseconds (Ferdi default is currently 1s) |
83 | 96 | ||
84 | #### Arguments | 97 | #### Arguments |
98 | |||
85 | 1. `function` action | 99 | 1. `function` action |
86 | 100 | ||
87 | #### Usage | 101 | #### Usage |
@@ -90,36 +104,42 @@ Runs an action every X milliseconds (Ferdi default is currently 1s) | |||
90 | // slack integration | 104 | // slack integration |
91 | const path = require('path'); | 105 | const path = require('path'); |
92 | 106 | ||
93 | module.exports = (Ferdi) => { | 107 | module.exports = Ferdi => { |
94 | const getMessages = () => { | 108 | const getMessages = () => { |
95 | const directMessages = $('.unread_highlights, .unread_highlight').not('.hidden').length; | 109 | const directMessages = $('.unread_highlights, .unread_highlight').not( |
110 | '.hidden', | ||
111 | ).length; | ||
96 | const indirectMessages = $('.unread').length - directMessages; | 112 | const indirectMessages = $('.unread').length - directMessages; |
97 | 113 | ||
98 | Ferdi.setBadge(directMessages, indirectMessages); | 114 | Ferdi.setBadge(directMessages, indirectMessages); |
99 | } | 115 | }; |
100 | 116 | ||
101 | Ferdi.loop(getMessages); | 117 | Ferdi.loop(getMessages); |
102 | 118 | ||
103 | Ferdi.injectCSS(path.join(__dirname, 'style.css')); | 119 | Ferdi.injectCSS(path.join(__dirname, 'style.css')); |
104 | } | 120 | }; |
105 | ``` | 121 | ``` |
106 | 122 | ||
107 | ### onNotify(fn) | 123 | ### onNotify(fn) |
124 | |||
108 | Runs `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) | 125 | Runs `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) |
109 | 126 | ||
110 | #### Arguments | 127 | #### Arguments |
128 | |||
111 | 1. `function` fn | 129 | 1. `function` fn |
112 | 130 | ||
113 | #### Usage | 131 | #### Usage |
114 | 132 | ||
115 | ```js | 133 | ```js |
116 | // messenger integration | 134 | // messenger integration |
117 | module.exports = (Ferdi) => { | 135 | module.exports = Ferdi => { |
118 | const getMessages = () => { | 136 | const getMessages = () => { |
119 | let count = document.querySelectorAll('._5fx8:not(._569x),._1ht3:not(._569x)').length; | 137 | let count = document.querySelectorAll( |
138 | '._5fx8:not(._569x),._1ht3:not(._569x)', | ||
139 | ).length; | ||
120 | const messageRequestsElement = document.querySelector('._5nxf'); | 140 | const messageRequestsElement = document.querySelector('._5nxf'); |
121 | if (messageRequestsElement) { | 141 | if (messageRequestsElement) { |
122 | count += parseInt(messageRequestsElement.innerHTML, 10); | 142 | count += parseInt(messageRequestsElement.textContent, 10); |
123 | } | 143 | } |
124 | 144 | ||
125 | Ferdi.setBadge(count); | 145 | Ferdi.setBadge(count); |
@@ -129,7 +149,8 @@ module.exports = (Ferdi) => { | |||
129 | 149 | ||
130 | Ferdi.onNotify(notification => { | 150 | Ferdi.onNotify(notification => { |
131 | if (typeof notification.title !== 'string') { | 151 | if (typeof notification.title !== 'string') { |
132 | notification.title = ((notification.title.props || {}).content || [])[0] || 'Messenger'; | 152 | notification.title = |
153 | ((notification.title.props || {}).content || [])[0] || 'Messenger'; | ||
133 | } | 154 | } |
134 | 155 | ||
135 | return notification; | 156 | return notification; |
@@ -138,6 +159,7 @@ module.exports = (Ferdi) => { | |||
138 | ``` | 159 | ``` |
139 | 160 | ||
140 | ### handleDarkMode(callback) | 161 | ### handleDarkMode(callback) |
162 | |||
141 | You 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 built-in dark modes), then you can use a custom dark mode handler instead. | 163 | You 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 built-in dark modes), then you can use a custom dark mode handler instead. |
142 | 164 | ||
143 | This handler should take the necessary steps to (de-)activate dark mode on the page, e.g. by clicking a button or flipping a switch. | 165 | This handler should take the necessary steps to (de-)activate dark mode on the page, e.g. by clicking a button or flipping a switch. |
@@ -145,18 +167,21 @@ This handler should take the necessary steps to (de-)activate dark mode on the p | |||
145 | Ferdi 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. | 167 | Ferdi 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. |
146 | 168 | ||
147 | #### Arguments | 169 | #### Arguments |
170 | |||
148 | 1. `function` callback | 171 | 1. `function` callback |
149 | 172 | ||
150 | #### Callback function arguments | 173 | #### Callback function arguments |
174 | |||
151 | 1. `boolean` isEnabled: Is Dark Mode currently enabled? | 175 | 1. `boolean` isEnabled: Is Dark Mode currently enabled? |
152 | 2. `object` helpers: Helper functions that you can use in your function: | 176 | 2. `object` helpers: Helper functions that you can use in your function: |
153 | `enableDarkMode` - Enable DarkReader | 177 | `enableDarkMode` - Enable DarkReader |
154 | `disableDarkMode` - Disable DarkReader | 178 | `disableDarkMode` - Disable DarkReader |
155 | `injectDarkModeStyle` - Inject darkmode.css | 179 | `injectDarkModeStyle` - Inject darkmode.css |
156 | `removeDarkModeStyle` - Remove service's darkmode.css | 180 | `removeDarkModeStyle` - Remove service's darkmode.css |
157 | `isDarkModeStyleInjected` - Function that returns true if darkmode.css is injected into the page | 181 | `isDarkModeStyleInjected` - Function that returns true if darkmode.css is injected into the page |
158 | 182 | ||
159 | #### Usage | 183 | #### Usage |
184 | |||
160 | ```JavaScript | 185 | ```JavaScript |
161 | // Handler that works for Reddit | 186 | // Handler that works for Reddit |
162 | Ferdi.handleDarkMode((isEnabled, helpers) => { | 187 | Ferdi.handleDarkMode((isEnabled, helpers) => { |