DeepSee Implementation Guide
Creating Portlets for Use in Dashboards
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

This chapter describes how to create portlets that users can add to dashboards, as widgets. It discusses the following topics:

Portlet Basics
To define a portlet, create and compile a class as follows:
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:
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:
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:
The following figure shows a sample of each of these types of 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
The following shows a simple example:
Class DeepSee.Model.Custom.MyPortlet Extends %DeepSee.Component.Portlet.abstractPortlet
{

/// Static HTML display method: draw the BODY of this component as HTML.
Method %DrawHTML()
{
  &html<<div class="portletDiv" style="overflow:hidden;">>
  &html<<div style="font-size:16px; border-bottom:1px solid gray;">My Widget</div>>
 
  Set tInfo(1) = $LB("Sales","UP","12")
  Set tInfo(2) = $LB("Costs","DOWN","-8")
  Set tInfo(3) = $LB("Profits","UP","18")

  &html<<table width="100%" cellspacing="0" border="0">>
  Set n = $O(tInfo(""))
  While (n'="") {
    Set tName = $LG(tInfo(n),1)
    Set tDir = $LG(tInfo(n),2)
    Set tPct = $LG(tInfo(n),3)
    Set clr = $S(tPct<0:"red",1:"black")
    Set bg = $S(n#2:"#FFEEEE",1:"white")
    Set tPct = tPct _ "%"
    &html<<tr style="font-size:24px; background:#(bg)#;color:#(clr)#;">
      <td style="padding:4px;">#(tName)#</td>
      <td style="padding:4px;">#(tDir)#</td>
      <td style="padding:4px;text-align:right;">#(tPct)#</td></tr>>
    Set n = $O(tInfo(n))
  }
  &html<</table>>
  &html<</div>>
}

}
When used as a widget, the widget has the following contents:
This example displays static data, but your portlet could display real-time data.
For a more complex example that also defines settings, see DeepSee.Model.PortletDemo.ClockPortlet in the SAMPLES database.
Using a Data Source
You can also define a portlet that accesses data, because %DeepSee.Component.Portlet.abstractPortlet implements the ZEN dataView API. To take advantage of this option, you should be familiar with Zen.
If a data source is defined, your portlet widget creates the appropriate dataController for the data source and connects to that. The most convenient way to create such a portlet is as follows: