Formula functions

Introduction

Formula functions, or simply, Formulas, are expressions that allow you to build algorithms in your app. They follow the same concept as the Excel "spreadsheet" formulas, and borrow the context-aware functionality from them.

With formulas, you can perform any transformation with relevant data such as the device and system info, GPS location, sensor values, data properties and the application state. For instance: calculate a distance between two coordinates, convert date field to a local format, predict future values based on historical data, calculate interest rates on a mortgage, confirm the total price when checking out a shopping cart, and many more.

Formulas are one of the component binding types, meaning that you can use formulas almost anywhere in the app. To bind a 'Text' component value to a formula, press the binding icon on the Properties tab and choose "Formula" as the desired binding type.

Using formula functions

Upon choosing "Formula" as the binding type, you will be presented with the formula preview in the raw format, and a field for the preview value on the view canvas. Click on the first field below "Formula" to open the formula editor.

As was mentioned before, formulas are context aware, meaning that they can dynamically output results of their expression. Under 'Example results' you can see the output of the formula. Every expression is additionally validated, eliminating possible errors and alerting you beforehand, if the formula is wrong. On the screenshot below, you can see an app variable with a value of 123 added with an integer 1, producing 124 as a result.

Formula operators

Arithmetic operators +, - , *, and /
Logical operators ||, && and !
Comparisons ==, === , != , !== , < , <= , > and >=
Remainders %
Conditionals <condition> ? <true value> : <false value>

Escape character: \
To escape the backslash in JavaScript, use two backslashes: \\

Formula types

There two types of formulas: static (Variables) and dynamic (Functions). Static ones are used to interact with static data, ranging from pre-set app variables to system variables fetched from the device. Functions, on the other hand, allow the execution of complex actions and dynamic generation of output based on provided input.

Below you will find an introduction for each Formula sub-type along with usage examples.

Variables

App Variables

• Purpose

Read/Modify App Variables.

• Usage (Substitute {name} with an appropriate name.)

appVars.{name}

• Example

IF(IS_EQUAL(appVars.appVariableOne, true), "Variable 1 is true", "Variable 1 is false")

Explanation:
IF function creates an IF-statement that checks if the App Variable "appVariableOne" is equal to "true" via the IS_EQUAL function. In case, it is "true", then the formula outputs the first string. If it is "false", then the second one is outputted.

Data Variables

• Purpose

Read/Modifty Data Variables.

• Usage

data.{name}

• Example

IS_EMAIL(data.usersList[0].email)

Explanation:
Data variable usersList has a field called email. By using the IS_EMAIL function, we are able to verify, whether or not the email entry of that data variable is a valid email address. A "true" output indicates that that the entry is indeed an email.

Page Parameters

• Purpose

Read/Modify Page Parameters.

• Usage

params.{name}

• Example

CAPITALIZE(params.pageParameterOne)

Explanation:
By using the CAPITALIZE function, we are able to capitalize every word in the page parameter pageParameterOne.

Page variables

• Purpose

Read/Modify Page Variables.

• Usage

pageVars.{name}

• Example

LENGTH(pageVars.pageVariableOne)

Explanation:
The LENGTH function returns the number of characters in the page variable pageVariableOne.

Selected component properties

• Purpose

Interact (Read/Modify) with component's properties.

• Usage

self.{property}

• Example

IF(IS_EQUAL(self.visible, true), "Component is visible", "Component is not visible")

Explanation:
By using the IF and IS_EQUAL functions, we verify if a component is visible. If the formula determines that the component is visible, it will return "Component is visible". Otherwise, "Component is not visible" will be the output.

Sensor variables

• Purpose

Interact with data gathered by device sensors, i.e accelerometer.

• Usage

sensorVars.{name}

• Example

ROUND(sensorVars.accelerometer.latestValue.x + sensorVars.accelerometer.latestValue.y)

Explanation:
sensorVars.accelerometer.latestValue.x provides the value for acceleration along the X axis, while sensorVars.accelerometer.latestValue.y gives the Y axis. By using the mathematical expression + (plus) we are finding their sum. The ROUND function will round the result to the first decimal.

System variables

• Purpose

Interact with the device's system data, i.e active browser or phone model.

• Usage

systemVars.{name}

• Example

"You are using " + systemVars.browser.browserCodeName + " browser."

Explanation:
By using the plus sign (+), we are able to use device's browser name in a sentence. It will appear differently depending on the user.

Theme variables

• Purpose

Interact with the application's theme variables.

• Usage

theme.${name}

• Example

COLOR(theme.$smartColorPalette_app.negative)

Explanation:
theme.$smartColorPalette_app.negative gets the current 'negative' color pre-set in HEX format. The COLOR function converts it into an RGB color.

Functions

Bitwise

A bitwise formula function operates on a number at the level of its individual bits.

• BIT_NOT(10) = -11
  Performs logical negation on each bit, forming the complement of the given number.

• BIT_AND(14, 9) = 8
  Binary operation that takes two numeral representations and performs the logical AND operation on each pair of the corresponding bits.

• BIT_OR(14, 9) = 15
  Performs the logical inclusive OR operation on each pair of corresponding bits.

• BIT_XOR(14, 9) = 7
  Performs the logical exclusive OR operation on each pair of corresponding bits.

• BIT_SHIFT_{direction}(number, shift)
  In a left shift, binary zeros are shifted in on the right; in a right arithmetic shift, the sign bit is shifted in on the left,

Color

Collection of functions that work with colors. Refer to reference pages for more details.

• Examples

RGB(0, 128, 250)

You can use the RGB function to generate 16777216 possible colors using the Red, Green and Blue color system.

SATURATE("rgb(0, 128, 250)", 50)

Saturates (increases intensity and clearness) a color by provided percentage. Takes color in RGB or HEX as input.

Date

Enables interaction with dates and time. Refer to reference pages for more details.

• Examples

NOW()

Returns current date and time in YYYY-MM-DD HH:MM:SS format.

FORMAT_DATETIME_LOCAL(NOW(), "DD-MM-YY HH:MM")

Formats the date time into human-friendly format. Gives posibility to omit unnecessary fields and change the order in a desired way.

Engineering

Collection of engineering functions. Currently contains only variations of the Bessel function. Refer to reference pages for more details.

• Bessel function

A set of mathematical functions systematically derived by the German astronomer Friedrich Wilhelm Bessel during an investigation of solutions of one of Kepler’s equations of planetary motion. Bessel equation:

Financial

Perform various financial manipulations. Refer to reference pages for more details.

• Example

FUTURE_VALUE(0.5, 12, 1000)

Calculates an annuity investment's future value, where 0.5 is the interest rate, 12 the number of payments, and 1000 the contribution amount per period.

List

Perform operations with lists. Refer to reference pages for more details.

• Example

COUNT(data.usersList)

Returns a number of items in a given list. In this case, a data variable is the list.

Math

Library of mathematical expressions and methods. Refer to reference pages for more details.

• Examples

FACTORIAL(6)

Calculates a factorial of the provided number.

RANDOM_INTEGER_BETWEEN(1,100)

Randomizes a number between provided integers,

Object

Represents available JavaScript Object methods. Refer to reference pages for more details.

• Examples

LOOKUP(appVars.object, "name")

Reads the value of the "name" property of Object appVars.object.

SET_KEY(appVars.object, "name", "John")

Sets the "name" parameter's value to "John". Overrides the previous value.

Statistical

List of operations used in statistical mathematics. Refer to reference pages for more details.

• Examples

PERMUTATIONA(5, 3)

Returns a number of permutations ( ) for given inputs.

COMBINA(5, 3)

Returns a number of combinations ( ) for given inputs

Text

Text-based operations. Refer to reference pages for more details.

• Examples

APPEND_URL_PARAMETERS("https://appgyver.com/", { href: "#" })

Appends the given URL parameter (href: "#") to the URL text (https://appgyver.com/)

REPLACE_ONE_REGEX("AppGyver Documentation 20:00 @ 01.01.2022", "[a-zA-Z]+" , "SAP AppGyver")

Uses a Regex expression to substitute a text/numerical string. Use a Regex generator in case you are unfamiliar with the pattern language.

Utility

Selection of various programming utility functions, for instance IF-Statements or Base64 encoders. Refer to reference pages for more details.

• Examples

ENCODE_BASE64("Hello world!")

Encodes the provided text string into Base64.

FILENAME_IS_IMAGE("cat.svg")

Checks if the given text has a file extension that belongs to an image.

Cryptography

Cryptography uses mathematical techniques to transform data and prevent it from being read or tampered with by unauthorized parties. That enables exchanging secure messages even in the presence of adversaries¹.

• Examples

RIPEMD160("My secret password")

Calculates the RIPEMD160 hash of the provided text. The return value is a 160-bit hash encoded as a text with 40 hexadecimal digits.

SHA256("Hello world")

Calculates the SHA256 hash of the provided text. The return value is a 256-bit hash encoded as a text with 64 hexadecimal digits.