docs/development.md

   1 # Development
   2
   3 If you want to contribute to Homer, please read the [contributing guidelines](https://github.com/bastienwirtz/homer/blob/main/CONTRIBUTING.md) first.
   4
   5 ```sh
   6 # Using yarn (recommended)
   7 yarn install
   8 yarn serve
   9
  10 # **OR** Using npm
  11 npm install
  12 npm run serve
  13 ```
  14
  15 ## Custom services
  16
  17 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.
  18 A dashboard can contain a lot of items, so performance is very important.
  19
  20 The [`Generic`](https://github.com/bastienwirtz/homer/blob/main/src/components/services/Generic.vue) service provides a typical card layout which
  21 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`.
  22 Each one is **optional**, and will display the usual information if omitted.
  23
  24 Each service must implement the `item` [property](https://vuejs.org/v2/guide/components-props.html) and bind it the Generic component if used.
  25
  26 ### Skeleton
  27 ```Vue
  28 <template>
  29   <Generic :item="item">
  30     <template #icon>
  31       <!-- left area containing the icon -->
  32     </template>
  33     <template #content>
  34       <!-- main area containing the title, subtitle, ... -->
  35     </template>
  36     <template #indicator>
  37       <!-- top right area, empty by default -->
  38     </template>
  39   </Generic>
  40 </template>
  41
  42 <script>
  43 import Generic from "./Generic.vue";
  44
  45 export default {
  46   name: "MyNewService",
  47   props: {
  48     item: Object,
  49   },
  50   components: {
  51     Generic,
  52   }
  53 };
  54 </script>
  55 ```
  56
  57
  58 ## Themes
  59
  60 Themes are meant to be simple customization (written in [scss](https://sass-lang.com/documentation/syntax)).
  61 To add a new theme, just add a file in the theme directory, and put all style in the `body #app.theme-<name>` scope. Then import it in the main style file.
  62
  63 ```scss
  64 // `src/assets/themes/my-awesome-theme.scss`
  65 body #app.theme-my-awesome-theme. { ... }
  66 ```
  67
  68 ```scss
  69 // `src/assets/app.scss`
  70 // Themes import
  71 @import "./themes/sui.scss";
  72 ...
  73 @import "./themes/my-awesome-theme.scss";
  74 ```