Defining preferences in the settings XML file

Follow these instructions to define preferences in a settings file that will be posted to an update site or included in a plugin_customization.ini file.

Procedure

Format the XML file using these parameters:
  • It must contain a <ManagedSettings> element that contains one or more <settingGroup> elements. Each <settingGroup> element must contain one or more <setting> elements.
  • Each <settingGroup> tag must have the following attributes:
    • name – Use the same name as the qualifier (typically plugin name, but it can be anything) that its settings are associated with.
    • lastModDate – Optional timestamp specifying the date using the jav.text.SimpleDateFormat format. The syntax is YYYYMMDDThhmmssZ, where YYYY=year, MM=month, DD=day, hh=hours, mm=minutes, ss=seconds. The values following the T are optional. If used, every change to a setting group must be accompanied by a change to the lastModDate attribute or the new values will not be updated. If no lastModDate is specified, the values are always updated, even if they are not new.
  • Each <setting> tag must have the following attributes:
    • name – Use a name that identifies what the setting does.
    • value – Provide a default value for the setting.
  • Each <setting> tag can have the following optional attributes:
    • isLocked – Boolean. The default value is true. If true, the setting is read-only and any changes that a user or application make to the value set by you, the administrator, are prevented or later overwritten. If this attribute is set to false, the administrator's setting is treated as a default value that can be changed.
    • overwriteUnlocked - Boolean. The default value is false. By default, a setting that is specified as being unlocked will be treated as a default and will not overwrite any existing value on the client. This is to avoid undoing changes that the user might have legitimately made. However, if this setting is set to true, the unlocked value will be overwritten with this new value even if it means clearing the user's existing value.
    • restartRequired - Boolean. The default value is false. This attribute applies only when you automatically update client preferences with the managed-settings.xml file. Setting this to true creates a user prompt to restart the client as soon as the managed setting is applied. Use this optional attribute only if a restart of the client is required to activate the preference. The restart occurs only if the setting that includes this attribute is updated.