Embedding Widget Layouts in Dataforms

Global Administrators can display Business Intelligence, Image Display, and Query widget layouts within the body of a dataform instead of only in the dataform header. This allows users to see related information in context with the fields or sections it relates to, without needing to scrolling to the top of the form.

This topic explains how an embedded widget layout works, the order in which to configure it, and basic configuration. Additional details can be found in the topics this workflow spans which are referenced through this topic as well as in the Related Topics section at the end.

How an Embedded Widget Layout Works

An embedded widget layout is configured in two places, in this order:

The widget layout (System Admin > Widget Layouts): Create a layout that contains a single Business Intelligence, Image Display, or Query widget, select the Available as a dataform field checkbox, set Target Type to the dataform that will display it, and publish the layout.

The dataform field (System Admin > Advanced > Dataform Admin > Fields). Add a field with an Element Type of Widget Layout and select the published layout in the Widget Layout field. Set the Row where you want the field to display.

Note:
- You do not need to set the Column since the widget is held in bordered container that spans both columns of the ClientSpace dataform's two-column format. The size of the widget itself is determined by the widget layout just like any other widget.
- A Widget Layout field is not a data entry field. No corresponding SQL Server field is created, and the field holds no value.

What You Can Embed and Loading Behavior

When Available as a dataform field is selected for a layout, the widget library is filtered to the three widget types that can be embedded. Loading behavior is set by the system. When a widget setting to control the loading behavior is required, it is read-only in the widget settings for the layout.

Widget Type	Loading Behavior on a Dataform
Business Intelligence	Always uses Run On Demand. The report loads when the user clicks Click to Load in the widget on the dataform.
Image Display	Loads with the dataform. No load behavior widget setting required.
Query Widget	Always uses Force Late Loading. The query runs and the widget loads after the dataform has loaded.

Before You Configure: Review Guidelines

Review the following guidelines before you configure an embedded dataform widget:

A layout with Available as a Dataform Field enabled can contain only one widget, and that widget must be a Business Intelligence, Image Display, or Query Widget.

A dataform can contain a maximum of five Widget Layout fields with Available as a Dataform Field enabled. Because each layout holds one widget, this means a maximum of five embedded widget layouts per dataform.

Only published layouts whose Target Type is the currently displayed dataform are listed in the Widget Layout field of System Admin > Advanced > Dataform Admin > Fields.

The layout's own security and display conditions are ignored when it is rendered as a dataform field. Instead, dataform field security and field display rules control the widget's field display and security conditions. See Dataform and Dataform Field Security.
Because the field holds no value and does not function like a traditional field, all of the options in the Settings section except Active and Secured are not applicable and are disabled.

Embedding a Widget Layout

The following procedures must be completed in order:

Step 1: Create and publish the widget layout

To create a widget layout for a dataform:

Go to System Admin > Widget Layouts and click Add.

The Widget Layout Details form opens.
Enter the layout Name.
In Target Type, select the dataform that will display the embedded widget.
Select the Available as a dataform field checkbox.

The layout can no longer display as a dataform header, and the widget library is filtered to Business Intelligence, Image Display, and Query Widget only.
Click Add Widgets and add one Business Intelligence, Image Display, or Query Widget to the layout.
Set the size of the widget in the grid area. The widget is displayed on the dataform at the size you set here.
Click Save and then select the Published checkbox next to the layout on the Widget Layouts dashboard.

The layout is now available for selection on the dataform identified in Target Type.

Note: For full details about each field on the Widget Layout Details form, browsing the widget library, sizing widgets in the grid, and publishing, see Adding Widget Layouts.

Step 2: Add the Widget Layout field to the dataform

To add the widget to the dataform:

Go to System Admin > Advanced > Dataform Admin, select the dataform you identified as the Target Type in Step 1, and click Fields in the Action Center.
Click (New).

The New Field form opens.
In Element Type, select Widget Layout.

The Widget Layout field displays in the Widget Layout Settings fieldset, and the options that do not apply to this element type are disabled in the Settings fieldset. See Configuring Dataform Datatypes for additional details about the Widget Layout datatype.
In the Widget Layout field, select the layout you published in Step 1. This field is required.

Complete the following additional fields as applicable. Only the fields relevant to embedding a widget layout in a dataform are covered here. For full details about each field property on the form, see Adding Dataform Fields.

Field Set	Optionally, define a fieldset to display the widget in.
Field Set Default	If you chose to display the widget in a field set, the Field Set Default field is set to display the fieldset as expanded by default. Select Collapsed to display the fieldset as collapsed by default. For both options, users have expand and collapse control on the fieldset. Clear the field to always display the widget with no expand or collapse control.
Field Label	Required. The label displayed on the container that holds the widget. You can change the label style by clicking (Settings) to open the Style Configuration fieldset and then scrolling down to tto edit Font Type, Font Style and Color. See additional details on Adding Dataform Fields.
Row	Required. The sort position of the field or fieldset vertically on the form. If the widget is in a fieldset, the row determines its order within the field set. Though the sort uses a standard numeric order, it is recommended to set rows in increments of ten. This allows for reordering fields or adding fields between rows without reordering the entire form. Note: The field always spans both columns, so the Column setting does not change its placement.
Secured	Optionally, select the checkbox to generate a security entity for the field, so that Role security controls who sees the widget.

Click Save.
Optionally, edit the Field Display Rules in the Dataform Properties of the form to set conditions related to when the widget displays on the dataform. See Configuring Dynamic Field Display.
Be certain to test the embedded widget on the selected dataform.

About Maintaining Embedded Widget Layouts

A widget layout that is used as a Widget Layout field is referenced by the dataform, so changes to the layout affect the form. In each case, a confirmation message names the affected dataforms before the change is applied.

If you...	Then...
Delete the layout	A confirmation message names the affected dataforms. Deleting the layout also removes the Widget Layout field from those dataforms.
Unpublish the layout	A confirmation message names the affected dataforms, and the Widget Layout field is inactivated on those dataforms. The field is retained, so no configuration is lost.
Publish the layout again	A confirmation message names the affected dataforms, and the Widget Layout field is activated again on those dataforms.