Managing expressions

Home

4D v18

Overview

4D Write Pro documents can contain references to dynamic 4D expressions such as variables, fields, formulas, project methods, or 4D commands. Specific variables such as the page number can also be referenced (see Inserting document and page expressions below).

Expressions are inserted in 4D Write Pro areas using the ST INSERT EXPRESSION command. They can be read using the ST Get expression command but are also returned by WP Get text and ST Get plain text commands.

Allowed expressions (see below) are evaluated when they are inserted, when the documents are displayed, printed, or when the ST COMPUTE EXPRESSIONS command is called. They become static values if you call the ST FREEZE EXPRESSIONS command (except for $wp_pageNumber and $wp_pageCount variables, see below).

Example

You want to replace the selection in a 4D Write Pro area with the contents of a variable:

 C_TEXT(fullName)

 fullName:="John Smith"

 Case of

    :(Form event code=On Clicked)

       ST INSERT EXPRESSION(myArea;"fullName";ST Start highlight;ST End highlight)

 End case

Support of standard 4D filtering feature

For security reasons, evaluation of project methods and 4D commands inserted in 4D Write Pro documents must be controlled by the developer to make sure that no inappropriate expression is used and that it will not generate any unexpected changes or side effects in the database. This prevents you from executing commands such as DELETE SELECTION or methods like "DeleteOrders".

Use the regular 4D filtering option defined at the database level. This option is located on the Security page of the "Database Settings" dialog box:

By default in 4D, this option is Enabled for all, which means that commands and methods must be explicitly allowed; otherwise evaluation errors are returned. You can disable this filtering partially (for the Designer and the Administrator), or for all users. This option is used in the entire 4D database and controls all user formula evaluations. For more information about this option, please refer to the Design Reference manual.

When the option is enabled:

users can only call commands belonging to the "formula compliant" list. This list is displayed in the right-hand part of the Formula editor:
users cannot execute any project method. Project methods that you want to allow in 4D Write Pro documents must be explicitly declared using the SET ALLOWED METHODS command.

Whenever a "forbidden" 4D method or command is found during the evaluation of an expression in a 4D Write Pro document, the value is replaced by " ## Error # 48".

Example

You inserted the following expression in your 4D Write Pro document:

ST INSERT EXPRESSION(*;"WriteProArea";"Gender")

By default if the security option is checked, the Gender method will not be evaluated:

If you execute the following code:

 ARRAY TEXT(aTallow;1)

 aTallow{1}:="Gender"

 SET ALLOWED METHODS(aTallow)

The Gender method will be evaluated and return a value:

Compatibility

This filtering was not enabled for 4D Write Pro documents in previous releases. If your 4D Write Pro documents were referencing 4D methods, they will no longer be evaluated once the database has been converted to 4D v16 or higher. "## Error # 48" messages will be displayed instead.
In this case, you need to add the methods to the approved list using the SET ALLOWED METHODS command.

Inserting document and page expressions

You can insert special expressions related to document attributes or page attributes in any document area (body, header, footer) using the ST INSERT EXPRESSION command.

Expression syntax	Type	Description
$wp_title	Text	Title defined in wk title attribute
$wp_author	Text	Author defined in wk author attribute
$wp_subject	Text	Subject defined in wk subject attribute
$wp_company	Text	Company defined in wk company attribute
$wp_notes	Text	Notes defined in wk notes attribute
$wp_dateCreation	Date	Date creation defined in wk date creation attribute
$wp_dateModified	Date	Date modified defined in wk date modified attribute
$wp_pageNumber	Longint	Page number as it is defined: from the document start (default) or from the section page start if it is defined by section page start. This expression is always dynamic, it is not affected by the ST FREEZE EXPRESSIONS command.
$wp_pageCount	LongInt	Page count: total count of pages. This expression is always dynamic, it is not affected by the ST FREEZE EXPRESSIONS command.

To insert an expression, make sure the cursor is located in the appropriate area (header, footer, or document body) and call the ST INSERT EXPRESSION command. For example, to insert the page number in the selected footer area:

ST INSERT EXPRESSION(*;"4DWPArea";"$wp_pageNumber")

The following document design can be defined, for example:

Support of virtual structure

Table and field expressions inserted in 4D Write Pro documents support the virtual structure definition of the database. The virtual structure exposed to formulas is defined through SET FIELD TITLES(...;*) and SET TABLE TITLES(...;*) commands.

When a virtual structure is defined, references to expressions containing fields display virtual names when the 4D Write Pro document shows references and not values. Commands that handle references expect and use virtual or real names according to the following table:

Command	Virtual structure support
WP Get text	Returns virtual structure names if wk expressions as source option is set in expressions parameter.
ST Get plain text	Returns virtual structure names if ST 4D Expressions as sources option is set in refMode parameter.
ST Get expression	Ignores virtual structure. Always returns real table/field names
ST INSERT EXPRESSION	Ignores virtual structure. Always expects real table/field names

Note: When a document is displayed in "display expressions" mode, references to tables or fields that do not belong to the virtual structure are displayed with "?" characters, for example [VirtualTableName]? when the field is not defined in the virtual structure.