diff options
author | vantezzen <hello@vantezzen.io> | 2020-03-08 11:10:17 +0100 |
---|---|---|
committer | vantezzen <hello@vantezzen.io> | 2020-03-08 11:10:17 +0100 |
commit | 9d715597a600710c20f75412d3dcd8cdb7b3c39e (patch) | |
tree | 65ab812834d486aaccf35e2a31a7a628a7100422 /docs/frontend_api.md | |
parent | Revert to using the standart file comparison function (diff) | |
download | ferdium-recipes-9d715597a600710c20f75412d3dcd8cdb7b3c39e.tar.gz ferdium-recipes-9d715597a600710c20f75412d3dcd8cdb7b3c39e.tar.zst ferdium-recipes-9d715597a600710c20f75412d3dcd8cdb7b3c39e.zip |
Add documentation
Diffstat (limited to 'docs/frontend_api.md')
-rw-r--r-- | docs/frontend_api.md | 169 |
1 files changed, 169 insertions, 0 deletions
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 | |||
3 | Provides 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]) | ||
13 | Sets the unread message badge | ||
14 | |||
15 | #### Arguments | ||
16 | 1. `int` directMessages | ||
17 | * sets the count of direct messages eg. Slack direct mentions, or a message to @channel | ||
18 | 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 | ||
20 | |||
21 | #### Usage | ||
22 | |||
23 | ```js | ||
24 | Ferdi.setBadge(4, 2); | ||
25 | |||
26 | // or | ||
27 | |||
28 | Ferdi.setBadge(3); | ||
29 | ``` | ||
30 | |||
31 | ### injectCSS(pathToCssFile) | ||
32 | Injects the contents of one or more CSS files into the current webview | ||
33 | |||
34 | #### Arguments | ||
35 | 1. `string` cssFile | ||
36 | * CSS files that should be injected. This must be an absolute path to the file | ||
37 | |||
38 | #### Usage | ||
39 | |||
40 | ```js | ||
41 | const path = require('path'); | ||
42 | |||
43 | // inject a single css file | ||
44 | Ferdi.injectCSS(path.join(__dirname, 'style.css')); | ||
45 | |||
46 | // inject multiple css files | ||
47 | const globalStyles = path.join(__dirname, 'global.css'); | ||
48 | const focusModeStyles = path.join(__dirname, 'focusmode.css'); | ||
49 | |||
50 | Ferdi.injectCSS(globalStyles, focusModeStyles); | ||
51 | ``` | ||
52 | |||
53 | ### loop(action) | ||
54 | Runs an action every X milliseconds (Ferdi default is currently 1s) | ||
55 | |||
56 | #### Arguments | ||
57 | 1. `function` action | ||
58 | |||
59 | #### Usage | ||
60 | |||
61 | ```js | ||
62 | // slack integration | ||
63 | const path = require('path'); | ||
64 | |||
65 | module.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) | ||
80 | 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) | ||
81 | |||
82 | #### Arguments | ||
83 | 1. `function` fn | ||
84 | |||
85 | #### Usage | ||
86 | |||
87 | ```js | ||
88 | // messenger integration | ||
89 | module.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) | ||
115 | 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 build-in dark modes) you can use a custom dark mode handler instead. | ||
116 | |||
117 | This 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 | |||
119 | 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. | ||
120 | |||
121 | #### Arguments | ||
122 | 1. `function` callback | ||
123 | |||
124 | #### Callback function arguments | ||
125 | 1. `boolean` isEnabled: Is Dark Mode currently enabled? | ||
126 | 2. `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 | ||
136 | Ferdi.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 | ||
158 | Ferdi.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 | ||