Child pages
  • The Settings Framework
Skip to end of metadata
Go to start of metadata

Introduction

The Settings Framework is an easy to use, yet powerful tool for storing arbitrary system or application settings. The settings are stored on the Filesystem so functionality depends on the presence of a memory card.

Settings are stored as string based key/value pairs. Parameters of a settings are:

ParameterDescription
ID"dot-separated" name (e.g. "network.ip.netmask")
LabelDisplayed name of the settings (e.g. "Subnetmask")
TypeArbitraty string defining the type (e.g. "ip_address" )
ValueString with the value of the setting (e.g. "255.255.255.0" )
EditableBoolean value indicating if the settings can be changed or not

Settings are organized in a tree structure. Each node has a name of at most 8 characters (case insensitive, numbers and letters only, no spaces or special characters allowed). The ID of a settings is a concatenation of the IDs of the nodes in its "path" down the tree.

E.g.

  • network
  • network.ip
  • network.ip.netmask
  • network.ip.gateway

Settings on the Filesystem

Settings are stored on the Filesystem in the form of a series of files and directories. The root of the settings is the directory called "settings".

The ID of a setting consists of a "Parent Tree" and "Name". The part behind the last dot (".") is the "Name", the part before the last dot is the "Parent Tree". Example:

IDnetwork.ip.netmask
Parent Treenetwork.ip
Namenetmask

The content of a settings is stored in a file called "Name.jsn". The Parent Tree is converted into a directory tree and prepended with the root directory of all setting files "settings/"

Full Filename = "settings/network/ip/netmask.jsn"

When creating a setting, the necessary directory tree is created automatically (with empty content). It is not necessary to create each parent individually.

When an empty parent is created, a dummy config element is stored in a file with extension .jst. It is still possible to create a real setting with the same name later; that action will not return the "Exists" error.

Setting Parameters

A setting has several parameters. The following sections describe them in detail.

ID

The ID is the unique identifier. As described in Settings on the Filesystem tte ID is mapped to a filename in a directory structure on the Filesystem. Because of Filesystem limitations, each ID node (parts between dots) can only be 8 characters long and may only contain number and letters. Additionally, the ID is case-insensitive.

Label

Describing a setting in a meaningful way is hard when only using the ID due to the strict limitation on the size and format of the ID. Therefore you can define a Label with a better description. For the Label there are no limitations on what the content can be. The Label is used for displaying the settings in the Online Settings Editor.

Type

The Type of a setting is an arbitrary string (any value is possible including 'nil'). The actual value of a settings is always a string, no matter what the Type says. The Type is used by the Online Settings Editor to display the setting in a suitable fashion. More details in the Online Settings Editor section.

Value

The actual value of the setting. This is always a string. Conversion to and from any other representation (e.g. a number) has to be done by the user.

Editable

A setting can be editable or not. Settings that are not editable receive their value when being created. This value can not be changed anymore afterwars. Writing to a setting that is not editable results in an error.

Online Settings Editor

The current state of all settings is available via the webinterface. The page settings.htm displays the settings and allows editing and saving them back to the device.

Settings are displayed under topics. Each "root node" becomes a topic. A topic cannot contain a value or it will not be displayed as a topic. Sub-topics are also possible.

By default all settings are rendered as a single line text input field. Some types however have a customized representation:

TypeRepresentation
booleanDisplayed as a checkbox
selectionDisplayed as a dropdown box
nilDisplayed as just a (sub-)topic
<everything else>Displayed as a text field

The selection type displays a dropdown box with all of its children as options. These children must have type nil. If any of these children has children of its own then those are only displayed when the selection parent has that child selected.

  • No labels