Handle entities in an entity selection

FIRST RECORD, LAST RECORD, NEXT RECORD, PREVIOUS RECORD; does that ring any bells? I bet it does. You’ve already been using them to handle selections! ORDA provides useful and familiar methods to navigate through entities in an entity selection – and obviously, some perks!

For starters, you can handle several entity selections at the same time and navigate through them independently, whereas normally you can only manage a single ‘current selection’ per table. That’s precisely what we’re going to see in this blog post.

We’ve already seen that querying the datastore returns an entity selection. ORDA provides the means to access the entities in an entity selection very easily.

ORDA: Handle entities in entity selections

CREATE AND FILL ENTITY SELECTIONS

An empty entity selection is created using the newSelection() method. You can also add entities to it with the add() method.

EXAMPLE

C_OBJECT($employee;$es)
C_TEXT($name)

//Create a new empty entity selection
$es:=ds.Employee.newSelection()
Repeat
$name:=Request("Which employee?")
 If (ok=1)
   //Get the first employee whose last name is $name
   $employee:=ds.Employee.query("lastName=:1";$name).first()
  //Add the entity to the new entity selection $es
  If ($employee#Null)
   $es.add($employee)
  End if
 End if
Until (ok=0)
alert(String($es.length) + " employees have been added to the new entity selection")


ACCESSING ENTITIES IN AN ENTITY SELECTION

Remember, you can iterate through entities in a entity selection with the for each loop. Here is a quick example, but also take a look at this blogpost.

C_OBJECT($employeesParis;$employee;$status)
 
// Get employees working in Paris
$employeesParis:=ds.Employee.query("city='Paris'")
//Iterate through each employee
For each ($employee;$employeesParis)
$employee.lastName:=Uppercase($employee.lastName)
$status:=$employee.save()
End for each

You can also load an entity with its index into an entity selection (index starts at 0). Here is an example:

C_OBJECT($gamers)
//Get all the gamers sorted by rank
$gamers:=ds.Gamer.all().orderBy("rank")
if($gamers.length >=3)
ALERT("The first three are: "+Char(13) \
+$gamers[0].lastName+Char(13)+$gamers[1].lastName+Char(13)+$gamers[2].lastName)
End if


FIRST AND LAST ENTITIES

The first() and last() methods let you get the first or last entity of an entity selection. These methods may return Null if the entity selection is empty.

In the example below, we get the first entity of the $gamers entity selection:

C_OBJECT($gamers;$first)
// Get the gamers whose last name starts with "H"
$gamers:=ds.Gamer.query("lastName='H@'")
// Get the first entity of the $gamers entity selection
$first:=$gamers.first()
If ($first#Null)
 ALERT("The first gamer has been found")
Else
 ALERT("The entity selection $gamers is empty")
End if


Previous AND next ENTITIES

An entity may belong to an entity selection. In this case, you can iterate through the entities of an entity selection with the previous() and next() methods.

In this example, we use a form to display a list of gamers. The user can navigate through the details of each gamer with the Previous and Next buttons.

The Next button has the following object method:

//Form.gamer is an entity, edited on the form. It belongs to an entity selection which is the entire list of gamers.
If (Form.gamer.next()#Null)
 //Edit the next entity of the entity selection to which the Form.gamer entity belongs.
 Form.gamer:=Form.gamer.next()
End if


info about an entity

And that’s not all! For any given entity, you can get the entity selection it comes from. Something else good to know, there are also methods to get contextual information about an entity, e.g. check if it belongs to a given entity selection, get its position in an entity selection, etc.

Here, we have two entity selections ($employeesParis and $employeesNY). The selectedEmployee method selects an employee in one of them. We can then determine which entity selection this employee belongs to with the contains() method:

C_OBJECT($employeesParis;$employeesNY;$employee)
// Get employees working in Paris
$employeesParis:=ds.Employee.query("city='Paris'")
// Get employees working in New York
$employeesNY:=ds.Employee.query("city='New York'")
// The method selectedEmployee returns an employee in one of the two given entity selections
$employee:=selectedEmployee($employeesParis;$employeesNY)
 
Case of
: ($employeesParis.contains($employee))
ALERT("The employee belongs to the entity selection $employeesParis")
: ($employeesNY.contains($employee))
ALERT("The employee belongs to the entity selection $employeesNY")
End case


 

Here, we have an entity selection ($employeesParis). The selectedEmployee method seelcts an employee from it. We can get the employee’s index in the entity selection with the indexOf() method:

C_OBJECT($employeesParis;$employee)
// Get employees working in Paris
$employeesParis:=ds.Employee.query("city='Paris'")
// The method selectedEmployee returns an employee in the given entity selection
$employee:=selectedEmployee ($employeesParis)
ALERT("The index of the selected employee is " + String($employee.indexOf()))


Take a look at the database example and you’ll know all about this subject!