Project method references

4D View Pro allows you to call 4D project methods from within your formulas. Using 4D project methods extends the possibilities of your 4D View Pro documents. 4D methods can receive parameters from the 4D View Pro area, and return values. For security reasons, only methods that have been explicitly allowed can be called by the user.

To be called in a 4D View Pro formula, a project method must be:

• Allowed: it was explicitly declared using the VP SET ALLOWED METHODS command.
• Runnable: it belongs to the host database or a loaded component with the "Shared by components and host database" option enabled (see Sharing of project methods).
• Not in conflict with an existing 4D View Pro function: if you call a project method with the same name as a 4D View Pro built-in function, the function is called.

Note: If the VP SET ALLOWED METHODS command has never been executed during the session, 4D View Pro custom functions rely on allowed methods defined by 4D's generic SET ALLOWED METHODS command. In this case, the project method names must comply with JavaScript Identifier Grammar (see ECMA Script standard). The global filtering option in the Settings dialog box (see Data Access) is ignored in all cases.

We want to print "Hello World" in a 4D View Pro area cell using a 4D project method:

1. Create a "myMethod" project method with the following code:
   
    C_TEXT($0)
 $0:="Hello World"
2. Execute the following code before opening any form that contains a 4D View Pro area (for example in the On Startup database method):
   
    C_OBJECT($allowed;VPHello)
 $allowed:=New object
 $allowed.VPHello:=New object
 $allowed.VPHello.method:="myMethod"
 $allowed.VPHello.summary:="VPHello prints Hello World" //optional
 VP SET ALLOWED METHODS($allowed)
3. Edit the content of a cell in a 4D View Pro area and type:
   
   "myMethod" is then called by 4D and the cell displays:
   

Parameters can be passed to 4D project methods using the following syntax:

These parameters are received in methodName in $1, $2...$N.

Note that the ( ) are mandatory, even if no parameters are passed:

You can declare the name, type, and number of parameters through the parameters collection of the function you declared using the VP SET ALLOWED METHODS command. Optionally, you can control the number of parameters passed by the user through minParams and maxParams properties. Example:

For more information on supported incoming parameter types, please refer to the VP SET ALLOWED METHODS command description. 

Note: If you do not declare parameters, values can be sequentially passed to methods (they will be received in $1, $2...) and their type will be automatically converted. Dates in jstype will be passed as C_OBJECT in 4D methods with two properties:

4D project methods can also return values in the 4D View Pro cell formula via $0. The following data types are supported for returned parameters:

• C_TEXT (converted to string in 4D View Pro)
• C_REAL/C_LONGINT (converted to number in 4D View Pro)
• C_DATE (converted to JS Date type in 4D View Pro - hour, minute, sec = 0)
• C_TIME (converted to JS Date type in 4D View Pro - date in base date, i.e. 12/30/1899)
• C_BOOLEAN (converted to bool in 4D View Pro)
• C_PICTURE (jpg,png,gif,bmp,svg other types converted into png) creates a URI (data:image/png;base64,xxxx) and then used as the background in 4D View Pro in the cell where the formula is executed
• C_OBJECT with the following two properties (allowing passing a date and time):
  

  Property	Type	Description
  value	Date	Date value
  time	Real	Time in seconds

If the 4D method returns nothing, an empty string is automatically returned.

An error is returned in the 4D View Pro cell if:

• the 4D method returns another type other than those listed above,
• an error occurred during 4D method execution (when user click on "abort" button).