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 VBScript 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.vbs" 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 VBScript. If you are not familiar with the scripting language, refer to the VBScript User's Guide and VBScript Language Reference. In most cases you only need to use the most basic string functions.

I. User Code Function Names

In the User Code File, you can override virtually all exposed functions. To override an existing function, you must write your own function in the user code. The function names for overriding functions begin with USER_. The User Code function name is:

Example
To override the existing function Script, you are required to write a User Code function USER_Script(str).

You can refer to the System Functions list for functions that you can override.

II. Overriding System Function

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.

Of course, sometimes you may need to customize other system functions also. 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 add the corresponding user function in the User Code File.

The function is always of the same syntax, only the function name is different:

The function has only one argument - str, it is the original code generated by the code generator. You can manipulate this string to generate codes as you want. In most case, you just find and replace part of the code, you only need to use the most basic VBScript string functions:

InStr - Find the start (and end) position of the code to be modified. Syntax: InStr([start, ]str, find[, compare])
Mid - Extract the part of code to be modified. Syntax: Mid(str, start[, length])
Replace - Replace the code with your modified code. Syntax: Replace(str, find, replacewith[, start[, count[, compare]]])

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

Function USER_FieldView(str)
    MsgBox("FieldView, Field: " & FIELD.FldName & vbCrLf & str) ' View the code to be generated
    USER_FieldView = str
End Function

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

Function USER_FieldView(str)
    USER_FieldView = Replace(str, "old_code", "new_code") ' Replace part of the code
End Function

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

Function USER_FieldView(str)
    Dim OldCode, NewCode, StartPos, EndPos
    USER_FieldView = str
    StartPos = InStr(str, "start_code") ' Find the start position of the old code
    If StartPos > 0 Then EndPos = InStr(StartPos, str, "end_code") ' Find the end position of the old code
    If EndPos > 0 Then
        OldCode = Mid(str, StartPos, EndPos - StartPos + Len("end_code")) ' Extract the code starting with "start_code" and ends with "end_code"
        NewCode = ...OldCode... ' Modify the old code as you need
        USER_FieldView = Replace(str, OldCode, NewCode) ' Replace part of the code
    End If
End Function

III. Creating your own Template Tag

You are not bound by overriding existing system functions, you can create your own Template Tags. More accurately, you write your own code-generating functions, put them in the User Code File so it can be called by Template Tags in any of your templates.

Syntax:

This is same as a normal VBScript function. "arglist" is optional, it is a list of comma-separated variables representing arguments that are passed to the function when it is called. To return your code from the function, assign it to the function name. Any number of such assignments can appear anywhere within the function. Remember to return your code, if no value is assigned to the function name, the function returns a default value: a zero-length string (""). That is, no codes will be generated.

To call the function, use one of the following syntax:

Function Block

Function block output an object property as string or output a string return by a function.

Syntax:

or

Function Block with Indentation

Syntax:

<!--##~USER_FunctionName(arglist)##-->

Example

You can create a user function to check if a field type is numeric, and then use this function in other user function

' Function to check if field type is numeric
Function USER_FieldIsNumeric(fieldtype)
  Select Case fieldtype
    Case adBigInt, adInteger, adSmallInt, adTinyInt, adSingle, adDouble, adNumeric, adCurrency
      USER_FieldIsNumeric = True
    Case Else
      USER_FieldIsNumeric = False
  End Select
End Function

' Function to override Script
Function USER_Script(str)
  Dim wrkstr
  If USER_FieldIsNumeric(FIELD.FldType) Then
    ' manipulate your numeric fields here
  Else
    wrkstr = str
  End If
  USER_Script = wrkstr
End Function

IV. User functions used in Extensions

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

Class <Ext>

  Function FieldEdit_Prefix(ctl)
    ' FieldEdit_Prefix = "..."
  End Function

  Function FieldEdit_Suffix(ctl)
    ' FieldEdit_Prefix = "..."
  End Function

End Class

It is a user class of class name <Ext> which should be the same as the extension name. It must also contain 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. (See usercode.vbs in the "jscalendar" and "fckeditor" extensions as examples.)

Also See:

Customizing Template
Template Tags
Template Object Properties
System Functions