{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":2920,"path":"application-development/ui-builder/work-events.md","title":"Manage actions in UI Builder pages","bundle":null,"doc_type":null,"release":"australia","body":"\n# Manage actions in UI Builder pages\n\nLearn how to work with events so that you can add actions to components, pages, data resources, and declarative actions in UI Builder.\n\n## Actions in UI Builder\n\nUI actions tell UI Builder what to do when an [event](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/ui-builder/ui-builder-glossary.md) is triggered. An event is an action a user takes or occurrence that happens on a [page](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/ui-builder/ui-builder-glossary.md). Use UI actions to create interactive, user-friendly interfaces that help your users complete tasks. Each [component](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/ui-builder/ui-builder-glossary.md) has its own events associated with it. Events include:\n\n-   User clicks a data visualization\n-   Page successfully fetches data\n-   User selects a radio button\n-   Page loads\n\n## Events in UI Builder\n\nUse an event to add actions to your components, pages, and data resources.\n\n-   A component event is an action that you set up for a component. You set up an event handler to configure that component action. For example, you can add a button component to your UI Builder page. Then, you can add an event handler to apply an action for that button, such as going to a web page.\n-   Page events perform actions for the entire page. You can configure the following page events:\n    -   Page event mappings. Add, remove, or clear alert notifications on your page.\n    -   Variant event mappings. Add, remove, or clear alert notifications on your page variant.\n    -   Dispatched events. Create dispatched events for your page to create relayed event mappings that model events after a parent event handler. Select a target parent event handler to model the payload fields after it.\n    -   Handled events. A handled event is an event that is exposed and available for use by other users. After you create a handled event, it is available under **Page event mappings** for other users to use. You can also set up payload fields that you create manually or choose a template for your handled event, such as an open or close a modal dialog.\n-   Data resources events map data resources to notify information about when data is fetched.\n-   Events for a page or component do nothing until the event is mapped to one or more event handlers.\n\n## Event mapping in UI Builder\n\nMap actions to events such as clicking a button or filling in a field. An event mapping is the process that enables you to map an event's payload or contextual values to the object or handler that acts on that event.\n\nFor more information about event mapping, see [Define map events](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/ui-builder/event-mapping.md).\n\n## Event handlers in UI Builder\n\nAn event handler is an action performed when an event occurs. By mapping an event handler to an event, you are specifying which action or actions to take when the event occurs. Use an event handler to configure an action for your UI Builder page or the components on the page. For example:\n\n-   Clicking a data visualization opens a list of records represented in the visualization\n-   Fetching data successfully for a list opens an alert that indicates the data fetch was successful\n-   Selecting a radio button adjusts the filter for a list on the page\n-   Loading a page opens a modal to confirm acceptance of cookies before proceeding\n\nWhen you add an event handler to a UI Builder page or component, you can choose different types of event handlers. For example, a Button component can have the following types of event handlers:\n\n-   Inherited event handlers. An inherited event handler is exposed from the page that you are working in. If you are in the parent UI Builder page, an inherited event handler could be exposed from the app shell. The following table lists the different types of inherited event handlers that you can use and what you can do with them.\n\n<table id=\"table_uwz_1py_24b\"><thead><tr><th>\n\nEvent handler\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nBreadcrumb URL changed\n\n</td><td>\n\n \n\n</td></tr><tr><td>\n\nLink to destination\n\n</td><td>\n\nNavigate to a destination.-   App routes: Link to another page within an app, like a home screen.\n-   External URL: Link to a website or any external URL.\nSample script\n\n```\n    return {\n        route: null, /* Page route, e.g. 'record' */\n        fields: null, /* Required params, e.g. {\"table\":\"incident\",\"sysId\":\"X\"} */\n        params: null, /* Optional params, e.g. {\"selectedIndex\" : 1} */\n        ☑️redirect: null, /* ??? True/false? */\n        ☑️passiveNavigation: null, /* Load in background, e.g. 'false' */\n        title: null, \n        multiInstField: null, \n        ☑️targetRoute: null, /* ??? */\n        ☑️external: null /* ??? True/false? */\n    };\n\n```\n\n</td></tr><tr><td>\n\nAdd parameters to URL\n\n</td><td>\n\nAdd additional parameters to a URL.Sample script\n\n```\n{ “selectedTabIndex” : 0 }\n```\n\n</td></tr><tr><td>\n\nOpen or close modal dialog\n\n</td><td>\n\nAfter you create a modal, use **Open or close modal dialog** to trigger the modal.\n\n</td></tr></tbody>\n</table>-   Page-level event handlers. This type of event handler is common to all pages, and you would use this handler type when you want to add or clear page-level alert notifications. The following table lists the different types of page-level event handlers that you can use and what you can do with them.\n\n<table id=\"table_xdx_dqy_24b\"><thead><tr><th>\n\nEvent handler\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nAdd alert notifications\n\n</td><td>\n\nAdd a code snippet to send an alert notification. For example: ```\nreturn {\n    items: [{\"type\" : \"info\", \"message\" : \"Info message\", \"id\" : \"optionalID\"}] /* Types: info, warning, error */\n};\n\n```\n\n</td></tr><tr><td>\n\nRemove alert notification\n\n</td><td>\n\nAdd code to call alert notification IDs that you want to dismiss. For example, click a button to remove a page load alert notification.\n\n</td></tr><tr><td>\n\nClear alert notification\n\n</td><td>\n\nAdd code to call all alert notification IDs that you want to dismiss. For example, click a button to remove all alert notifications.\n\n</td></tr><tr><td>\n\nSet loading state\n\n</td><td>\n\nToggle loading on or off. For example, you can toggle loading on to load the page when you click a button or toggle loading off to not load the page when a button is clicked.\n\n</td></tr><tr><td>\n\nUpdate client state parameter\n\n</td><td>\n\nDeclaratively set the client state parameter. Let's say that you have a client state parameter that you set up with a value. You can configure the **Update client state parameter** event handler to update the client state parameter with a new value. For example, you have a client state parameter that is called **Greeting** that is set up with `Hello` as the initial value. You can add an **Update client state parameter** event handler, select the **Greeting** client state parameter, and then enter a new value like `Goodbye`. When you click the button, **Goodbye** replaces **Hello** on the page.\n\n</td></tr><tr><td>\n\nUXF macroponent viewport load requested\n\n</td><td>\n\nAdd to a component, such as a button component, to open a viewport. For more information, see [Add a viewport component to your page](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/ui-builder/work-with-viewport-components.md).\n\n</td></tr></tbody>\n</table>-   Data resource handlers. This type of event handler triggers the fetching or writing of data to the server.\n\n    You can refresh the app shell data source data on your UI Builder page by clicking a button. For example, with a data resource handler, you can do the following actions:\n\n    -   Bind data to the description of an incident record.\n    -   Change the value of the incident description.\n    -   Add a button component to your page.\n    -   Label the button as `Refresh incident`.\n    -   Add a **Look Up Record** event handler for the button.\n    -   Save your page.\n    -   If the description of the incident record changes, click **Refresh** to update the description on your page.\n-   Client scripts. Scripts that execute when an event is triggered on a component. You create these scripts in the Client scripts section in UI Builder. For more information, see [Define and bind client scripts to components](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/ui-builder/define-client-scripts.md).\n\n## Binding events to components in UI Builder\n\nBind event handlers to the events on a component. When you add components to your UI Builder page, these components are not configured to perform any action on your page. For example, a button component is static and does not do anything until you bind an event action to it, such as deleting a record. Some components have several events where event handlers can be assigned. For example, on the list component, you can assign a navigation handler to the **Row clicked** event. You can also assign an open modal to the **Data fetch failed** event. For more information, see [Bind an event to a component](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/ui-builder/bind-event-component.md).\n\n## Binding events to UI Builder pages\n\nBind a page-level event to execute event handlers on the page. For example, use page-level events for page notifications, page load, or when a page property changes. The assignment of the event handler to the page-level event is similar to assigning handlers to events from components.\n\nYou can bind event mappings using the following methods:\n\n-   Page event mappings. Add, remove, or clear alert notifications on your page.\n-   Variant event mappings. Add, remove, or clear alert notifications on your page variant.\n-   Dispatched events. Create dispatched events for your page to create relayed event mappings that model events after a parent event handler. Select a target parent event handler to model the payload fields after it.\n-   Handled events. Add a handled event for an event that is exposed and available for use by other users.\n\nFor more information, see [Bind an event to a page](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/ui-builder/bind-event-page.md).\n\n## Binding events to data resources in UI Builder\n\nBind event handlers to individual data resources on your UI Builder page. For example, when a data resource successfully fetches new data, it executes an event handler, like navigation, to take a user to the next step in a flow. When a data resource successfully adds a record to a table, it shows a success modal that uses the show modal event handler. For more information, see [Bind an event to a data resource](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/ui-builder/bind-event-data-resource.md).\n\n## Binding events to declarative actions in UI Builder\n\nBind data elements to add event actions to a declarative action definition in **Actions &amp; Components** in the ServiceNow AI Platform®. For example, you could bind a data element to add an event action to complete work on a table.\n\nIf you add a component to your UI Builder page that has a declarative action, you must bind it to a handled event. The handled event creates an action that is performed when a user selects the component. By selecting **Configure declarative action event mapping**, you add a new event handler to define what the declarative action does on the page.\n\n\\[Omitted image \"declarative-action-config.png\"\\] Alt text: Configure the declarative action event mappings option in the Configure panel.\n\nFor more information, see [Bind an event to a declarative action](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/ui-builder/bind-event-declarative-action.md).\n\n-   **[Define map events](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/ui-builder/event-mapping.md)**  \nAn event mapping in UI Builder is the process that enables you to map an event's payload or contextual values to the object or handler that acts on that event. The four event types are: component, page, data resource, and declarative action.\n-   **[Event payloads in UI Builder](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/ui-builder/event-payloads.md)**  \nUse event payloads to link data to an action.\n-   **[Configure an event handler manually](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/ui-builder/event-handler.md)**  \nAdd an event handler to a page, component, data resource, or declarative action within UI Builder so that your user can trigger an action.\n-   **[Bind events to add actions](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/ui-builder/bind-events.md)**  \nAfter you have created events, you can bind them to actions on your components, pages, data resources, and declarative actions.\n-   **[Disable component preset event mappings](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/ui-builder/disable-preset-event-mappings.md)**  \nYou can disable event mappings that are automatically created by a component preset.\n-   **[Delete an event handler](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/ui-builder/delete-event-handler.md)**  \nDelete an event handler that you no longer need in UI Builder.\n-   **[Delete an event mapping](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/ui-builder/delete-event-mapping.md)**  \nDelete an event mapping that you no longer need in UI Builder.\n-   **[Add events to track components with unsaved changes](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/ui-builder/dirty-state-event.md)**  \nLocate dirty state components through event configuration.\n-   **[UI interactions](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/ui-builder/uib-ui-interactions.md)**  \nTrigger UI interactions directly from events in UI Builder, allowing you to link event-driven behavior to reusable interaction logic.\n\n**Parent Topic:**[Working in UI Builder](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/ui-builder/using-ui-builder.md)\n\n"}}