Using User Code

To provide best code generation flexibility, it is possible to override an existing code generating function to suit your needs. To do this you need to write your event listener in JavaScript and place them in the User Code File.

By default, the User Code File is named as "usercode.js" and can be found under the "src" subfolder of the installed directory, e.g. C:\Program Files (x86)\PHPMaker <version>\src. However, you can rename it or put it elsewhere if necessary, just modify the value of the following registry key and specify the full path of your User Code File:

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

 

1. 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,

ScriptView - This function generates code to render the fields in list, view and delete pages.
ScriptEdit - 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 code with the corresponding page in the template, find out which function generate the code you want to customize. Then you can modify the generated code outputted by the system function by adding a listener to the function:

where <SystemFunction> is the system function name.

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

ewEvent.on("FieldView", (args) => {
    //console.log(JSON.stringify(args)); // Output the args as string
    //console.log(args.code); // Output the code only
    Throw(args.code); // Output the code and stop generation
});

 

The Throw() function will throw the code as error message and stop generation so that you can view the code.

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

ewEvent.on("FieldView", (args) => {
    args.code = args.code.replace(<old_code>, "new_code"); // Replace part of the code
});

<old_code> is part of the old code to be replaced, it 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 = args.code;
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
    args.code = args.code.replace(oldCode, newCode); // Replace the old code
}
...

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

...
args.code.concat("<code_1>", "<code_2>", ...);
...

Example 4 - Use your own code

...
args.code = <Your own code>;
...

 

2. BeginGenerate and EndGenerate Events

You can add your listeners for the BeginGenerate and EndGenerate events to do your things before and after generation, e.g.

ewEvent.on("EndGenerate", () => {
    // Your code to do something after generation
});

 

3. 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 *_function.js in the "JSCalendar" and "CKEditor" extensions as examples.)

 

4. Project Settings

You can access the global PROJ object BEFORE generation. The PROJ contains all project settings and you can change them by code.

Example - Add a package to composer.json

PROJ.Require = { "aws/aws-sdk-php": "3.65.1" }; // In JSON format

 

Also See:

Customizing Template
Template Tags
Object Properties
System Functions