Region width event

The region width event is used to act on changes to a floating or embedded region width. This event causes custom scripting to get a callback when a floating or embedded region width changes in such a way that it is in a different interval. To determine the initially active interval when rendered, an API is used to query about the currently active region width interval. This functionality is available for grids and charts.

Region width intervals are defined in the Layout Editor. You must specify a minimum width breakpoint for the interval. When at least one interval has been defined, there is always one interval with the minimum width breakpoint of zero. The upper breakpoint for an interval is defined by the lower breakpoint value for the next interval in the list. The last interval in the list has an upper breakpoint value of infinity. For example, you could have a narrow interval from 0 to 719 pixels and a wide interval from 720 to infinity.

Each interval consists of a lower bound, in pixels, and a name. The name is used at runtime when referring to the interval in the layout scripting.

How it works

When a grid or chart region changes width, such that it is in a different region width interval, the custom scripting of the layout gets a callback containing the name of the interval. The callback event is called RegionWidthIntervalChanged, and it uses a GridRegionWidthIntervalChangedContextI or ChartRegionWidthIntervalChangedContextI parameter and also a GridRegionWidthIntervalChangedParmsI or ChartRegionWidthIntervalChangedParmsI object. This is defined in the client and server APIs.

Two getter properties are defined in the latter two interfaces: Region, returning the region name for the region whose width interval changed; and Item, returning the item (IPFItemI), if any, of the region whose width interval changed. The RegionWidthIntervalChanged event is coalesced and is not run during initial render. Instead, an API function can be used. The API function allows a custom script to query about which region width interval is currently active. This function is called CurrentWidthInterval and is defined in IPFRegionI. It returns the name of the currently active region width interval. This function exists both on the client and server.

Restrictions

When rendering for email, none of the APIs are available.

Example

In the IPF portals, we have wide and narrow layouts. The wide layout is referred to as the 700 layout. The narrow layout is referred to as the 320 layout.

In the wide layout, the portal navigation menu is positioned across the top of each web page. In the narrow layout, a hamburger menu is displayed at the top of the page, and users must tap it to see navigation options.

On our MasterPageResponsive layout, we set the Main region to have expanding limits. The minimum width is 320 pixels and the maximum width is 980 pixels. For the HeaderGrid embedded region, we set these width intervals:

  • 320Grid = [0 - 699]
  • 700Grid = [700 - 979]
  • 980Grid = [980 - infinity]

If a user is viewing a portal page on a desktop PC at full size, they see the navigation menu across the top of the page. If the user adjusts the page to be smaller, then when it reaches the breakpoint of 699 pixels, the narrow layout container is invoked. The page automatically changes to use the hamburger menu and other UI features of our narrow layout.