Show Modals using Page Collections, UX Controllers and Sub-Pages in UI Builder

[Kamalesh]

Page collections/Extension Points refer to clusters of sub-pages distinguished by a specific extension point. It is available to configure for the viewport family of components.​

1. Reusability​
2. No ownership

• Page Collection and Extension point are named interchangeably. UXF named them Extension Points, UIB exposes them as Page Collections.
• In general, extension points are a way for page authors to write viewport subpages with only a controller as an interface, which results in a set of subpages that can be used anywhere a certain controller is present.
• The data that makes up an Extension Point
  1. App shell reference - Where the subpages will be served.
  2. Component - Which component the subpages will be served in
  3. Controller - The controller that provides the API for the subpage.
  4. Related lists - These are used the same way they would be used on a page directly to add content to a viewport.
     1. Screens
     2. Routes

Implementation:

1. Use case is to show the modal on change of parent incident field in incident record page to inform about the details of parent incident.
2. Here, we will create the modal as dynamic one which can be used in other pages also, by taking the fields to be shown on modal as input props.
3. We will be implementing this usecase by using extension points, UX Controllers and Sub-Pages.

Steps:

• Create UX Controller
  • Create a new page in UI Builder and provide meaningful name (as ‘Extension Point Demo Controller’).
  • Now let’s convert this page into UX Controller in backend as there is no direct way to create UX Controllers from UI Builder.
    • Open UX Controller table.   {instanceurl}/sys_ux_controller_list.do
    • In “Controller Config Guidance”, add the properties required to be sent to controller from record page and their default config values as shown.

• • •  Now open the Macroponent Definition, and change the category as “UI Controller”, so that the page created earlier will act as controller which can encapsulate the Data Resources, Client Scripts and state params for all the sub pages of our extension point.
    • Note: All the properties mentioned in “Controller Config Guidance” should be added as required parameters of the controller page if the valueType is ‘Field’ , if valueType is “param” then add the properties as “Optional parameters” in UI Builder Page Settings.
  • Let’s start building our logic to get the reference fields values using a data broker in controller and expose the fields from Controller by defining them in “Output Prop Mapping” field in Macroponent definition. 
    
    • Open the controller in UI Builder to build the logic.
    • Create a transform data resource.
    • Add the logic in the new Data Resource to fetch the preview field details of reference field dynamically.

• • • Also, Execute ACL should be to use Data Resource in UIB Pages.
    • Done with data resource setup, we can add the data resource in our controller and map the context prop fields in the properties.
    • Now, we have to define “Output Prop Mapping” to expose fields from UX Controller to be used in sub-pages.

• Create a new Extension Point/Page Collections
  • Add the mandatory details in the fields like below, link the controller created in previous step in controller field.
  • Once saving the form, new UI Action ‘Open in UI Builder’, click on this button.

• Create subpage in UIBuilder in the page collection created in previous step.
  • Click on ‘Create new page’ and add required parameters for subpage. For our use case, no need of any required parameters as all the details will be available from UX Controller created previously.
  • In the subpage, we should notice that controller created and attached to extension point/Page Collection should be added as inherited data resource like below.

• • For current usecase, Created Repeater Component and add label-value component inside it to show the field label and value of Reference Field.

• Add Extension Point/Page Collection and controller in Parent Page (Ex: Asset Workspace SRP).
  • In Modals, click on Modal Container Viewport and add page Collection created earlier in it.
  • Then add the parameters for Our UX Controller (which should be added automatically after adding the page collection) like below and verify the output from the controller.

• Next step is to add event handler on change of Parent Incident field to show the details of Parent Incident in a modal using Page Collection.
  • Create event handler.
    • Create a client script ‘View Parent Incident’ and emit event to show the modal/subpage created earlier.

    • /**
      * @param {params} params
      * @param {api} params.api
      * @param {any} params.event
      * @param {any} params.imports
      * @param {ApiHelpers} params.helpers
      */
      function handler({api, event, helpers, imports}) {
      var fieldName = event.payload.fieldName;
          var newValue = event.payload.value;
              api.emit('MACROPONENT_VIEWPORT_LOAD_REQUESTED', {
                  viewportElementId: 'modalContainerViewport',
                  route: 'preview-reference-field-modal',
                  fields: {},
                  params: ''
              });
      }

    • DataResources -> Standard record -> Events -> Add Event Mapping, then Select Field Value Changed and link the new client script ‘View Parent Incident’ client script created earlier.

• Configuration is completed, modal should come on change of parent incident field.