Skip to main content


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

Append or insert rows in page lists and page groups by using newRow

Updated on November 23, 2022

Update the visible page list or page group without multiple trips to the server to insert or append multiple rows with a newRow object in the Pega APIs. Use newRow to insert or append a new row into a page list or page group. You can either send a full page list or page group in content or by using pageInstructions.

The newRow object contains the following items:

  • A blank row that matches what is inserted into an existing page list or page group, both for table and repeating dynamic layout.
  • Default values.
  • A token that is replaced with a row number or row group, for example, "listIndex":"{0635a0898ec699564286ca3fd52cded2_listIndex}".

Each newRow object has either a listIndex (for a page list) or groupIndex (for a page group) property that contains a unique token for the page list or page group. When you insert or append a row, you replace all instances of this token with either a row number or a group name through a simple string replace.

Note: If you insert a row, adjust the references of the subsequent rows.

The following Pega APIs support the newRow object:

  • GET /assignments/{ID}/actions/{actionID}
  • GET /cases/{ID}/actions/{actionID}
  • GET /casetypes/{ID}
  • GET /cases/{ID}/actions/{actionID}
  • PUT /casetypes/{ID}/refresh
  • PUT /assignments/{ID}/actions/{actionID}/refresh
  • PUT /cases/{ID}/actions/{actionID}/refresh

The following JSON is an example of a repeating layout with a text box and button, both with newRow, and one row (rows):

"groups": [{
   "layout": {
"newRow": {
         "listIndex": "{584b5b08d4e2981c9d910634946f7e75_listIndex}",
         "groups": [{
            "field": {
                  "validationMessages": "",
                  "visible": true,
                  "labelReserveSpace": false,
                  "readOnly": false,
                  "control": {
                     "modes": [{
                        "modeType": "editable",
                        "controlFormat": "Standard",
                        "textAlign": "Left",
                        "tooltip": "",
                        "maxChars": "",
                        "formatType": "none",
                        "specifySize": "auto",
                        "minChars": ""
                        }, {
                        "modeType": "readOnly",
                        "tooltip": "",
                        "showReadOnlyValidation": "false",
                        "formatType": "none"
                     }],
                     "actionSets": [],
                        "type": "pxTextInput"
                  },
                  "label": "PL_A",
                  "type": "Text",
                  "required": false,
                  "reference": "PageList({584b5b08d4e2981c9d910634946f7e75_listIndex}).PL_A",
                  "labelFormat": "Standard",
                  "disabled": false,
                  "value": "",
                  "maxLength": 256,
                  "expectedLength": "",
                  "fieldID": "PL_A"
               }, {
         "field": {
                  "validationMessages": "",
                  "visible": true,
                  "labelReserveSpace": false,
                  "readOnly": false,
                  "control": {
                     "modes": [{
                        "modeType": "ignore",
                        "tooltip": ""
                        }, {
                        "modeType": "readOnly",
                        "autoPrepend": "",
                        "controlFormat": "pzhc",
                        "tooltip": "",
                        "showReadOnlyValidation": "false",
                        "autoAppend": "",
                        "formatType": "text"
}],
                  "actionSets": [{
                     "actions": [{
                        "action": "refresh",
                        "refreshFor": "UGFnZUxpc3QucHlUZW1wbGF0ZUJ1dHRvbiNweEJ1dHRvbiMzNA%3D%3D_{584b5b08d4e2981c9d910634946f7e75_listIndex}"
                        }],
                     "events": [{
                        "event": "click"
                        }]
                  }],
                  "label": "Refresh DT",
                  "type": "pxButton"
               },
            "label": "",
            "type": "Text",
            "showLabel": false,
            "required": false,
            "reference": "PageList({584b5b08d4e2981c9d910634946f7e75_listIndex}).pyTemplateButton",
            "labelFormat": "Standard",
            "disabled": false,
            "value": "",
            "maxLength": 0,
            "expectedLength": "",
            "fieldID": "pyTemplateButton"
            }
   ]}
},
“rows”: {
         "groups": [{
            "field": {
                  "validationMessages": "",
                  "visible": true,
                  "labelReserveSpace": false,
                  "readOnly": false,
                  "control": {
                     "modes": [{
                        "modeType": "editable",
                        "controlFormat": "Standard",
                        "textAlign": "Left",
                        "tooltip": "",
                        "maxChars": "",
                        "formatType": "none",
                        "specifySize": "auto",
                        "minChars": ""
                        }, {
                        "modeType": "readOnly",
                        "tooltip": "",
                        "showReadOnlyValidation": "false",
                        "formatType": "none"
                     }],
                     "actionSets": [],
                        "type": "pxTextInput"
                  },
                  "label": "PL_A",
                  "type": "Text",
                  "required": false,
                  "reference": "PageList(1).PL_A",
                  "labelFormat": "Standard",
                  "disabled": false,
                  "value": "",
                  "maxLength": 256,
                  "expectedLength": "",
                  "fieldID": "PL_A"
               }, {
         "field": {
                  "validationMessages": "",
                  "visible": true,
                  "labelReserveSpace": false,
                  "readOnly": false,
                  "control": {
                     "modes": [{
                        "modeType": "ignore",
                        "tooltip": ""
                        }, {
                        "modeType": "readOnly",
                        "autoPrepend": "",
                        "controlFormat": "pzhc",
                        "tooltip": "",
                        "showReadOnlyValidation": "false",
                        "autoAppend": "",
                        "formatType": "text"
}],
                  "actionSets": [{
                     "actions": [{
                        "action": "refresh",
                        "refreshFor": "UGFnZUxpc3QucHlUZW1wbGF0ZUJ1dHRvbiNweEJ1dHRvbiMzNA%3D%3D_1"
                        }],
                     "events": [{
                        "event": "click"
                        }]
                  }],
                  "label": "Refresh DT",
                  "type": "pxButton"
               },
            "label": "",
            "type": "Text",
            "showLabel": false,
            "required": false,
            "reference": "PageList(1).pyTemplateButton",
            "labelFormat": "Standard",
            "disabled": false,
            "value": "",
            "maxLength": 0,
            "expectedLength": "",
            "fieldID": "pyTemplateButton"
            }
   ]}
},
“groupFormat”: “Grid”,
“layoutFormat”: “REPEATINGROW”

The following JavaScript code is an example of a client that calls insertRow ("page.property(2)", 2, layoutComp):

insertRow(rowRef: string, newRowIndex, layoutComp) {

  // convert object to string
  let addRowJSON = JSON.stringify(layoutComp.newRow);

  // get listIndex token
  let sRefToken = layoutComp.newRow.listIndex; 
  
  // replace all instances of the “token” with the new “index”
  addRowJSON = addRowJSON. replace( new RegExp(this.escapeRegExp(sRef), 'g'),   
                                                             nNewRowIndex);
  let addRow = JSON.parse(addRowJSON); // convert back to json object

  // insert the new row  the “rows” object
  this.layoutComp.rows.splice(nNewRowIndex – 1, 0, addRow);

  let rowRefName = rowRef.substring(0, rowRef.lastIndexOf("("));

  // now adjust all existing rows below insert 
  // (change the reference index “page(n).prop”)

  this.updateRowsWithNewReferenceFrom(layoutComp.rows, rowIndex,     
     rowRefName, true);

  // now layoutComp.rows has a new row, can move forward with redrawing
  // the view and updating state

escapeRegExp(str: string): string {
    return str.replace(str.replace(/([.*+?^=!:${}()|\[\]\/\\])/g, "\\$1");
}

updateRowsWithNewReferenceFrom(oRows: any, nStartingIndex: number, 
 sReferencePrefix: string,  
 bIncrement: boolean = true): any {
    let nRowLength = oRows.length;
    for ( let nIndex = nStartingIndex; nIndex < nRowLength; nIndex++ ) {
	let oRow = oRows[nIndex];

	let sNewRef = "";
	let sRef;
	if (bIncrement) {
	  sNewRef = sReferencePrefix.concat("(").concat((nIndex + 
1).toString()).concat(")");
	  sRef = sReferencePrefix.concat("(").concat(
nIndex.toString()).concat(")");
	}
	else {
	  // should be a number higher, and so if 
        //we set to index, should be one less
	  sNewRef = sReferencePrefix.concat("(").concat((nIndex + 
1).toString()).concat(")");
	  sRef = sReferencePrefix.concat("(").concat((nIndex + 
2).toString()).concat(")");
	}

	// iterate though all the stuff in the row and change the reference
	this.replaceReference(oRow, "groups", sRef, 
sNewRef, (nIndex + 1).toString());

  }
}

// handles updating refrences (Page(x).property, etc.)
replaceReference(oElement: any, oElementType: string, sOldReference: string, 
                 sNewReference: string, sNewIndex: string, 
     sOldIndex: string = "") {

    switch (oElementType) {
      case "groups":
        for (let groupIndex in oElement.groups) {
          let groupElement = oElement.groups[groupIndex];
          for (let elType in groupElement) {
            this.replaceReference(groupElement, elType, sOldReference, 
sNewReference, sNewIndex, sOldIndex);
          }
        }
        break;
      case "field":
        oElement.field.reference = oElement.field.reference.replace(
sOldReference, sNewReference, sNewIndex);
        if (oElement.field.controlName) {
          oElement.field.controlName = oElement.field.controlName.replace(
sOldReference, sNewReference, sNewIndex);
        }
        if (oElement.field.fieldID == "pxSubscript") {
          oElement.field.value = sNewIndex;
        }
        this.updateRefreshFor(oElement.field.control, sNewIndex, sOldIndex);
        break;
      case "layout":
        if (oElement.layout.reference) {
          oElement.layout.reference = oElement.layout.reference.replace(
sOldReference, sNewReference, sNewIndex);
        }
        for (let groupIndex in oElement.layout.groups) {
          let groupElement = oElement.layout.groups[groupIndex];
          for (let elType in groupElement) {
            this.replaceReference(groupElement, elType, 
sOldReference, sNewReference, sNewIndex, sOldIndex);
          }
        }
        break;
      case "view":
        oElement.view.reference = oElement.view.reference.replace(
sOldReference, sNewReference, sNewIndex);
        for (let groupIndex in oElement.view.groups) {
          let groupElement = oElement.view.groups[groupIndex];
          for (let elType in groupElement) {
            this.replaceReference(groupElement, elType, 
sOldReference, sNewReference, sNewIndex, sOldIndex);
          }        
        }
        break;
    }
  }
// handles updateing a “refreshFor” reference in actions
updateRefreshFor(oControl, sNewIndex: string, sOldIndex: string) {
    if (oControl.actionSets != null) {

      for (let setIndex in oControl.actionSets) {
        let arActions = oControl.actionSets[setIndex].actions;

        for (let actionIndex in arActions) {
          let oAction = arActions[actionIndex];
          if (oAction.refreshFor != null) {
            var sRefreshFor = oAction.refreshFor;
            let sIndex = sRefreshFor.lastIndexOf("_");
            if (sIndex > 0) {
              sRefreshFor = sRefreshFor.substring(0, sIndex+1);
              sRefreshFor = sRefreshFor.concat(sNewIndex);
              oAction.refreshFor = sRefreshFor;
            }
            else {
              // old reference could be missing "_"
              if (sOldIndex != "") {
                sIndex = sRefreshFor.lastIndexOf(sOldIndex);
                if (sIndex > 0) {
                  sRefreshFor = sRefreshFor.substring(0, sIndex);
                  sRefreshFor = sRefreshFor.concat(sNewIndex);
                  oAction.refreshFor = sRefreshFor; 
                }
              }
            }
          }
        }
      }
    }
  }
  • Previous topic Retrieve a flat list of fields from Pega APIs
  • Next topic Page-related operation queuing with page instructions in Pega APIs

Have a question? Get answers now.

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

Did you find this content helpful?

Want to help us improve this content?

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