ECExpressions
ECExpressions is a very basic language that allows customizing presentation rules' behavior.
Symbols that can be used depend on current context. Example:
this.GetContextB().ContextC.DoSomething()
Here, symbol this
returns a context which has a function symbol
GetContextB()
. This function returns a context which has a property
symbol ContextC
. And the property value is a context that contains a
function symbol DoSomething()
. The latter function might return some value
or return nothing, but instead do some action - it all depends on the symbol.
ECExpression syntax
Data types
ECExpressions
contain values of primitive types or data type of ECClass
or ECArray
.
Primitive value types
Type | Description | Example |
---|---|---|
Boolean | Boolean (true/false) value | True , False |
DateTime | Date and time in ticks | @1549278124937 |
Integer (Long) | 32-bit (64-bit) number | 1 |
Double | Floating point number | 6.84 |
String | String of characters | "" ,"Dog and Cat" |
Null | Null value | Null |
Other primitive types
Type | Description |
---|---|
Binary | Array of bytes |
Point2d | 2D point containing X and Y components as double values |
Point3d | 3D point containing X, Y and Z components as double values |
IGeometry | A common geometry value of any type |
ECClass data type
ECClass
data types define ECInstances
. ECClasses
contain ECProperties
and Methods which can be accessed via dot (.
) operator.
ECArray data type
ECArray
data types define arrays of values. Each value can be accessed via []
operator.
Expression components
In addition to values of primitive types ECExpressions
may contain symbols and operators
Symbols
Symbols are used to supply values to expression evaluator. Symbols can be supplied from ECInstance
via an access string, from an application defined value or from application defined method.
Access string is a limited expression that holds no blanks, no operators, and no variable portions. It may contain array indexing and member selection using []
or dot .
operators, but no part of the expression can be variable, and the access string cannot contain embedded blanks.
Property symbols
ECInstance
Property symbols supply Property values of some ECInstance
when the symbol is being evaluated.
this.PropertyName
this.StructPropertyName.PropertyName
this.StructArray[5].Struct.PropertyName
Value symbols
Value symbols supply some named predefined value in a context.
System.Math.PI
Method symbols
Method symbols supply a named method in a context.
System.Math.Sin(1.57)
this.IsOfClass("ClassName", "SchemaName")
Value lists
Value lists in ECExpressions are iterable containers and can be handled with lambdas. Currently presentation rules
engine supports only a single simple lambda for value lists, AnyMatches
, which checks if any of the items in the value list passes given condition. Examples:
value_list.AnyMatches(x => x = this.PropertyValue)
value_list.AnyMatches(x => this.PropertyValue = x)
value_list.AnyMatches(x => this.IsOfClass(x.PropertyValue))
Operators
Parentheses (
,)
(2 * (3 + 4))
Logical operators
Description | Operator |
---|---|
Conjunction | And *, AndAlso |
Disjunction | Or *, OrElse |
Exclusive disjunction | Xor |
Negation | Not |
Note: *Checks right side of expression even if result value can be deducted from the left side.
False And True OrElse True
Comparison operators
Description | Operator |
---|---|
Less than | < |
Less than or equal to | <= |
Greater than | > |
Greater than or equal to | >= |
Equal to | = |
Not equal to | <> |
20 < 10 ==> False
Arithmetic operators
Description | Operator |
---|---|
Exponentation | ^ |
Multiplication | * |
Double division | / |
Integer division | \ |
Modular division | Mod |
Addition | + |
Subtraction | - |
1 + "4" ==> 5
2.2 * 3 ==> 6.6
12 / 5 ==> 2.4
12 \ 5 ==> 2
25 Mod 3 ==> 1
Bit shift operators
Description | Operator |
---|---|
Signed shift left | << |
Signed shift right | >> |
Unsigned shift right | >>> |
5 << 1 ==> 10
24 >> 2 ==> 6
-105 >> 1 ==> -53
-105 >>> 1 ==> 75
Conditional operator
IIf (condition, true-result, false-result)
Returns result based on given condition. If condition evaluates to true, returns true-result
. Otherwise returns false-result
.
IIf (500>200, "Math ok", "Math wrong") ==> "Math ok"
IIf (500<200, "Math ok", "Math wrong") ==> "Math wrong"
Concatenation operator
"Dog" & " and " & "Cat" ==> "Dog and Cat"
"1" & 4 ==> "14"
1 & "4" ==> "14"
Lambda operator
Lambda operator =>
creates a callback expression for a given symbol.
MyArray.Find(item => item.IntProperty = 5)
Combined expressions
System.Math.Cos (System.Math.PI * 45.0 / 180.0) ==> 0.707
System.String.Length ("Dog" & " and " & "Cat") ==> 11
Evaluating if property is Null
Method IsNull (value)
evaluates if given value is Null
.
Method IfNull (value, value-if-null)
evaluates to value
if it is not null, otherwise evaluates to value-if-null
.
In case this.MiddleName
is null:
IfNull (this.MiddleName, "") ==> ""
IIf (Not IsNull(this.MiddleName), " " & this.MiddleName & " ", "") ==> ""
In case this.MiddleName
is set to "Harvey"
IfNull (this.MiddleName, "") ==> "Harvey"
IIf (Not IsNull (this.MiddleName), " " & this.MiddleName & " ", "") ==> " Harvey "
Checking to see if a this.MiddleName
is Null
or empty
IIf (IsNull (this.MiddleName) or this.MiddleName = "", "Is null or empty", "Has a value")
ECExpression contexts
NavNode
Symbol | Type | Value |
---|---|---|
IsNull |
bool | Is this context null |
Type |
string | Type of the node |
Label |
string | Node label |
Description |
string | Node description |
ClassName |
string | ECClass name if its an EC-related node |
ClassLabel |
string | ECClass display label if its an EC-related node |
SchemaName |
string | ECSchema name if its an EC-related node |
SchemaLabel |
string | ECSchema display label if its an EC-related node |
SchemaMajorVersion |
number | ECSchema major version if its an EC-related node |
SchemaMinorVersion |
number | ECSchema minor version if its an EC-related node |
InstanceId |
number | ECInstance ID if its an ECInstance node |
IsInstanceNode |
bool | Is this an ECInstance node |
IsClassGroupingNode |
bool | Is this an ECClass grouping node |
IsPropertyGroupingNode |
bool | Is this an ECProperty grouping node |
GroupedInstancesCount |
number | Count of grouped ECInstances (only available for ECClass and ECProperty grouping nodes) |
ECInstance |
ECInstance context | ECInstance symbol context if its an ECInstance node |
HasChildren |
bool | Does this node have any children |
ChildrenArtifacts |
object[] | A value list of objects generated using the NodeArtifacts customization rule on child nodes. Child nodes in this case are immediate child nodes that are not necessarily visible. |
ECInstance
ECInstance expression context provides access to ECInstance property values. Example:
this.PropertyName
this.StructPropertyName.PropertyName
this.StructArray[1].Struct.PropertyName
Additionally, when evaluating ECInstance contexts, the below symbols are available:
Symbol | Type | Value |
---|---|---|
GetRelatedDisplayLabel("RelationshipSchemaName:RelationshipName", "Forward|Backward", "RelatedClassSchemaName:RelatedClassName") |
string | Returns display label of the related instance |
GetRelatedInstancesCount("RelationshipSchemaName:RelationshipName", "Forward|Backward", "RelatedClassSchemaName:RelatedClassName") |
number | Number of related instances following the specified relationship |
GetRelatedInstancesCount("RelatedClassSchemaName:RelatedClassName", lambda_for_filtering_related_instances) |
number | Number of related instances that match criteria described by given lambda |
HasRelatedInstance("RelationshipSchemaName:RelationshipName", "Forward|Backward", "RelatedClassSchemaName:RelatedClassName") |
bool | Does this instance has a related instance following the specified relationship |
HasRelatedInstance("RelatedClassSchemaName:RelatedClassName", lambda_for_filtering_related_instances) |
bool | Does this instance has a related instance that matches criteria described by given lambda |
GetRelatedValue("RelationshipSchemaName:RelationshipName", "Forward|Backward", "RelatedClassSchemaName:RelatedClassName", "PropertyName") |
any | Returns property value of the related instance |
GetRelatedValue("RelatedClassSchemaName:RelatedClassName", lambda_for_filtering_related_instances, "PropertyName") |
any | Returns property value of related instance that matches criteria described by given lambda |
IsOfClass("SchemaName", "ClassName")) |
bool | Returns true if the instance is of a class with given schema and class names |
IsOfClass(SomeECClassId)) |
bool | Returns true if the instance is of a class with specified ECClass ID |
Deprecated symbols:
Symbol | Type | Value |
---|---|---|
GetRelatedInstance("RelationshipName:0|1:RelatedClassName") |
ECInstance context | Returns related instance context. Not available when evaluating instance filters. |
ECInstance key
ECInstance key expression context provides access to class and instance IDs. The context has the following symbols:
Symbol | Type | Value |
---|---|---|
ECClassId |
number | ID of ECInstance's ECClass |
ECInstanceId |
number | ID of ECInstance |
Symbols in global context
Ruleset variables (user settings)
Note: User Settings is a deprecated name of Ruleset Variables concept.
Ruleset variable access symbols allow accessing variable values through ECExpressions.
Symbol | Deprecated Symbol | Type | Value |
---|---|---|---|
GetVariableStringValue("var_id") |
GetSettingValue("var_id") |
string | Get string value of a variable with the specified ID |
GetVariableBoolValue("var_id") |
GetSettingBoolValue("var_id") |
bool | Get boolean value of a variable with the specified ID |
GetVariableIntValue("var_id") |
GetSettingIntValue("var_id") |
number | Get int value of a variable with the specified ID |
GetVariableIntValues("var_id") |
GetSettingIntValues("var_id") |
number[] | Get int value list of a variable with the specified ID |
HasVariable("var_id") |
HasSetting("var_id") |
bool | Does variable with the specified ID exist |
Other symbols
Symbol | Type | Value |
---|---|---|
Set(number1, number2, ..., numberN) |
number[] | Create a value list of the supplied numbers. |
GetFormattedValue(this.MyProp, "Metric|UsCustomary|UsSurvey|BritishImperial") |
any | Returns property value formatted using specified unit system. If unit system is not specified default presentation units are used to format value |
Formatted property values
Comparison of formatted property values in ECExpressions can be done using
GetFormattedValue
function. Specific unit system can be passed as a second argument
to function or omitted to use default presentation format:
GetFormattedValue(this.Length, "Metric") = "10.0 m"
GetFormattedValue(this.Length) = "10.0 m"
Last Updated: 04 October, 2024