Using User Code

To provide full code generation flexibility. It is allowed to override an existing code generating function or create your own custom code generating function to suit your needs. To do this you need to write your JavaScript functions and place them in the User Code File for the changes to take effect.

By default, the User Code File is named as "usercode.js" and can be found under the "src" subfolder of the installed directory. However, you can rename it or put it elsewhere if necessary. In that case, you need to modify the following registry key:

HKEY_CURRENT_USER\Software\<product name>\<version>\Settings\General
Value name: UserCode

Note
Using User Code requires knowledge in JavaScript. If you are not familiar with the scripting language, refer to the JavaScript Fundamentals and JavaScript Reference. In most cases you only need to use the most basic string functions.

I. Overriding System Function

In the User Code File, you can override virtually all exposed functions. Refer to the System Functions list for functions that you can override.

Although there are many system functions, in real applications you usually only need to customize a few of them, for example,

Script_View - This function generates code to render the fields in list, view and delete pages.
Script_Edit - This function generates insert/update codes for the fields in add/copy and edit pages.
FieldView - This function outputs code for displaying the field in list, view and delete pages.
FieldEdit - This function outputs code for the field as form elements in add/copy, edit and search pages.

In general, you compare the generated codes with the corresponding page in the template, find out which tag generate the codes you want to customize. Then you can call the replace or concat method of the system function in the User Code File. Both mehtod is same as the JavaScript replace and concat methods.

where <Function> is the system function name.

Follow the following steps to override a system function. For example, if you want to override the function FieldView,

Step 1 - View the original code first, make sure the codes you want to replace is indeed generated by the function.

Example

Step 2 - Generate scripts, view the generated code, copy the code you want to replace, modify it as you need.

Step 3 - Replace it.

Example 1 - Directly replace part of the code

SYSTEMFUNCTIONS.FieldView.replace(<old_code>, "new_code"); // Replace part of the code

<old_code> can be a string or regular expression.

Example 2 - Find the part of code to be replaced and then modify and replace it

var OriginalCode = SYSTEMFUNCTIONS.FieldView.result;
var StartPos = OriginalCode.indexOf("start_code"); // Find the start position of the old code
var EndPos = OriginalCode.indexOf("end_code", StartPos); // Find the end position of the old code
if (StartPos > -1 && EndPos > -1 && EndPos > StartPos) { // Found
    var OldCode = OriginalCode.substring(StartPos, EndPos + "end_code".length); // Extract the code starting with "start_code" and ends with "end_code"
    var NewCode = ...OldCode...; // Write your code to modify the old code as you need
    SYSTEMFUNCTIONS.FieldView.replace(OldCode, NewCode); // Replace the old code
}

Example 3 - Append your code to the end of the original code

SYSTEMFUNCTIONS.<function>.concat("<code_1>", "<code_2>", ...);

Example 4 - Use your own function to modify the code. Add your function to the System Function's modifiers which is an array of functions, you can add as many modifier functions as you need.

SYSTEMFUNCTIONS.FieldView.modifiers.push(function() {
    var oldvalue = this.result; // Get old value
    alert(oldvalue); // View the old value
    var newvalue = <your code here>; // Modify the oldvalue or write your own code
    this.result = newvalue; // Overwrite value
});

II. User functions used in Extensions

The user functions used in Extensions must take the following form:

var <Ext> = {

  FieldEdit_Prefix: function(ctl, ctlid) {
    return "...";
  }

  FieldEdit_Suffix: function(ctl, ctlid) {
    return "...";
  }

}

It is a user object with name <Ext> which should be the same as the extension name. It contains two methods "FieldEdit_Prefix" and "FieldEdit_Suffix". The "FieldEdit_Prefix" method returns a prefix value which is appended to the start of the output from the "FieldEdit" system function. Similarly, the "FieldEdit_Suffix" method returns a suffix value which is appended to the end of the output from the "FieldEdit" system function. Both methods take on a parameter "ctl" which contains the name of the field control to be created. The parameter "ctlid" contains an ID which denotes the mode of the control, e.g. "add", "edit", etc.. (See usercode.js in the "jscalendar" and "fckeditor" extensions as examples.)

Also See:

Customizing Template
Template Tags
Template Object Properties
System Functions