Class pvd.widget.settings.helpers.SettingsHelper

Provides services for managing a widget's settings and their associated controls in the settings panel.

The pvd.widget.settings.helpers.SettingsHelper object provides the following services.

Retrieving and updating widget settings.
Generating the widget's markup and resources strings
Retrieving the widget's settings when objects are cloned within the view designer.
Retrieving the controls associated with the widget settings.
Updating the controls when a new object is selected in the canvas.
Triggering an event to commit an update to the change history of the view definition.
Triggering an event to refresh of the controls in the settings panel.

A pvd.widget.designer.SettingsGroup object provides a collection of pvd.widget.designer.settings._Setting controls for each of the settings supported by a particular widget class. In some cases, there may be more than one settings groups defined for a particular widget class. These settings groups are shared by all instances of the widget class.

For each widget class, a settings configuration defines the treatment of each setting and the structure of its related control. These settings configurations are typically found in the pvr.widget.registy.Registry configuration or a related module. (Note: Currently this is only true for editor widgets. Eventually this pattern will be followed for all supported widgets.)

The settings configuration consists of an array of objects with the following structure. With some exceptions noted below, each parameter can be specified as either a literal value or a function. The pvd.widget.settings.helpers.SettingsHelper object is passed to each function to enable its services and to provide a reference to its widget.

{
	name: "", // The setting name. Must be a literal.
	controlClass: TextBoxSetting, // The _Setting control class. Must be a literal.
	controlParams: { // The _Setting control parameters. Include only those that apply.
		label: "", // The control's label.
		help: "", // The contol's help text.
		required: false, // Indicates that the control value is required.
		readOnly: false, // Indicates that the control is read-only.
		disabled: false, // Indicates that the control is disabled.
		intermediateChanges: false, // Indicates that intermediate changes are to be applied immediately.
		options: [], // Provides the options for SelectSetting.
		constraints: {}, // Provides the constraints for NumberTextBoxSetting.
		rangeMessage: "", // Provides the range message for NumberTextBoxSetting.
		editorSpec: "pvr/widget/editors/SomeEditor", // Provides the editor specification for EditorSetting.
	},
	defaultValue: null, // Provides the setting's default value.
	hidden: false, // Indicates whether the control is visible.
	excluded: false, // Indicates whether the setting is excluded from the settings collection.
	localized: false, // Indicates whether the setting will be included in the resources object.
	getSetting: function(helper) {}, // A function that overrides how the setting is retrieved from the widget.
	updateSetting: function(helper, value) {}, // A function that overrides how the setting is updated to the widget.
	initialValue: function(helper) {}, // A function that overrides how the initial value for the control is obtained (calls getSetting() by default).
	onSettingChanged: function(helper, value) {} // A function that overrides the control's change event handler (calls updateSetting() by default).
};

Defined in: <pvd\widget\settings\helpers\SettingsHelper.js>.

Constructor Summary

Constructor Attributes	Constructor Name and Description
	pvd.widget.settings.helpers.SettingsHelper()

Field Summary

Field Attributes	Field Name and Description
	controls The pvd.widget.designer.settings._Setting controls within each of the settings groups.
	settingsGroups The collection of pvd.widget.designer.SettingsGroup objects associated with the widget.
	widget The widget.

Method Summary

Method Attributes	Method Name and Description
	activateSettings() Active the settings controls within each settings group.
	addResources(resources) Adds this widget's resource strings to the resources object.
	commitToChangeHistory() Fires an event to commit an update the change history of the view definition.
	constructor(widget, settingsGroups) Creates a pvd.widget.settings.helpers.SettingsHelper instance for the specified widget and settings groups.
	createMarkup(childMarkup) Generates the widget's markup.
	deactivateSettings() Deactivate the settings controls within each settings group.
	forEachControl(callback, context) Calls the specified callback function for each pvd.widget.designer.settings._Setting control in the controls collection.
	getControl(name) Gets the pvd.widget.designer.settings._Setting control associated with the specified setting.
	getSetting(name, defaultValue) Gets the specified setting value from the widget.
	getSettings(includeAll) Gets the widget's settings values.
	getSettingsGroups() Gets the settings groups collection.
	refreshSettings() Fires an event to refresh the controls in the settings panel.
	updateSetting(name, value) Updates the specified setting value in the widget.

Constructor Detail

pvd.widget.settings.helpers.SettingsHelper()

Field Detail

{object} controls

The pvd.widget.designer.settings._Setting controls within each of the settings groups.

{object} settingsGroups

The collection of pvd.widget.designer.SettingsGroup objects associated with the widget.

{object} widget

The widget.

Method Detail

activateSettings()

Active the settings controls within each settings group.

This method is called automatically after the settings groups are added to the settings panel. You should never call this method directly.

addResources(resources)

Adds this widget's resource strings to the resources object.

The resources object can later be translated as required.

Parameters:
resources: The resources object.

commitToChangeHistory()

Fires an event to commit an update the change history of the view definition.

constructor(widget, settingsGroups)

Creates a pvd.widget.settings.helpers.SettingsHelper instance for the specified widget and settings groups.

pvd.widget.settings.helpers.SettingsHelper objects are created by the widget classes which use them. You should not create a setting helper for ad-hoc usage.

Parameters:
widget: The widget.
settingsGroups: The collection of pvd.widget.designer.SettingsGroup objects associated with the widget.

createMarkup(childMarkup)

Generates the widget's markup.

Parameters:
childMarkup: The child widget markup to be included within a container widget's markup.

Returns:: This markup for the widget..

deactivateSettings()

Deactivate the settings controls within each settings group.

This method is called automatically before the settings groups are removed from the settings panel. You should never call this method directly.

forEachControl(callback, context)

Calls the specified callback function for each pvd.widget.designer.settings._Setting control in the controls collection.

Parameters:
callback: The callback function.
context: The JavaScript context of the callback method. If not specified, this object is used as the context.

getControl(name)

Gets the pvd.widget.designer.settings._Setting control associated with the specified setting.

Parameters:
name: The setting name.

Returns:: The pvd.widget.designer.settings._Setting control.

getSetting(name, defaultValue)

Gets the specified setting value from the widget.

Parameters:
name: The setting name.
defaultValue: The default value of the setting.

Returns:: the setting value.

getSettings(includeAll)

Gets the widget's settings values.

Parameters:
includeAll: Indicates whether all settings should be included or only those that have non-default values.

Returns:: An object containing the widget's settings values.

getSettingsGroups()

Gets the settings groups collection.

Returns:: The settings groups collection.

refreshSettings()

Fires an event to refresh the controls in the settings panel.

updateSetting(name, value)

Updates the specified setting value in the widget.

Parameters:
name: The setting name.
value: The setting value.