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 using the radio buttons near the bottom of the page. Each tile will then show a gear icon, a red dot, and a blue dot. Clicking on the gear icon will open the Tile Editor shown below. The red dot will delete the tile, and the blue dot will open the Tile Customizer described in the next section.

HousePanel Tile Editor

The Tile Editor window can be dragged around on the screen so that you can see the effects of edits made on the main screen immediately. The Tile Editor is mostly self-explanatory as it uses standard dialog box features.

Custom Name and Effect Scope

The Custom Name and Effect Scope perhaps require explanation. A custom name can be assigned to the tile. Any text can be specified in the top central box, and then the “Save Name” button must be pressed. The Effect Scope determines whether changes made in the Tile Editor apply to just this tile on all pages (default), just this tile on this page, all tiles like this on all pages, all tiles like this on this page, all tiles everywhere, or all tiles on this page. Edits made after making this selection will have the selected scope. This means you should select the desired scope first and then make edits.

Field Selection

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, un-hide them, and style them however you like.

The first option in the list is called “whole tile” and is used to style the background or border of the entire tile. So if you want an image background on a tile, select “whole tile” and then pick the image you want. Images can also be assigned to individual fields on the tile. Some fields have multiple states such as “on” and “off”. Some tiles have multiple states such as thermostats. Each click rotates to the next state. If you want to have the style of all field states to be the same, you will have to select the tile field in the list. If you recently clicked on the field, you will need to click on a different field and then select the field you want to style. The way CSS works is more specific styling always takes precedence so if you style a specific field state, that style will still be used even if you set a style for all field states.

Icons

Icons can be selected from your Local Storage or it can be taken from a library of standard Android icons. The Local Storage option will list all icons in the “icon” folder of the active skin. There is also a directory called “media” in each skin’s folder. This is where you can load any custom image you want to show. In the default “skin-housepanel” skin this folder contains a number of interesting backgrounds you can use. This is how I used my photo in the presence tile. Once an icon is selected, it can be aligned to the left, center, or right side of the tile using the radio buttons just beneath the storage type dropdown box. If you want to clear an icon select the None checkbox.

Colors and Fonts

Entire tiles or specific fields can also be set to any color you like. The three boxes on the left are used to set the background and foreground colors. The Background Effect box is used to add a gradient to the background color to add some flair to your tiles. If you want the text of an item to not show, pick any color and set the transparency to a very small number, such as 0.01. Hiding will also work, but hiding will also hide any icon assigned, so if you want the icon to show but not the text, use the transparency trick. The font type and size boxes do what one expects they do. One nuance is the font size is in pixels, not font points.

Text Alignment

Text alignment is achieved by using one of the radio buttons under Text Alignment. If you select Left, you can also nudge the item to the down or right by selecting a non-zero value for Top Padding or Left Padding. If you want a specific location, you can also click “Absolute Loc” and then change the Top Padding and Left Padding values to your liking. When in absolute mode padding is actually interpreted as the absolute location of the item. Normally fields are stacked on top of each other in the order they appear. You can force a field to display side by side with the next field by selecting the “Inline” checkbox. When you do this you may want to also add some Left Padding to the next field.

Borders

Border Type selections are applied every time a selection is made in the drop down box. For example, if you want an item to have a round, thick, white border, you would first select “Circle”, then “Thick”, and then “White Color”. The order matters – the shape should be selected first, then the line thickness, and then the color. The “Default”, “Shadow Square” and “Action Tiles Look” options are intended for use only when Whole Tile is selected. These options will make the entire tile look one of three specific ways.

Customize Button

The “Customize” button will launch the Tile Customizer where new fields can be added to the tile. The Tile Customizer can also be launched from the main screen using the blue dot as described earlier. The button here in the editor is provided as a convenience. Note that when one does use this button and new fields are created or old ones modified, those changes will not be reflected in the editor until it is closed and reopened.

CSS Editing

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, you can write your own custom CSS, but using the Tile Editor is much easier. It is worth noting that the Tile Editor writes CSS to achieve the requested style and stores them in a file named “customtiles.css” in the skin folder. This file normally should not be edited directly, but if you do want to make your own custom CSS edits, this is the best place to store them. You can also customize your setup by editing the housepanel.css file. HousePanel applies the CSS in housepanel.css first and then those in customtiles.css, so edits made in customtiles.css will override any made in housepanel.css.

Tile Customizer

Tile content can also be altered or added using the built in Tile Customizer in HousePanel. 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. To use the customizer, select “Edit” mode in the radio buttons near the bottom of the page. Clicking on the blue dot will open the following Tile Customizer page.

The Custom Type option in the upper left is used to pick what type of customization you are performing. Six options are available: TEXT, POST, GET, 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. Also, some user provided TEXT field names have special meanings and can do special things. The next few sections describe these special cases.

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 custom field is present and the tile is clicked, the password must be given for the action to be performed.

All on and all off

If a field is created with the name “allon” or “alloff” then clicking on the field will cause all switches on the page to turn on or off. Be careful using this because anything with a field named “switch” will be turned on, including audio tiles. Everything in ISY is a switch so for ISY only the tiles with a unit of measure equal to “100” will be activated.

POST and GET Customization Type

POST and GET 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 and GET except it opens the given URL in a new window. The text entered must begin with http for this to work.

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.

Simple Rules (Macros)

RULE types provide a powerful automation capability. The simplest rule types can be thought of as macros that activate more than one tile. The macro is defined by providing 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 macros 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 

Any valid field that has an action is allowed such as setting a level or opening a garage door. 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 feature.

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

A fourth field can be specified in a macro to delay the execution of the action. This is optional, and if omitted, the action will be invoked immediately. If provided, the delay value must be a numerical integer representing the number of seconds to wait before executing the command. For example, the following will open the door, turn a light on, and then turn that same light off after 30 seconds.

16=door=open, 60=switch=on, 60=switch=off=30 

To use this feature you need to have the tile numbers that you want to control. Tile numbers can be obtained from the Show Info page or from the Tile Editor.

ADVANCED RULEs (Rule Engine)

Prior versions of HP had a MACRO type. This was removed from HP V2 and in its place the RULE engine described above was upgraded to support both Macro type automations (noted above) and conditional Rule Engine like automations. This section introduces the RULE engine. Detailed documentation is provided on the Rules page.

All rules begin with the word “if” followed by a tile number (optional for the first trigger), a field name, and a logic test. The logic test can be any of ==, <, >, <=, >= != following usual logic math conventions. A simple rule would then be:

if contact==open, 60=switch=on

This would cause the light to come on if the contact noted is opened. A more complex rule can add “and” and “or” logical math with additional checks as shown below. This example checks the weather for being above a certain temperature and mode, and sets some action.

if temperature > 80 and 16=themode=Home, 49=switch=on, 52=coolingSetpoint=72

Note that the first part of the if statement does not give a tile number. This is because the rule assumes the fields of the tile where the rule is defined. To mix in another field from another tile in a rule, as shown above, the tile number must be given as the first parameter. In the above example, tile #16 is our mode tile and the field “themode” is the name of the field holding the mode status. Rules are case sensitive so be careful when comparing to text fields to use the proper case.

To learn more about rules, proceed to the RULES page for detailed documentation.