Customizing HP

There are three ways to customize HousePanel

  • Tile Editor
  • Tile Customizer
  • Manual “hmoptions.cfg” and CSS Editing

The Tile Editor is used to change how tiles and pages look, including background images, colors, fonts, and alignment. The first section describes the main functionality of the Tile Editor. The Tile Customizer changes the actual content of each tile. Tile Customizer can be used to add user text and images to a tile, add clickable hyperlinks, and even add fields from one tile into another. The next section describes how to use this powerful feature. Finally, all styling in HousePanel is done using industry standard CSS settings, so maximum flexibility can be obtained by manually editing certain files. Powerful macros can also be created by editing the hmoptions.cfg file directly. The last section below describes the macro format and the CSS files for power users who wish to do deep customization.

Tile Editor

Some amazing work done by @nitwit in the SmartThings community inspired the development of a robust tile editor in HousePanel that can be used to modify the look of just about every element of every tile. To use the editor, select “Edit” mode in the radio buttons near the bottom of the page. Each tile will then show a green, blue, and red dot. Red will delete the tile, Blue will open the Tile Customizer described in the next section, and Green will open the following Tile Editor page.

This window can be dragged around on the screen such that you can see the effects of edits made on the main screen immediately. Tile editor use is self-explanatory as it uses standard dialog box features. To style a particular item, first click on it in the tile display or you can select the item from the drop down list below the tile. Some items are hidden and can only be selected from the drop down list. For those items you can select them and then unhide them and style them however you like. The icon background will style the entire tile. So if you want an image background on a tile, select “whole tile” and then pick the image you want. The on or off state of some tiles can be toggled by clicking on the main icon. Some tiles have multi-state icons such as thermostats. Each click rotates to the next state.

There is even a gradient background feature to add some flair to your tiles. The icon can be selected from your local subdirectory or it can be taken from a library of standard Android icons. There is also a directory called “media” where you can load any custom images. By default this directory contains a number of interesting backgrounds you can use. This is how I used my photo in the presence tile.

I think you will enjoy tinkering with this feature. If you are more of a power user and want to fully control your own destiny, keep reading for how one would style the page using custom written CSS. One other thing is worth noting — if you use the tile editor feature, HousePanel will create a file named “customtiles.css” containing the styling information specified. This file should not be edited directly. You can save this file and create a library of profiles for later use. There are lots of options here. If you want to customize your setup, you should make those custom edits in the housepanel.css file in your skins directory following the instructions below.

Tile Customizer

Tile content can also be altered using the built in Tile Customizer in HousePanel. To use the customizer, select “Edit” mode in the radio buttons near the bottom of the page. Clicking on the blue circle will open the Tile Customizer page that looks as follows:

The Custom Type option in the upper left is used to pick what type of customization you are performing. Seven options are available: TEXT, POST, GET, PUT, URL, LINK, and RULE.

TEXT Customization Type

TEXT links are used to add any user provided text to the tile. When adding anything to the tile, you must name the field in the User Field Name area on the left. You can also select an existing field, in which case your text will show up instead of the default behavior that this tile normally shows. Be careful with this feature because it can remove important functionality. Then again, this flexibility means you can make all sorts of creative effects.

TEXT Passwords

TEXT custom fields can be used to add a password to any tile. To do this create a new TEXT field named password, all lowercase. Then enter the password in the text box in the upper right. Click “Add” and the password will be converted to a hash. This hash is the value stored in the TEXT field. When this tile is clicked, the password must be given to

POST, GET, and PUT Customization Type

POST, GET, and PUT types are used to add a user-specified web service to the tile being customized using the method selected. In the top of the right column, enter a valid URL to the web service. You must also either pick the field this will override OR give a new user-defined field name using the entry box on the left. Click the “Add” button and this field will be added to the list of “Existing Fields” shown on the left side of this dialog box. You can mix and match this with any other addition.

URL Customization Type

URL types are similar to POST, GET, and PUT except it opens the given URL in a new window. The text entered must begin with http for this to work. TEXT fields will behave like URL fields when a valid URL is provided.

LINK Customization Type

LINK types enable you to add any other field from any other tile in your smart home to the tile being customized. This will be a virtual link in that the state will stay in sync with the original. The customize page will look different in this mode:

In the top of the right column, select the tile to link to, and then select which field of this tile to link into the customized tile using the “Available Fields” list above on the right. Once you are happy with your selection, click the “Add” button and this field will be added to the list of “Existing Fields” shown on the left side of this dialog box. You can mix and match this with any other addition. In the above example I added a light switch to a temperature tile, followed by two user text fields.

Note that with LINK customizations the field name must be taken from the linked tile. If you link in a switch field from another tile, it will replace the existing switch field. If you attempt to link in another switch field, it will overwrite any existing one unless you alter the field name by adding some custom text after the word switch. For example, you could make this field name switchtwo. This only works if there is already a linked field named switch.

RULE Customization Type

RULE types provide a simple automation capability. The rule is provided as a single line of text representing the tile number you want to control, the field, and the type of action you want to take. These three values are separated by an equal sign. Any number of rules can be entered separated by a comma or semicolon. For example, to turn on tiles 42 and 60 that are both switches you would enter:

42=switch=on, 60=switch=on 

More complex rules are allowed such as setting level and mixing on and off. For example, the following will open a garage door, turn off a light, and set the level of a dimmer. Any number of commands can be strung together using this RULE feature.

16=door=open, 60=switch=off, 51=level=30 

To use this rule feature you need to have the tile numbers that you want to control. Tile numbers can be obtained from the Info page. RULE can only contain single word commands like on, off, open, close. Macros do not have this limitation, but they can only be created manually by editing the hmoptions.cfg file.

The Tile Customizer is a powerful tool for making custom panels. All fields added by the customizer are subsequently available to the Tile Editor so they can be styled. By default added fields take on the style of their parent, but that can be modified using the Tile Editor.

Macros

Macros are a more powerful alternative to automation than the RULE system provided by the Tile Customizer described in the previous section. With Macros you can string together any number of action calls that HousePanel supports and connect it to any field on any tile. The catch is there is no GUI for defining Macros. Macros must be hand-written and saved in your hmoptions.cfg file, so this is a feature only for power users. Macros are defined in a section of the hmoptions.cfg file called “macros”. That section looks something like:

"macros":{
"custom|custom_4|test":
[
  ["-","adcd1-12345-4a33-c111-11223ea123","switch","switch","toggle"],
  ["-","dcba9-54321-4cda-a222-223344abcd","switch","switch","off"],
  ["-","dcba9-26371-5cda-b333-65432abcda","switchlevel","level","on","60"]
]
}

The keys are a string composed of the type, the id, and the field, separated by the “|” symbol. The type|id pair is the “connected tile” that is used to trigger the macro. This should be one of the tiles listed in the “index” section of the hmoptions.cfg file. The field specified is the field that is clicked on to invoke the macro. An array of arrays follow. Each array entry has up to 6 fields. The first array element is the hub id. If “-” is entered, the hubid of the connected tile is used. The second element is the id of the thing to automate. The third element is the type of thing. The fourth element is the field to control. The fifth element is the command or value to pass to HP. For example, it could be “on”, “off”, “open”, or “close”. A sixth element is attribute that is sent for some tiles to be controlled. For example, level can be sent this way.

Any number of macros can be defined and they can be tied to anything, including custom fields as is shown in the above example. The only restriction is they cannot be mixed with RULE custom fields.