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 VBScript, download the documentation from Microsoft and learn the basics first:
http://msdn.microsoft.com/library/default.asp?url=/downloads/list/webdev.asp

I. User Code Function Names

In the User Code File, you can override virtually all exposed properties and functions. To override an existing property or function, you must write your own function in the user code. The function names for overriding properties and functions are somewhat different, but they all begin with USER_.

The function name for overriding an object property is:

Example
If you want to override the PROJ.ProjName property, you need to write a User Code function with name USER_PROJ_ProjName(str).

In most cases, you'll want to override an existing function. 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 an existing Template Tag

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

FieldView This function outputs code for displaying the field in report 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 internal 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

Also See:

Template Tags
Template Object Properties
System Functions