Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

Mashup attributes

Updated on February 7, 2022

Learn about the attributes, actions, and events that you can use in a mashup so that you can fully benefit from the functionality.

After generating the mashup code on the mashup channel, copying the <div> or the <iframe> tag with the mashup code, and embedding the code in your host page (a web application or a web page), you can modify the attributes in the tags to change the behavior of the mashup gadget.

For example, you can modify the way in which the host page displays the embedded content by changing the values in the data-pega-resizetype attribute. You can also add or modify attributes and actions in the host page JavaScript. For example, you can specify the log off JavaScript action to manage the session ending.

The following simplified architecture of a web page that hosts a mashup contains various categories of attributes, actions, and events, most of which you can modify to meet you specific business needs:

<!DOCTYPE html>
<html>
<head>
<script src ='http://example.com/prweb?pyActivity=pzIncludeMashupScripts'> (the activity that loads the Gadget Manager, which is a JavaScript file that loads on your host page to implement mashup gadgets)
</script>
</head>
<body>
(JavaScript page actions)(configuration object attributes)
<div data-pega-gadgetname = "GadgetName" 
(mashup attributes),
(mashup action),
(action-specific attributes),
(mashup events) >
<script>
var data-pega-gadgetname = {
(mashup action object/actionMapping, which handles gadget-to-gadget interaction)
}
</script>
</div>
</body>
</html>

The components of the mashup <div> code (HTML-5 compliant) that you paste into your host page HTML fall into the following categories:

  • Mashup attributes (optional or obligatory, depending on the attribute)
  • Mashup action (obligatory)
  • Action-specific attributes (obligatory if you specify a mashup action)
  • Mashup events (optional)
  • Mashup action objects (optional)
    Note: Mashup action objects are object literals that your assign to a JavaScript variable. For more information, see Mashup action objects.

Apart from the attributes, actions, and events that you can find in the <div> tag, you can also use the following JavaScript components to specify mashup behaviour:

Configuration object attributes

Configuration object attributes are JavaScript objects that you can use to provide information about the mashup configuration. You can use the configuration object attributes instead of corresponding mashup attributes in the <div> code.

For example, you can use the pega.web.config.appName configuration object attribute when you want to specify the attribute for all the mashups on your host page that share the same application name without the need to repeat the data-pega-applicationname mashup attribute in the <div> code of each mashup.

You can use the following configuration object attributes at the top of the host page HTML:

pega.web.config.appName
The name of a application that specifies a single work pool.
pega.web.config.thread
The thread ID.
pega.web.config.encrypt
The script encryption.
Note: When you set the pega.web.config.encrypt property to false, you disable all encryption and obfuscation for the script. The setting is useful when you test mashup deployments or use a mashup in a secure intranet deployment.

The following extract shows an example of the pega.web.config.appName attribute in a script:

<HTML>
   <HEAD>
      <script src="https://community.pega.com/example.com/prweb?pyActivity=pzIncludeMashupScripts"></script>
      <script>
         pega.web.config.appName = "AutoClaim";
               
      </script>
   </HEAD>

Mashup attributes

The following attributes in the mashup <div> code define the mashup that the host page displays as a gadget:

data-pega-gadgetname
Provides the names of the gadget. The default name, which you can change, is PegaGadget.

The following extract shows an example of the data-pega-gadgetname attribute in a script:

<div id="PegaGadgetDIV" data-pega-gadgetname = "PegaSampleTask"…>
data-pega-applicationname, data-pega-threadname

Provide the name of a application that specifies a single work pool and the name of a thread in which the mashup action takes place.

Note:

  • If all of the mashups on your web page display processes from the same application, instead of repeating the data-pega-applicationname attribute in the <div> code of each mashup, you can use the pega.web.config.appName configuration object attribute in the configuration object, at the top of the page, and then, optionally, specify a unique thread name in the <div> code of each mashup with the data-pega-threadname attribute.
  • If you have more than one mashup on your web page and the mashups need to share clipboard pages, provide the same thread name for each mashup. If each mashup needs its own clipboard context, provide different thread names for each mashup with the data-pega-threadname mashup attribute, so that the system maintains the mashup pages separately.
channelID (obligatory)
Provides the channel ID. The system automatically generates the channelID attribute in your mashup code. Do not change the value of the attribute.
Note: If you change the value of the channelID attribute, the mashup does not load due to the breach of Pega security measures.

For more information about troubleshooting this issue, see Mashup code is not consistent with the latest security enhancements.

data-pega-url (obligatory)
Provides the URL of the mashup application in the system.

The following extract shows an example of the mashup attributes in a script:

<HTML> <HEAD> <script
      src="https://community.pega.com/example.com/prweb?pyActivity=pzIncludeMashupScripts"></script> </HEAD> <BODY> <div
      id="PegaGadgetDIV"
      style="overflow:auto"
      data-pega-gadgetname = "PegaSampleTask"
      data-pega-action = "display"
      data-pega-applicationname= "PegaSample"
      data-pega-action-param-classname
      = "PegaSample-Task"
      data-pega-action-param-harnessname = "New"  
      data-pega-channelID ='MASHUPc219f4bfad0e4576944c8c9f5df8a1ca'  
      data-pega-url ='https://sample.pega.com/prweb/'      > </div> </BODY> </HTML>
data-pega-isdeferloaded (obligatory)
Specifies whether the action that we selected for the mashup occurs when the Gadget Manager first loads the page, or whether the action waits until the pega.web.api.doAction("myGadget", "load") function in the page JavaScript or a mashup action in another mashup invokes the action. The default value for this attribute is false.

The following extract shows an example of the data-pega-isdeferloaded attribute in a script:

<div id="PegaWebGadgetB" style="display:none; "data-pega-gadgetname="PWGadgetB" data-pega-isdeferloaded="true" > </div>
data-pega-resizetype (obligatory)
Specifies the sizing behavior of the mashup gadget. The attribute determines whether the mashup gadget fits into a fixed space or expands to fill the available space on the web page. By default, the value of the attribute is stretch.
Note: When you accept the default value of stretch, to ensure that the mashup’s display is not clipped, set the style of the <div> element to "overflow:auto". When the value of the data-pega-resizetype attribute is stretch, do not set other sizing attributes, such as height or width.

The following extract shows an example of the data-pega-resizetype attribute in a script:

<div id="PegaContent"
   style="overflow:auto; width:800; height:440; display:none;"
   data-pega-gadgetname="PWGadgetB"
   data-pega-action = "createNewWork"
   data-pega-action-param-classname = "UServ-InsuranceProducts-SimpleCollision"
   data-pega-action-param-flowname = "ProcessVehicleApplication"
   data-pega-isdeferloaded = "true"
   data-pega-resizetype = "fixed">    </div>
data-pega-targettype (optional)
Specifies whether the mashup displays the content on the page or in a pop-up window. The values that you can select for this attribute are _self (default) and _popup.

The following extract shows an example of the data-pega-targettype attribute in a script:

<div id= "PegaGadget1"
   data-pega-gadgetname="GadgetPopup"
   data-pega-targettype="_popup"
   data-pega-popupoptions="height=200; width=400; toolbar=no; menubar=no;"
   data-pega-threadname = "Thread1"
   data-pega-action="createNewWork"
   data-pega-action-param-classname="PegaSample-Task"
   data-pega-action-param-flowname="basicProcess"
   data-pega-isdeferloaded="true"    >    </div>
data-pega-popupoptions (optional)
If the value of the data-pega-targettype attribute is _popup, then the data-pega-popupoptions attribute specifies values for the pop-up window by providing a string with name-value pairs for the pop-up attributes.

The following extract shows an example of the data-pega-popupoptions attribute in a script:

<div id= "PegaGadget1"
   data-pega-gadgetname="GadgetPopup"
   data-pega-targettype="_popup"
   data-pega-popupoptions="height=200; width=400; toolbar=no; menubar=no;"
   data-pega-threadname = "Thread1"
   data-pega-action="createNewWork"
   data-pega-action-param-classname="PegaSample-Task"
   data-pega-action-param-flowname="basicProcess"
   data-pega-isdeferloaded="true"    >   </div>

Mashup actions

The mashup action attribute (data-pega-action) specifies the action that the Gadget Manager performs when it loads the mashup.

Note: The action that you specify for your mashup requires a relevant action-specific attribute.

You can select a mashup action attribute from the following list:

createNewWork
Creates a work object that you specify with the use of the data-pega-action-param-classname and data-pega-action-param-flowname attributes.
display
Displays the harness that you define in the <div> code with the use of the harnessName and className action-specific attributes.
getNextWork
Retrieves the next work item of the highest priority from the user’s worklist.
openAssignment
Opens the assignment that you specify with the use of the data-pega-action-param-key action-specific attribute.
openWorkItem
Opens the work object that you specify with the use of the data-pega-action-param-workid action-specific attribute.
openWorkByHandle
Opens the work object that you specify with the data-pega-action-param-key action-specific attribute.
openWorkByURL
Opens the work object by using the URL that you specify in the data-pega-action-param-query action-specific attribute.

The following extract shows an example of the data-pega-action attribute in a script:

<div id="PegaGadgetA" 
   style="overflow:auto;" 
   data-pega-gadgetname ="GadgetA" 
   data-pega-threadname = "NewWork" 
   data-pega-action = "createNewWork" 
   data-pega-action-param-classname = "PegaSample-CustomerRequest"
   data-pega-action-param-flowname = "NewWork">   </div>

Action-specific attributes

When you use a mashup action, then, depending on the type of the data-pega-action action attribute, you provide values for the following action-specific attributes:

data-pega-action-param-classname
The name of the applies to class of the specified flow or harness. You specify the attribute for display, createNewWork, and getNextWork actions.
data-pega-action-param-model
(Optional) The name of a model to use when creating a clipboard page for the applies to class when a className is specified.
data-pega-action-param-flowname
The name of a flow rule. You specify the attribute for display and createNewWork.
data-pega-action-param-harnessname
The name of a harness rule. You specify the attribute for the display action.
data-pega-action-param-pagename
The name of an existing clipboard page.
data-pega-action-param-query
The query string that opens the work item. You specify the attribute for the openWorkByURL action.
data-pega-action-param-isreadonly
Displays the mashup content as read-only. By default, the displayed assignment, work object, or flow are editable.You specify the attribute for the display action.
data-pega-action-param-key
The pzInsKey property of the work object. You specify the attribute for the openAssignment and openWorkByHandle action parameters.
data-pega-action-param-workid
The work object ID of a work item. You specify the attribute for the openWorkItem action parameter.
data-pega-action-param-parameters
An object for passing additional parameters such as user-defined parameters. Use object literal notation data-pega-action-param-parameters= "{name: 'value',name: 'value'}" to preserve the parameters' case with mixed-case strings even when the operator uses a Firefox browser.

The following extract shows an example of action-specific attributes for the action that displays a page:

<div id="PegaGadgetDIV" 
   style="overflow:auto;"
   data-pega-gadgetname = "PegaSampleTask"
   data-pega-action = "display"
   data-pega-action-param-classname = "PegaSample-Task"
   data-pega-action-param-harnessname = "New"> </div>

Mashup attributes for events (optional)

The gadget name is passed to the function that is called by the gadget event attribute. The system supports events with the following gadget event attributes:

data-pega-event-onload
Specifies the name of a JavaScript function that the Gadget Manager invokes when loading the gadget. The value that you provide for this attribute is a function reference,which is a string that identifies the function that is defined at the top of the page.

In the following example of the data-pega-event-onload attribute in a script, after the Gadget Manager loads GadgetA, the event displays GadgetB:

<script>
      function onLoadFunc(sID) { PegaWebGadgetB.style.display = "block"; }     
      </script>
     <div id="PegaGadgetA"
      data-pega-gadgetname="GadgetA"
      data-pega-threadname = "ThreadA"
      data-pega-applicationname = "AutoClaim"
      data-pega-action = "display"
      data-pega-action-param-harnessname = "PegaWebAssignList"
      data-pega-action-param-classname = "Assign-Worklist"
      data-pega-event-onload = "onLoadFunc" >  </div>
data-pega-event-onbeforeload
Specifies the name of a JavaScript function that the Gadget Manager invokes before loading the gadget. The function returns the value of true or false. If the function returns false, the Gadget Manager does not load the gadget. The value that you provide in the attribute is a function reference,which is a string that identifies the function that is defined at the top of the page.

In the following example of the data-pega-event-onbeforeload attribute in a script, when the user name is undefined, the mashup does not load itself:

<script>
       function onBeforeLoadFunc(pID) {        
        if(typeof(UserName) == 'undefined') {        
        alert("Missing UserName input field");        
        return false;        }
        else
        return true;        }
      </script>   
      <div id="PegaGadgetA"
      style="overflow:auto;"
      data-pega-gadgetname="GadgetA"
      data-pega-action = "display"
      data-pega-action-param-harnessname = "PegaWebAssignList"
      data-pega-action-param-classname = "Assign-Worklist"
      data-pega-event-onbeforeload = "onBeforeLoadFunc" >  </div>
data-pega-event-onconfirm
The name of a JavaScript function that the Gadget Manager invokes when the gadget displays a Confirm harness. The value that you provide for this attribute is a function reference, which is a string that identifies the function that is defined at the top of the page.

The following extract shows an example of the data-pega-event-onconfirm attribute in a script:

<script>  
  function onConfirmFunc(pID) { 
  //Custom code
  alert(“On confirm event got triggered.” );
  return true;
 }
     </script>
     <div id = "PegaGadgetA"
      data-pega-gadgetname = "GadgetA"
      data-pega-applicationname = "AutoClaim"
      data-pega-threadname = "ThreadA"
      data-pega-action = "display"
      data-pega-action-param-harnessname = "PegaWebAssignList"
      data-pega-action-param-classname
      = "Assign-Worklist"
      data-pega-event-onconfirm =
        "onConfirmFunc" >  </div>
data-pega-event-onclose
The name of a JavaScript function that the Gadget Manager invokes when the gadget closes a harness. The value that you provide for this attribute is a function reference, which is a string that identifies the function that is defined at the top of the page.

In the following example of the data-pega-event-onclose attribute in a script, when the harness closes, the event invokes the refresh action of GadgetA:

<script>
      function onCloseFunc(pID) {        
       pega.web.api.doAction("GadgetA", "refresh");  }
      </script> 
      <div id = "PegaGadgetA"
      data-pega-gadgetname="GadgetA"
      data-pega-threadname="ThreadA"
      data-pega-applicationname = "AutoClaim"
      data-pega-action = "display"
      data-pega-action-param-harnessname = "PegaWebAssignList"
      data-pega-action-param-classname = "Assign-Worklist"
      data-pega-event-onclose = "onCloseFunc" >  </div>
data-pega-event-onpagedata
The name of a JavaScript function that the Gadget Manager calls to retrieve data from the page. The value that you provide for this attribute is a function reference, which is a string that identifies the function that is defined at the top of the page.

In the following example of the data-pega-event-onpagedata attribute in a script, the className attribute for the CreateNewWork action is read from the dataFromPage function:

<script>
      function dataFromPage(test){       
       if(test == "className")        
       return "pegaSample-Task";}    
     </script> 
      <div id="PegaGadgetA"
      style="overflow:auto"
      data-pega-gadgetname = "PWGadgetA"
      data-pega-threadname = "Thread1"
      data-pega-applicationname = "AutoClaim"
      data-pega-action = "createNewWork"
      data-pega-action-param-classname = [page/function/className]
      data-pega-action-param-flowname = "BasicProcess"
      data-pega-event-onpagedata = "dataFromPage" >  </div>
data-pega-event-oncustom
The name of a JavaScript function that the Gadget Manager calls in response to a custom event. To generate the custom event, you invoke the pega.desktop.gadgetCustomEvent(string) function from the mashup.

In the following example of the data-pega-event-oncustom attribute in a script, when a user calls the pega.desktop.gadgetCustomEvent(string) function, the function invokes the custom callback:

<script>
function customCallback(gadgetName, strToken){ 
if( gadgetName == "PWGadgetA") {
 //String passed from mashup is strToken
 alert(strToken);
}
      </script>
      <div id="PegaGadgetA"
      style = "overflow:auto"
      data-pega-gadgetname = "PWGadgetA"
      data-pega-threadname = "Thread1"
      data-pega-applicationname= "AutoClaim"
      data-pega-action = "createNewWork"
      data-pega-action-param-classname = [page/function/className]
      data-pega-action-param-flowname = "BasicProcess"
      data-pega-event-oncustom = "customCallback">  </div>
Note:
  • The strToken token is a string value that the developer defines. For example, the string can contain a property name and value pairs delimited by characters, and the custom callback JavaScript function is responsible for parsing and processing the token.
  • Because the value for the data-pega-event-oncustom attribute is a Javascript function reference, the string token has no default value when the attribute is used as a <div> attribute.
  • You cannot use the data-pega-event-oncustom event in the actionMapping setting.
data-pega-event-onresize
The name of a JavaScript function that the Gadget Manager invokes when the gadget resizes. To use this event, you set the data-pega-resizetype attribute in the gadget <div> element to stretch. The value that you provide for this attribute is a function reference, which is a string that identifies the function that is defined at the top of the page.

An example of the data-pega-event-onresize attribute in a script:

<script>
      functiononResizeFunc()     alert("Gadget is resized");    }
      </script>
      <div id="PegaGadgetA" 
       style="overflow:auto; 
       "data-pega-gadgetname = "GadgetA" 
        data-pega-resizetype = "stretch"
        data-pega-action = "display"
        data-pega-action-param-harnessname = "PegaWebAssignList"
        data-pega-action-param-classname = "Assign-Worklist"
        data-pega-event-onresize = "onResizeFunc" >  </div>

Tags

Pega Platform 8.5 User Experience

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Visit the Support Center

Did you find this content helpful?

Yes
No

Want to help us improve this content?
Suggest an edit

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us