Latest revision as of 19:13, 6 February 2025

ADF ceRecord API Methods

TThe ADF ceRecord API is a collection of wrapper functions designed for CommonSpot 11's Custom Data API. This Custom Data API allows developers to add and update specific user-defined CommonSpot objects, such as Global Custom Elements, Local Custom Elements, Metadata Form Elements, and Simple Form Elements.

The ceRecord API wrapper functions for Global and Local Custom Elements serve as replacements for the CCAPI functions: apiElement.populateCustom() and csContent.populateContent(). Additionally, the ceRecord API includes functions that can be used with Metadata Form Elements and Simple Form Elements.

Minimal Configuration for Global Custom Elements

Unlike the extra configuration required to set up the CCAPI, the new ceRecordAPI requires minimal to no configuration. Additional CommonSpot configuration is only needed if the script being used allows data modifications of a Global Custom Element by users with permissions lower than those set by the GCE's security permissions. In such cases, registering the script as a CommonSpot Privileged Module would be required.

For more details on registering Privileged Modules review this page: Privileged Module Configuration.

gceRecord

addRecord()

Adds a new record to a Global Custom Element. Arguments:

• ceName - The name of the Global Custom Element where the record will be added.
• dataValues - The field name/value pairs structure for the record to be added.
• fieldSpecs - A field name/specs option pairs structure used to modify the data values expected by the configured field (currently only used for Taxonomy fields).

Returns:

• Struct:
  • contentUpdateResponse: string (Success:1 or Success:0)
  • contentUpdated: boolean
  • data: struct
  • datapageid: numeric (0 if status=false)
  • error_msg: string
  • errorfields: array
  • status: boolean
  • updatefields: array
  • error_msg: string
  • error: struct (key added only on error)

updateRecord()

Updates an existing record in a Global Custom Element. Arguments:

• ceName - The name of the Global Custom Element where the specified record will be updated.
• dataPageID - The dataPageID value for the record to be updated
• dataValues - The field name/value pairs structure of the record to be updated
• fieldSpecs - A field name/specs option pairs structure used to modify the data values expected by the configured field (currently only used for Taxonomy fields).

Returns:

• Struct:
  • contentUpdateResponse: string (Success:1 or Success:0)
  • contentUpdated: boolean
  • data: struct
  • datapageid: numeric (0 if status=false)
  • error_msg: string
  • errorfields: array
  • status: boolean
  • updatefields: array
  • error_msg: string
  • error: struct (key added only on error)

saveRecord()

Adds or updates a Global Custom Element record. Updates the record if an existing ‘datapageid’ value greater than 0 is passed in with the dataValues, otherwise it will create a new record. Arguments:

• ceName - The name of the Global Custom Element where the record will be saved.
• dataValues - The field name/value pairs structure for the record to be saved. A ‘dataPageID’ key/value pair must be included to update a specific record.
• fieldSpecs - A field name/specs option pairs structure used to modify the data values expected by the configured field (currently only used for Taxonomy fields).

Returns:

• Struct:
  • contentUpdateResponse: string (Success:1 or Success:0)
  • contentUpdated: boolean
  • data: struct
  • datapageid: numeric (0 if status=false)
  • error_msg: string
  • errorfields: array
  • status: boolean
  • updatefields: array
  • error_msg: string
  • error: struct (key added only on error)

lceRecord

addRecord()

Creates a new page and adds a new record to a Local Custom Element on the new page. Arguments:

• ceName - The name of the Local Custom Element where the record will be added.
• subsiteid - The subsiteid of subsite where the new page will be created
• templateid - The templateid of the template used to create the new page
• controlid - The controlID value for the element instance where the data will be added
• pageValues - A struct of standard metadata used to create the new page
• dataValues - The field name/value pairs structure for the record to be added.
• fieldSpecs - A field name/specs option pairs structure used to modify the data values expected by the configured field (currently only used for Taxonomy fields).
• activatePage - A boolean flag to set the new page as active or inactive after creation
• useRemoteCreate - A boolean flag used to enable or disable the remote command API for the page creation

Returns:

• Struct:
  • contentUpdateResponse - string (Success:1 or Success:0)
  • contentUpdated - boolean
  • data - struct
  • pageid - numeric (0 if status=false)
  • subsiteid - numeric
  • templateid - numeric
  • controlid - numeric
  • error_msg - string
  • errorfields - array
  • status - boolean
  • updatefields - array
  • error_msg - string
  • error - struct (key added only on error)

updateRecord()

Updates an existing record in a Local Custom Element on a page. Arguments:

• ceName - The name of the Local Custom Element where the specified record will be updated.
• pageID - The pageID value for the page to be updated
• controlid - The controlID value for the element instance to be updated
• dataValues - The fieldname/value pairs structure of the record to be updated
• fieldSpecs - A field name/specs option pairs structure used to modify the data values expected by the configured field (currently only used for Taxonomy fields).

Returns:

• Struct:
  • contentUpdateResponse - string (Success:1 or Success:0)
  • contentUpdated - boolean
  • data - struct
  • pageid - numeric (0 if status=false)
  • controlid - numeric
  • error_msg- string
  • errorfields - array
  • status - boolean
  • updatefields - array
  • error_msg - string
  • error - struct (key added only on error)

mdfRecord

updateRecord()

Updates a metadata form element record bound to a page. Arguments:

• mdFormName - The name of the Metadata Form Element where the specified record will be updated.
• pageID - The pageID value for the page where the metadata record to be added/updated
• dataValues - The fieldname/value pairs structure of the record to be updated
• fieldSpecs - A field name/specs option pairs structure used to modify the data values expected by the configured field (currently only used for Taxonomy fields).

Returns:

• Struct:
  • contentUpdateResponse: string (Success:1 or Success:0)
  • contentUpdated: boolean
  • data: struct
  • pageid: numeric (0 if status=false)
  • error_msg: string
  • errorfields: array
  • status: boolean
  • updatefields: array
  • error_msg: string
  • error: struct (key added only on error)

Note: There is no 'addRecord' function for modifying Metadata Form Elements data because these records are inherently tied to a CommonSpot page. When a new page is created, a corresponding metadata form record is automatically generated. As a result, only an 'updateRecord' function is offered in the mdfRecord ceRecord API Library.

sfsRecord

addRecord()

Adds a new record to a Simple Form Element Arguments:

• formName - The name of the Global Custom Element where the record will be added.
• dataValues - The field name/value pairs structure for the record to be added.
• fieldSpecs - A field name/specs option pairs structure used to modify the data values expected by the configured field (currently only used for Taxonomy fields).

Returns:

• Struct:
  • contentUpdateResponse- string (Success:1 or Success:0)
  • contentUpdated- boolean
  • data- struct
  • datapageid- numeric (0 if status=false)
  • error_msg- string
  • errorfields- array
  • status- boolean
  • updatefields - array
  • error_msg - string
  • error - struct (key added only on error)

updateRecord()

Updates an existing record in a Simple Form Element Arguments:

• formName - The name of the Global Custom Element where the specified record will be updated.
• dataPageID - The dataPageID value for the record to be updated
• dataValues - The field name/value pairs structure of the record to be updated
• fieldSpecs - A field name/specs option pairs structure used to modify the data values expected by the configured field (currently only used for Taxonomy fields).

Returns:

• Struct:
  • content update response - string (Success:1 or Success:0)
  • contentUpdated - boolean
  • data - struct
  • datapageid - numeric (0 if status=false)
  • error_msg - string
  • errorfields - array
  • status - boolean
  • updatefields - array
  • error_msg - string
  • error - struct (key added only on error)

Usage Examples

GCE: add record

<cfscript>
  gceName = "imageTestGCE"; // name of an example GCE -  
                            // this element has 5 fields: 
                            // img, caption, plainURL, extURL, and creationTimestamp
  dataValues = StructNew();
  dataValues.img = { 
     'imageid': 1388,  // ID of an image in the gallery
     'altText': "alt text for image",
     'titleText': "title for image added at #Now()#"
   }; 
  dataValues.caption = "caption for this instance";
  dataValues.plainURL = "https://www.boston.com";
  dataValues.extURL = 1422;		   // pageID of a CS page to link to
  dataValues.creationTimestamp = Server.CommonSpot.UDF.util.formatCSDate(Now());

  addResult = Application.ADF.gceRecord.addRecord(ceName=gceName, dataValues=dataValues);

  if ( addResult.status )
     WriteOutput("new GCE instance #addResult.datapageid# created at #Now()#");
</cfscript>

GCE: update record

<cfscript>
  gceName = "imageTestGCE";  // name of an example GCE -  
                             // this element has 5 fields: 
                             // img, caption, plainURL, extURL, and creationTimestamp
  dataPageID = 10921;
  dataValues = StructNew();
  dataValues.img = { 
     'imageid': 1388,  // ID of an image in the gallery
     'altText': "alt text for image",
     'titleText': "title for image added at #Now()#"
   }; 
  dataValues.caption = "caption for this instance";
  dataValues.plainURL = "https://www.boston.com";
  dataValues.extURL = 1422;		   // pageID of a CS page to link to
  dataValues.creationTimestamp = Server.CommonSpot.UDF.util.formatCSDate(Now());

  updateResult = Application.ADF.gceRecord.updateRecord(ceName=gceName, dataPageID=dataPageID, dataValues=dataValues);
    
  if ( updateResult.status )
     WriteOutput("Updated GCE instance #updateResult.datapageid# at #Now()#");
</cfscript>

LCE: add record (and create page)

<cfscript>
  lceName = "imageTestLCE";  // name of an example GCE -  
                             // this element has 5 fields: 
                             // img, caption, plainURL, extURL, and creationTimestamp
  subsiteid = 91;
  templateID = 1021;
  controlid = 69119;
  activatePage = true;

  pageValues = {};
  pageValues.name = 'New Page';
  pageValues.title = 'New Page';
  pageValues.categoryID = 1;	    // update with appropriate page category id
  pageValues.showInList = ;      // update with appropriate show in list values
  pageValues.pageMetadata = [];    // update with custom metadata array of form structs  

  dataValues = StructNew();
  dataValues.img = { 
     'imageid': 1388,  // ID of an image in the gallery
     'altText': "alt text for image",
     'titleText': "title for image added at #Now()#"
  }; 
  dataValues.caption = "caption for this instance";
  dataValues.plainURL = "https://www.boston.com";
  dataValues.extURL = 1422;		   // pageID of a CS page to link to
  dataValues.creationTimestamp = Server.CommonSpot.UDF.util.formatCSDate(Now());
    
  addResult = Application.ADF.lceRecord.addRecord(ceName=lceName, subsiteid=subsiteid, templateid=templateid, controlid=controlid, pageValues=pageValues, dataValues=dataValues, activatePage=activatePage);

  if ( addResult.status )
     WriteOutput("New Page and LCE instance #addResult.pageid# created at #Now()#");
</cfscript>

LCE: update record

<cfscript>
  lceName = "imageTestGCE";  // name of an example GCE -  
                             // this element has 5 fields: 
                             // img, caption, plainURL, extURL, and creationTimestamp
  pageID = 10921;
  controlid = 69119;

  dataValues = StructNew();
  dataValues.img = { 
     'imageid': 1388,  // ID of an image in the gallery
     'altText': "alt text for image",
     'titleText': "title for image added at #Now()#"
   }; 
  dataValues.caption = "caption for this instance";
  dataValues.plainURL = "https://www.boston.com";
  dataValues.extURL = 1422;		   // pageID of a CS page to link to
  dataValues.creationTimestamp = Server.CommonSpot.UDF.util.formatCSDate(Now());

  updateResult = Application.ADF.lceRecord.updateRecord(ceName=lceName, controlid=controlid, pageID=pageID, dataValues=dataValues);

  if ( updateResult.status )
     WriteOutput("Updated LCE instance #updateResult.datapageid# at #Now()#");
</cfscript>

MDF: update record

<cfscript>
  mdfName = "imageTestMDF";  // name of an example custom medata data form -  
                             // this metadata form has 5 fields: 
                             // img, caption, plainURL, extURL, and creationTimestamp
  pageID = 10921;

  dataValues = StructNew();
  dataValues.img = { 
     'imageid': 1388,  // ID of an image in the gallery
     'altText': "alt text for image",
     'titleText': "title for image added at #Now()#"
   }; 
  dataValues.caption = "caption for this instance";
  dataValues.plainURL = "https://www.boston.com";
  dataValues.extURL = 1422;		   // pageID of a CS page to link to
  dataValues.creationTimestamp = Server.CommonSpot.UDF.util.formatCSDate(Now());

  updateResult = Application.ADF.mdfRecord.updateRecord(mdFormName=mdfName, pageID=pageID, dataValues=dataValues);

  if ( updateResult.status )
     WriteOutput("Updated LCE instance #updateResult.datapageid# at #Now()#");
</cfscript>

SFE: add record

<cfscript>
  sfeName = "testSimpleForm"; // name of an example Simple Form -  
                              // this element has 4 fields: 
                              // firstName, lastName, emailAddress(email) and creationTimestamp

  dataValues = StructNew();
  dataValues.firstName = "Joe";
  dataValues.lastName = "Smith";
  dataValues.emailAddress = "joesmith@test.com";		  
  dataValues.creationTimestamp = Server.CommonSpot.UDF.util.formatCSDate(Now());

  addResult = Application.ADF.sfeRecord.addRecord(formName=sfeName, dataValues=dataValues);

  if ( addResult.status )
     WriteOutput("new SFE instance #addResult.datapageid# created at #Now()#");
</cfscript>

SFE: update record

<cfscript>
  sfeName = "testSimpleForm"; // name of an example Simple Form -  
                              // this element has 4 fields: 
                              // firstName, lastName, emailAddress(email) and creationTimestamp

  dataPageID = 10921;

  dataValues = StructNew();
  dataValues.firstName = "Jane";
  dataValues.lastName = "Smith";
  dataValues.emailAddress = "janesmith@test.com";		  
  dataValues.creationTimestamp = Server.CommonSpot.UDF.util.formatCSDate(Now());

  updateResult = Application.ADF.sfeRecord.updateRecord(formName=sfeName, dataPageID=dataPageID, dataValues=dataValues);

  if ( updateResult.status )
     WriteOutput("Updated GCE instance #updateResult.datapageid# at #Now()#");
</cfscript>

Utility Function Reference

ceRecordBase

setFieldValue()

Sets the value of the field in ceRecord set object Arguments:

• ceObject(r) - The gce-, lce-, mdf-, or sfe- recordset object for the field to be set.
• fieldName(r) - The name of field to be updated.
• fieldValue - The string value of the field to be updated.
• fieldType - The field type of the field to be updated.
• fieldOptions - An option/value pairs structure that could be used to modify the data values expected by the configured field.

Returns:

• Struct:
  • error_msg - string

Note:

• The arguments ‘fieldType’ and ‘fieldOptions’ are not directly utilized by this function. However, their data is made available for potential overrides at the site level and for future enhancements.

prepareFieldValues()

Parses field values of the incoming struct of field name/field values pairs and prepares them to be passed the setFieldValue() function as fieldName and fieldValue arguments. Arguments:

• ceObject(r) - The gce-, lce-, mdf-, or sfe- recordset object for the field to be set.
• fieldValues(r) - The field name/value pairs structure of the record to be updated
• fieldSpecs - The field name/option pairs used to modify specific field preparations.

Returns:

• Struct:
  • ceName - string
  • fieldName - string
  • fieldValueStr - string
  • fieldOptions - string
  • error - string

prepareFieldValueHook()

Override hook that enables custom logic to be added to modify the field value before it is passed back to the CE Record API call, ensuring the correct data is set. Arguments:

• ceName(r) - The name of the custom element, metadata form or simple form element to be updated.
• fieldName(r) - The name of field to be updated.
• fieldValueStr - The string value of the field to be updated.
• fieldType - The field type of the field to be updated.
• fieldOptions - A option/value pairs structure that could be used to modify the data values expected by the configured field.
• error - The field error that has been generated when attempting to parse the value for the field.

Returns:

• Struct:
  • ceName - string
  • fieldName - string
  • fieldValueStr - string
  • fieldType - string
  • fieldOptions - string
  • error - string

convertExtendedUrlDataValueToArgs()

Converts the string or struct value to the arguments struct needed for the CSExtendedURL fldRenderer.formatData() function. Arguments:

• fieldRenderer(r) - object
• fieldParams(r) - struct
• dataValue - any

Returns:

• Struct:
  • fieldParams - struct
  • targetType - string
  • pageID - integer
  • target - string
  • bookmark - string
  • newWindowParams - string

getCsExtendedUrlTargetType()

An ADF wrapper for CS UDF: Server.CommonSpot.UDF.linkmgt.getTargetType() with an added target argument to also return email targets and a struct of other target properties. Arguments:

• pageID - numeric
• target - string

Returns:

• String

convertNewWinParamsToArgs()

Converts a new window param string to the correct format for the fldRenderer.formatNewWindowParams() function. Utility function for the convertExtendedUrlDataValueToArgs() convert function. Utility function for the convertExtendedUrlDataValueToArgs() convert function. Arguments:

• paramsList - string
• targetName - string

Returns:

• Struct:
  • targetType - ('tab' or 'popup')
  • targetName - name for new tab or window
  • top - vertical position for new window
  • left - horizontal position for new window
  • height - vertical size for new window
  • width - horizontal size for new window
  • toolbar - 1 to display toolbar in new window, 0 otherwise
  • loc - 1 to display location bar in new window, 0 otherwise
  • directories - 1 to display directories in new window, 0 otherwise
  • status - 1 to display status bar in new window, 0 otherwise
  • menubar - 1 to display menu bar in new window, 0 otherwise
  • scrollbars - 1 to display scrollbars in new window, 0 otherwise
  • resizable - 1 to allow user to resize the new window, 0 otherwise

convertImageDataValueToArgs()

Convert field data value to a struct of the arguments needed for the image field's formatData() function Arguments:

• fieldRenderer - object
• fieldParams - struct
• dataValue - any

Returns:

• Struct:
  • fieldParams - struct
  • imageID - integer
  • altText - string
  • titleText - string
  • captionText - string

convertImageDataValueToStr()

An ADF wrapper function for CE Record API formatValue_Image() that returns a CS image formatted string Arguments:

• dataValue - any

Returns:

• String:

convertMultimediaDataValueToArgs()

Converts multimedia data value (xml string or struct) into the arguments needed for the multimedia field fldRenderer.formatData() function. Arguments:

• fieldRenderer(r) - object
• fieldParams(r) - struct
• dataValue - any

Returns:

• Struct:
  • fieldParams
  • mediaId
  • player
  • playerParams

convertTaxonomyDataValueToIdList()

Converts taxonomy field data value string into the id list with the correct delimiters. Arguments:

• dataValue - any

Returns:

• String

convertTaxonomyDataValueToTermList()

Converts taxonomy field data value string into the term name list with the correct delimiters Arguments:

• dataValue - any

Returns:

• String

convertTreeControlDataValueToTreeList()

Converts tree field data value string into the field value string with the correct delimiters. Arguments:

• dataValue - any

Returns:

• String