Handler

A handler specifies what happens when a normal action is triggered or response or failure is received after a save, submit or upload action is triggered.

Handler parts

Each handler has the following four parts:

• assignments: assign the given values to certain fields
• updates: update certain fields using the given values through update methods
• next: next stage
• redirect: redirect outside to a different URL, for example, after a user is successfully authenticated at the login page.

Handler assignments

Default Value

An array of { “field”:..., “value”: … }

General

Assign the given values to certain fields. An array of { “field”:..., “value”: … }, where

• field: a variable expression

  • An actor’s property or appearance

    • $nav(actorName).property(fieldName);

    • $nav(actorName).appearance(fieldName);

  • The current actor’s data

    • $this.attr(fieldName);

  • Other actor’s data

    • $state(actorName).attr(fieldName);

  • Global data

    • $global.attr(fieldName);

• value: a JS value or a variable expression

  • The arguments from built-in handlers

    • $args[index];

    • $args[index].attr(fieldName);

  • The remote response

    • $result;

    • $result.attr(fieldName);

  • An actor’s property or appearance

    • $nav(actorName).property(fieldName);

    • $nav(actorName).appearance(fieldName);

  • The current actor’s data

    • $this.attr(fieldName);

  • Other actor’s data

    • $state(actorName).attr(fieldName);

  • Global data

    • $global.attr(fieldName);

Status

Code JSON 

Implementation Example

The following handler assignment sets the URL of the document preview iframe using the attachment Id from the first record of the DocCat_Attachment children relationship.

"assignments": [{
  "field": "$nav(PreviewPageInclude).property(url);",
  "value": "/servlet/servlet.FileDownload?file=$this.attr(clcommon__DocCat_Attachment_Associations__r).attr(clcommon__Attachment_Id__c);"  
}]

In the following handler assignment, after the save action succeeds, the saved record is returned as a response. Use the Id of the saved record to query property (whereClause.recordId) the data in FinancialDetailView and move to the second step of ApplicationSteps.

"assignments": [{
  "field": "$nav(FinancialDetailView).property(whereClause.recordId);",
  "value": "$result.attr(id);"  
}, {
  "field": "$nav(ApplicationSteps).appearance(current);",
  "value": 1
  
}]

In the following handler assignment, the remote API returns an array of all the children relationship records from DocCat_Attachment_Association. Use the response to set the component’s children relationship data.

"assignments": [{
  "field": "$this.attr(clcommon__DocCat_Attachment_Associations__r);",
  "value": "$result;"  
}]

In the following handler assignment, sessionId is a global attribute specified in navigation JSON. Use it to query BorrowerCardView and GuarantorCardView and move to the third step of ApplicationSteps.

"assignments": [{
  "field": "$nav(BorrowerCardView).property(whereClause.Guest_Account__c);",
  "value": "$global.attr(sessionId);"  
}, {
  "field": "$nav(GuarantorCardView).property(whereClause.Guest_Account__c);",
  "value": "$global.attr(sessionId);"  
}, {
  "field": "$nav(ApplicationSteps).appearance(current);",
  "value": 2
  
}]

The following handler assignment uses the ID of the first record in the current component to query property (whereClause.recordId)the data in BorrowerDetailView.

"assignments": [{
  "field": "$nav(BorrowerDetailView).property(whereClause.recordId);",
  "value": "$this.attr(id);"  
}, {
  "field": "$nav(ApplicationSteps).appearance(current);",
  "value": 0
  
}]

The following handler assignment sets BorrowerDetailView’s whereClause to null so that the component displays a new view.

"assignments": [{
  "field": "$nav(BorrowerDetailView).property(whereClause);",
  "value": null
  
}]

In the following handler assignment, clickRecord is a built-in handler in component actor. It takes the record being clicked as the first and only argument. Use the Application__c value in the first argument (a clicked record) to set the query.

"clickRecord": {
  "assignments": [{
    "field": "$nav(BusinessDocumentQueueView).property(whereClause.applicationId);",
    "value": "$args[0].attr(genesis__Application__c);"    
  }],
  "trigger": "APPLICATION_DETAILS"  
}

The following handler assignment uses the response from a remote API ($result;) to set data of a component.

"componentActions": [{
  "name": "save",
  "actionType": "submit",
  "remoteActionClassname": "sampleRemoteApi",
  "successHandler": {
    "assignments": [{
      "field": "$nav(ApplicationSteps).appearance(current);",
      "value": 1
      
    }, {
      "field": "$state(FinancialDetailView);",
      "value": "$result;"      
    }]
    
  }
  
}]

Handler updates

Default Value

An array of { “name”: …, “value”: … }

General

Update certain fields using the given values through update methods. Sometimes, we need to update values based on what they are. Then we cannot use assignments. Updates are for special cases ONLY. (We have three built-in updates so far.)

• Add reloads: $nav.reloads.add with an actorName or an array of actorNames
• Add overlay (modal dialogs): $nav.overlay.add with a layout name or an array of layout names
• Remove overlay (modal dialogs): $nav.overlay.remove with a layout name or an array of layout names(need it because some actions (not the built-in close button) in the overlay can cause it to close.)

Status

Implementation Example

In the following handler update, after the save succeeds, mark reload to the two actors, the BorrowerCardView and the GuaranterCardView. When we display those actors again, they will query the data from the server (even though they have data already since the data is considered stale) and remove their own reload flag.

"successHandler": {
  "assignments": [...],
  "updates": [{
    "name": "$nav.reloads.add;",
    "value": [ "BorrowerCardView", "GuarantorCardView" ]
    
  }]
  
}

In the following handler update, overlay is an array of layouts, which specifies all modal dialogs that can be open in the current stage.

"ApplciationDetailPage": {
  "layout": {...},
  "overlay": [{
    "name": "preview",
    "children": [{
      "name": "PreviewPageInclude"      
    }]
    
  }]
  
}

In the following handler update, when the preview action is triggered, the preview layout in the overlay is added to the current overlay array, and thus displayed as a modal dialog. By default, the overlay array is empty, and thus no modal dialog is displayed.

"recordActions": [{
  "name": "preview",
  "actionType": "normal",
  "handler": {
    "assignments": [...],
    "updates": [{
      "name": "$nav.overlay.add;",
      "value": "preview"      
    }]
    
  }...

Handler next and redirect

Default Value

General

Can be variable expression too

Status

"componentActions": [{

"name": "login",

"actionType": "submit",
"label": "Log In",
"remoteActionArguments": {
  "username": "$this.attr(username);",
  "password": "$this.attr(password);"  
},
"remoteActionAPIname": "login",
"successHandler": {
  "redirect": "$result;"  
}
  
}]
“redirect”: url
“redirect”: {
  “url”: url,
  “target”: “_blank”
  
}

Handler Triggering Actions

Default Value

General

Handler from one action can conditionally trigger other actions (in the same or different actors)

• The triggered action can be rendered false.
• But the actor has to be in the current stage.

Status

successHandler: {
  "assignments": […]
  "updates": […]
  "cruds": […]
  "actions": [
    { "condition": "$result...", "actorName": …, "name": … }
    ]
  
}

Implementation Example

"AccountDetails2": {
  "componentActions": [{
    "name": "save",
    "actionType": "save",
    "successHandler": {
      "assignments": [{
        "field": "$state(AccountDetail2);",
        "value": "$result;"        
      }],
      "actions": [{
        "actorName": "ContactList",
        "name": "saveContacts"        
      }]
      
    }
    
  }]…}
  
"ContactList": {
  "componentActions": [{
    "name": "saveContacts",
    "actionType": "save",
    "appearance": { "render": false },
    "remoteActionArguments": { "AccountId": "$state(AccountDetail2).attr(id);" },
    
  }]…}

Features

Assignment using JS

Default Value

General

The portal framework can be configured to trigger external JS code for certain use cases.

Status

Implementation Example

loan calculation – when the residual amount or term changes, update interest rate and monthly payment in real-time.

"generalHandlers": { "fieldChange": {
  "genesis__Residual_Amount__c, genesis__Payment_Frequency__c": {
    "assignments": [{
      "field": "$this.attr(genesis__Interest_Rate__c);",
      "value": "$ext.calculateInterestRate",
      "arguments": [ "$this.attr(genesis__Residual_Amount__c);", "$this.attr(genesis__Payment_Frequency__c);" ]
      
    }, {
      "field": "$this.attr(genesis__Payment_Amount_Per_Period__c);",
      "value": "$ext.calculateMonthlyPayment",
      "arguments": [ "$this.attr(genesis__Residual_Amount__c);", "$this.attr(genesis__Payment_Frequency__c);" ]
      
    }]...

• The external JS function returns the value that can be assigned to another field in real-time.

portalext.calculateMonthlyPayment = (amount, term) => {
  const rate = calcInterestRate(amount, term);
  let calTerm = term/12;
  if (rate == 0) { return 0; }
  term = Number.parseInt(term);
  if (Number.isNaN(term)) { return 0; }
  let perRate = rate/12;
  return (amount * (perRate * (1+perRate) ** term)) / ((1+perRate) ** term - 1);
};

Assignment with recordId

General

Assign a value to a specific record (not just the first record) in a list/queue/card view.

"assignments": [{ "field": "$global.attr(contactId);", "value": "$this.attr(id);" }]

Status

Implementation Example

"assignments": [{
  "field": "$state(ContactList).attr(AccountId);",
  "value": "$interaction.attr(highlighted).attr(id);",
  "recordId": "$global.attr(contactId);"}],