Using Dynamic Configuration

Former Member — Wed, 05 Aug 2020 16:17:33 GMT

Current Revision posted to Developer Training by Former Member on 08/05/2020 16:17:33

Dynamic configuration is a metadata-based dynamic form generation format used by [[Scripting|scripted customizations]] to define configuration options.

[toc]

When would I use Dynamic Configuration?

Dynamic configuration is necessary when a developer wants to expose configuration options on a widget, theme, or automation to managers using the scripted customization. Dynamic configuration is defined as XML on a [[Widgets|widgets]], [[Themes|themes]], and [[Automations|automations]].

XML configuration definition

[
<propertyGroup>
  [
  <property>
    [<propertyValue />]*
    [<propertyRule />]*
  </property>
  ]*
</propertyGroup>
]*

One or more property groups can contain one or more properties each. Each group is represented as a tab on the widget configuration window and each property stores a single value. Each property can optionally define selectable values and rules.

Property values can be retrieved within widgets using the get and set methods on the core_v2_widget extension.

<propertyGroup />

<propertyGroup [id=""] [labelResourceName=""] [labelText=""] [descriptionResourceName=""] [descriptionText=""] [orderNumber=""] [visible=""] >...</propertyGroup>

Defines a grouping of configuration properties. Within the widget configuration window, each group is represented by a tab.

Attributes:

id is the identifier for the group.
labelResourceName is the name of the language resource identifying the name of this group.
labelText is the plain labelText name of this group.
descriptionResourceName is the name of the language resource identifying the description of this group.
descriptionText is the plain labelText description of this group.
orderNumber is the integer order number of this group (by default, groups are ordered as they are defined in the XML configuration).
visible is a boolean (true or false) identifying whether this group should be shown on the widget configuration window (by default, all groups with visible properties are shown).

labelResourceName or labelText are required.

<propertySubGroup />

<propertySubGroup [id=""] [labelResourceName=""] [labelText=""] [descriptionResourceName=""] [descriptionText=""] [orderNumber=""] [visible=""] >...</propertySubGroup>

Defines a sub-grouping of configuration properties. Within the widget configuration window, each sub-group is represented with a heading.

Attributes:

id is the identifier for the sub-group.
labelResourceName is the name of the language resource identifying the name of this sub-group.
labelText is the plain labelText name of this sub-group.
descriptionResourceName is the name of the language resource identifying the description of this sub-group.
descriptionText is the plain labelText description of this sub-group.
orderNumber is the integer order number of this sub-group (by default, sub-groups are ordered as they are defined in the XML configuration).
visible is a boolean (true or false) identifying whether this sub-group should be shown on the widget configuration window (by default, all sub-groups with visible properties are shown).

labelResourceName or labelText are required.

<property />

<property id="" dataType="" [labelResourceName=""] [labelText=""] [descriptionResourceName=""] [descriptionText=""] [orderNumber=""] [defaultValue=""] [editable=""] [visible=""] [template=""] [scope=""] [other attributes] />

Defines a configuration property within a configuration group.

Attributes:

id is the identifier for this property. This is the identifier used when retrieving values via the $core_v2_widget extension methods within widgets.
dataType is the data type of this property. Possible values are:
- Bool stores a true or false value.
- Color stores a CSS color value.
- Date stores a date.
- DateTime stores a date and a time.
- Double stores a double-precision floating point value.
- Guid stores a globally unique identifier value.
- Html stores an HTML value.
- Int stores an integer value.
- String stores as a string value.
- Time stores a time.
- Unit stores a CSS unit.
- Url stores a URL.
- UrlList stores a list of zero or more URLs.
- Custom stores a custom string value suitable for use with custom property templates.
labelResourceName is the name of the language resource identifying the name of this property.
labelText is the plain labelText name of this property.
descriptionResourceName is the name of the language resource identifying the description of this property.
descriptionText is the plain labelText description of this property.
orderNumber is the integer order number of this property (by default, properties are ordered as they are defined in the XML configuration).
defaultValue is the default value for this property.
editable is a boolean (true or false) identifying whether this property should be editable on the widget configuration window (by default, all properties are editable).
visible is a boolean (true or false) identifying whether this property should be shown on the widget configuration window (by default, all properties are shown).
template the name of a shared property template (an installed plugin implementing the Telligent.Evolution.Extensibility.Configuration.Version1.IPropertyTemplate interface) or a local .vm file (the filename including the .vm extension) containing an [[Embedding a custom user interface for a configuration property|implementation of the user interface of this property]]. If not specified, the default template (named for the data type) will be used. Note that there is no default template for custom properties and an explicit template should always be provided.
scope defines the non-standard scope in which this property's value should be stored (for [[Widgets|widgets]] only). Normally, a property's value is associated to a single instance of the widget, however, when scope is defined, the value will apply to all instances of the widget within the defined scope. Possible values are:
- site shares the value of this property with all instances of this widget throughout the site.
- group shares the value of this property with all instances of this widget within the context of the current group.
- blog shares the value of this property with all instances of this widget within the context of the current blog.
When the user does not have the proper permission to edit themes within the property's defined scope, the property will not be shown within the widget's configuration form.
[other attributes] are any additional attributes used by property rules or property templates for additional configuration.

labelResourceName or labelText are required in addition to id and dataType.

When using a local custom property template (implemented using a VM file or JSM file), the executed file is provided an additional API, core_v2_propertyTemplate, which provides access to property rendering specific data.

HTML properties can be sanitized according to the global content filtering rules of the community by setting the sanitize attribute on the property to true.

String properties are always HTML encoded.

To support file storage within a property with a custom data type, set the trackEmbeddedFiles attribute on the <property /> node to true. By default, file detection within custom properties considers the value as plain text. By setting the encoding attribute on <property /> to Url, the custom value will be parsed as a URL encoded set of keys or key value pairs when detecting file URLs.

<propertyValue />

<propertyValue value="" [labelResourceName=""] [labelText=""] [orderNumber=""] [other attributes] />

Defines a selectable value for a property. When selectable values are defined for a property, the property, by default, is rendered using a drop-down list.

Attributes:

value is the selectable value to which the the associated property should be set when selected.
labelResourceName is the name of the language resource identifying the name of this selectable value.
labelText is the plain labelText name of this selectable value.
orderNumber is the integer order number of this selectable value (by default, selectable values are ordered as they are defined in the XML configuration).
[other attributes] are any additional attributes used by property rules or property controls for additional configuration.

labelResourceName or labelText are required in addition to value.

<propertyRule />

<propertyRule name="" [other attributes]/>

Defines a rule to be applied to a property.

Attributes:

name is the name of a shared property rule (an installed plugin implementing the Telligent.Evolution.Extensibility.Configuration.Version1.IPropertyRule interface).
[other attributes] are any additional attributes used to configure the property rule.

Property Value Data Types

When working with property values on the server and client side via property rules or templates, note the data representation:

Configuration data type	Server data type (.Net)	Client data type (Javascript)
Bool	Bool	Boolean
Color	Telligent.Evolution.Extensibility.Configuration.Version1.Color	String representation of the color: #RRGGBB, #RRGGBBAA, rgb(1-255, 1-255, 1-255), rgba(1-255, 1-255, 1-255, 0-1), hsl(1-255, %, %), hsla(1-255, %, %, 0-1), or a named HTML color.
Date	DateTime	Date
DateTime	DateTime	Date
Double	Double	Number
Guid	Guid	String representation of a GUID: FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF.
Html	String	String
Int	Int32	Number
String	String	String
Time	DateTime	Date
Unit	Telligent.Evolution.Extensibility.Configuration.Version1.Unit	String representation of a CSS unit, a px, pt, pc, in, mm, cm, %, em, ex, ch, rem, v2, or vh value.
Url	Uri	String representation of a URL.
UrlList	Uri[]	Array of string representations of URL that, when converted to a string, represents the URLs in querystring format with the key Uri, for example, Uri=http://url.com/&Uri=http://url2.com/.
Custom	String	String

Example

The following sample will demonstrate exposing simple configuration options for a hypothetical weather forecast widget.

The following Dynamic Configuration exposes configuration options for zip code, scale, forecast days, and low temperature inclusion. Note that resources are used to localize the field names. Also note the min/max rule to restrict forecast days to a maximum of 10.

<propertyGroup id="options" resourceName="Options">
	<property id="fragmentHeader" labelResourceName="title" dataType="string" defaultValue="${resource:WeatherForecast_Name}" controlType="Telligent.Evolution.Controls.ContentFragmentTokenStringControl, Telligent.Evolution.Controls" />
	<property id="zipCode" labelResourceName="zipCode" dataType="string" defaultValue="" />
	<property id="scale" labelResourceName="scale" dataType="string" defaultValue="celsius">
		<propertyValue value="fahrenheit" labelResourceName="fahrenheit" />
		<propertyValue value="celsius" labelResourceName="celsius" />
	</property>
	<property id="days" labelResourceName="days" dataType="int" defaultValue="3">
		<propertyRule name="minmax" min="1" max="10" />
	</property>
	<property id="includeLow" labelResourceName="includeLow" descriptionResourceName="includeLowDescription" dataType="bool" defaultValue="true" />
</propertyGroup>

Yields

The following sample [[Using Velocity|Velocity script]] reads and simply prints these configuration values. A real implementation would use them against a weather forecast API.

#set ($zipCode = $core_v2_widget.GetStringValue('zipCode', ''))
#set ($days = $core_v2_widget.GetIntValue('days', 3))
#set ($scale = $core_v2_widget.GetStringValue('scale', 'celsius'))
#set ($includeLow = $core_v2_widget.GetBoolValue('includeLow', true))

<ul>
	<li>Zip Code: $zipCode</li>
	<li>Forecast Days: $days</li>
	<li>Scale: $scale</li>
	<li>Include Low: #if($includeLow) Yes #else No #end</li>
</ul>

Tags: Dynamic Configuration, widgets

Using Dynamic Configuration

Ben Tiedt — Mon, 02 Mar 2020 18:10:45 GMT

Revision 7 posted to Developer Training by Ben Tiedt on 03/02/2020 18:10:45

Dynamic configuration is a metadata-based dynamic form generation format used by [[Scripting|scripted customizations]] to define configuration options.

[toc]

When would I use Dynamic Configuration?

XML configuration definition

[
<propertyGroup>
  [
  <property>
    [<propertyValue />]*
    [<propertyRule />]*
  </property>
  ]*
</propertyGroup>
]*

Property values can be retrieved within widgets using the get and set methods on the core_v2_widget extension.

<propertyGroup />

<propertyGroup [id=""] [labelResourceName=""] [labelText=""] [descriptionResourceName=""] [descriptionText=""] [orderNumber=""] [visible=""] >...</propertyGroup>

Defines a grouping of configuration properties. Within the widget configuration window, each group is represented by a tab.

Attributes:

id is the identifier for the group.
labelResourceName is the name of the language resource identifying the name of this group.
labelText is the plain labelText name of this group.
descriptionResourceName is the name of the language resource identifying the description of this group.
descriptionText is the plain labelText description of this group.
orderNumber is the integer order number of this group (by default, groups are ordered as they are defined in the XML configuration).
visible is a boolean (true or false) identifying whether this group should be shown on the widget configuration window (by default, all groups with visible properties are shown).

labelResourceName or labelText are required.

<propertySubGroup />

<propertySubGroup [id=""] [labelResourceName=""] [labelText=""] [descriptionResourceName=""] [descriptionText=""] [orderNumber=""] [visible=""] >...</propertySubGroup>

Defines a sub-grouping of configuration properties. Within the widget configuration window, each sub-group is represented with a heading.

Attributes:

id is the identifier for the sub-group.
labelResourceName is the name of the language resource identifying the name of this sub-group.
labelText is the plain labelText name of this sub-group.
descriptionResourceName is the name of the language resource identifying the description of this sub-group.
descriptionText is the plain labelText description of this sub-group.
orderNumber is the integer order number of this sub-group (by default, sub-groups are ordered as they are defined in the XML configuration).
visible is a boolean (true or false) identifying whether this sub-group should be shown on the widget configuration window (by default, all sub-groups with visible properties are shown).

labelResourceName or labelText are required.

<property />

<property id="" dataType="" [labelResourceName=""] [labelText=""] [descriptionResourceName=""] [descriptionText=""] [orderNumber=""] [defaultValue=""] [editable=""] [visible=""] [template=""] [scope=""] [other attributes] />

Defines a configuration property within a configuration group.

Attributes:

id is the identifier for this property. This is the identifier used when retrieving values via the $core_v2_widget extension methods within widgets.
dataType is the data type of this property. Possible values are:
- Bool stores a true or false value.
- Color stores a CSS color value.
- Date stores a date.
- DateTime stores a date and a time.
- Double stores a double-precision floating point value.
- Guid stores a globally unique identifier value.
- Html stores an HTML value.
- Int stores an integer value.
- String stores as a string value.
- Time stores a time.
- Unit stores a CSS unit.
- Url stores a URL.
- UrlList stores a list of zero or more URLs.
- Custom stores a custom string value suitable for use with custom property templates.
labelResourceName is the name of the language resource identifying the name of this property.
labelText is the plain labelText name of this property.
descriptionResourceName is the name of the language resource identifying the description of this property.
descriptionText is the plain labelText description of this property.
orderNumber is the integer order number of this property (by default, properties are ordered as they are defined in the XML configuration).
defaultValue is the default value for this property.
editable is a boolean (true or false) identifying whether this property should be editable on the widget configuration window (by default, all properties are editable).
visible is a boolean (true or false) identifying whether this property should be shown on the widget configuration window (by default, all properties are shown).
template the name of a shared property template (an installed plugin implementing the Telligent.Evolution.Extensibility.Configuration.Version1.IPropertyTemplate interface) or a local .vm file (the filename including the .vm extension) containing an [[Embedding a custom user interface for a configuration property|implementation of the user interface of this property]]. If not specified, the default template (named for the data type) will be used. Note that there is no default template for custom properties and an explicit template should always be provided.
scope defines the non-standard scope in which this property's value should be stored (for [[Widgets|widgets]] only). Normally, a property's value is associated to a single instance of the widget, however, when scope is defined, the value will apply to all instances of the widget within the defined scope. Possible values are:
- site shares the value of this property with all instances of this widget throughout the site.
- group shares the value of this property with all instances of this widget within the context of the current group.
- blog shares the value of this property with all instances of this widget within the context of the current blog.
When the user does not have the proper permission to edit themes within the property's defined scope, the property will not be shown within the widget's configuration form.
[other attributes] are any additional attributes used by property rules or property templates for additional configuration.

labelResourceName or labelText are required in addition to id and dataType.

HTML properties can be sanitized according to the global content filtering rules of the community by setting the sanitize attribute on the property to true.

String properties are always HTML encoded.

<propertyValue />

<propertyValue value="" [labelResourceName=""] [labelText=""] [orderNumber=""] [other attributes] />

Defines a selectable value for a property. When selectable values are defined for a property, the property, by default, is rendered using a drop-down list.

Attributes:

value is the selectable value to which the the associated property should be set when selected.
labelResourceName is the name of the language resource identifying the name of this selectable value.
labelText is the plain labelText name of this selectable value.
orderNumber is the integer order number of this selectable value (by default, selectable values are ordered as they are defined in the XML configuration).
[other attributes] are any additional attributes used by property rules or property controls for additional configuration.

labelResourceName or labelText are required in addition to value.

<propertyRule />

<propertyRule name="" [other attributes]/>

Defines a rule to be applied to a property.

Attributes:

name is the name of a shared property rule (an installed plugin implementing the Telligent.Evolution.Extensibility.Configuration.Version1.IPropertyRule interface).
[other attributes] are any additional attributes used to configure the property rule.

Property Value Data Types

When working with property values on the server and client side via property rules or templates, note the data representation:

Configuration data type	Server data type (.Net)	Client data type (Javascript)
Bool	Bool	Boolean
Color	Telligent.Evolution.Extensibility.Configuration.Version1.Color	String representation of the color: #RRGGBB, #RRGGBBAA, rgb(1-255, 1-255, 1-255), rgba(1-255, 1-255, 1-255, 0-1), hsl(1-255, %, %), hsla(1-255, %, %, 0-1), or a named HTML color.
Date	DateTime	Date
DateTime	DateTime	Date
Double	Double	Number
Guid	Guid	String representation of a GUID: FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF.
Html	String	String
Int	Int32	Number
String	String	String
Time	DateTime	Date
Unit	Telligent.Evolution.Extensibility.Configuration.Version1.Unit	String representation of a CSS unit, a px, pt, pc, in, mm, cm, %, em, ex, ch, rem, v2, or vh value.
Url	Uri	String representation of a URL.
UrlList	Uri[]	Array of string representations of URL that, when converted to a string, represents the URLs in querystring format with the key Uri, for example, Uri=http://url.com/&Uri=http://url2.com/.
Custom	String	String

Example

The following sample will demonstrate exposing simple configuration options for a hypothetical weather forecast widget.

<propertyGroup id="options" resourceName="Options">
	<property id="fragmentHeader" labelResourceName="title" dataType="string" defaultValue="${resource:WeatherForecast_Name}" controlType="Telligent.Evolution.Controls.ContentFragmentTokenStringControl, Telligent.Evolution.Controls" />
	<property id="zipCode" labelResourceName="zipCode" dataType="string" defaultValue="" />
	<property id="scale" labelResourceName="scale" dataType="string" defaultValue="celsius">
		<propertyValue value="fahrenheit" labelResourceName="fahrenheit" />
		<propertyValue value="celsius" labelResourceName="celsius" />
	</property>
	<property id="days" labelResourceName="days" dataType="int" defaultValue="3">
		<propertyRule name="minmax" min="1" max="10" />
	</property>
	<property id="includeLow" labelResourceName="includeLow" descriptionResourceName="includeLowDescription" dataType="bool" defaultValue="true" />
</propertyGroup>

Yields

The following sample [[Using Velocity|Velocity script]] reads and simply prints these configuration values. A real implementation would use them against a weather forecast API.

#set ($zipCode = $core_v2_widget.GetStringValue('zipCode', ''))
#set ($days = $core_v2_widget.GetIntValue('days', 3))
#set ($scale = $core_v2_widget.GetStringValue('scale', 'celsius'))
#set ($includeLow = $core_v2_widget.GetBoolValue('includeLow', true))

<ul>
	<li>Zip Code: $zipCode</li>
	<li>Forecast Days: $days</li>
	<li>Scale: $scale</li>
	<li>Include Low: #if($includeLow) Yes #else No #end</li>
</ul>

Using Dynamic Configuration

Ben Tiedt — Mon, 02 Mar 2020 18:02:27 GMT

Revision 6 posted to Developer Training by Ben Tiedt on 03/02/2020 18:02:27

Dynamic configuration is a metadata-based dynamic form generation format used by [[Scripting|scripted customizations]] to define configuration options.

[toc]

When would I use Dynamic Configuration?

XML configuration definition

[
<propertyGroup>
  [
  <property>
    [<propertyValue />]*
    [<propertyRule />]*
  </property>
  ]*
</propertyGroup>
]*

Property values can be retrieved within widgets using the get and set methods on the core_v2_widget extension.

<propertyGroup />

<propertyGroup [id=""] [labelResourceName=""] [labelText=""] [descriptionResourceName=""] [descriptionText=""] [orderNumber=""] [visible=""] >...</propertyGroup>

Defines a grouping of configuration properties. Within the widget configuration window, each group is represented by a tab.

Attributes:

id is the identifier for the group.
labelResourceName is the name of the language resource identifying the name of this group.
labelText is the plain labelText name of this group.
descriptionResourceName is the name of the language resource identifying the description of this group.
descriptionText is the plain labelText description of this group.
orderNumber is the integer order number of this group (by default, groups are ordered as they are defined in the XML configuration).
visible is a boolean (true or false) identifying whether this group should be shown on the widget configuration window (by default, all groups with visible properties are shown).

labelResourceName or labelText are required.

<propertySubGroup />

<propertySubGroup [id=""] [labelResourceName=""] [labelText=""] [descriptionResourceName=""] [descriptionText=""] [orderNumber=""] [visible=""] >...</propertySubGroup>

Defines a sub-grouping of configuration properties. Within the widget configuration window, each sub-group is represented with a heading.

Attributes:

id is the identifier for the sub-group.
labelResourceName is the name of the language resource identifying the name of this sub-group.
labelText is the plain labelText name of this sub-group.
descriptionResourceName is the name of the language resource identifying the description of this sub-group.
descriptionText is the plain labelText description of this sub-group.
orderNumber is the integer order number of this sub-group (by default, sub-groups are ordered as they are defined in the XML configuration).
visible is a boolean (true or false) identifying whether this sub-group should be shown on the widget configuration window (by default, all sub-groups with visible properties are shown).

labelResourceName or labelText are required.

<property />

<property id="" dataType="" [labelResourceName=""] [labelText=""] [descriptionResourceName=""] [descriptionText=""] [orderNumber=""] [defaultValue=""] [editable=""] [visible=""] [template=""] [scope=""] [other attributes] />

Defines a configuration property within a configuration group.

Attributes:

id is the identifier for this property. This is the identifier used when retrieving values via the $core_v2_widget extension methods within widgets.
dataType is the data type of this property. Possible values are:
- Bool stores a true or false value.
- Color stores a CSS color value.
- Date stores a date.
- DateTime stores a date and a time.
- Double stores a double-precision floating point value.
- Guid stores a globally unique identifier value.
- Html stores an HTML value.
- Int stores an integer value.
- String stores as a string value.
- Time stores a time.
- Unit stores a CSS unit.
- Url stores a URL.
- UrlList stores a list of zero or more URLs.
- Custom stores a custom string value suitable for use with custom property templates.
labelResourceName is the name of the language resource identifying the name of this property.
labelText is the plain labelText name of this property.
descriptionResourceName is the name of the language resource identifying the description of this property.
descriptionText is the plain labelText description of this property.
orderNumber is the integer order number of this property (by default, properties are ordered as they are defined in the XML configuration).
defaultValue is the default value for this property.
editable is a boolean (true or false) identifying whether this property should be editable on the widget configuration window (by default, all properties are editable).
visible is a boolean (true or false) identifying whether this property should be shown on the widget configuration window (by default, all properties are shown).
template the name of a shared property template (an installed plugin implementing the Telligent.Evolution.Extensibility.Configuration.Version1.IPropertyTemplate interface) or a local .vm file (the filename including the .vm extension) containing an [[Embedding a custom user interface for a configuration property|implementation of the user interface of this property]]. If not specified, the default template (named for the data type) will be used. Note that there is no default template for custom properties and an explicit template should always be provided. Note that use of IPropertyControls is obsolete and will be removed in the 12.0 release.
scope defines the non-standard scope in which this property's value should be stored (for [[Widgets|widgets]] only). Normally, a property's value is associated to a single instance of the widget, however, when scope is defined, the value will apply to all instances of the widget within the defined scope. Possible values are:
- site shares the value of this property with all instances of this widget throughout the site.
- group shares the value of this property with all instances of this widget within the context of the current group.
- blog shares the value of this property with all instances of this widget within the context of the current blog.
When the user does not have the proper permission to edit themes within the property's defined scope, the property will not be shown within the widget's configuration form.
[other attributes] are any additional attributes used by property rules or property templates for additional configuration.

labelResourceName or labelText are required in addition to id and dataType.

HTML properties can be sanitized according to the global content filtering rules of the community by setting the sanitize attribute on the property to true.

String properties are always HTML encoded.

<propertyValue />

<propertyValue value="" [labelResourceName=""] [labelText=""] [orderNumber=""] [other attributes] />

Defines a selectable value for a property. When selectable values are defined for a property, the property, by default, is rendered using a drop-down list.

Attributes:

value is the selectable value to which the the associated property should be set when selected.
labelResourceName is the name of the language resource identifying the name of this selectable value.
labelText is the plain labelText name of this selectable value.
orderNumber is the integer order number of this selectable value (by default, selectable values are ordered as they are defined in the XML configuration).
[other attributes] are any additional attributes used by property rules or property controls for additional configuration.

labelResourceName or labelText are required in addition to value.

<propertyRule />

<propertyRule name="" [other attributes]/>

Defines a rule to be applied to a property.

Attributes:

name is the name of a shared property rule (an installed plugin implementing the Telligent.Evolution.Extensibility.Configuration.Version1.IPropertyRule interface).
[other attributes] are any additional attributes used to configure the property rule.

Property Value Data Types

When working with property values on the server and client side via property rules or templates, note the data representation:

Configuration data type	Server data type (.Net)	Client data type (Javascript)
Bool	Bool	Boolean
Color	Telligent.Evolution.Extensibility.Configuration.Version1.Color	String representation of the color: #RRGGBB, #RRGGBBAA, rgb(1-255, 1-255, 1-255), rgba(1-255, 1-255, 1-255, 0-1), hsl(1-255, %, %), hsla(1-255, %, %, 0-1), or a named HTML color.
Date	DateTime	Date
DateTime	DateTime	Date
Double	Double	Number
Guid	Guid	String representation of a GUID: FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF.
Html	String	String
Int	Int32	Number
String	String	String
Time	DateTime	Date
Unit	Telligent.Evolution.Extensibility.Configuration.Version1.Unit	String representation of a CSS unit, a px, pt, pc, in, mm, cm, %, em, ex, ch, rem, v2, or vh value.
Url	Uri	String representation of a URL.
UrlList	Uri[]	Array of string representations of URL that, when converted to a string, represents the URLs in querystring format with the key Uri, for example, Uri=http://url.com/&Uri=http://url2.com/.
Custom	String	String

Example

The following sample will demonstrate exposing simple configuration options for a hypothetical weather forecast widget.

<propertyGroup id="options" resourceName="Options">
	<property id="fragmentHeader" labelResourceName="title" dataType="string" defaultValue="${resource:WeatherForecast_Name}" controlType="Telligent.Evolution.Controls.ContentFragmentTokenStringControl, Telligent.Evolution.Controls" />
	<property id="zipCode" labelResourceName="zipCode" dataType="string" defaultValue="" />
	<property id="scale" labelResourceName="scale" dataType="string" defaultValue="celsius">
		<propertyValue value="fahrenheit" labelResourceName="fahrenheit" />
		<propertyValue value="celsius" labelResourceName="celsius" />
	</property>
	<property id="days" labelResourceName="days" dataType="int" defaultValue="3">
		<propertyRule name="minmax" min="1" max="10" />
	</property>
	<property id="includeLow" labelResourceName="includeLow" descriptionResourceName="includeLowDescription" dataType="bool" defaultValue="true" />
</propertyGroup>

Yields

The following sample [[Using Velocity|Velocity script]] reads and simply prints these configuration values. A real implementation would use them against a weather forecast API.

#set ($zipCode = $core_v2_widget.GetStringValue('zipCode', ''))
#set ($days = $core_v2_widget.GetIntValue('days', 3))
#set ($scale = $core_v2_widget.GetStringValue('scale', 'celsius'))
#set ($includeLow = $core_v2_widget.GetBoolValue('includeLow', true))

<ul>
	<li>Zip Code: $zipCode</li>
	<li>Forecast Days: $days</li>
	<li>Scale: $scale</li>
	<li>Include Low: #if($includeLow) Yes #else No #end</li>
</ul>

Using Dynamic Configuration

Ben Tiedt — Tue, 02 Jul 2019 15:21:31 GMT

Revision 5 posted to Developer Training by Ben Tiedt on 07/02/2019 15:21:31

Dynamic configuration is a metadata-based dynamic form generation format used by [[Scripting|scripted customizations]] to define configuration options.

[toc]

When would I use Dynamic Configuration?

XML configuration definition

[
<propertyGroup>
  [
  <property>
    [<propertyValue />]*
    [<propertyRule />]*
  </property>
  ]*
</propertyGroup>
]*

Property values can be retrieved within widgets using the get and set methods on the core_v2_widget extension.

<propertyGroup />

<propertyGroup [id=""] [labelResourceName=""] [labelText=""] [descriptionResourceName=""] [descriptionText=""] [orderNumber=""] [visible=""] >...</propertyGroup>

Defines a grouping of configuration properties. Within the widget configuration window, each group is represented by a tab.

Attributes:

id is the identifier for the group.
labelResourceName is the name of the language resource identifying the name of this group.
labelText is the plain labelText name of this group.
descriptionResourceName is the name of the language resource identifying the description of this group.
descriptionText is the plain labelText description of this group.
orderNumber is the integer order number of this group (by default, groups are ordered as they are defined in the XML configuration).
visible is a boolean (true or false) identifying whether this group should be shown on the widget configuration window (by default, all groups with visible properties are shown).

labelResourceName or labelText are required.

<propertySubGroup />

<propertySubGroup [id=""] [labelResourceName=""] [labelText=""] [descriptionResourceName=""] [descriptionText=""] [orderNumber=""] [visible=""] >...</propertySubGroup>

Defines a sub-grouping of configuration properties. Within the widget configuration window, each sub-group is represented with a heading.

Attributes:

id is the identifier for the sub-group.
labelResourceName is the name of the language resource identifying the name of this sub-group.
labelText is the plain labelText name of this sub-group.
descriptionResourceName is the name of the language resource identifying the description of this sub-group.
descriptionText is the plain labelText description of this sub-group.
orderNumber is the integer order number of this sub-group (by default, sub-groups are ordered as they are defined in the XML configuration).
visible is a boolean (true or false) identifying whether this sub-group should be shown on the widget configuration window (by default, all sub-groups with visible properties are shown).

labelResourceName or labelText are required.

<property />

<property id="" dataType="" [labelResourceName=""] [labelText=""] [descriptionResourceName=""] [descriptionText=""] [orderNumber=""] [defaultValue=""] [editable=""] [visible=""] [template=""] [scope=""] [other attributes] />

Defines a configuration property within a configuration group.

Attributes:

id is the identifier for this property. This is the identifier used when retrieving values via the $core_v2_widget extension methods within widgets.
dataType is the data type of this property. Possible values are:
- Bool stores a true or false value.
- Color stores a CSS color value.
- Date stores a date.
- DateTime stores a date and a time.
- Double stores a double-precision floating point value.
- Guid stores a globally unique identifier value.
- Html stores an HTML value.
- Int stores an integer value.
- String stores as a string value.
- Time stores a time.
- Unit stores a CSS unit.
- Url stores a URL.
- UrlList stores a list of zero or more URLs.
- Custom stores a custom string value suitable for use with custom property templates.
labelResourceName is the name of the language resource identifying the name of this property.
labelText is the plain labelText name of this property.
descriptionResourceName is the name of the language resource identifying the description of this property.
descriptionText is the plain labelText description of this property.
orderNumber is the integer order number of this property (by default, properties are ordered as they are defined in the XML configuration).
defaultValue is the default value for this property.
editable is a boolean (true or false) identifying whether this property should be editable on the widget configuration window (by default, all properties are editable).
visible is a boolean (true or false) identifying whether this property should be shown on the widget configuration window (by default, all properties are shown).
template the name of a shared property template (an installed plugin implementing the Telligent.Evolution.Extensibility.Configuration.Version1.IPropertyTemplate interface) or a local .vm file (the filename including the .vm extension) containing an [[Embedding a custom user interface for a configuration property|implementation of the user interface of this property]]. If not specified, the default template (named for the data type) will be used. Note that there is no default template for custom properties and an explicit template should always be provided.
scope defines the non-standard scope in which this property's value should be stored (for [[Widgets|widgets]] only). Normally, a property's value is associated to a single instance of the widget, however, when scope is defined, the value will apply to all instances of the widget within the defined scope. Possible values are:
- site shares the value of this property with all instances of this widget throughout the site.
- group shares the value of this property with all instances of this widget within the context of the current group.
- blog shares the value of this property with all instances of this widget within the context of the current blog.
When the user does not have the proper permission to edit themes within the property's defined scope, the property will not be shown within the widget's configuration form.
[other attributes] are any additional attributes used by property rules or property templates for additional configuration.

labelResourceName or labelText are required in addition to id and dataType.

HTML properties can be sanitized according to the global content filtering rules of the community by setting the sanitize attribute on the property to true.

String properties are always HTML encoded.

<propertyValue />

<propertyValue value="" [labelResourceName=""] [labelText=""] [orderNumber=""] [other attributes] />

Defines a selectable value for a property. When selectable values are defined for a property, the property, by default, is rendered using a drop-down list.

Attributes:

value is the selectable value to which the the associated property should be set when selected.
labelResourceName is the name of the language resource identifying the name of this selectable value.
labelText is the plain labelText name of this selectable value.
orderNumber is the integer order number of this selectable value (by default, selectable values are ordered as they are defined in the XML configuration).
[other attributes] are any additional attributes used by property rules or property controls for additional configuration.

labelResourceName or labelText are required in addition to value.

<propertyRule />

<propertyRule name="" [other attributes]/>

Defines a rule to be applied to a property.

Attributes:

name is the name of a shared property rule (an installed plugin implementing the Telligent.Evolution.Extensibility.Configuration.Version1.IPropertyRule interface).
[other attributes] are any additional attributes used to configure the property rule.

Property Value Data Types

When working with property values on the server and client side via property rules or templates, note the data representation:

Configuration data type	Server data type (.Net)	Client data type (Javascript)
Bool	Bool	Boolean
Color	Telligent.Evolution.Extensibility.Configuration.Version1.Color	String representation of the color: #RRGGBB, #RRGGBBAA, rgb(1-255, 1-255, 1-255), rgba(1-255, 1-255, 1-255, 0-1), hsl(1-255, %, %), hsla(1-255, %, %, 0-1), or a named HTML color.
Date	DateTime	Date
DateTime	DateTime	Date
Double	Double	Number
Guid	Guid	String representation of a GUID: FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF.
Html	String	String
Int	Int32	Number
String	String	String
Time	DateTime	Date
Unit	Telligent.Evolution.Extensibility.Configuration.Version1.Unit	String representation of a CSS unit, a px, pt, pc, in, mm, cm, %, em, ex, ch, rem, v2, or vh value.
Url	Uri	String representation of a URL.
UrlList	Uri[]	Array of string representations of URL that, when converted to a string, represents the URLs in querystring format with the key Uri, for example, Uri=http://url.com/&Uri=http://url2.com/.
Custom	String	String

Example

The following sample will demonstrate exposing simple configuration options for a hypothetical weather forecast widget.

<propertyGroup id="options" resourceName="Options">
	<property id="fragmentHeader" labelResourceName="title" dataType="string" defaultValue="${resource:WeatherForecast_Name}" controlType="Telligent.Evolution.Controls.ContentFragmentTokenStringControl, Telligent.Evolution.Controls" />
	<property id="zipCode" labelResourceName="zipCode" dataType="string" defaultValue="" />
	<property id="scale" labelResourceName="scale" dataType="string" defaultValue="celsius">
		<propertyValue value="fahrenheit" labelResourceName="fahrenheit" />
		<propertyValue value="celsius" labelResourceName="celsius" />
	</property>
	<property id="days" labelResourceName="days" dataType="int" defaultValue="3">
		<propertyRule name="minmax" min="1" max="10" />
	</property>
	<property id="includeLow" labelResourceName="includeLow" descriptionResourceName="includeLowDescription" dataType="bool" defaultValue="true" />
</propertyGroup>

Yields

The following sample [[Using Velocity|Velocity script]] reads and simply prints these configuration values. A real implementation would use them against a weather forecast API.

#set ($zipCode = $core_v2_widget.GetStringValue('zipCode', ''))
#set ($days = $core_v2_widget.GetIntValue('days', 3))
#set ($scale = $core_v2_widget.GetStringValue('scale', 'celsius'))
#set ($includeLow = $core_v2_widget.GetBoolValue('includeLow', true))

<ul>
	<li>Zip Code: $zipCode</li>
	<li>Forecast Days: $days</li>
	<li>Scale: $scale</li>
	<li>Include Low: #if($includeLow) Yes #else No #end</li>
</ul>

Using Dynamic Configuration

Ben Tiedt — Fri, 21 Jun 2019 20:58:18 GMT

Revision 4 posted to Developer Training by Ben Tiedt on 06/21/2019 20:58:18

Dynamic configuration is a metadata-based dynamic form generation format used by [[Scripting|scripted customizations]] to define configuration options.

[toc]

When would I use Dynamic Configuration?

XML configuration definition

[
<propertyGroup>
  [
  <property>
    [<propertyValue />]*
    [<propertyRule />]*
  </property>
  ]*
</propertyGroup>
]*

Property values can be retrieved within widgets using the get and set methods on the core_v2_widget extension.

<propertyGroup />

<propertyGroup [id=""] [labelResourceName=""] [labelText=""] [descriptionResourceName=""] [descriptionText=""] [orderNumber=""] [visible=""] >...</propertyGroup>

Defines a grouping of configuration properties. Within the widget configuration window, each group is represented by a tab.

Attributes:

id is the identifier for the group.
labelResourceName is the name of the language resource identifying the name of this group.
labelText is the plain labelText name of this group.
descriptionResourceName is the name of the language resource identifying the description of this group.
descriptionText is the plain labelText description of this group.
orderNumber is the integer order number of this group (by default, groups are ordered as they are defined in the XML configuration).
visible is a boolean (true or false) identifying whether this group should be shown on the widget configuration window (by default, all groups with visible properties are shown).

labelResourceName or labelText are required.

<propertySubGroup />

<propertySubGroup [id=""] [labelResourceName=""] [labelText=""] [descriptionResourceName=""] [descriptionText=""] [orderNumber=""] [visible=""] >...</propertySubGroup>

Defines a sub-grouping of configuration properties. Within the widget configuration window, each sub-group is represented with a heading.

Attributes:

id is the identifier for the sub-group.
labelResourceName is the name of the language resource identifying the name of this sub-group.
labelText is the plain labelText name of this sub-group.
descriptionResourceName is the name of the language resource identifying the description of this sub-group.
descriptionText is the plain labelText description of this sub-group.
orderNumber is the integer order number of this sub-group (by default, sub-groups are ordered as they are defined in the XML configuration).
visible is a boolean (true or false) identifying whether this sub-group should be shown on the widget configuration window (by default, all sub-groups with visible properties are shown).

labelResourceName or labelText are required.

<property />

<property id="" dataType="" [labelResourceName=""] [labelText=""] [descriptionResourceName=""] [descriptionText=""] [orderNumber=""] [defaultValue=""] [editable=""] [visible=""] [template=""] [scope=""] [other attributes] />

Defines a configuration property within a configuration group.

Attributes:

id is the identifier for this property. This is the identifier used when retrieving values via the $core_v2_widget extension methods within widgets.
dataType is the data type of this property. Possible values are:
- Bool stores a true or false value.
- Color stores a CSS color value.
- Date stores a date.
- DateTime stores a date and a time.
- Double stores a double-precision floating point value.
- Guid stores a globally unique identifier value.
- Html stores an HTML value.
- Int stores an integer value.
- String stores as a string value.
- Time stores a time.
- Unit stores a CSS unit.
- Url stores a URL.
- UrlList stores a list of zero or more URLs.
- Custom stores a custom string value suitable for use with custom property templates.
labelResourceName is the name of the language resource identifying the name of this property.
labelText is the plain labelText name of this property.
descriptionResourceName is the name of the language resource identifying the description of this property.
descriptionText is the plain labelText description of this property.
orderNumber is the integer order number of this property (by default, properties are ordered as they are defined in the XML configuration).
defaultValue is the default value for this property.
editable is a boolean (true or false) identifying whether this property should be editable on the widget configuration window (by default, all properties are editable).
visible is a boolean (true or false) identifying whether this property should be shown on the widget configuration window (by default, all properties are shown).
template the name of a shared property template (an installed plugin implementing the Telligent.Evolution.Extensibility.Configuration.Version1.IPropertyTemplate interface) or a local .vm file (the filename including the .vm extension)containing an implementation of the user interface of this property. If not specified, the default template (named for the data type) will be used. Note that there is no default template for custom properties and an explicit template should always be provided.
scope defines the non-standard scope in which this property's value should be stored (for [[Widgets|widgets]] only). Normally, a property's value is associated to a single instance of the widget, however, when scope is defined, the value will apply to all instances of the widget within the defined scope. Possible values are:
- site shares the value of this property with all instances of this widget throughout the site.
- group shares the value of this property with all instances of this widget within the context of the current group.
- blog shares the value of this property with all instances of this widget within the context of the current blog.
When the user does not have the proper permission to edit themes within the property's defined scope, the property will not be shown within the widget's configuration form.
[other attributes] are any additional attributes used by property rules or property templates for additional configuration.

labelResourceName or labelText are required in addition to id and dataType.

HTML properties can be sanitized according to the global content filtering rules of the community by setting the sanitize attribute on the property to true.

String properties are always HTML encoded.

<propertyValue />

<propertyValue value="" [labelResourceName=""] [labelText=""] [orderNumber=""] [other attributes] />

Defines a selectable value for a property. When selectable values are defined for a property, the property, by default, is rendered using a drop-down list.

Attributes:

value is the selectable value to which the the associated property should be set when selected.
labelResourceName is the name of the language resource identifying the name of this selectable value.
labelText is the plain labelText name of this selectable value.
orderNumber is the integer order number of this selectable value (by default, selectable values are ordered as they are defined in the XML configuration).
[other attributes] are any additional attributes used by property rules or property controls for additional configuration.

labelResourceName or labelText are required in addition to value.

<propertyRule />

<propertyRule name="" [other attributes]/>

Defines a rule to be applied to a property.

Attributes:

name is the name of a shared property rule (an installed plugin implementing the Telligent.Evolution.Extensibility.Configuration.Version1.IPropertyRule interface).
[other attributes] are any additional attributes used to configure the property rule.

Property Value Data Types

When working with property values on the server and client side via property rules or templates, note the data representation:

Configuration data type	Server data type (.Net)	Client data type (Javascript)
Bool	Bool	Boolean
Color	Telligent.Evolution.Extensibility.Configuration.Version1.Color	String representation of the color: #RRGGBB, #RRGGBBAA, rgb(1-255, 1-255, 1-255), rgba(1-255, 1-255, 1-255, 0-1), hsl(1-255, %, %), hsla(1-255, %, %, 0-1), or a named HTML color.
Date	DateTime	Date
DateTime	DateTime	Date
Double	Double	Number
Guid	Guid	String representation of a GUID: FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF.
Html	String	String
Int	Int32	Number
String	String	String
Time	DateTime	Date
Unit	Telligent.Evolution.Extensibility.Configuration.Version1.Unit	String representation of a CSS unit, a px, pt, pc, in, mm, cm, %, em, ex, ch, rem, v2, or vh value.
Url	Uri	String representation of a URL.
UrlList	Uri[]	Array of string representations of URL that, when converted to a string, represents the URLs in querystring format with the key Uri, for example, Uri=http://url.com/&Uri=http://url2.com/.
Custom	String	String

Example

The following sample will demonstrate exposing simple configuration options for a hypothetical weather forecast widget.

<propertyGroup id="options" resourceName="Options">
	<property id="fragmentHeader" labelResourceName="title" dataType="string" defaultValue="${resource:WeatherForecast_Name}" controlType="Telligent.Evolution.Controls.ContentFragmentTokenStringControl, Telligent.Evolution.Controls" />
	<property id="zipCode" labelResourceName="zipCode" dataType="string" defaultValue="" />
	<property id="scale" labelResourceName="scale" dataType="string" defaultValue="celsius">
		<propertyValue value="fahrenheit" labelResourceName="fahrenheit" />
		<propertyValue value="celsius" labelResourceName="celsius" />
	</property>
	<property id="days" labelResourceName="days" dataType="int" defaultValue="3">
		<propertyRule name="minmax" min="1" max="10" />
	</property>
	<property id="includeLow" labelResourceName="includeLow" descriptionResourceName="includeLowDescription" dataType="bool" defaultValue="true" />
</propertyGroup>

Yields

The following sample [[Using Velocity|Velocity script]] reads and simply prints these configuration values. A real implementation would use them against a weather forecast API.

#set ($zipCode = $core_v2_widget.GetStringValue('zipCode', ''))
#set ($days = $core_v2_widget.GetIntValue('days', 3))
#set ($scale = $core_v2_widget.GetStringValue('scale', 'celsius'))
#set ($includeLow = $core_v2_widget.GetBoolValue('includeLow', true))

<ul>
	<li>Zip Code: $zipCode</li>
	<li>Forecast Days: $days</li>
	<li>Scale: $scale</li>
	<li>Include Low: #if($includeLow) Yes #else No #end</li>
</ul>

Using Dynamic Configuration

Ben Tiedt — Fri, 21 Jun 2019 20:56:58 GMT

Revision 3 posted to Developer Training by Ben Tiedt on 06/21/2019 20:56:58

Dynamic configuration is a metadata-based dynamic form generation format used by [[Scripting|scripted customizations]] to define configuration options.

[toc]

When would I use Dynamic Configuration?

XML configuration definition

[
<propertyGroup>
  [
  <property>
    [<propertyValue />]*
    [<propertyRule />]*
  </property>
  ]*
</propertyGroup>
]*

Property values can be retrieved within widgets using the get and set methods on the core_v2_widget extension.

<propertyGroup />

<propertyGroup [id=""] [labelResourceName=""] [labelText=""] [descriptionResourceName=""] [descriptionText=""] [orderNumber=""] [visible=""] >...</propertyGroup>

Defines a grouping of configuration properties. Within the widget configuration window, each group is represented by a tab.

Attributes:

id is the identifier for the group.
labelResourceName is the name of the language resource identifying the name of this group.
labelText is the plain labelText name of this group.
descriptionResourceName is the name of the language resource identifying the description of this group.
descriptionText is the plain labelText description of this group.
orderNumber is the integer order number of this group (by default, groups are ordered as they are defined in the XML configuration).
visible is a boolean (true or false) identifying whether this group should be shown on the widget configuration window (by default, all groups with visible properties are shown).

labelResourceName or labelText are required.

<propertySubGroup />

<propertySubGroup [id=""] [labelResourceName=""] [labelText=""] [descriptionResourceName=""] [descriptionText=""] [orderNumber=""] [visible=""] >...</propertySubGroup>

Defines a sub-grouping of configuration properties. Within the widget configuration window, each sub-group is represented with a heading.

Attributes:

id is the identifier for the sub-group.
labelResourceName is the name of the language resource identifying the name of this sub-group.
labelText is the plain labelText name of this sub-group.
descriptionResourceName is the name of the language resource identifying the description of this sub-group.
descriptionText is the plain labelText description of this sub-group.
orderNumber is the integer order number of this sub-group (by default, sub-groups are ordered as they are defined in the XML configuration).
visible is a boolean (true or false) identifying whether this sub-group should be shown on the widget configuration window (by default, all sub-groups with visible properties are shown).

labelResourceName or labelText are required.

<property />

<property id="" dataType="" [labelResourceName=""] [labelText=""] [descriptionResourceName=""] [descriptionText=""] [orderNumber=""] [defaultValue=""] [editable=""] [visible=""] [template=""] [scope=""] [other attributes] />

Defines a configuration property within a configuration group.

Attributes:

id is the identifier for this property. This is the identifier used when retrieving values via the $core_v2_widget extension methods within widgets.
dataType is the data type of this property. Possible values are:
- Bool stores a true or false value.
- Color stores a CSS color value.
- Date stores a date.
- DateTime stores a date and a time.
- Double stores a double-precision floating point value.
- Guid stores a globally unique identifier value.
- Html stores an HTML value.
- Int stores an integer value.
- String stores as a string value.
- Time stores a time.
- Unit stores a CSS unit.
- Url stores a URL.
- UrlList stores a list of zero or more URLs.
- Custom stores a custom string value suitable for use with custom property templates.
labelResourceName is the name of the language resource identifying the name of this property.
labelText is the plain labelText name of this property.
descriptionResourceName is the name of the language resource identifying the description of this property.
descriptionText is the plain labelText description of this property.
orderNumber is the integer order number of this property (by default, properties are ordered as they are defined in the XML configuration).
defaultValue is the default value for this property.
editable is a boolean (true or false) identifying whether this property should be editable on the widget configuration window (by default, all properties are editable).
visible is a boolean (true or false) identifying whether this property should be shown on the widget configuration window (by default, all properties are shown).
template the name of a shared property template (an installed plugin implementing the Telligent.Evolution.Extensibility.Configuration.Version1.IPropertyTemplate interface) or a local .vm file (the filename including the .vm extension)containing an implementation of the user interface of this property. If not specified, the default template (named for the data type) will be used. Note that there is no default template for custom properties and an explicit template should always be provided.
scope defines the non-standard scope in which this property's value should be stored (for [[Widgets|widgets]] only). Normally, a property's value is associated to a single instance of the widget, however, when scope is defined, the value will apply to all instances of the widget within the defined scope. Possible values are:
- site shares the value of this property with all instances of this widget throughout the site.
- group shares the value of this property with all instances of this widget within the context of the current group.
- blog shares the value of this property with all instances of this widget within the context of the current blog.
When the user does not have the proper permission to edit themes within the property's defined scope, the property will not be shown within the widget's configuration form.
[other attributes] are any additional attributes used by property rules or property templates for additional configuration.

labelResourceName or labelText are required in addition to id and dataType.

When working with property values on the server and client side via property rules or templates, note the data representation:

Configuration data type	Server data type (.Net)	Client data type (Javascript)
Bool	Bool	Boolean
Color	Telligent.Evolution.Extensibility.Configuration.Version1.Color	String representation of the color: #RRGGBB, #RRGGBBAA, rgb(1-255, 1-255, 1-255), rgba(1-255, 1-255, 1-255, 0-1), hsl(1-255, %, %), hsla(1-255, %, %, 0-1), or a named HTML color.
Date	DateTime	Date
DateTime	DateTime	Date
Double	Double	Number
Guid	Guid	String representation of a GUID: FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF.
Html	String	String
Int	Int32	Number
String	String	String
Time	DateTime	Date
Unit	Telligent.Evolution.Extensibility.Configuration.Version1.Unit	String representation of a CSS unit, a px, pt, pc, in, mm, cm, %, em, ex, ch, rem, v2, or vh value.
Url	Uri	String representation of a URL.
UrlList	Uri[]	Array of string representations of URL that, when converted to a string, represents the URLs in querystring format with the key Uri, for example, Uri=http://url.com/&Uri=http://url2.com/.
Custom	String	String

HTML properties can be sanitized according to the global content filtering rules of the community by setting the sanitize attribute on the property to true.

String properties are always HTML encoded.

<propertyValue />

<propertyValue value="" [labelResourceName=""] [labelText=""] [orderNumber=""] [other attributes] />

Defines a selectable value for a property. When selectable values are defined for a property, the property, by default, is rendered using a drop-down list.

Attributes:

value is the selectable value to which the the associated property should be set when selected.
labelResourceName is the name of the language resource identifying the name of this selectable value.
labelText is the plain labelText name of this selectable value.
orderNumber is the integer order number of this selectable value (by default, selectable values are ordered as they are defined in the XML configuration).
[other attributes] are any additional attributes used by property rules or property controls for additional configuration.

labelResourceName or labelText are required in addition to value.

<propertyRule />

<propertyRule name="" [other attributes]/>

Defines a rule to be applied to a property.

Attributes:

name is the name of a shared property rule (an installed plugin implementing the Telligent.Evolution.Extensibility.Configuration.Version1.IPropertyRule interface).
[other attributes] are any additional attributes used to configure the property rule.

Example

The following sample will demonstrate exposing simple configuration options for a hypothetical weather forecast widget.

<propertyGroup id="options" resourceName="Options">
	<property id="fragmentHeader" labelResourceName="title" dataType="string" defaultValue="${resource:WeatherForecast_Name}" controlType="Telligent.Evolution.Controls.ContentFragmentTokenStringControl, Telligent.Evolution.Controls" />
	<property id="zipCode" labelResourceName="zipCode" dataType="string" defaultValue="" />
	<property id="scale" labelResourceName="scale" dataType="string" defaultValue="celsius">
		<propertyValue value="fahrenheit" labelResourceName="fahrenheit" />
		<propertyValue value="celsius" labelResourceName="celsius" />
	</property>
	<property id="days" labelResourceName="days" dataType="int" defaultValue="3">
		<propertyRule name="minmax" min="1" max="10" />
	</property>
	<property id="includeLow" labelResourceName="includeLow" descriptionResourceName="includeLowDescription" dataType="bool" defaultValue="true" />
</propertyGroup>

Yields

The following sample [[Using Velocity|Velocity script]] reads and simply prints these configuration values. A real implementation would use them against a weather forecast API.

#set ($zipCode = $core_v2_widget.GetStringValue('zipCode', ''))
#set ($days = $core_v2_widget.GetIntValue('days', 3))
#set ($scale = $core_v2_widget.GetStringValue('scale', 'celsius'))
#set ($includeLow = $core_v2_widget.GetBoolValue('includeLow', true))

<ul>
	<li>Zip Code: $zipCode</li>
	<li>Forecast Days: $days</li>
	<li>Scale: $scale</li>
	<li>Include Low: #if($includeLow) Yes #else No #end</li>
</ul>

Using Dynamic Configuration

Ben Tiedt — Fri, 21 Jun 2019 19:35:15 GMT

Revision 2 posted to Developer Training by Ben Tiedt on 06/21/2019 19:35:15

Dynamic configuration is a metadata-based dynamic form generation format used by [[Widgets|widgets]] to define configuration options.

[toc]

When would I use Dynamic Configuration?

Dynamic configuration is necessary when a developer wants to expose configuration options on a widget to administrators and other non-deveopers. Dynamic configuration is defined as XML on a [[Widgets|widget]] in [[Working with Widget Studio|Widget Studio]].

XML configuration definition

[
<propertyGroup>
  [
  <property>
    [<propertyValue />]*
    [<propertyRule />]*
  </property>
  ]*
</propertyGroup>
]*

Property values can be retrieved within widgets using the get and set methods on the $core_widget extension.

<propertyGroup />

<propertyGroup [id=""] [resourceName="" [resourceFile=""]] [text=""] [descriptionResourceName="" [descriptionResourceFile=""]] [descriptionText=""] [orderNumber=""] [visible=""] [other attributes]>...</propertyGroup>

Defines a grouping of configuration properties. Within the widget configuration window, each group is represented by a tab.

Attributes:

id is the identifier for the group.
resourceName is the name of the language resource identifying the name of this group.
resouceFile is the filename of the language resource file containing the resource identified by resourceName.
text is the plain text name of this group.
descriptionResourceName is the name of the language resource identifying the description of this group.
descriptionResourceFile is the filename of the language resource file containing the resource identified by descriptionResourceName.
descriptionText is the plain text description of this group.
orderNumber is the integer order number of this group (by default, groups are ordered as they are defined in the XML configuration).
visible is a boolean (true or false) identifying whether this group should be shown on the widget configuration window (by default, all groups are shown).
[other attributes] are any additional attributes used by property rules or property controls for additional configuration.

resourceName or text are required.

<property />

<property id="" dataType="" [resourceName="" [resourceFile=""]] [text=""] [descriptionResourceName="" [descriptionResourceFile=""]] [descriptionText=""] [orderNumber=""] [defaultValue=""] [editable=""] [visible=""] [controlType=""] [scope=""] [other attributes] />

Defines a configuration property within a configuration group.

Attributes:

id is the identifier for this property. This is the identifier used when retrieving values via the $core_widget extension methods within widgets.
dataType is the data type of this property. Possible values are:
- Bool stores a true or false value and is rendered as a checkbox by default.
- Color stores an HTML color value and is rendered as a color selector by default.
- Date stores a date and is rendered as a date-bound text box with a calendar selector by default.
- DateTime stores a date and a time and is rendered as a date/time-bound text box with a calendar selector by default.
- Double stores a double-precision floating point value and renders as a double-validated text box by default.
- Guid stores a globally unique identifier value and renders as a GUID-validated text box by default.
- Html stores an HTML value and renders as a text box by default (HTML values are automatically HTML sanitized for rendering).
- Int stores an integer value and renders as an integer-validated text box by default.
- String stores as a string value and renders as a text box by default (string values are automatically HTML encoded for rendering).
- Time stores a time and is rendered as a time-bound text box by default.
- Unit stores a CSS unit and is rendered as a unit-bound text box by default.
- Url stores a URL and is rendered as a URL-validated text box by default.
- Custom stores a custom string value suitable for use with custom property control implementations.
resourceName is the name of the language resource identifying the name of this property.
resouceFile is the filename of the language resource file containing the resource identified by resourceName.
text is the plain text name of this property.
descriptionResourceName is the name of the language resource identifying the description of this property.
descriptionResourceFile is the filename of the language resource file containing the resource identified by descriptionResourceName.
descriptionText is the plain text description of this property.
orderNumber is the integer order number of this property (by default, properties are ordered as they are defined in the XML configuration).
defaultValue is the default value for this property.
editable is a boolean (true or false) identifying whether this property should be editable on the widget configuration window (by default, all properties are editable).
visible is a boolean (true or false) identifying whether this property should be shown on the widget configuration window (by default, all properties are shown).
controlType is the full .net type name (Namespace.ClassName, AssemblyName) of the Telligent.DynamicConfiguration.Components.IPropertyControl implementation to use when editing this property.
scope defines the non-standard scope in which this property's value should be stored. Normally, a property's value is associated to a single instance of the widget, however, when scope is defined, the value will apply to all instances of the widget within the defined scope. Possible values are:
- site shares the value of this property with all instances of this widget throughout the site.
- group shares the value of this property with all instances of this widget within the context of the current group.
- blog shares the value of this property with all instances of this widget within the context of the current blog.
  When the user does not have the proper permission to edit themes within the property's defined scope, the property will not be shown within the widget's configuration form.
[other attributes] are any additional attributes used by property rules or property controls for additional configuration.

resourceName or text are required in addition to id and dataType.

<propertyValue />

<propertyValue value="" [resourceName="" [resourceFile=""]] [text=""] [orderNumber=""] [other attributes] />

Defines a selectable value for a property. When selectable values are defined for a property, the property, by default, is rendered using a drop-down list.

Attributes:

value is the selectable value to which the the associated property should be set when selected.
resourceName is the name of the language resource identifying the name of this selectable value.
resouceFile is the filename of the language resource file containing the resource identified by resourceName.
text is the plain text name of this selectable value.
orderNumber is the integer order number of this selectable value (by default, selectable values are ordered as they are defined in the XML configuration).
[other attributes] are any additional attributes used by property rules or property controls for additional configuration.

resourceName or text are required in addition to value.

<propertyRule />

<propertyRule type="" [other attributes]/>

Defines a rule to be applied to a property.

Attributes:

type is the full .net type name (Namespace.ClassName, AssemblyName) of the Telligent.DynamicConfiguration.Components.IPropertyRule implementation to apply to the associated property.
[other attributes] are any additional attributes used to configure the property rule.

Scoped Properties

At times, it may be useful to have a widget placed on multiple pages share a single configuration. For example, the Group Application Navigation widget when shown on multiple pages within a group should always show the same set of navigation tabs. Widget developers can enable this behavior by defining an explicit scope for one or more widget configuration properties.

Defining a Property's Scope

A property's scope is defined by the scopeattribute. Normally, a property's value is associated to a single instance of the widget, however, when scope is defined, the value will apply to all instances of the widget within the defined scope.

For example, in the following sample, the fragmentHeader property uses the default scoping (widget instance) and the navigation property defines an explicit scope of group.

<propertyGroup id="options" resourceName="Options">
	<property id="fragmentHeader" resourceName="CF_Title" dataType="string" defaultValue="${resource:Groups_GroupApplicationNavigation_Name}" controlType="Telligent.Evolution.Controls.ContentFragmentTokenStringControl, Telligent.Evolution.Controls" />
	<property id="navigation" dataType="custom" controlType="Telligent.Evolution.Controls.CustomNavigationCustomControl, Telligent.Evolution.Controls" maximumDepth="1" resourceName="Groups_GroupApplicationNavigation_Navigation" descriptionResourceName="Groups_GroupApplicationNavigation_Navigation_Description" navigationType="group" scope="group" />
</propertyGroup>

Supported Scopes

The default scope is the instance of the widget. This scope is used if the scope attribute is not defined. When scope is explicitly defined, the following values are supported:

siteshares the value of this property with all instances of this widget throughout the site.
group shares the value of this property with all instances of this widget within the context of the current group.
blogshares the value of this property with all instances of this widget within the context of the current blog.

When the user does not have the proper permission to edit themes within the property's defined scope, the property will not be shown within the widget's configuration form.

Platform Property Control Types

Dynamic configuration defines a default user interface for editing each of the supported property data types, however, there are situations where a more specific user interface is helpful. Dynamic configuration supports alternate editing experiences by defining a controlType when declaring a . The platform includes support for the following alternative property control types:

[[Blog Selection Custom Control]]
[[Checkbox List String Control]]
[[Custom Navigation Custom Control]]
[[Email String Control]]
[[Forum Selection Custom Control]]
[[Forum Sortable List Control]]
[[Group or Application Selection Custom Control]]
[[Group Selection Custom Control]]
[[Media Gallery Selection Custom Control]]
[[Property Visibility Select Box Control]]
[[Rich Editor HTML Control]]
[[Sortable List Custom Control]]
[[Tokenized String Control]]
[[User File URL Control]]
[[User Profile Field Selection Custom Control]]
[[User Profile Group Int Control]]
[[Wiki Selection Custom Control]]

Example

The following sample will demonstrate exposing simple configuration options for a hypothetical weather forecast widget.

<propertyGroup id="options" resourceName="Options">
	<property id="fragmentHeader" resourceName="title" dataType="string" defaultValue="${resource:WeatherForecast_Name}" controlType="Telligent.Evolution.Controls.ContentFragmentTokenStringControl, Telligent.Evolution.Controls" />
	<property id="zipCode" resourceName="zipCode" dataType="string" defaultValue="" />
	<property id="scale" resourceName="scale" dataType="string" defaultValue="celsius">
		<propertyValue value="fahrenheit" resourceName="fahrenheit" />
		<propertyValue value="celsius" resourceName="celsius" />
	</property>
	<property id="days" resourceName="days" dataType="int" defaultValue="3">
		<propertyRule type="Telligent.Evolution.Controls.PropertyRules.MinMaxValueRule, Telligent.Evolution.Controls" minValue="1" maxValue="10" />
	</property>
	<property id="includeLow" resourceName="includeLow" descriptionResourceName="includeLowDescription" dataType="bool" defaultValue="true" />
</propertyGroup>

Yields

The following sample [[Using Velocity in Widgets|widget content script]] reads and simply prints these configuration values. A real implementation would use them against a weather forecast API.

#set ($zipCode = $core_v2_widget.GetStringValue('zipCode', ''))
#set ($days = $core_v2_widget.GetIntValue('days', 3))
#set ($scale = $core_v2_widget.GetStringValue('scale', 'celsius'))
#set ($includeLow = $core_v2_widget.GetBoolValue('includeLow', true))

<ul>
	<li>Zip Code: $zipCode</li>
	<li>Forecast Days: $days</li>
	<li>Scale: $scale</li>
	<li>Include Low: #if($includeLow) Yes #else No #end</li>
</ul>

Yields

The complete example can be downloaded:

community.telligent.com/.../WeatherForecast_2D00_Widget.xml

Supporting Configuration

Ben Tiedt — Fri, 14 Jun 2019 17:07:07 GMT

Revision 1 posted to Developer Training by Ben Tiedt on 06/14/2019 17:07:07

Dynamic configuration is a metadata-based dynamic form generation format used by [[Widgets|widgets]] to define configuration options.

[toc]

When would I use Dynamic Configuration?

XML configuration definition

[
<propertyGroup>
  [
  <property>
    [<propertyValue />]*
    [<propertyRule />]*
  </property>
  ]*
</propertyGroup>
]*

Property values can be retrieved within widgets using the get and set methods on the $core_widget extension.

<propertyGroup />

<propertyGroup [id=""] [resourceName="" [resourceFile=""]] [text=""] [descriptionResourceName="" [descriptionResourceFile=""]] [descriptionText=""] [orderNumber=""] [visible=""] [other attributes]>...</propertyGroup>

Defines a grouping of configuration properties. Within the widget configuration window, each group is represented by a tab.

Attributes:

id is the identifier for the group.
resourceName is the name of the language resource identifying the name of this group.
resouceFile is the filename of the language resource file containing the resource identified by resourceName.
text is the plain text name of this group.
descriptionResourceName is the name of the language resource identifying the description of this group.
descriptionResourceFile is the filename of the language resource file containing the resource identified by descriptionResourceName.
descriptionText is the plain text description of this group.
orderNumber is the integer order number of this group (by default, groups are ordered as they are defined in the XML configuration).
visible is a boolean (true or false) identifying whether this group should be shown on the widget configuration window (by default, all groups are shown).
[other attributes] are any additional attributes used by property rules or property controls for additional configuration.

resourceName or text are required.

<property />

<property id="" dataType="" [resourceName="" [resourceFile=""]] [text=""] [descriptionResourceName="" [descriptionResourceFile=""]] [descriptionText=""] [orderNumber=""] [defaultValue=""] [editable=""] [visible=""] [controlType=""] [scope=""] [other attributes] />

Defines a configuration property within a configuration group.

Attributes:

id is the identifier for this property. This is the identifier used when retrieving values via the $core_widget extension methods within widgets.
dataType is the data type of this property. Possible values are:
- Bool stores a true or false value and is rendered as a checkbox by default.
- Color stores an HTML color value and is rendered as a color selector by default.
- Date stores a date and is rendered as a date-bound text box with a calendar selector by default.
- DateTime stores a date and a time and is rendered as a date/time-bound text box with a calendar selector by default.
- Double stores a double-precision floating point value and renders as a double-validated text box by default.
- Guid stores a globally unique identifier value and renders as a GUID-validated text box by default.
- Html stores an HTML value and renders as a text box by default (HTML values are automatically HTML sanitized for rendering).
- Int stores an integer value and renders as an integer-validated text box by default.
- String stores as a string value and renders as a text box by default (string values are automatically HTML encoded for rendering).
- Time stores a time and is rendered as a time-bound text box by default.
- Unit stores a CSS unit and is rendered as a unit-bound text box by default.
- Url stores a URL and is rendered as a URL-validated text box by default.
- Custom stores a custom string value suitable for use with custom property control implementations.
resourceName is the name of the language resource identifying the name of this property.
resouceFile is the filename of the language resource file containing the resource identified by resourceName.
text is the plain text name of this property.
descriptionResourceName is the name of the language resource identifying the description of this property.
descriptionResourceFile is the filename of the language resource file containing the resource identified by descriptionResourceName.
descriptionText is the plain text description of this property.
orderNumber is the integer order number of this property (by default, properties are ordered as they are defined in the XML configuration).
defaultValue is the default value for this property.
editable is a boolean (true or false) identifying whether this property should be editable on the widget configuration window (by default, all properties are editable).
visible is a boolean (true or false) identifying whether this property should be shown on the widget configuration window (by default, all properties are shown).
controlType is the full .net type name (Namespace.ClassName, AssemblyName) of the Telligent.DynamicConfiguration.Components.IPropertyControl implementation to use when editing this property.
scope defines the non-standard scope in which this property's value should be stored. Normally, a property's value is associated to a single instance of the widget, however, when scope is defined, the value will apply to all instances of the widget within the defined scope. Possible values are:
- site shares the value of this property with all instances of this widget throughout the site.
- group shares the value of this property with all instances of this widget within the context of the current group.
- blog shares the value of this property with all instances of this widget within the context of the current blog.
  When the user does not have the proper permission to edit themes within the property's defined scope, the property will not be shown within the widget's configuration form.
[other attributes] are any additional attributes used by property rules or property controls for additional configuration.

resourceName or text are required in addition to id and dataType.

<propertyValue />

<propertyValue value="" [resourceName="" [resourceFile=""]] [text=""] [orderNumber=""] [other attributes] />

Defines a selectable value for a property. When selectable values are defined for a property, the property, by default, is rendered using a drop-down list.

Attributes:

value is the selectable value to which the the associated property should be set when selected.
resourceName is the name of the language resource identifying the name of this selectable value.
resouceFile is the filename of the language resource file containing the resource identified by resourceName.
text is the plain text name of this selectable value.
orderNumber is the integer order number of this selectable value (by default, selectable values are ordered as they are defined in the XML configuration).
[other attributes] are any additional attributes used by property rules or property controls for additional configuration.

resourceName or text are required in addition to value.

<propertyRule />

<propertyRule type="" [other attributes]/>

Defines a rule to be applied to a property.

Attributes:

type is the full .net type name (Namespace.ClassName, AssemblyName) of the Telligent.DynamicConfiguration.Components.IPropertyRule implementation to apply to the associated property.
[other attributes] are any additional attributes used to configure the property rule.

Scoped Properties

Defining a Property's Scope

For example, in the following sample, the fragmentHeader property uses the default scoping (widget instance) and the navigation property defines an explicit scope of group.

<propertyGroup id="options" resourceName="Options">
	<property id="fragmentHeader" resourceName="CF_Title" dataType="string" defaultValue="${resource:Groups_GroupApplicationNavigation_Name}" controlType="Telligent.Evolution.Controls.ContentFragmentTokenStringControl, Telligent.Evolution.Controls" />
	<property id="navigation" dataType="custom" controlType="Telligent.Evolution.Controls.CustomNavigationCustomControl, Telligent.Evolution.Controls" maximumDepth="1" resourceName="Groups_GroupApplicationNavigation_Navigation" descriptionResourceName="Groups_GroupApplicationNavigation_Navigation_Description" navigationType="group" scope="group" />
</propertyGroup>

Supported Scopes

The default scope is the instance of the widget. This scope is used if the scope attribute is not defined. When scope is explicitly defined, the following values are supported:

siteshares the value of this property with all instances of this widget throughout the site.
group shares the value of this property with all instances of this widget within the context of the current group.
blogshares the value of this property with all instances of this widget within the context of the current blog.

When the user does not have the proper permission to edit themes within the property's defined scope, the property will not be shown within the widget's configuration form.

Platform Property Control Types

[[Blog Selection Custom Control]]
[[Checkbox List String Control]]
[[Custom Navigation Custom Control]]
[[Email String Control]]
[[Forum Selection Custom Control]]
[[Forum Sortable List Control]]
[[Group or Application Selection Custom Control]]
[[Group Selection Custom Control]]
[[Media Gallery Selection Custom Control]]
[[Property Visibility Select Box Control]]
[[Rich Editor HTML Control]]
[[Sortable List Custom Control]]
[[Tokenized String Control]]
[[User File URL Control]]
[[User Profile Field Selection Custom Control]]
[[User Profile Group Int Control]]
[[Wiki Selection Custom Control]]

Example

The following sample will demonstrate exposing simple configuration options for a hypothetical weather forecast widget.

<propertyGroup id="options" resourceName="Options">
	<property id="fragmentHeader" resourceName="title" dataType="string" defaultValue="${resource:WeatherForecast_Name}" controlType="Telligent.Evolution.Controls.ContentFragmentTokenStringControl, Telligent.Evolution.Controls" />
	<property id="zipCode" resourceName="zipCode" dataType="string" defaultValue="" />
	<property id="scale" resourceName="scale" dataType="string" defaultValue="celsius">
		<propertyValue value="fahrenheit" resourceName="fahrenheit" />
		<propertyValue value="celsius" resourceName="celsius" />
	</property>
	<property id="days" resourceName="days" dataType="int" defaultValue="3">
		<propertyRule type="Telligent.Evolution.Controls.PropertyRules.MinMaxValueRule, Telligent.Evolution.Controls" minValue="1" maxValue="10" />
	</property>
	<property id="includeLow" resourceName="includeLow" descriptionResourceName="includeLowDescription" dataType="bool" defaultValue="true" />
</propertyGroup>

Yields

The following sample [[Using Velocity in Widgets|widget content script]] reads and simply prints these configuration values. A real implementation would use them against a weather forecast API.

#set ($zipCode = $core_v2_widget.GetStringValue('zipCode', ''))
#set ($days = $core_v2_widget.GetIntValue('days', 3))
#set ($scale = $core_v2_widget.GetStringValue('scale', 'celsius'))
#set ($includeLow = $core_v2_widget.GetBoolValue('includeLow', true))

<ul>
	<li>Zip Code: $zipCode</li>
	<li>Forecast Days: $days</li>
	<li>Scale: $scale</li>
	<li>Include Low: #if($includeLow) Yes #else No #end</li>
</ul>

Yields

The complete example can be downloaded:

community.telligent.com/.../WeatherForecast_2D00_Widget.xml