Introduction to Xen HTML

Widget Locations

To load widgets into Xen HTML, it is recommended to place those that are intended for the Lockscreen into:

/var/mobile/Library/LockHTML

The file LockBackground.html will be then be used to load your widget. This is to ensure backwards compatibility with both GroovyLock and LockHTML.

For the Homescreen, Xen HTML will load widgets from:

/var/mobile/Library/SBHTML

The HTML file loaded from here will be Wallpaper.html, again, to maintain backwards compatibility with SBHTML.

Both of these folders will be created on installation by Xen HTML if they do not currently exist.

WidgetInfo.plist

When building widgets to run in Xen HTML, you now have the option to include a new file named WidgetInfo.plist in your widget. Including this file allows you to specify additional metadata to be loaded, and furthermore allows you to use Options.plist (as per iWidgets) as user-facing settings. Please note that the usage of Options.plist is optional.

Example widget using WidgetInfo.plist: download here.

General WidgetInfo.plist Keys

A number of keys can be set in WidgetInfo.plist, with more to be added over time:

isFullscreen

Configures whether the widget's size should be set to the display's bounds, or to the size key.

<key>isFullscreen</key>
<false/>

size

Configures the size of the widget, and is typically used in conjunction with isFullscreen.

<key>size</key>
<dict>
  <key>width</key>
  <integer>100</integer>
  <key>height</key>
  <integer>100</integer>
</dict>

useOptionsPlist

Configures whether to use Options.plist in this widget.

<key>useOptionsPlist</key>
<true/>

widgetCanScroll

Configures whether the widget can scroll vertically when in use, such as how a typical webpage functions.

<key>widgetCanScroll</key>
<true/>

Options.plist Keys

Since utilising WidgetInfo.plist allows for usage of Options.plist, this will also be documented here.

Example Options.plist: download here.

To add a new settings option in Options.plist, you will want to create a new dictionary item:

<dict>
</dict>

There a few options that can be specified to complete a setting, with one being optional. These are placed inside the new dictionary item:

type

Configures what type the setting is.

<key>type</key>
<string>edit</string>

Available options:

switch - specifies that the setting is a simple true/false toggle

edit - allows the user to enter any text or number for this variable

select - allows the user to select a number of possible settings from a list

name

This setting is the name of the variable used in your code.

<key>name</key>
<string>someVariable</string>

label

This setting is the variable's formatted name as dislayed to the user when configuring settings.

<key>label</key>
<string>Some Variable</string>

default

The default value for this settings option.

If using switch as the type:

<key>default</key>
<true/>

If using edit as the type:

<key>default</key>
<string>val</string>

or

<key>default</key>
<integer>1</integer>

If using select as the type:

<key>default</key>
<string>Options Title</string>

Where the value is equal to the <key> in the dictionary supplied in options (see below).

options

This provides the list of available options the user can pick from when using the select type. The other two types don't need this key.

<key>options</key>
<dict>
  <key>First Title</key>
  <string>firstval</string>
  <key>Second Title</key>
  <string>secondval</string>
</dict>

For each line in the dictionary provided to this key, the <key> is what is displayed to the user in Settings, and the following line is the variable in your code it corresponds to.

Make sure to check on an iWidget how this works if you're unsure.