Defining and Using Settings

It is fairly simple to define a portlet that provides configurable settings. To do this, implement the %OnGetPortletSettings() method in the portlet class. This method has two purposes:

To define settings to be listed in the Settings menu for this widget, in the Dashboard Designer.
To receive values for these settings via the dashboard URL. For information on passing the values via the URL, see Accessing Dashboards from Your Application.

The %OnGetPortletSettings() method has the following signature:

classmethod %OnGetPortletSettings(Output pInfo As %List, ByRef pSettings) as %Status

pInfo should be a multidimensional array that contains the following nodes:

Node	Value
pInfo(integer)	List returned by $LISTBUILD as follows: $LB(name,default,type,caption,tooltip) name is the logical name of the setting default is the default value of the setting type is the type of the setting. See the following subsection. caption is the localized caption of the setting tooltip is an optional tooltip

Node

Value

pInfo(integer)

List returned by $LISTBUILD as follows:

$LB(name,default,type,caption,tooltip)

name is the logical name of the setting
default is the default value of the setting
type is the type of the setting. See the following subsection.
caption is the localized caption of the setting
tooltip is an optional tooltip

pSettings is a multidimensional array that is passed to this method; it contains the values of any settings passed via the URL. For details, see the second subsection.

Types of Settings

In the pInfo argument of %OnGetPortletSettings(), you can specify the type of each setting; this controls how the Dashboard Designer displays that setting. Use one of the following:

"%Integer"
"%Boolean"
"ENUM^caption1:value1,caption2:value2" or a similar form. In this string, caption1 and caption2 are labels to display in the Dashboard Designer, and value1 and value2 are the corresponding values that are actually used. In practice, a setting of this type can provide only a few options, before the Dashboard Designer runs out of space to display them. See the next item.
"DRILL^caption1:value1,caption2:value2" or a similar form. In this string, caption1 and caption2 are labels to display in the Dashboard Designer, and value1 and value2 are the corresponding values that are actually used.

The following figure shows a sample of each of these types of settings:

Sample settings for a widget, showing one integer setting, one boolean setting, one ENUM setting, and one DRILL setting.

The following implementation of %OnGetPortletSettings() shows how these settings were defined:

ClassMethod %OnGetPortletSettings(Output pInfo As %List, ByRef pSettings) As %Status
{
 Kill pInfo
 set pInfo($I(pInfo)) = $LB("INTEGERSETTING","150","%Integer","Integer Setting","Sample integer setting")

 set pInfo($I(pInfo)) = $LB("BOOLEANSETTING","1","%Boolean","Boolean Setting","Sample boolean setting")

 set pInfo($I(pInfo)) = $LB("ENUMSETTING","150","ENUM^option1:150,option2:200,option3:200",
 "ENUM Setting","Sample ENUM setting")

 set pInfo($I(pInfo)) = $LB("DRILLSETTING","150",
 "DRILL^option1:150,option2:200,option3:200,option4:200,option5:200,option6:200,option7:200",
 "DRILL Setting","Sample DRILL setting")

 Quit pInfo
}

Receiving Settings Passed Via URL

The URL of a dashboard can pass values to some or all widgets on that dashboard, including values for any portlet settings. To accept these values, when you implement %OnGetPortletSettings(), use the pSettings argument, which is a multidimensional array that contains values for any settings that were provided in the URL. The structure of this array is as follows:

Node	Value
pSettings("setting") where setting is the name of a setting	Value of that setting

One approach is to use $GET(pSettings("setting") as the default value for each setting. For example:

ClassMethod %OnGetPortletSettings(Output pInfo As %List, ByRef pSettings) As %Status
{
  Kill pInfo
  Set pInfo($I(pInfo)) = $LB("LOGO",$G(pSettings("LOGO")),"","Clock logo","Logo displayed on top of clock")

  Set pInfo($I(pInfo)) = $LB("STEP",$G(pSettings("STEP"),"10"),"%Integer",
 "Second hand redraw interval (msec)","milliseconds steps of second hand")

  Set pInfo($I(pInfo)) = $LB("OFFSET",$G(pSettings("OFFSET"),"0"),"%Integer",
  "Offset from base time (min)","minutes difference from base time (Local or UTC)")

  Set pInfo($I(pInfo)) = $LB("UTC",$G(pSettings("UTC"),"0"),"%Boolean","UTC","Time Base: local (default) or UTC")

  Set pInfo($I(pInfo)) = $LB("CIRCLE",$G(pSettings("CIRCLE"),"1"),"%Boolean",
  "Circle","Shape: square (default) or circle")

  Set pInfo($I(pInfo)) = $LB("SIZE",$G(pSettings("SIZE"),"150"),"%Integer","Size","Size of the clock")
     
  Quit pInfo
}

Using Settings

To use the settings in the portlet, define the %DrawHTML() method so that it extracts the values of the settings from the settings property of the portlet and then uses those values in whatever manner is suitable for your needs. The settings property of the portlet is a multidimensional array of the following form:

Node	Value
settings("setting") where setting is the name of a setting	Value of that setting

For a simple example, %DrawHTML() could contain extract a setting called SIZE:

 set size=$G(..settings("SIZE"))

And the method could use this value to set the size of the portlet.

Examples

Portlet Basics