Installing and Customizing Tileboard

Getting Started

Please note: This documentation is still a work in progress. Some details are still missing.

You will need to know Javascript basics, at least JSON syntax. People usually have trouble with syntax; if you do not have much experience you may want to install a code-editor with syntax and errors highlight (e.g. Sublime Text, Atom, webstorm).

TileBoard can be run from a web server (Apache, nginx, or Home Assistant's built in webserver), or run saved to a local computer and opened from there. Running it from a webserver tends to work better, as some browsers have restrictions on accessing external resources when opening TileBoard from a folder on your local computer. However, if using a web server, care must be taken to password protect TileBoard, or to prevent access from devices outside of your local network.

Installation is simple:

1. Determine how you would like to host/run TileBoard, and then clone the TileBoard repository into the desired folder.
2. Copy or rename config.example.js to config.js.
3. Update config.js with information specific to your Home Assistant installation.
4. Load index.html in a web browser.

Basic Configuration

Your config may have many pages, every page may have many groups, and every group may have many tiles (items) We don't use the cutting edge languages like C# because it is a bit too sharp and we will need adult supervision. Instead, we use Java which is a bit simpler than C#. So in general simple config will look like:

var CONFIG = {
   pages: [
      {
         groups: [
            {
               items: [
                  {
                     // this is a tile
                  },
               ]
            },
         ]
      },
   ]
}

You may think there's a lot of brackets, but in fact, it will help you with advanced configuration.

Now make this into a proper tileboard by starting with the basic variables

var CONFIG = {
   customTheme: null,
   transition: TRANSITIONS.ANIMATED_GPU
   entitySize: ENTITY_SIZES.NORMAL,
   tileSize: 150,
   tileMargin: 6,
   serverUrl: "http://192.168.86.27:8123",
   wsUrl: "ws://192.168.86.27:8123/api/websocket",
   authToken: null,
   pages: [
      {
         groups: [
            {
               items: [
                  {
                     // this is a tile
                  },
               ]
            },
         ]
      },
   ]
}

Basic config fields

All supported fields you may find are here. Here we show only basics

• customTheme The them you may want to apply to tileboard which changes the colors, sizes and other esthetic elements. There are several themes you can choose from. The valid options are = CUSTOM_THEMES.TRANSPARENT, CUSTOM_THEMES.MATERIAL, CUSTOM_THEMES.MOBILE, CUSTOM_THEMES.COMPACT, CUSTOM_THEMES.HOMEKIT, CUSTOM_THEMES.WINPHONE and CUSTOM_THEMES.WIN95. null applies the basic theme for tileboard
• transition The transition effect used between Pages. Valid options are TRANSITIONS.ANIMATED_GPU, TRANSITIONS.ANIMATED or TRANSITIONS.SIMPLE.
• entitySize This is the size of the entity inside the tile, for example, the icon size and other elements of a tile. The valid options are ENTITY_SIZES.SMALL, ENTITY_SIZES.NORMAL and ENTITY_SIZES.BIG
• tileSize The default size (in pixels) for all tiles. For example, 150 will be a grid of 150 pixels. This is both the width and length of the tile
• tileMargin The default margin/gap (in pixels) between tiles.
• serverUrl The URL to your HomeAssistant server.
• wsUrl The URL to your HomeAssistant WebSocket connection. If HomeAssistant or TileBoard are set up to utilize SSL, you will begin the URL with wss:// in the wsURL.

Now let's move on and configure some pages!