Summary

Fields can be

All fields can be single-valued or multi-valued, except for

They are stored in Firefox preferences (on top of values manifests). Therefore

Special values

Undefined

A field of any type can be undefined (unless it was instantiated with value of parameter requireAndPopulate other than false). If the module is associated with a folder, and the field is undefined in that associated set, it gets inherited from

See also SettingsScope.

Present and empty

‘Present and empty’ is only allowed for multivalued fields (choice or non-choice). It means that a multi-valued field has no entry, and it should be stored and presented as such (rather than inheriting values from other applicable sets or manifests). It can be present in values manifests or preferences. In values manifests it’s represented by string SELITE_VALUE_PRESENT.

Null

Most Field types can be configured to allow null. It’s possible only for single-valued fields (Boolean/Int/String, File (including Folder and SQLite) and single-valued Choice). However, while single-valued Choice itself can have value null when no choice is selected, its selectable choices cannot have null value.

Values of multi-valued fields can’t be null (see below); but they can be undefined or empty but present. The whole multi-valued field can’t be null, either. (Explanation: null will never be supported for items of multi-valued/choice fields. For practicality the API presents and stores both values of multi-valued fields and keys of choice fields as names of Javascript object properties (i.e. object keys). That can’t handle null well. Javascript transforms it into string 'null', which then couldn’t be distinguished from proper null. E.g. var o={}; o[null]= 1; Object.keys(o)[0]==='null' evaluates to true.)

Use literal SELITE_NULL to represent null in values manifests (as per SettingsManifests > Literals for special values). You can specify Javascript’s null as a field default value in the module definition.

Default values

SeLite Settings populates default values for some fields. It happens when

If module.associatesWithFolders==true, we want the ability to inherit values from sets or values manifests from higher folders. Therefore it doesn’t populate default value for any fields of such modules.

If the schema defines a field with defaultValue===undefined, then it’s not populated in the set(s).

File fields

Values of Field.File fields stored in configuration sets are full (absolute) paths to files (or folders). So they may not work for other users. Also, if you copy your Firefox profile folder to a system that uses a different folder separator (between Windows and Max OS/Linux), these fields won’t work.

However, you can use values manifests to assign Field.File fields relative to the manifest’s folder. Also, such paths will work on either system (Windows or Mac OS/Linux). See SettingsManifests > Literals for special values.

Selecting files in GUI

When selecting a value (a file) for fields of class Field.File defined with saveFile option, the file selector dialog behaves as if you were saving a file. So if you select an existing file, it will confirm with you whether you want to overwrite it. However, the file won’t be overwritten until the field is actually used for that purpose. Examples of such fields are ones for and vanillaDB (see SettingsInterface > Reloading databases).

Whether a Field.File or Field.SQLite field is marked as saveFile or not, the framework can overwrite such a file. However, saveFile makes it possible to specify names of files that don’t exist yet. Without that flag a file needs to exist first before you can select it for the field.

Standard and custom validation

Standard validation

If you provide a custom validation function, that is used in addition to standard validation.

Do not inherit directly from Field class, because the implementation may change. Only SeLite Settings defines its subclasses. That’s why there are two axis for validation - standard & custom. You can have a field with custom validation without having a special subclass for it.

Customising existing fields

Frameworks can add or remove fields from existing configuration modules (like extensions.selite-settings.common) and they can add keys to existing fields. See