aboutsummaryrefslogtreecommitdiffhomepage
path: root/docs
diff options
context:
space:
mode:
authorBastien Wirtz <bastien.wirtz@gmail.com>2021-09-13 13:09:40 -0700
committerGitHub <noreply@github.com>2021-09-13 13:09:40 -0700
commit92d5b8d424cbd4c227c9c76931930787deec4a2f (patch)
treeaa52c1955c9cf210bd95ad32e20f1b4286f7c0a7 /docs
parent97f0c43ccc724ec4502e55f73874a89f822f0a81 (diff)
parent55c3ea4d92b0c5628ead4475ae7359bbf2cc59c4 (diff)
downloadhomer-92d5b8d424cbd4c227c9c76931930787deec4a2f.tar.gz
homer-92d5b8d424cbd4c227c9c76931930787deec4a2f.tar.zst
homer-92d5b8d424cbd4c227c9c76931930787deec4a2f.zip
Merge branch 'main' into main
Diffstat (limited to 'docs')
-rw-r--r--docs/configuration.md21
-rw-r--r--docs/customservices.md41
-rw-r--r--docs/tips-and-tricks.md58
3 files changed, 117 insertions, 3 deletions
diff --git a/docs/configuration.md b/docs/configuration.md
index c88069e..a76ecb3 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -66,6 +66,17 @@ colors:
66# Optional message 66# Optional message
67message: 67message:
68 # url: "https://<my-api-endpoint>" # Can fetch information from an endpoint to override value below. 68 # url: "https://<my-api-endpoint>" # Can fetch information from an endpoint to override value below.
69 # mapping: # allows to map fields from the remote format to the one expected by Homer
70 # title: 'id' # use value from field 'id' as title
71 # content: 'value' # value from field 'value' as content
72 # refreshInterval: 10000 # Optional: time interval to refresh message
73 #
74 # Real example using chucknorris.io for showing Chuck Norris facts as messages:
75 # url: https://api.chucknorris.io/jokes/random
76 # mapping:
77 # title: 'id'
78 # content: 'value'
79 # refreshInterval: 10000
69 style: "is-warning" 80 style: "is-warning"
70 title: "Optional message!" 81 title: "Optional message!"
71 icon: "fa fa-exclamation-triangle" 82 icon: "fa fa-exclamation-triangle"
@@ -81,6 +92,11 @@ links:
81 - name: "link 2" 92 - name: "link 2"
82 icon: "fas fa-book" 93 icon: "fas fa-book"
83 url: "https://github.com/bastienwirtz/homer" 94 url: "https://github.com/bastienwirtz/homer"
95 # this will link to a second homer page that will load config from page2.yml and keep default config values as in config.yml file
96 # see url field and assets/page.yml used in this example:
97 - name: "Second Page"
98 icon: "fas fa-file-alt"
99 url: "#page2"
84 100
85# Services 101# Services
86# First level array represents a group. 102# First level array represents a group.
@@ -88,6 +104,8 @@ links:
88services: 104services:
89 - name: "Application" 105 - name: "Application"
90 icon: "fas fa-code-branch" 106 icon: "fas fa-code-branch"
107 # A path to an image can also be provided. Note that icon take precedence if both icon and logo are set.
108 # logo: "path/to/logo"
91 items: 109 items:
92 - name: "Awesome app" 110 - name: "Awesome app"
93 logo: "assets/tools/sample.png" 111 logo: "assets/tools/sample.png"
@@ -118,9 +136,10 @@ services:
118 # background: red # optional color for card to set color directly without custom stylesheet 136 # background: red # optional color for card to set color directly without custom stylesheet
119``` 137```
120 138
139
121View [Custom Services](customservices.md) for details about all available custom services (like PiHole) and how to configure them. 140View [Custom Services](customservices.md) for details about all available custom services (like PiHole) and how to configure them.
122 141
123If you choose to fetch message information from an endpoint, the output format should be: 142If you choose to fetch message information from an endpoint, the output format should be as follows (or you can [custom map fields as shown in tips-and-tricks](./tips-and-tricks.md#mapping-fields)):
124 143
125```json 144```json
126{ 145{
diff --git a/docs/customservices.md b/docs/customservices.md
index 40f2e3d..4f64ecc 100644
--- a/docs/customservices.md
+++ b/docs/customservices.md
@@ -1,6 +1,8 @@
1# Custom Services 1# Custom Services
2 2
3Here is an overview of all custom services that are available within Homer. 3Some service can use a specific a component that provides some extra features by adding a `type` key to the service yaml
4configuration. Available services are in `src/components/`. Here is an overview of all custom services that are available
5within Homer.
4 6
5## PiHole 7## PiHole
6 8
@@ -17,6 +19,7 @@ The following configuration is available for the PiHole service.
17 type: "PiHole" 19 type: "PiHole"
18``` 20```
19 21
22
20## OpenWeatherMap 23## OpenWeatherMap
21 24
22Using the OpenWeatherMap service you can display weather information about a given location. 25Using the OpenWeatherMap service you can display weather information about a given location.
@@ -35,4 +38,38 @@ items:
35``` 38```
36 39
37**Remarks:** 40**Remarks:**
38If for some reason your city can't be found by entering the name in the `location` property, you could also try to configure the OWM city ID in the `locationId` property. To retrieve your specific City ID, go to the [OWM website](https://openweathermap.org), search for your city and retrieve the ID from the URL (for example, the City ID of Amsterdam is 2759794). \ No newline at end of file 41If for some reason your city can't be found by entering the name in the `location` property, you could also try to configure the OWM city ID in the `locationId` property. To retrieve your specific City ID, go to the [OWM website](https://openweathermap.org), search for your city and retrieve the ID from the URL (for example, the City ID of Amsterdam is 2759794).
42
43
44## Medusa
45
46This service displays News (grey), Warning (orange) or Error (red) notifications bubbles from the Medusa application.
47Two lines are needed in the config.yml :
48```
49type: "Medusa"
50apikey: "01234deb70424befb1f4ef6a23456789"
51```
52The url must be the root url of Medusa application.
53The Medusa API key can be found in General configuration > Interface. It is needed to access Medusa API.
54
55
56## Sonarr/Radarr
57
58This service displays Activity (blue), Warning (orange) or Error (red) notifications bubbles from the Radarr/Sonarr application.
59Two lines are needed in the config.yml :
60```
61type: "Radarr" or "Sonarr"
62apikey: "01234deb70424befb1f4ef6a23456789"
63```
64The url must be the root url of Radarr/Sonarr application.
65The Radarr/Sonarr API key can be found in Settings > General. It is needed to access the API.
66
67
68## PaperlessNG
69
70For Paperless you need an API-Key which you have to store at the item in the field `apikey`.
71
72
73## Ping
74
75For Ping you need an API-Key which you have to store at the item in the field `apikey`.
diff --git a/docs/tips-and-tricks.md b/docs/tips-and-tricks.md
index 2719fc5..94167fb 100644
--- a/docs/tips-and-tricks.md
+++ b/docs/tips-and-tricks.md
@@ -113,6 +113,64 @@ docker create \
113 113
114 114
115## Get the news headlines in Homer 115## Get the news headlines in Homer
116
117### Mapping Fields
118Most times, the url you're getting headlines from follows a different schema than the one expected by Homer.
119
120For example, if you would like to show jokes from ChuckNorris.io, you'll find that the url https://api.chucknorris.io/jokes/random is giving you info like this:
121
122```json
123{
124 "categories": [],
125 "created_at": "2020-01-05 13:42:22.089095",
126 "icon_url": "https://assets.chucknorris.host/img/avatar/chuck-norris.png",
127 "id": "MR2-BnMBR667xSpQBIleUg",
128 "updated_at": "2020-01-05 13:42:22.089095",
129 "url": "https://api.chucknorris.io/jokes/MR2-BnMBR667xSpQBIleUg",
130 "value": "Chuck Norris can quitely sneak up on himself"
131}
132```
133
134but... you need that info to be transformed to something like this:
135
136```json
137{
138 "title": "MR2-BnMBR667xSpQBIleUg",
139 "content": "Chuck Norris can quitely sneak up on himself"
140}
141```
142
143Now, you can do that using the `mapping` field in your `message` configuration. This example would be something like this:
144
145```yml
146message:
147 url: https://api.chucknorris.io/jokes/random
148 mapping:
149 title: 'id'
150 content: 'value'
151```
152
153As you would see, using the ID as a title doesn't seem nice, that's why when a field is empty it would keep the default values, like this:
154
155```yml
156message:
157 url: https://api.chucknorris.io/jokes/random
158 mapping:
159 content: 'value'
160 title: "Chuck Norris Facts!"
161```
162
163and even an error message in case the `url` didn't respond or threw an error:
164
165```yml
166message:
167 url: https://api.chucknorris.io/jokes/random
168 mapping:
169 content: 'value'
170 title: "Chuck Norris Facts!"
171 content: "Message could not be loaded"
172```
173
116#### `by @JamiePhonic` 174#### `by @JamiePhonic`
117 175
118Homer allows you to set a "message" that will appear at the top of the page, however, you can also supply a `url:`. 176Homer allows you to set a "message" that will appear at the top of the page, however, you can also supply a `url:`.