Accessing Data in Entities

All the entities configured in the Admin Panel in Miracle Mobile App can be accessed using the Entity keyword. For instance, the following expression will retrieve all the records in the Departments entity.

Entity[Departments]

 

However, if you want to access only the first record in this entity and view or use its Designation field, you should write the following.

Entity[Departments][0][Designation]

If your application requires authentication, you can access the information related to the authenticated user with the Login keyword.

If you wish to show the display name for the logged in user, the following expression will help.

Login.DisplayName

To show the roles the logged in user, type in this expression.

Login.Roles

To provide access to all the fields and values provided by the authentication connector, use the following.

Login.Extras

The ‘In’ keyword provides access to the current context of the loaded page. The expression In.SelectedItem is usually used for list items when the List Select action is configured and an item had been selected by the user.

To better explain the function of this expression, here is an example.

Create a page that displays a list of all users in a List View by binding the expression Entity[Users] to List View Data Source. Configure a List Select action so that when a user taps an item, the In.SelectedItem expression is assigned the selected record. You can display the data retrieved in a Text Box control using the following expression to bind the selected user’s name.

In.SelectedItem[FullName]

The ‘Controls’ keyword allows users to use a control’s value in an expression. For instance, if you have a page with two controls, a picker and a text box, you can show the value selected in the first control by binding the second control with the following expression.

Controls[pickerID].SelectedItem

The ‘AppSettingsData’ keyword provides access to users’ settings. You can define settings that a user can alter and which are specific to that user’s device, such as the user’s email address and default values for entities. If, for instance, you want to access the email address a user has configured, use the expression below. In this case, UserEmail is the key used to access the value in the settings object.

AppSettingsData[UserEmail].Value

The Bool Function converts the result of any expression into a Boolean value for evaluation or use. The expression below will return the Boolean value ‘True’.

Bool(In.SelectedItem[acceptedTerms]=’Yes’)

The Percent function calculates the percentage between two values. For instance, the expression {10}.Percent(20) will result in ‘50’. The following expression is more complex, but it effectively shows how you can benefit from this function. Entering it will return a percentage rating for the first record in the entity ‘Users’.

Entity[Users][0][userRating].Percent(AppSettingsData[maxRating].Value)

The ToList Function creates a list from a set of provided values. This list can then be used as a native list object in expressions. For example, the following expression will return TRUE if the selected value in the control ‘abc’ is equal to ‘Red’, ‘Blue’ or ‘Green’.

 Bool(Controls[abc].SelectedValue~ToList(Red,Blue,Green))

The ToDate Function converts a TEXT or STRING value into a DATE object. That way, the system can carry out mathematical calculations based on date values, such as calculating the age of an employee. For example, the expression below will fetch all records where the birth date is before January 1st, 1990.

Entity[Users].FindAll([birthDate] < ToDate(’01/01/1990′))

The ToString Function converts any data type into a STRING value that can be used as normal text.

The IsDate Function checks whether a retrieved value is a proper date value or not. The following expression will only return the records where birthdate is a valid date set.

Entity[Users].FindAll(IsDate([birthDate]))

The IsToday Function checks whether the date provided is today’s date value or not. You can add a secondary parameter to determine whether this check is for Day and Month or for Year as well. For instance, this expression will return the records in the entity ‘Users’ where users’ birthdays are today.

Entity[Users].FindAll(IsToday([birthDate],FALSE))

The MatchDates Function compared two sets of data values to determine whether or not they are the same. Again, you can add a secondary parameter to decide whether the check is only for Day and Month or for Year too. The following expression, for instance, will return users whose join date is October 1st, 2016.

Entity[Users].FindAll(MatchDates([joinDate], ToDate(’01/10/2016′),TRUE))

The Now Function will return the current date and time values.

The UtcNow Function will return the current time and date, but expressed as Coordinated Universal Time.

The SubString Function is used to return a part of the string. The expression below will return the first record’s userName value after removing its first letter.

Entity[Users][0][userName].Substring(1)

This expression will return the same record, but after removing the first and only retrieving the next six letters.

Entity[Users][0][userName].Substring(1,6)

The Replace Function is used to replace a string or a part of a string with a specified value. In this expression, a projectName record such as ‘The London Bridge’ will be changed to ‘The Golden Gate Bridge’.

Entity[Projects][0][projectName].Replace(‘London’,’Golden Gate’)

However, the actual value of the entity record will not be changed. Only the value in the expression will be altered.

The ToUpper Keyword will change all the letters in a text to upper case. Again, the following expression will only change ‘The London Bridge’ to ‘THE LONDON BRIDGE’ in the expression while the value in the entity will remain the same.

Entity[Projects][0][projectName].ToUpper()

The ToLower Keyword is the opposite of the ToUpper Keyword as it changes all the letters in a text to lower case. Only the value in the expression will be changed while the actual value of the entity will remain the same.

 Entity[Projects][0][projectName].ToLower()

A query function, FindAll Function is used on list type values to return records that are filtered based on certain criteria. The expression below returns the users whose birth dates are before 1990.

Entity[Users].FindAll([birthDate] < ToDate(’01/01/1990′))

The Find Function acts just like the FindAll Function, but it only returns the first record in the entity that is based on your criteria. The expression below will only return one user that matches the criteria.

Entity[Users].Find([birthDate] < ToDate(’01/01/1990′))

The Select Function can be used to return a subset of the attributes in a record for all the records included in the entity. For instance, the expression below will retrieve all the records in the entity ‘Users’, but only display the data in ‘userName’ and ‘birthDate’.

Entity[Users].Select([userName],[birthDate])

The Joins Function is used to combine the records lists of two or more entities. Miracle Mobile Platform supports the following types of joins:

  • InnerJoin – Also known as Join, it returns all records when there is at least one match in both lists.
  • FullJoin – This function returns all the records if there is a match in one of the lists.
  • LeftJoin – This function returns all the records from the first entity’s list along with the matched records from the second entity’s list.
  • RightJoin – The function returns all the records from the second entity’s list along with the matched records from the first entity’s list.

The following are the syntax of joins which you can use. (_list1 indicates the list from the first entity whereas _list2 is the list from the second entity)

_list1_.Join( _list2_ , item1 = item2 )
_list1_.Join( _list2_ , item1 = item2[_list2Attribute_] )
_list1_.Join( _list2_ , item1[_list1Attribute_] = item2 )
_list1_.Join( _list2_ , item1[_list1Attribute_] = item2[_list2Attribute_])

The SortBy Function is used to sort a list based on a given attribute. The expression below, for instance, will sort the list of users by their birth date in ascending order.

Entity[Users].SortBy([birthDate])

To display the same in descending order, use the following expression.

Entity[Users].Find([birthDate] DESC)

The OrderBy Function is used to sort the list values according to specific attributes. It can use an attribute name or the index of the column to order the records. For instance, the following expression will return the ‘userName’ and ‘birthDate’ attributes for all records in the ‘User’ entity and order it according to ‘birthDate’.

Entity[Users].Select([userName],[birthDate]).OrderBy([birthDate])

The following expression retrieves the userName and birthdate attributes for all the records while ordering them according to the 0th column.

Entity[Users].Select([userName],[birthDate]).OrderBy([0])

The GroupBy Function is used to group multiple records based on a condition that equates the values of the attributes of two or more records. This function also allows many advanced aggregate functions which you will find out about shortly. The following expression produces a list of records, each of which has unique teamID and the count of users per team.

Entity[Users].Select([teamID],[userName]).GroupBy([0], Count([1]))

An advanced function, the Switch Function allows the generalization of a set of values into standard values so that they can be used for advanced logical evaluations. It can take any number of parameters for substitution. The following expression will return ‘True’ for all the values of TaskStatus except when it is ‘Complete’ or ‘Inactive’. The last value, which in the expression is without an equal sign, provides the default value.

In.SelectedItem[TaskStatus].Switch(‘Complete’=’False’,’Inactive’=’False’,’True’)

The Substituted Values Function uses curly brackets {} to quickly substitute values with user-provided values in an expression. For instance, the expression below substitutes each single letter in MaritalStatus with a corresponding value.

In.SelectedItem[MaritalStatus]{‘m’=’Married’,’s’=’Single’,’w’=’Widowed’,’d’=’Divorced’,’-‘}

There are a number of operators that you can use while writing expressions.

  1. ‘&’ – The AND operator is used for logical AND operations. For instance, the expression Entity[Document].FindAll([userName]=’John’ & [ID]=1) will return all the records that have the userName ‘John’ and ID ‘1’ from the entity ‘Document’. If even one of these conditions is not met, the record will not be retrieved.
  2. ‘|’ – The OR operator is used for logical OR operations. For example, the expression Entity[Document].FindAll([userName]=’John’ | [ID]=1) will retrieve the record even if one of these conditions is not met.
  3. ‘=’ – The EQUALS operator is mainly used for EQUALITY operations. For example, the expression Entity[Document].FindAll([userName]=’John’) will return all the records where the ‘userName’ is exactly ‘John’ in the entity ‘Document’.
  4. ‘>’ – The GREATER THAN operator can be used for INEQUALITY operations. In the expression, Entity[Document].FindAll([ID]>10), records whose ‘ID’ values are greater than 10 will be retrieved from the entity ‘Document’. Records with ‘ID’ equals 10 or less will not be retrieved.
  5. ‘<’ – The LESS THAN operator is also used for INEQUALITY operations. Entity[Document].FindAll([ID]<25) will return records which have ‘ID’ values less than 25. Only records that have IDs with values from 0 to 24 will be fetched.
  6. ‘!’ – The NOT EQUALS operator is also used for INEQUALITY operations. The expression Entity[Document].FindAll([userName]!’John’) will return all the records in the entity ‘Document’ where userName is anything but ‘John’.
  7. ‘~’ – The EXISTS IN operator can be used for EQUALITY operations to check a value inside a list of values and return TRUE if the value has been found in the list. For instance, in the expression Entity[Document].FindAll([userName]~ToList(John, Mark, Cage)) , all records where the userName is equal to ‘John’, ‘Mark’ or ‘Cage’ will be retrieved.
  8. ‘%’ – The LIKE operator is also used for EQUALITY operations. The expression, Entity[Document].FindAll([userName]%’sara’)  will return records where the username contains ‘sara’ in it. Examples of names that may be retrieved include ‘Sara’, ‘Sarah’, and ‘Basarah’.

The GroupBy Function comes with a list of advanced functions. To simplify these, assume that the following data set is the ‘User’ entity and consider the following functions.

ID userName birthdate teamID maritalStatus noOfRewards
1 Jonathan Briggs 23/12/1978 334 m 7
2 Samantha Tanner 23/4/1983 334 s 5
3 Babar Karim 16/5/1981 338 s 1
4 Mike Johnson 12/3/1984 338 m 1
5 Anand Patel 05/07/1968 338 m 9

 

  • Count – The Count Function calculates the number of values in an expression. The expression Entity[Users].Select([teamID],[userName]).GroupBy([0], Count([1])) will group users by teamID and then count the number of users. The output in this case would 2 for team 334 and 3 for team 338.
  • Sum – The Sum Function calculates the sum of values in an expression. Entity[Users].Select([teamID],[noOfRewards]).GroupBy([0], Sum([1])) will group users by teamID and count how many rewards they received. The output according to the data set above will be 12 rewards for team 334 and 11 for team 338.
  • Max – The Max Function calculates the maximum values in an expression. For instance, the maximum number of rewards for any user in a team can be computed through the expression Entity[Users].Select([teamID],[noOfRewards]).GroupBy([0], Max([1])).
  • Min – The opposite of the Max Function, Min calculates the minimum values in an expression. Through the expression Entity[Users].Select([teamID],[noOfRewards]).GroupBy([0], Min([1])) , the app will group users by teamID and then display the minimum number of awards any user received. The output of this expression should be 5 for team 334 and 1 for 338.
  • First – The First Function returns the first value of a grouped set of records. Entity[Users].Select([teamID],[userName]).GroupBy([0], First([1]))  will group users by teamID and then display the first user in the team.
  • Last – The Last Function returns the last value of a grouped set of records. This expression will provide the name of the last user in a team: Entity[Users].Select([teamID],[userName]).GroupBy([0], Last([1])) .
  • Concat – The Concat Function returns the concatenated values of a grouped set of records, separated by a specified delimiter parameter. Entity[Users].Select([teamID],[userName]).GroupBy([0], Concat([1],’,’))   is an expression that groups users by teamID and shows the values of userName separated by a comma.