WidgetView class

Methods and members exposed by the widget view returned from widget methods.

WidgetRowView, WidgetGridView, and related widget methods return an
IWidgetView. Use it to reload data, swap themes, change how many items show,
update the data source, and attach widget-level delegates without rebuilding the
whole page.

For global events (analytics, player open and close), see
Global delegate methods.

Widget Options

Pass these options when you create a widget with WidgetRowView, WidgetGridView, or related methods.

Property	Type	Required	Default	Description
`shouldOrderWidgetByReadStatus`	`boolean`	No	`true`	When `true`, unread items appear before read items. When `false`, read/unread does not change order.
`widgetRemoteIdentifier`	`string`	No		Remote-managed widget identifier. See BlazeSDK class.

const widgetView = BlazeSDK.WidgetRowView('container-id', {
  dataSource: myDataSource,
  shouldOrderWidgetByReadStatus: true,
  widgetRemoteIdentifier: 'homepage-top-stories',
});

For behavior details (all items read, manual order type, and liveFirst), see Ordering and item limits.

Methods

For remote-managed standard row and grid widgets created with widgetRemoteIdentifier, public mutators that change widget configuration at runtime no-op after the remote configuration is applied. This includes setTheme, updateDataSource, setLabels, setLabelsPriority, setContentIds, setMaxItemsSize, setMaxItemsDisplaySize, updateOverrideStyles, and setPersonalized. This does not apply to embedded widgets.

IWidgetView {
  setTheme: (theme: IWidgetTheme | ThemeType) => void;
  getTheme: () => IWidgetTheme;
  reload: () => void;
  updateWidgetUI: () => void;
  setMaxItemsDisplaySize: (size: number) => void;
  setDelegations: (delegates: Record<Delegation, EventListenerOrEventListenerObject>) => void;
  updateOverrideStyles: (perItemStyleOverrides: PerItemStyleOverrides) => void;
  updateDataSource: (dataSource: BlazeDataSourceType) => void;

  /**
   * @deprecated Use `updateDataSource` by creating a new data using `DataSourceBuilder` under the `BlazeSDK` function instead.
   */
  setLabels: (labels: string | string[] | BlazeWidgetLabel, options?: ISetWidgetOptions) => void;
  setLabelsPriority: (labelsPriority: string | string[] | BlazeWidgetLabel[], options?: ISetWidgetOptions) => void;
  setContentIds: (storyIds: string[], options?: ISetWidgetOptions) => void;
  setMaxItemsSize: (size: number) => void;
}

ICustomWidgetView

ICustomWidgetView extends IWidgetView {
  getContainer: () => HTMLElement;
  getContents: () => IBlazeContent[];
}

reload(): void

Reloads the view by creating another API call to fetch new content

 widgetView.reload()

updateWidgetUI(): void

Reloads the layout after changes were made with updateOverrideStyles , don't perform API call to fetch new content

 widgetView.updateWidgetUI()

setMaxItemsDisplaySize(size: number): void

Set the number of displayed item in the widget

Parameter	Type	Required	Description
size	number	Yes	update the widget layout

 widgetView.setMaxItemsDisplaySize(5)

setTheme(theme: IWidgetTheme): void

Sets the view theme

Parameter	Type	Required	Description
theme	IWidgetTheme	Yes	theme to apply on view
contentType	'story'	'moment'	'video'

const newTheme = BlazeSDK.Theme('row-rectangle','story');
 
widgetView.setTheme(newTheme);

getTheme(): IWidgetTheme

Gets the view current theme

const currentTheme = widgetView.getTheme()

setDelegations( delegations : Object ): void

Parameter	Type	Required	Description
delegations	Object	Yes	key - Delegation of widget - event string, value - Callback function

widgetRowView.setDelegations({
    [BlazeSDK.Delegations.onWidgetDataLoadCompleted]: (e) => console.log("widgetRowView onWidgetDataLoadCompleted", e.detail)
 })
// 3 more events: onWidgetDataLoadStarted, onWidgetTriggerCTA, onWidgetStoryPlayerDismissed

updateOverrideStyles(perItemStyleOverrides: PerItemStyleOverrides)

Parameter	Type	Required	Description
perItemStyleOverrides	PerItemStyleOverrides	Yes	key - Delegation of widget - event string, value - Callback function

To update item style overrides after the initial setup, utilize the updateOverrideStyles method available on the IWidgetView instance. This method accepts an object structure similar to PerItemStyleOverrides, where the keys correspond to entity identifiers such as playerId, gameId, or teamId.

// Create a copy of the theme for further customization
const themeCopy = JSON.parse(JSON.stringify(rowCircleTheme));
// Customize chip text and background color
const chipText = '20:30 PM | LIVE';
const color = 'red';

// Apply custom chip text and background color to all states
themeCopy.layoutStyle.statusUnreadStyle.text = chipText;
themeCopy.layoutStyle.statusReadStyle.text = chipText;
themeCopy.layoutStyle.statusLiveUnreadStyle.text = chipText;
themeCopy.layoutStyle.statusLiveStyle.text = chipText;

themeCopy.layoutStyle.statusUnreadStyle.backgroundColor = color;
themeCopy.layoutStyle.statusReadStyle.backgroundColor = color;
themeCopy.layoutStyle.statusLiveUnreadStyle.backgroundColor = color;
themeCopy.layoutStyle.statusLiveStyle.backgroundColor = color;

// Define per-item style overrides for a specific player entity
const itemOverrideStyle = {
  "playerId": [
    {
   		 name: "46046",
    	theme: themeCopy 
    }
  ]
};

// Apply per-item style overrides and update the widget UI
widgetRowView.updateOverrideStyles(itemOverrideStyle);
widgetRowView.updateWidgetUI();

In this example, the updateOverrideStyles method updates the styling for specific entities within the widget, such as players, based on the provided playerId. You can employ a similar approach for other entity identifiers like gameId or teamId.

updateDataSource(dataSource: BlazeDataSourceType)

This method updates the data source with the provided BlazeDataSourceType object.

 const dataSource = BlazeSDK.DataSourceBuilder().labels({
   labels: BlazeSDK.LabelBuilder().atLeastOneOf('top-stories', 'live-stories'),
   labelsPriority: `[${BlazeSDK.LabelBuilder().singleLabel('live-stories')}]`,
   orderType: 'RecentlyUpdatedFirst',
   maxItems: 4,
 });

widgetView.updateDataSource(dataSource);
widgetView.reload();

getContainer: () => HTMLElement

Returns the HTML container element where your custom widget content is rendered.

const customWidget = BlazeSDK.WidgetCustomView('my-container', {
  customRenderer: myRenderer
});

// Get the widget's container element
const container = customWidget.getContainer();

// You can use this to access rendered elements
const storyElements = container.querySelectorAll('.story-item');

getContents: () => IBlazeContent[];

Returns the current contents data (IBlazeStory[] | IBlazeMoment[] | IBlazeVideo[])

const customWidget = BlazeSDK.WidgetCustomView('my-container', {
  customRenderer: {
    render(contents, container, playContent) {
      // contents parameter is already transformed
      // But you can also get fresh data anytime:
    }
  }
});

// Get current content data
const contents = customWidget.getContents();

// Access clean, public properties
contents.forEach(content => {
  console.log(content.title);        // ✅ Safe public property
  console.log(content.hasViewed);    // ✅ View status
});

// Listen for content updates
customWidget.addEventListener('onWidgetPlayerDismissed', () => {
  const updatedContents = customWidget.getContents();
  const container = customWidget.getContainer();

  // Update individual elements based on new view status
  updatedContents.forEach(content => {
    const element = container.querySelector(`#story-${content.id}`);
    element.className = content.hasViewed ? 'viewed' : 'unviewed';
  });
});

Deprecated

setLabels(labels: string\string[]\BlazeWidgetLabel, options?: ISetWidgetOptions): void - deprecated

Set the view new labels. Once new labels are set, the view will reload with new labels

Parameter	Type	Required	Description
labels	string~~string[]~~\BlazeWidgetLabel	Yes	set new labels on the view and reload
options.shouldReloadData	boolean	no	will prevent the SDK from loading new data from the server

widgetView.setLabels('live-stories', {shouldReloadData: false}) // default of shouldReloadData is true

setLabelsPriority(labelsPriority: string, options?: ISetWidgetOptions): void - deprecated

Set the label priority of the view

Parameter	Type	Required	Description
labelsPriority	string	Yes	set a new priority for the widget, it will send a new API request and reload the widget
options.shouldReloadData	boolean	no	will prevent the SDK from loading new data from the server

widgetView.setLabelsPriority('[ronaldo,messi]', {shouldReloadData: false})

setContentIds(storyIds: string[], options?: ISetWidgetOptions): void - deprecated

Set the view new story Ids. Once new story ids are set, the view will reload

Parameter	Type	Required	Description
storyIds	string[]	Yes	set new stories to load
options.shouldReloadData	boolean	no	will prevent the SDK from loading new data from the server

widgetView.setContentIds(['1234','5678'],{shouldReloadData: false})

setMaxItemsSize(size: number): void

Set the number of items in the widget

Parameter	Type	Required	Description
size	number	Yes	update the widget layout

Updated 16 days ago

Did this page help you?