tsai
/
abp
mirror of https://github.com/abpframework/abp.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Merge pull request #25998 from abpframework/salihozkara/update-lowcode-formula-docs 

Update Low-Code formula documentation
pull/25999/head
Enis Necipoglu 3 days ago
committed by GitHub
parent
f04bf4e4da bf4e406173
commit
987882f0c9
No known key found for this signature in database GPG Key ID: B5690EEEBB952194
2 changed files with 45 additions and 14 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 39
      docs/en/low-code/expression-language.md
  2. 20
      docs/en/low-code/formula-properties.md

39
docs/en/low-code/expression-language.md
View File

@ -7,9 +7,9 @@
# Low-Code Expression Language
The Low-Code expression language is a provider-safe scalar profile used by virtual calculated properties and by the one-time **Formula** option for existing-data backfill. Its syntax is intentionally familiar to Power Fx users, but it is a smaller language designed for server validation and database-provider translation.
The Low-Code expression language is a provider-safe scalar language used by virtual calculated properties and by the one-time **Formula** option for existing-data backfill. It is designed for server validation and database-provider translation.
Expressions are not JavaScript. They cannot contain arbitrary code, SQL, network calls, browser APIs, side effects, or unsupported Power Fx table and record operations.
Expressions are not JavaScript. They cannot contain arbitrary code, SQL, network calls, browser APIs, side effects, or table and record operations.
An expression can contain up to 4096 characters.
@ -45,6 +45,16 @@ If(CustomerId.IsPreferred, Amount * 90%, Amount)
Related paths may also contain quoted identifiers. The Designer loads the available fields for each relationship level and applies the backend's configured maximum traversal depth. Missing related values produce a blank result where the expression is nullable.
### Enum values
Use `EnumType.Value` to return an enum value from a formula. For example, if `InvoiceCount` is a rollup property:
```text
If(InvoiceCount > 0, CustomerType.Customer, CustomerType.Prospect)
```
The Designer suggests enum types and loads their values after you type the dot. The result is inferred as the referenced enum, so there is no separate enum-type setting. All result branches must use values from the same enum type.
## Operators
| Purpose | Operators and forms |
@ -65,11 +75,12 @@ The current scalar profile supports these functions:
| Category | Functions |
| --- | --- |
| Conditional and blank values | `If(condition, trueValue, falseValue)`, `Coalesce(value, fallback)`, `IsBlank(value)` |
| Conditional and blank values | `If(condition, trueValue, falseValue)`, `Coalesce(value, fallback)`, `IsBlank(value)`, `Blank()` |
| Logical | `And(condition1, condition2, ...)`, `Or(condition1, condition2, ...)`, `Not(condition)` |
| Numeric | `Abs(number)`, `Round(number, places)`, `Min(left, right)`, `Max(left, right)` |
| Text | `Lower(text)`, `Upper(text)`, `Trim(text)`, `Len(text)`, `Left(text, length)`, `Right(text, length)`, `Mid(text, start[, length])` |
| Date and time | `Year(value)`, `Month(value)`, `Day(value)`, `Date(year, month, day)`, `DateTime(year, month, day, hour, minute, second[, millisecond])` |
| Numeric | `Abs(number)`, `Round(number, places)`, `Trunc(number)`, `RoundDown(number, places)`, `RoundUp(number, places)`, `Min(left, right)`, `Max(left, right)`, `Mod(number, divisor)` |
| Text | `Lower(text)`, `Upper(text)`, `Trim(text)`, `Len(text)`, `Left(text, length)`, `Right(text, length)`, `Mid(text, start[, length])`, `StartsWith(text, prefix)`, `EndsWith(text, suffix)`, `Contains(text, value)`, `Replace(text, start, characterCount, newText)` |
| Conversion | `Text(value)`, `Value(text)`, `Int(number)`, `Boolean(text)`, `DateValue(text)`, `DateTimeValue(text)` |
| Date and time | `Year(value)`, `Month(value)`, `Day(value)`, `Hour(value)`, `Minute(value)`, `Second(value)`, `Date(year, month, day)`, `DateTime(year, month, day, hour, minute, second)`, `DateAdd(value, days[, "day"])`, `DateDiff(startValue, endValue[, "day"])` |
Examples:
@ -79,11 +90,19 @@ Coalesce(Discount, 0)
Round(UnitPrice * Quantity, 2)
FirstName & " " & LastName
Mid(ProductCode, 2, 3)
Contains(Name, "pro")
Value(UnitPriceText) * Quantity
DateDiff(StartDate, EndDate)
If(InvoiceCount > 0, CustomerType.Customer, CustomerType.Prospect)
```
`Round` uses midpoint-away-from-zero semantics. `Mid` uses a one-based start position. `Date` and `DateTime` require literal numeric components in the provider-neutral profile. Numeric and date literals use invariant syntax; browser and database locale settings do not change their meaning.
`Round` uses midpoint-away-from-zero semantics. `RoundDown` rounds toward zero and `RoundUp` rounds away from zero; their decimal-place argument must be a literal from -6 through 6. `Mid` and `Replace` use a one-based start position. `StartsWith`, `EndsWith`, and `Contains` ignore case.
`Text` accepts numeric or text values. `Value`, `Boolean`, `DateValue`, and `DateTimeValue` parse invariant text; `DateValue` expects `yyyy-MM-dd`, while `DateTimeValue` accepts invariant ISO date-time text. `Int` rounds down to the nearest integer.
Functions from the full Power Fx language that are not listed here are rejected. For example, `Floor`, `Ceiling`, `Concat`, and `Substring` are not aliases for the supported scalar functions.
`Date` and `DateTime` require literal numeric components in the provider-neutral profile. `DateAdd` and `DateDiff` currently support calendar days only; omit the unit or use the literal `"day"`. Calendar calculations follow the Gregorian calendar, including leap years. Numeric and date literals use invariant syntax; browser and database locale settings do not change their meaning.
Functions that are not listed here are rejected. For example, `Floor`, `Ceiling`, `Concat`, and `Substring` are not aliases for the supported scalar functions.
## Local values with `With`
@ -118,7 +137,9 @@ Related-record aggregates are not written inside a formula expression. Create a
## Validation errors
The Designer validates syntax, field and related-field references, function arity and argument types, inferred result type, dependency cycles, server-only exposure, and translation by the active database provider. Validation covers transitive calculated dependencies, not only the expression currently being edited.
Select **Validate** before saving a calculated property. The Designer validates syntax, field and related-field references, function arity and argument types, inferred result type, dependency cycles, server-only exposure, and translation by the active database provider. Validation covers transitive calculated dependencies, not only the expression currently being edited.
When validation succeeds, the action changes to **Save**. Changing the expression or any property setting returns the action to **Validate**, so the saved metadata always matches the validated values.
Common errors include:

20
docs/en/low-code/formula-properties.md
View File

@ -30,9 +30,17 @@ In the Low-Code Designer:
2. Open **Add Property** and select **Calculated Property**.
3. Enter the property name and an optional display name.
4. Enter an expression such as `Round(UnitPrice * Quantity, 2)`.
5. Review the inferred result type and validation result, then select **Create Calculated Property**.
5. Select **Validate** to infer the result type and verify the formula with the active database provider.
6. Configure any settings exposed for the inferred type, such as decimal places or currency symbol, then validate again.
7. When the action changes to **Save**, select it to create the property.
The result type is inferred from the expression. Supported property types are String, Int, Long, Decimal, Money, Boolean, Date, and DateTime. Decimal and Money results can also define display precision, and Money results can define a currency symbol.
The result type is inferred from the expression. Supported property types are String, Int, Long, Decimal, Money, Boolean, Date, DateTime, and Enum. Decimal and Money results can also define display precision, and Money results can define a currency symbol.
Use `EnumType.Value` constants to return an enum value. The referenced enum becomes the inferred result type, so no separate enum selection is required. For example, `InvoiceCount` can be a Count rollup property:
```text
If(InvoiceCount > 0, CustomerType.Customer, CustomerType.Prospect)
```
Formula properties may use both JSON-backed and database-mapped scalar fields. Use dot notation to read a scalar field through a foreign key:
@ -41,7 +49,7 @@ CustomerId.CreditLimit
Round(CustomerId.CreditLimit - CurrentBalance, 2)
```
The formula editor offers fields, related fields, local values, and supported functions as suggestions. See the [Low-Code Expression Language](expression-language.md) reference for the complete scalar syntax.
The formula editor offers fields, related fields, enum values, local values, and supported functions as suggestions. See the [Low-Code Expression Language](expression-language.md) reference for the complete scalar syntax.
Client applications cannot set a calculated property. Enable **Server only** when the result must also be omitted from client-facing metadata and responses. A client-visible formula cannot expose a server-only dependency; a server-only formula may use server-only fields.
@ -82,7 +90,7 @@ This is different from the one-time **Formula** option used to backfill an ordin
## Validation and dependency safety
Before a calculated property is saved, the Designer validates:
Before a calculated property is saved, select **Validate**. The Designer validates:
* syntax, field paths, functions, and argument types
* inferred result type and display metadata
@ -91,12 +99,14 @@ Before a calculated property is saved, the Designer validates:
* server-only dependency exposure
* translation by the active database provider
Successful validation changes the action to **Save**. Editing the name, display name, expression, server-only setting, or inferred-type settings such as decimal places and currency symbol invalidates the validation result and changes the action back to **Validate**.
Saving publishes the calculated metadata only after the complete affected dependency closure passes provider validation. Renaming or deleting fields that are still referenced is guarded so an existing calculation is not silently broken.
Provider-specific translation remains authoritative. An expression that is syntactically valid but cannot be translated by the active provider is rejected instead of falling back to full-table client-side evaluation.
## Current limitations
Formula expressions are scalar. They do not contain arbitrary aggregate subqueries; use a Rollup Property for a supported related-record aggregate. Arbitrary SQL, JavaScript, network calls, browser APIs, side effects, and unsupported Power Fx table or record operations are not allowed.
Formula expressions are scalar. They do not contain arbitrary aggregate subqueries; use a Rollup Property for a supported related-record aggregate. Arbitrary SQL, JavaScript, network calls, browser APIs, side effects, and table or record operations are not allowed.
Related-field access must follow configured foreign keys and stay within the query capability exposed by the backend. Rollups require a source-side Guid foreign key that points to the entity receiving the rollup.

Write Preview
Loading…
Cancel
Save