Configure Custom Field Behavior with JavaScript

System administrators add JavaScript to SmartSimple custom fields to control form behavior, including buttons and triggers, drop-down and check box options, field input formatting, dates, record and status updates, and advanced page techniques.

Who: System administrators with technical experience who configure business processes with custom JavaScript, ideally with an understanding of basic secure coding practices.

When to Use Custom Field JavaScript

Custom field JavaScript is for specific situations only. Use it only when a particular need justifies the added upkeep, for example to:

• Run a small, specific script from a button or check box.
• Limit the options in a drop-down field, including by role.
• Require a specific format for field input, such as uppercase text or no special characters.
• Clear a default date, such as the default end date on a new record.

Each script added increases the upkeep an instance needs, so limit custom field JavaScript to situations that require it.

↑ Back to top

Add a Button That Runs a Browser Script

To add a button that runs a Browser Script:

1. Create a Display - Text custom field. See the Access the Configuration Page for Custom Fields section of the Configure Custom Fields article.

2. Click the Content field and enter the button code:

   <input type="button" class=Button value="Button Label" onClick='runThisScript()'/>

   Replace Button Label with the text to show on the button. runThisScript() is the function defined in step 4.

3. Create a Special - Browser Script custom field. See the Access the Configuration Page for Custom Fields section of the Configure Custom Fields article.

4. Click the Custom Script field and enter the function to run:

   function runThisScript() {
     // enter the script to run here
   }

↑ Back to top

Use a Check Box to Run a Browser Script

A check box custom field can run a Browser Script so that the check box acts like a button. A line in the script can clear the check box after it runs.

To run a Browser Script from a check box:

1. Create a Select Many - Checkboxes custom field. See the Access the Configuration Page for Custom Fields section of the Configure Custom Fields article.
2. Click the Classic Options tab.

3. Click the Custom HTML Tag field and enter an onclick event:

   onclick="runthis()"

4. Create a Special - Browser Script custom field. See the Access the Configuration Page for Custom Fields section of the Configure Custom Fields article.

5. Click the Custom Script field and enter:

   function runthis() {
     // enter the script to run here
     document.frmevent.cf_123456[1].checked = false;
   }

   123456 is the Custom Field ID of the check box. The checked = false line clears the check box so it behaves like a button.

   • At Level 1, use document.form1 instead of document.frmevent.

   • On a tab, use document.frmedit instead of document.frmevent.

↑ Back to top

Add or Remove Drop-Down Options

JavaScript can change the options available in a drop-down field on the page.

Add a Blank Option to Time Fields

JavaScript can add a blank option to the top of the time drop-down fields on a record.

Example

This example adds a blank option to the top of the starthour, startminute, endhour, and endminute fields for new Level 2 records. It runs only when no start date is saved yet.

function clearTimes() {
  var frm = document.forms[0];
  if (frm.startdate.value == "") {
    frm.starthour.add(new Option("", "", true, true), frm.starthour.options[0]);
    frm.startminute.add(new Option("", "", true, true), frm.startminute.options[0]);
    frm.endhour.add(new Option("", "", true, true), frm.endhour.options[0]);
    frm.endminute.add(new Option("", "", true, true), frm.endminute.options[0]);
  }
}
clearTimes();

At Level 1, use document.form1 instead of document.forms[0].

The syntax to add an option to a drop-down field is:

document.forms[0].starthour.add(new Option(Display text, Store value, defaultSelected, selected), document.forms[0].starthour.options[0])

• Display text is the visible label and Store value is the stored value.
• defaultSelected and selected are true or false.
• options[0] is the option that the new option is inserted before.

↑ Back to top

Remove Options from a Drop-Down

JavaScript can remove options from a drop-down field by display text or by value.

Example

This example removes options by display text for new Level 2 records, which is useful when only certain types should be available:

function RemoveTypes() {
  var frm = document.frmevent;
  // at Level 1 use document.form1 instead of document.frmevent
  if (frm.eventid.value == 0) {
    for (i = frm.eventtype.options.length - 1; i >= 0; i--) {
      if (frm.eventtype.options[i].text == 'FirstType' || frm.eventtype.options[i].text == 'SecondType') {
        frm.eventtype.options[i] = null;
      }
    }
  }
}
RemoveTypes();

Example

This example removes options by value from the Branch drop-down at Level 1:

function RemoveBranches() {
  var frm = document.form1;
  if (frm) {
    for (i = frm.branchid.options.length - 1; i >= 0; i--) {
      if (frm.branchid.options[i].value != 1111 && frm.branchid.options[i].value != 2222) {
        frm.branchid.remove(i);
      }
    }
  }
}
RemoveBranches();

The loop runs from the last option to the first so that re-indexing does not skip options as they are removed.

↑ Back to top

Restrict Drop-Down Options by Role

To control options by role, add the role list at the start of the script and check membership.

Example

This example checks whether role 1234 is in the user’s role list:

New syntax

var myrolelist = "{{me.rolelist}}";
if (myrolelist.indexOf(",1234,") >= 0) {
  // remove or keep options for this role
}

Old syntax

var myrolelist = "@me.rolelist@";
if (myrolelist.indexOf(",1234,") >= 0) {
  // remove or keep options for this role
}

Test for a value greater than or equal to zero. If the role is first in the user’s role list, indexOf returns zero because of the leading comma.

↑ Back to top

Restrict a Select Many Field to One Check Box

To stop a user from selecting more than one check box on a Select Many - Checkboxes field, add an onclick event to the Custom HTML Tag section of the custom field:

1. Navigate to the Select Many - Checkboxes custom field. See the Access the Configuration Page for Custom Fields section of the Configure Custom Fields article.
2. Click the Classic Options tab.

3. Click the Custom HTML Tag field and enter:

   onclick="onlyonechecked(this)"

4. Click Save.

When onlyonechecked is used on a Select Many - Checkboxes field that also shows or hides a header, use _showhideheader instead of _showhideheadercheckbox.

↑ Back to top

Select Check Boxes by Default

To select one or more check boxes by default, create a Special - Browser Script custom field that checks the boxes when the page loads.

Example

This example checks the 2nd and 4th options for Custom Field 568279 on new records.

var oldonload = window.onload;
if (typeof window.onload != 'function') window.onload = newonload;
else {
  window.onload = function() {
    oldonload();
    newonload();
  }
}
function newonload() {
  var frm = document.form1;
  if (frm) {
    if (frm.opportunityid.value == 0) {
      frm.cf_568279[2].checked = true;
      frm.cf_568279[4].checked = true;
    }
  }
}

At Level 2 or Level 3, use document.frmevent instead of document.form1 and eventid instead of opportunityid.

↑ Back to top

Convert Field Text to Uppercase or Lowercase

To change the case of text entered in a custom field, add an event handler to the Custom HTML Tag box in the field settings.

To convert entered text to uppercase:

onChange="this.value=this.value.toUpperCase();"

To convert entered text to lowercase:

onChange="this.value=this.value.toLowerCase();"

The code runs as soon as the user enters a value and clicks outside the field, even before saving. Use onblur instead of onchange to run the code when focus leaves the field:

onblur="this.value=this.value.toUpperCase()"

• onblur runs when focus leaves the field.
• onchange runs when the field content changes.

↑ Back to top

Remove Special Characters from a Field

To stop users from entering special characters in a custom field, add a replace expression to the Custom HTML Tag box. Special characters can cause problems when data is exported to other systems.

onchange="this.value=this.value.replace(/[Search Expression]/flag,'New String');"

In this pattern, Search Expression is the characters to match, flag is the matching option, and New String is the replacement text. The examples in this section use these options:

• \W matches any character that is not a basic Latin letter, digit, or underscore.
• \D matches any character that is not a digit.
• g is a global match.

Use onkeyup instead of onchange to replace characters as the user types.

Example

This example replaces anything that is not a letter or number with an underscore:

onkeyup="this.value=this.value.replace(/[\W]/g,'_');"

Example

This example restricts a field to integers only:

onkeyup="this.value=this.value.replace(/[\D]/g,'');"

↑ Back to top

Set or Clear Default Dates

Use a Special - Browser Script custom field or a Computed - Calculated Value custom field to control default dates on a record.

Clear the Default End Date at Level 1

By default, the end date for a Level 1 record is set to the start date. To control it, use a Special - Browser Script field.

To clear the default end date at Level 1:

1. Create a Special - Browser Script custom field. See the Access the Configuration Page for Custom Fields section of the Configure Custom Fields article.

2. Click the Custom Script field and enter the following JavaScript:

   function changeEndDate() {
     var frm = document.form1;
     if (frm.opportunityid.value == 0)
       frm.enddate.value = '';
   }
   changeEndDate();

   • opportunityid is 0 for a Level 1 record before it is saved.
   • For a new record (value 0), the end date is cleared.
   • The same approach can set the end date to another value, such as the start date plus 60 days.

↑ Back to top

Clear Dates at Level 2 and Level 3

At Level 2, clear the start date:

function changeStartDate() {
  var frm = document.frmevent;
  if (frm.eventid.value == 0) frm.startdate.value = '';
}
changeStartDate();

At Level 3, clear the end date:

function changeEndDate() {
  var frm = document.frmevent;
  if (frm.eventid.value == 0)
    frm.enddate.value = '';
}
changeEndDate();

↑ Back to top

Add Business Days Based on a Drop-Down Value

To set a date a number of business days after another date, where the number depends on a drop-down value, create a Computed - Calculated Value custom field with an expression like the following.

Example

Where the date is a custom field with a Custom Field ID of 12345 and the drop-down is named Client Category:

[Client Category]=='Regular'?busdateadd(frm.cf_12345.value,10):[Client Category]=='Under Investigation'?busdateadd(frm.cf_12345.value,5):[Client Category]=='Special'?busdateadd(frm.cf_12345.value,30):'0000-00-00'

Example

Where the date is the standard Start Date field and the drop-down is named Time Line:

[Time Line]=='Regular'?busdateadd(frm.startdate.value,10):[Time Line]=='Under Investigation'?busdateadd(frm.startdate.value,5):[Time Line]=='Special'?busdateadd(frm.startdate.value,30):'0000-00-00'

• If the drop-down value is Regular, the result is 10 business days after the date.
• If the value is Under Investigation, the result is 5 business days after the date.
• If the value is Special, the result is 30 business days after the date.
• If the value matches none of these, the result is 0000-00-00.

The busdateadd function has the syntax busdateadd(datefield, business days to add). The datefield value can be a standard field or a custom field. The function excludes Saturday, Sunday, and Canadian public holidays (not banking holidays) and is not connected to any SmartSimple calendar.

↑ Back to top

Change the Record Owner by Status

This Browser Script sets the owner to the person editing the Level 1 record, based on status:

New syntax

function changeOwner() {
  var frm = document.form1;
  if (frm.stageid.value == '1829') {
    frm.ownerid.value = {{me.userid}};
  }
}
changeOwner();

Old syntax

function changeOwner() {
  var frm = document.form1;
  if (frm.stageid.value == '1829') {
    frm.ownerid.value = @me.userid@;
  }
}
changeOwner();

stageid is the status, here the web status. The script sets ownerid to the current user. To set a fixed owner, hard-code the user ID, for example frm.ownerid.value = userid, where userid is the actual ID of the user.

↑ Back to top

Change a Record Status from a Web Page View

To change the status of the related record from a Web Page View, use the following.

At Level 1:

document.getElementById("obj.fd_stageid").value = "8885";

At Level 2:

document.getElementById("obj.fd_statusid").value = "8885";

8885 is the ID of the status to set.

↑ Back to top

Pass Values Between Pages with Parameters

Values, known as parameters, can pass from one page to another to pre-populate form fields or display information on a page.

Scripts that read URL parameters can also break when the configuration changes. For example, if a field is no longer needed, the script must be updated to exclude that field. This is especially true when the script does not account for missing values.

Configure the Sending Page

Build a link to the destination page that includes the parameters:

New syntax

/urltopage?var1={{variable1}}&var2={{variable2}}

Old syntax

/urltopage?var1=@variable1@&var2=@variable2@

urltopage is the relative URL to the destination page. variable1 and variable2 are SmartSimple variables, such as {{firstname}} (@firstname@ in the old syntax). var1 and var2 are the parameter names. SmartSimple replaces the variable references with values from the current user session.

Add the link to a portal shortcut, a button, or a hyperlink. For a button, use a Read Only - System Variables field with:

New syntax

<input type="button" class=Button value="Button Label" onClick='parent.location.href="/urltopage?var1={{variable1}}&var2={{variable2}}"'/>

Old syntax

<input type="button" class=Button value="Button Label" onClick='parent.location.href="/urltopage?var1=@variable1@&var2=@variable2@"'/>

For a hyperlink, use:

New syntax

<a href="/urltopage?var1={{variable1}}&var2={{variable2}}">Link Text</a>

Old syntax

<a href="/urltopage?var1=@variable1@&var2=@variable2@">Link Text</a>

• User and company variables can pass details of the logged-in user and their organization.

↑ Back to top

Configure the Receiving Page

Add a population script just before the closing body tag to fill a form field or HTML element with the parameter values:

<script>
(function () {
  var params = new URLSearchParams(window.location.search);

  var para1 = document.getElementById('field1');
  if (para1 && params.has('var1')) {
    para1.value = params.get('var1');
  }

  var para2 = document.getElementById('field2');
  if (para2 && params.has('var2')) {
    para2.value = params.get('var2');
  }
})();
</script>

Replace field1 and field2 with the actual field or element IDs, and var1 and var2 with the parameter names. The checks on para1, para2, and params.has() keep the script from failing when a field or parameter is missing.

↑ Back to top

Create a Button to Generate a Level 1 Record

System administrators can add a button that lets users create Level 1 records on demand.

To add a button that creates a Level 1 record:

1. Create a Display - Text and Variables custom field. See the Access the Configuration Page for Custom Fields section of the Configure Custom Fields article.

2. Click the Content field and enter:

   <script language=javascript>
   function createNewLevel1() {
     location.href = "/Apps/app_editopportunity.jsp?appid=12345&nextlevel=1&opportunityid=0&defaultstatusid=52525&opportunitytypeid=121212";
   }
   </script>
   <input type="button" class=Button value="Button Label" onClick="createNewLevel1()">

• appid is the ID of the UTA/module in which the Level 1 record is created.
• defaultstatusid is the status ID for the new record. If omitted, the default status applies.
• opportunitytypeid is the template ID for the new record. If omitted, the default template applies.
• opportunityid=0 creates a new, blank Level 1 record.
• Button Label is the text shown on the button, such as Create New Grant.
• defaultownerid can set the owner of the new record to the contact with a matching user ID.

If the link uses variables, place the script in the onClick so the variables parse correctly in a list view:

New syntax

<input type="button" class=Button value="Button Label" onClick="location.href='/Apps/app_editopportunity.jsp?appid=12345&nextlevel=1&opportunityid=0&defaultstatusid=52525&opportunitytypeid=121212&defaultownerid={{userid}}'">

Old syntax

<input type="button" class=Button value="Button Label" onClick="location.href='/Apps/app_editopportunity.jsp?appid=12345&nextlevel=1&opportunityid=0&defaultstatusid=52525&opportunitytypeid=121212&defaultownerid=@userid@'">

The Display - Text and Variables custom field can then be referenced in a list view, on a report, or on another Level 1 record.

↑ Back to top

Create a Button to Generate a Level 2 Record

System administrators can add a button that lets users create Level 2 records.

To add a button that creates a Level 2 record:

1. On the Level 1 record, create a Display - Text and Variables custom field. See the Access the Configuration Page for Custom Fields section of the Configure Custom Fields article.

2. Click the Content field and enter:

   New syntax

   <script language=javascript>
   function createNewLevel2() {
     location.href = "/Apps/app_editevent.jsp?appid={{apptype}}&islevel2=1&objecttype=23&nextlevel=1&companyid={{companyid}}&objectid={{opportunityid}}&eventid=0";
   }
   </script>
   <input type="button" class=Button value="Button Label" onClick="createNewLevel2()">

   Old syntax

   <script language=javascript>
   function createNewLevel2() {
     location.href = "/Apps/app_editevent.jsp?appid=@apptype@&islevel2=1&objecttype=23&nextlevel=1&companyid=@companyid@&objectid=@opportunityid@&eventid=0";
   }
   </script>
   <input type="button" class=Button value="Button Label" onClick="createNewLevel2()">

• appid is the ID of the UTA/module in which the Level 2 record is created.
• companyid links the organization from the Level 1 record to the new Level 2 record.
• objectid links the new Level 2 record to the Level 1 record where the button was used.
• eventid=0 creates a new, blank Level 2 record.
• Button Label is the text shown on the button, such as Create New Activity.
• defaultstatusid sets the status and eventtypeid sets the type. If omitted, the defaults apply.

↑ Back to top

Control the Save and Submit Buttons in a UTA/Module Level 1 Template

To let only certain roles submit a Level 1 template while other roles can still save it, control the Save and Submit buttons with JavaScript.

To control the Save and Submit buttons on a UTA/module Level 1 template:

1. If present, remove @SYSTEMBUTTONS@ from the template page.

2. Add the JavaScript below the fields reference (@APPFIELDS@) on the template page. Update the role IDs to match the roles to manage:

   @APPFIELDS@
   <center>
   <input type=submit id=savedraftbutton value='Save Draft' onClick="this.form.butaction.value=1;" class=Button>
   <script language='javascript'>
   var m_utaroleids = "@UTAROLEIDS@";
   var m_showsave = true;
   var m_showsubmit = false;
   var subpage = "ex_apppage_save.jsp";
   if (m_utaroleids.indexOf(',5659,') > -1 || m_utaroleids.indexOf(',5036,') > -1 || m_utaroleids.indexOf(',3291,') > -1)
     m_showsave = true;
   if (m_utaroleids.indexOf(',5659,') > -1)
     m_showsubmit = true;
   if (m_showsave)
     document.write("<input type=submit id=savebutton value='Save' onClick='this.form.butaction.value=0;' class=Button> ");
   if (m_showsubmit)
     document.write("<input type=submit id=submitbutton value='Submit EOI' onClick='this.form.butaction.value=2;this.form.action=subpage' class=Button> ");
   document.close();
   </script>
   </center>

In this example, three roles can save, but only role 5659 can submit. Adjust the role IDs and button labels to match the configuration.

↑ Back to top