Extendable base service for easier development.

CONTRIBUTING.md

@@ -12,10 +12,6 @@ UX and usability. If you are looking for a full featured dashboard, there is ton
 - Configuration is stored in a simple config file, avoiding the need for a backend/database while making possible to use versioning or [config template](https://docs.ansible.com/ansible/latest/user_guide/playbooks_templating.html).
 - Only modern browsers are supported, feel free to use any JS features without any polyfill as soon as the latest version of the major browsers supports them.
 
-### Roadmap
-
-If you want to know more about the project direction or looking for something to work on, checkout the [roadmap](https://github.com/bastienwirtz/homer#Roadmap)!
-Feel free to open an issue if you have any question.
 
 # Ground Rules
 
@@ -40,8 +36,9 @@ feel free to open an issue to present your idea.
 ### How to submit a contribution
 
 The general process to submit a contribution is as follow:
-1. Create your own fork of the code
+1. Take a look to the [development guideline](https://github.com/bastienwirtz/homer/blob/main/docs/development.md).
-2. Do the changes in your fork
+2. Create your own fork of the code
-3. Make sure to fill the [pull request description](https://github.com/bastienwirtz/homer/blob/main/.github/PULL_REQUEST_TEMPLATE.md) properly.
+3. Do the changes in your fork
+4. Make sure to fill the [pull request description](https://github.com/bastienwirtz/homer/blob/main/.github/PULL_REQUEST_TEMPLATE.md) properly.
 
 ### Happy coding :metal:

docs/development.md

@@ -1,5 +1,7 @@
 # Development
 
+If you want to contribute to Homer, please read the [contributing guidelines](https://github.com/bastienwirtz/homer/blob/main/CONTRIBUTING.md) first. 
+
 ```sh
 # Using yarn (recommended)
 yarn install
@@ -10,6 +12,49 @@ npm install
 npm run serve
 ```
 
+## Custom services
+
+Custom services are small VueJs component (see `src/components/services/`) that add little features to a classic, "static", dashboard item. It should be very simple.
+A dashboard can contain a lot of items, so performance is very important. 
+
+The [`Generic`](https://github.com/bastienwirtz/homer/blob/main/src/components/services/Generic.vue) service provides a typical card layout which
+you can extend to add specific features. Unless you want a completely different design, extended the generic service is the recommended way. It gives you 3 [slots](https://vuejs.org/v2/guide/components-slots.html#Named-Slots) to extend: `icon`, `content` and `indicator`. 
+Each one is **optional**, and will display the usual information if omitted.
+
+Each service must implement the `item` [property](https://vuejs.org/v2/guide/components-props.html) and bind it the Generic component if used.
+
+### Skeleton
+```Vue
+<template>
+  <Generic :item="item">
+    <template #icon>
+      <!-- left area containing the icon -->
+    </template>
+    <template #content>
+      <!-- main area containing the title, subtitle, ... -->
+    </template>
+    <template #indicator>
+      <!-- top right area, empty by default -->
+    </template>
+  </Generic>
+</template>
+
+<script>
+import Generic from "./Generic.vue";
+
+export default {
+  name: "MyNewService",
+  props: {
+    item: Object,
+  },
+  components: {
+    Generic,
+  }
+};
+</script>
+```
+
+
 ## Themes
 
 Themes are meant to be simple customization (written in [scss](https://sass-lang.com/documentation/syntax)).

src/components/Service.vue

@@ -7,16 +7,13 @@ import Generic from "./services/Generic.vue";
 
 export default {
   name: "Service",
-  components: {
-    Generic,
-  },
   props: {
     item: Object,
   },
   computed: {
     component() {
       const type = this.item.type || "Generic";
-      if (type == "Generic") {
+      if (type === "Generic") {
         return Generic;
       }
       return () => import(`./services/${type}.vue`);

src/components/services/AdGuardHome.vue

@@ -1,20 +1,6 @@
 <template>
-  <div>
+  <Generic :item="item">
-    <div class="card" :class="item.class">
+    <template #content>
-      <a :href="item.url" :target="item.target" rel="noreferrer">
-        <div class="card-content">
-          <div class="media">
-            <div v-if="item.logo" class="media-left">
-              <figure class="image is-48x48">
-                <img :src="item.logo" :alt="`${item.name} logo`" />
-              </figure>
-            </div>
-            <div v-if="item.icon" class="media-left">
-              <figure class="image is-48x48">
-                <i style="font-size: 35px" :class="['fa-fw', item.icon]"></i>
-              </figure>
-            </div>
-            <div class="media-content">
       <p class="title is-4">{{ item.name }}</p>
       <p class="subtitle is-6">
         <template v-if="item.subtitle">
@@ -24,26 +10,26 @@
           {{ percentage }}&percnt; blocked
         </template>
       </p>
-            </div>
+    </template>
+    <template #indicator>
       <div class="status" :class="protection">
         {{ protection }}
       </div>
-          </div>
+    </template>
-          <div class="tag" :class="item.tagstyle" v-if="item.tag">
+  </Generic>
-            <strong class="tag-text">#{{ item.tag }}</strong>
-          </div>
-        </div>
-      </a>
-    </div>
-  </div>
 </template>
 
 <script>
+import Generic from "./Generic.vue";
+
 export default {
   name: "AdGuardHome",
   props: {
     item: Object,
   },
+  components: {
+    Generic,
+  },
   data: () => {
     return {
       status: null,

src/components/services/Generic.vue

@@ -8,6 +8,7 @@
       <a :href="item.url" :target="item.target" rel="noreferrer">
         <div class="card-content">
           <div :class="mediaClass">
+            <slot name="icon">
               <div v-if="item.logo" class="media-left">
                 <figure class="image is-48x48">
                   <img :src="item.logo" :alt="`${item.name} logo`" />
@@ -18,12 +19,16 @@
                   <i style="font-size: 35px" :class="['fa-fw', item.icon]"></i>
                 </figure>
               </div>
+            </slot>
             <div class="media-content">
+              <slot name="content">
                 <p class="title is-4">{{ item.name }}</p>
                 <p class="subtitle is-6" v-if="item.subtitle">
                   {{ item.subtitle }}
                 </p>
+              </slot>
             </div>
+            <slot name="indicator" class="indicator"></slot>
           </div>
           <div class="tag" :class="item.tagstyle" v-if="item.tag">
             <strong class="tag-text">#{{ item.tag }}</strong>

src/components/services/Ping.vue

@@ -1,46 +1,24 @@
 <template>
-  <div>
+  <Generic :item="item">
-    <div class="card" :class="item.class">
+    <template #indicator>
-      <a :href="item.url" :target="item.target" rel="noreferrer">
-        <div class="card-content">
-          <div class="media">
-            <div v-if="item.logo" class="media-left">
-              <figure class="image is-48x48">
-                <img :src="item.logo" :alt="`${item.name} logo`" />
-              </figure>
-            </div>
-            <div v-if="item.icon" class="media-left">
-              <figure class="image is-48x48">
-                <i style="font-size: 35px" :class="['fa-fw', item.icon]"></i>
-              </figure>
-            </div>
-            <div class="media-content">
-              <p class="title is-4">{{ item.name }}</p>
-              <p class="subtitle is-6">
-                <template v-if="item.subtitle">
-                  {{ item.subtitle }}
-                </template>
-              </p>
-            </div>
       <div v-if="status" class="status" :class="status">
         {{ status }}
       </div>
-          </div>
+    </template>
-          <div class="tag" :class="item.tagstyle" v-if="item.tag">
+  </Generic>
-            <strong class="tag-text">#{{ item.tag }}</strong>
-          </div>
-        </div>
-      </a>
-    </div>
-  </div>
 </template>
 
 <script>
+import Generic from "./Generic.vue";
+
 export default {
   name: "Ping",
   props: {
     item: Object,
   },
+  components: {
+    Generic,
+  },
   data: () => ({
     status: null,
   }),
@@ -70,9 +48,6 @@ export default {
 </script>
 
 <style scoped lang="scss">
-.media-left img {
-  max-height: 100%;
-}
 .status {
   font-size: 0.8rem;
   color: var(--text-title);