What UI events are

Clio Operate screens are built from independent widgets, panels, and list views placed side by side on the same page. UI events let those pieces communicate in the browser. When something changes in one place, for example a work item is saved, a phase is progressed, or a document is generated, that action broadcasts a named event. Any widget that listens for that event refreshes itself.

The model has two halves: one place broadcasts an event, and other places subscribe to it. To make widget B refresh when action A happens, find the event that A broadcasts and add that event name to widget B's configuration. This article lists the built-in event names and shows where to configure them.

Who this article is for

This article is for Modellers who configure widgets on portals and want a widget to refresh when something changes elsewhere on the page. It covers the common case: subscribing a widget to built-in events through the UI. Narrowing a subscription to specific widgets is included as an advanced sub-topic. See Reduce the scope of a subscription.

UI events can do more than this first version documents. Broadcasting your own events, working with events in the IDE, and the full set of platform events are out of scope here, and may be documented in a later pass.

Top 15 events: quick reference

These are the events you will reach for most often. Select an event to jump to its section in the reference below. For most "keep my widget in sync with the matter" cases, listening to sharedo.updated and sharedo.core.case.forms.phase.phase-changed is enough.

Where to configure events

Modellers configure a widget's events in the page designer. You need Modeller access.

1. In the Modeller, navigate to Forms and views > Portal editor.
2. Select the portal, then select Design on the page that holds the widget.
3. In the page designer, select the widget, then select its Edit (pencil) icon. The Edit widget blade opens.

Events are entered in a field called UI Events, found in the Advanced settings section of a widget's configuration (or its scope). 

The UI Events field holds one or more event names separated by a semicolon (;). Each entry is trimmed, so spaces around the semicolon do not matter. The field's own help text lists a few common events to get you started.

sharedo.updated;sharedo.core.case.components.taskList.data-changed;sharedo.core.case.components.portfolioList.data-changed

This subscribes the widget to all three events, so it refreshes when any of them fire. For a single event, enter the name on its own with no separator.

Where the UI Events field lives, by widget

Not every widget can subscribe to events. Where the UI Events field appears depends on the widget:

• List views: select Edit scope on the list view widget to open the list view scope, then expand Advanced settings. You can reach the same scope from Forms and views > List views in the Modeller.
• Reports: select Edit report on the report widget, open the Customise tab, then expand the Advanced section.
• Other supported widgets, such as Key Facts and Key Dates: expand Advanced settings in the widget's own configuration.

Common configuration mistakes

1. Event names are case-sensitive and must match exactly. Enter each name character-for-character as listed below. Some built-in events are lowercase dotted (sharedo.core.case.sharedo-updated), others are PascalCase (Sharedo.Core.Case.Participants.Updated).
2. The UI Events field uses a semicolon (;) to separate event names. Enter multiple events as one string separated by ;. Each entry is trimmed, so spaces around the semicolon are fine. If a widget does not refresh when expected, check the separator first.
3. Listening to too many events affects performance. Each event a widget listens for can trigger a reload, so a long listen list means more reloading. Subscribe only to the events the widget needs.

Reduce the scope of a subscription (advanced)

By default, a widget responds to a matching event fired anywhere on the page. To narrow a subscription so that only a specific group of widgets responds, give those widgets the same Topic Name in their Messaging section (available from Clio Operate 7.10, currently on list views and reports). The Modeller describes the field as follows:

This is the mechanism behind interactive reports and list views, where selecting or filtering in one report filters another report or list on the same page. For example, a page has two report widgets and two list views. You want a filter on the first report to update only the list view beneath it, not the second pair. Give the first report and its list view a shared Topic Name, and give the second pair a different one. Enter the exact same name in every widget in the group, and remove any trailing space introduced by copying and pasting. For the full walkthrough, see Create interactive ShareDo reports and list views.

Worked examples

Refresh a Key Facts widget when the phase changes

You have a Key Facts widget on a matter page that should re-read its data whenever the matter changes phase. In the widget's Advanced settings, enter the phase event in the UI Events field:

sharedo.core.case.forms.phase.phase-changed

To also refresh on any save, add another event separated by a semicolon (;):

sharedo.core.case.forms.phase.phase-changed;sharedo.updated

Checklist: a widget does not refresh

• Is the event name spelt exactly right, including capitalisation?
• In the UI Events field, are multiple event names separated by a semicolon (;)?
• If you are using a Topic Name to scope, do all the widgets in the group share the exact same Topic Name, with no trailing spaces?
• Does the action you expect to trigger the refresh actually fire the event? Check the tables above. Some actions that seem like they should fire an event do not, and the reverse is also true.

Related articles

• Portal Widget: List View
• Create interactive ShareDo reports and list views (from 7.10)
• Portal Widgets: Available Widgets