class_="spy"

Detects the size of the display area used to show a QuickApp and changes values in a package variable when the dimensions of the display area change. These values can then be used to change dimensional aspects of the QuickApp.

Note: Including more than one spy widget in a QuickApp is highly discouraged and could potentially cause problems. In addition, the spy widget should only be used in standalone QuickApps and should not be incorporated into tools that are intended to be part of the Insights Platform internal framework.

Syntax

<dynamic var="">
  <widget class_="spy" pkgvalue_="@var"/>
</dynamic>

Attributes

pkgvalue_
Information about the current display area is stored as a package in the variable associated with this attribute.

The package contains the following keys:

height
An integer value that represents the current height of the display area as detected by the spy widget.
width
An integer value that represents the current width of the display area as detected by the spy widget.
fullheight
An integer value that represents the total available height of the display area.
fullwidth
An integer value that represents the total available width of the display area.
vscroll
An integer value that represents the current position of the vertical scrolling in the display area.
hscroll
An integer value that represents the current position of the horizontal scrolling in the display area.
useragent
The user agent string sent by the browser accessing the QuickApp.

The variable must be declared as a package in the opening <dynamic> tag of the QuickApp (e.g., <dynamic var_name="{pkg(;)}">).

go_
Accepts an integer value. Only updates the dimensions of the spy widget when the value provided to go_ is greater than 0.

The default is 0.

auto_
Accepts a 1 to activate. Automatically updates the attributes of the package-value provided to the pkgvalue_ attribute when a triggering event occurs.

The default is 0.

trigger_
Specify a list of events that will trigger the values in the package-value passed to pkgvalue_ to update when auto_="1".

Valid values are:

scroll
The user horizontally or vertically scrolls the browser window containing the display area.
resize
The user resizes the browser window containing the display area.

If the trigger_ attribute is not specified, both events act as a trigger when auto_="1".

delay_
Accepts an integer value representing the number of milliseconds to wait after a triggering event before the values in the package-value passed to pkgvalue_ are updated.

The default value if the delay_ attribute is omitted is 250. It is recommended that you not provide a lower number than the default value.

Example

This example demonstrates how to place a spy widget in a QuickApp and display the dimensional information stored in the package-value p. The example uses auto_="1" to ensure that the information displayed in the text widget updates when the display area changes. To change the display area in this example, simply resize the browser window in which the QuickApp is displayed.

Notice that in addition to the spy widget itself, the example uses <widget class_="nest"> to parameterize the values passed to the height_ and width_ attributes. The values are referenced from the package-value p created in the outer <dynamic> element. For more information on using the nest widget, see class_="nest".

<dynamic p="">
  <widget class_="spy" pkgvalue_="@p" auto_="1"/>
  <widget class_="nest" require_="{@p.foo<>na}">
    <dynamic>
      <layout border_="5" width_="{{@p.width}-75}" height_="{{@p.height}-145}">
        <widget class_="text" border_="2" margin_="20" width_="500" 
         text_="Window dimensions: {@p.width} x {@p.height}"/>
        <widget class_="text" border_="2" margin_="20" width_="500" 
         text_="Document dimensions: {@p.fullwidth} x {@p.fullheight}"/>
      </layout>
    </dynamic>
  </widget>
</dynamic>

Example: Using go_ to update

In this example, the go_ attribute is used to update the dimensions of the display area. The update process can only take place if the value of go_ is greater than 0, so a set button is also used to increment the value of the x variable. To see the behavior, render the QuickApp shown below, then resize the display area and click the Update dimensions button.

<dynamic p="" x="0">
  <layout arrange_="v">
    <widget class_="button" type_="set" value_="@x" newvalue_="{@x+1}" 
     text_="Update dimensions"/>
    <widget class_="spy" pkgvalue_="@p" go_="{@x}"/>
    <widget class_="nest" require_="{@p.foo<>na}">
      <dynamic>
        <layout border_="5" width_="{{@p.width}-75}" height_="{{@p.height}-145}">
          <widget class_="text" border_="2" margin_="20" width_="500" 
           text_="Window dimensions: {@p.width} x {@p.height}"/>
          <widget class_="text" border_="2" margin_="20" width_="500" 
           text_="Document dimensions: {@p.fullwidth} x {@p.fullheight}"/>
        </layout>
      </dynamic>
    </widget>
  </layout>
</dynamic>