Feature Pages

Feature pages are used to display information that is not settings related. To display settings, use the JUI formatted settings page. A feature page is an HTML file that exists in the HomeSeer html folder, plugin folder. All plugin HTML content is stored in a folder that is named with the plugin ID. Feature pages are registered to HomeSeer using the HomeSeerSystem.RegisterFeaturePage API call. When a page is registered it will appear in the Plugins menu in HomeSeer.

A feature page is a standard HTML page and may contain dynamic content. Dynamic content is provided with the use of tags. See HTML Pages for more information.

For reference, install the sample plugin. This will install some sample feature pages that can be used as template for new pages.

HTML pages are based on the Bootstrap responsive CSS library. This allows pages to display properly on desktop as well as mobile devices. The HTML uses the MDB Boostrap libray. See the MDB documentation for more information about Bootstrap formatting.

When To Use

Any settings that the plugin requires need to be handled by a JUI settings page. Anything that is device related, should be handled by devices and can be supported with GetJuiDeviceConfigPage. Anything that is not device related, say status, debug, or general information, should be supported with a feature page.

Installation

When installing a plugin, feature pages need to be installed in the HomeSeer HTML folder in a folder named with the ID of the plugin.

Page Format

Feature pages need to display the HomeSeer navigation menu and header. Tags are available to insert these for you. For styles, CSS and javascript are provided with tags.

Page header that includes required CSS files.

CODE

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <!--This maintains the scale of the page based on the scale of the screen-->
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta name="author" content="HomeSeer Technologies">
    <!--This liquid tag loads all of the necessary css files for HomeSeer-->
    {{includefile '/bootstrap/css/page_common.css'}}
    <title>YOUR FEATURE PAGE TITLE HERE</title>
</head>

Page body that includes standard HomeSeer header, navigation bar, and javascript files.

CODE

<body class="body homeseer-skin">
<!--These liquid tags add the HomeSeer header and navbar to the top of the page when appropriate-->
{{includefile 'header.html'}}
{{includefile 'navbar.html'}}
<!--Primary container for the page content
    The .container class ensures the page content is fit and centered to the screen-->
<div class="container">
    <!--This is an intentionally blank page that you can use as a blueprint to create feature pages from-->
</div>
<!-- Bootstrap core JavaScript
================================================== -->
<!-- Placed at the end of the document so the pages load faster -->
{{includefile 'bootstrap/js/page_common.js'}}
</body>
</html>

The two code blocks above complete a full working feature page.

Registering Feature Pages with HomeSeer

From the plugin Initialize function, call HomeSeerSystem.RegisterFeaturePage(..). Assuming your feature page is name "acme.html" and your plugin ID is "acme", the call would be:

CODE

HomeSeerSystem.RegisterFeaturePage("acme","acme.html","Acme Plugin Status");

The page will installed in the HomeSeer Plugins menu under the plugin name.

Feature pages must have a .html extension or they will not display properly.

Images

HomeSeer uses 2 sites for images and it is suggested you use these sites so images are consistent throughout the UI.

https://fontawesome.com/icons?d=gallery

https://materialdesignicons.com/

Fontawesome is the easiest to use since you can reference an icon easily with just an <i> tag. Materialdesignicons will require you to download the image and save it in an images folder in your plugin's HTML folder.

Plugin Tags

To create dynamic HTML pages for plugins a dedicated tag is available that will allow you to call custom functions in your plugin. The format of the tag is:

CODE

{{plugin_function PLUGID PLUG_FUNCTION PLUG_PARAMETERS_ARRAY}}

Where the PLUGID is the ID of your plugin, PLUG_FUNCTION is the name of the function to call, and PLUG_PARAMETERS_ARRAY is an array of parameters to pass to the function. If no parameters are required, set this to Null (C#) or Nothing (VB).

For example, your feature page may need to display a table of information that is dynamic or just some information that changes depending on the plugin usage. The sample plugin has some examples of custom tags.

To create a custom tag first create the function in your HSPI class. If you need a function that simply returns a string of data, a number, or any standard .NET type create a function like:

CODE

C#
public string MyCustomFunction(string param) {
	return "1234";
}
VB
Public Function MyCustomFunction(param as String) as String
	return "1234"
End Function

In your feature page HTML file enter the tag:

CODE

{{ plugin_function 'HomeSeerSamplePlugin' 'MyCustomFunction' ['1'] }}

When the page is displayed your function MyCustomFunction(param) will be called, which returns the string "1234" and "1234" will be displayed on the page. Note that "[1]" in the example is that parameter that is sent to the plugin function, not used in this case.

'HomeSeerSamplePlugin' is the ID of the plugin that is being called.

You can also return arrays from your plugin and iterate over the array in the tag.

Create the function in your HSPI class as:

CODE

C#
public List<string> MyCustomFunctionArray(string param)
{
	List<string> list = new List<string>();
	list.Add("item 1");
    list.Add("item 2");
	return list;
}
VB
public List<string> Public Function MyCustomFunctionArray(param as String) as List(of String)
{
	dim list as new List(of String)
	list.Add("item 1")
    list.Add("item 2")
	return list;
}

To iterate over this with a tag:

CODE

{{ list=plugin_function 'HomeSeerSamplePlugin' 'MyCustomFunctionArray' ['1'] }}
Custom function array values:<br>
{{ for item in list }}
	Item: {{item}}<br>
{{ end }}

If you want to use your own class as the returned type, you need to make it Serializable:

C#

C#
[Serializable]
public class TriggerOptionItem 
{
	public int Id { get; set; }
	public string Name { get; set; }

	public TriggerOptionItem(int id, string name) {
		Id = id;
		Name = name;
	}

	public TriggerOptionItem() { }
}

public List<TriggerOptionItem> GetTriggerOption(int numTriggerOptions) 
{
	var triggerOptions = new List<TriggerOptionItem>();
	for (var i = 1; i <= numTriggerOptions; i++) 
	{
		triggerOptions.Add(new TriggerOptionItem(i, $"Trigger Option {i}"));
	}
	return triggerOptions;
}

To use the properties of your class in your html file:

XML

{{ list2=plugin_function 'HomeSeerSamplePlugin' 'GetTriggerOption' [2] }}
{{ for item in list2 }}
<div class="jui-view jui-toggle">
	<label class="jui-toggle-text" for="{{ item.id }}">{{ item.name }}</label>
	<span class="jui-toggle-control"><span class="form-check form-check-inline jui-toggle-checkbox"><input type="checkbox" class="form-check-input jui-input" id="{{ item.id }}"/> <label class="form-check-label jui-toggle-checkbox-label" for="{{ item.id }}"></label></span></span>
</div>
{{ end }}

The definition of the serializable class needs to be in the plugin exe, located in the HS root folder.