entitySelection.orderByFormula( )

Home

4D v19.8


entitySelection.orderByFormula ( formula {; sortOrder}{; settings} ) -> Result

Parameter	Type	Description
formula	Text, Object	Formula string, or Formula object
sortOrder	Longint	dk ascending (default) or dk descending
settings	Object	Parameter(s) for the formula
Result	EntitySelection	New ordered entity selection

Description

The entitySelection.orderByFormula( ) method returns a new, ordered entity selection containing all entities of the entity selection in the order defined through the formula and, optionnally, sortOrder and settings parameters.

Note: This method does not modify the original entity selection.

In the formula parameter, you can pass either a text or an object:

text: a 4D expression such as "Year of(this.birthDate)"
object: a valid formula object created using the Formula or Formula from string command.

The formula is executed for each entity of the entity selection and its result is used to define the position of the entity in the returned entity selection. The result must be of a sortable type (boolean, date, number, text, time, null).

Note: A null result is always the smallest value.

By default if you omit the sortOrder parameter, the resulting entity selection is sorted in ascending order. Optionnally, you can pass one of the following values in the sortOrder parameter:

Constant	Value	Comment
dk ascending	0	Ascending sort order (default)
dk descending	1	Descending sort order

Within the formula, the processed entity and thus its attributes are available through the This command (for example, This.lastName).

You can pass parameter(s) to the formula using the args property (object) of the settings parameter: formula receives the settings.args object in $1.

Example 1

Sorting students using a formula provided as text:

 C_OBJECT($es1;$es2)

 $es1:=ds.Students.query("nationality=:1";"French")

 $es2:=$es1.orderByFormula("length(this.lastname)") //ascending by default

 $es2:=$es1.orderByFormula("length(this.lastname)";dk descending)

Same sort order but using a formula object:

 C_OBJECT($es1;$es2;$formula)

 $es1:=ds.Students.query("nationality=:1";"French")

 $formula:=Formula(Length(This.lastname))

 $es2:=$es1.orderByFormula($formula) // ascending by default

 $es2:=$es1.orderByFormula($formula;dk descending)

Example 2

A formula is given as a formula object with parameters; settings.args object is received as $1 in the computeAverage method.

In this example, the marks object field in the Students dataClass contains students' grades for each subject. A single formula object is used to compute a student's average grade with different coefficients for schoolA and schoolB.

 C_OBJECT($es1;$es2;$formula;$schoolA;$schoolB)

 $es1:=ds.Students.query("nationality=:1";"French")

 $formula:=Formula(computeAverage($1))

 

 $schoolA:=New object() //settings object

 $schoolA.args:=New object("english";1;"math";1;"history";1) // Coefficients to compute an average

 

  //Order students according to school A criteria

 $es2:=$es1.entitySelection.orderByFormula($formula;$schoolA)

 

 $schoolB:=New object() //settings object

 $schoolB.args:=New object("english";1;"math";2;"history";3) // Coefficients to compute an average

 

  //Order students according to school B criteria

 $es2:=$es1.entitySelection.orderByFormula($formula;dk descending;$schoolB)

  //

  // computeAverage method

  // -----------------------------

 C_TEXT($subject)

 C_LONGINT($0;$average;$sum)

 C_OBJECT($coefList;$1)

 

 $coefList:=$1

 $average:=0

 $sum:=0

 

 For each($subject;$coefList)

    $sum:=$sum+$coefList[$subject]

 End for each

 

 For each($subject;This.marks)

    $average:=$average+(This.marks[$subject]*$coefList[$subject])

 End for each

 

 $0:=$average/$sum