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 Template Tags, in real applications you usually only need to customize a few of them, for example,

<!--##=FieldView##-->

This tag calls the internal FieldView() function and output codes for displaying the field in the scripts.

Of course, sometimes you may need to customize other tags 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 before returning it. In this way, you override the original code generating and generate codes as you want. In most case, you just replace part of the codes with yours.

Practically, you can view the original code first, make sure the codes you want to replace is indeed generated by the tag.

Example 1

Function USER_FieldView(str)
    MsgBox("FieldView, Field: " & FIELD.FldName & vbCrLf & str)
    USER_FieldView = str
End Function

Generate codes, you'll see the original codes for each field. Write down the codes you want to replace.

Then you can replace the codes by editing the function as follows:

Function USER_FieldView(str)
    USER_FieldView = Replace(str, "old_code", "new_code")
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