Removed elements INSTALLATIONFILE and PREFFILE. Changed processPrefsTree() number of params.    02 Jan 2002
Removed choose attribute.    ~~13 Dec 2001~~
Original version.    ~~11 Dec 2001~~
Steve Meredith

Structure of the Pref Editor XML File for the PrefsTree Widget

Introduction

The Pref Editor is a widget for CCK/Factory, named PrefsTree in .ini files. It is a tree control which displays prefs in a hierarchy and allows a user to edit their values. It reads an XML file to determine the structure of the tree control. This XML file includes information on each pref, including its name, its default value, a description of it, etc. It also includes structure for how these prefs are grouped in the tree control. The name of the XML file is specified in the .ini section for the PrefsTree Widget. The default file must be located in the same directory as the WIZARDMACHINE.EXE . When used, a copy of the file is saved in the working config directory. This copy contains the changes made by the CCK/Factory user, and is used by the install builder to write preferences in the install image. A SCRIPT.IB entry must be made in order for it process the .XML file: processPrefsTree(,browser.xpi,bin/netscp6.cfg) . Note that spaces are not allowed between the parameters. For details on adding a PrefsTree control to wizard pages, see the document PrefsTree.htm

Who This Document is For

You will need to understand the structure of the XML file if you want to add or remove prefs to the Pref Editor or change how they are grouped.

Conventions

For XML item tags, we use ALL CAPS. For attribute names, we use lower case. “true” and “false” are also written in lower case. Generally, for PREF items, the attributes are those things about the pref which are fixed, and use elements for thing the CCK/Factory app will change. The exception is for <CHOICES>, which are difficult to represent as attributes, so these are elements.

General Structure

Example 1

The simplest file that may exist consists of one group containing one pref.

<?xml version="1.0"?>

<PREFSGROUP uiname="Netscape Preferences">

  <PREF uiname="Open Browser on Startup" prefname="general.startup.browser"
type="bool" lockable="true" description="When the application starts, open
a browser window.">

    <VALUE>true</VALUE>

    <LOCKED>false</LOCKED>
  </PREF>

</PREFSGROUP>

The above file will result in a tree control with one parent, the group, and one child, the pref. See the example below.

Example 1

Example 2

The more complicated example below shows the top level group, with two sub groups, each with two preferences.

<?xml version="1.0"?>


<PREFSGROUP uiname="Netscape Preferences">

  <PREFSGROUP uiname="Group 1">

    <PREF uiname="Autoload What's Related" prefname="browser.related.autoload"
type="int" lockable="true" description="A good description
of this pref goes here.">

      <CHOICES>

        <CHOICE uiname="Always" value="0"/>

        <CHOICE uiname="After First Use" value="1"/>

        <CHOICE uiname="Never" value="2"/>

      </CHOICES>

      <VALUE>0</VALUE>

      <LOCKED>false</LOCKED>
    </PREF>

    <PREF uiname="Start Page" prefname="browser.startup.page"
type="int" lockable="true" description="Display this page when
Navigator starts up.">

      <CHOICES>

        <CHOICE uiname="Blank Page" value="0"/>

        <CHOICE uiname="Home Page" value="1"/>

        <CHOICE uiname="Last Page Visited" value="2"/>

      </CHOICES>

      <VALUE>0</VALUE>

      <LOCKED>false</LOCKED>
    </PREF>

  </PREFSGROUP>

  <PREFSGROUP uiname="Group 2">

    <PREF uiname="Bookmarks" prefname="browser.toolbars.showbutton.bookmarks"
type="bool" lockable="true" description="Show Booksmarks button on browser
toolbar.">

      <VALUE>true</VALUE>

      <LOCKED>false</LOCKED>
    </PREF>

    <PREF uiname="Go" prefname="browser.toolbars.showbutton.go"
type="bool" lockable="true" description="Show Go button on browser toolbar.">

      <VALUE>true</VALUE>

      <LOCKED>false</LOCKED>
    </PREF>

  </PREFSGROUP>

</PREFSGROUP>

The above example also demonstrates how to include multiple choice prefs. These make it easier for the CCK/Factory user to select pref values without understanding how they are implemented. This XML file results in the prefs tree structure in the example below.

Example 2

Reference

The structure of the file is important. Not much work as been put into handling malformed files. If the XML is invalid, you'll get an error that the file failed to load, an error type, and a line number. If you create valid XML, but don't follow the rules as defined here, the behaviour is undefined. It's probably easiest to start with an existing prefs XML file, then cut, paste, and edit the <PREF>s from there.

<PREFSGROUP>

Each <PREFSGROUP> element will make a new level of hierarchy in the tree control. A <PREFSGROUP> may contain <PREF>s or other <PREFSGROUP> or both, but must not be empty. The first element in the file must be a <PREFSGROUP>. These may be nested arbitrarily deep.

Attribute	Example	Description
`uiname`	`uiname="Netscape Preferences"`	This is the name of the group as it appears in the tree control.

<PREF>

Each pref element will make a leaf node in the tree control--a pref which the user can edit.These elements must be contained in some <PREFSGROUP>.

Attribute	Example	Description
`uiname`	`uiname="Open Browser on Startup"`	This is the name of the pref as is appears in the tree control. It doesn't have to be the name of the pref--it should be something easy for the user to understand.
`prefname`	`prefname="general.startup.browser"`	This is the real name of the pref as it is used by the Netscape client products.
`type`	`type="bool"`	Must be one of `int`, `bool`, or `string`. This determines how the pref will be edited in the Pref Editor and how it is written to the prefs file in the install image. `bool` Pref Editor user allowed to select “true” or “false” from a drop-down. No quotes are used when writing the pref in the pref file. For example, `pref("general.startup.browser", true);` `int` Pref Editor user allowed to enter integers. No quotes are used when writing the pref in the pref file. For example, `pref("network.proxy.socks_version", 5);` `string` Pref Editor user may enter whatever he likes. Quotes are used when writing the pref in the pref file. For example, `pref("general.useragent.vendorComment", "AK-MyISP");`
`lockable`	`lockable="true"`	Determines whether or not the Pref Editor user can change the lock state the pref.
`description`	`description="When the application starts, open a browser window."`	This is some text which further describes the pref to the Pref Editor user. It appears when the user selected the pref for editing. Any text which helps the user under the pref should go here.

<CHOICES>

This element can optionally appear in <PREF> element if the values are to be translated into easy to understand multiple choice options. It contains more than one <CHOICE> element. When the user edits one of these prefs, he gets a list box from which he can select from those choices described in the <CHOICE> elements which are contained in the <CHOICES> element. It will work for any type, but it is up to the person creating the XML to set the values in the value attribute to the correct type for the enclosing <PREF>. See Example 2, and <CHOICE>.

The example below shows how a multiple choice pref will look like when the user selects it for editing.

Example 3

<CHOICE>

This element appears in <CHOICES> elements to describe one item of a multiple choice. Each <CHOICE> element in a <CHOICES> element for a <PREF> appears in a list box when the user edits a pref of this type. When selected, the value of the value attribute for the selected <CHOICE> is saved as the pref's value. See Example 2, and <CHOICES>.

Attribute	Example	Description
`uiname`	`uiname="Blank Page"`	The text of this choice in the list box for this choice.
`value`	`value="0"`	The value saved in the `<VALUE>` element for the `<PREF>` when the pref is edit and this choice is selected in the list box. The type of the value must be correct for the enclosing `<PREF>` element.

<VALUE>

One and only one must appear in a <PREF> element. This is the value of the pref. No quotes, regardless of type. This gets modified when the user edits the pref. Note that the modified file is saved to the working config directory.

<LOCKED>

One and only one must appear in a <PREF> element. This is true or false, depending on whether the pref is locked or not. If locked, prefs are written as lockPref() instead of pref(). See also <PREF lockable="true">.