Table of Contents

DatasourceCurrent versus Item

It is important to make the distinction between DatasourceCurrent versus Item to know when to use one instead of the other and avoid problems.

What is DatasourceCurrent ?

Datasource

The Datasource property of ViewModel is a collection of data source elements (Model of the ViewModel design pattern).
The data source is always a collection even if the screen is designed to display only one record. In this case the data source contains only one element.

Concept of position

When a screen containing form, it is necessary to be data-bound to a single element in the datasource. Therefore, the view model has a Position property designating the current record in the data source which is the one that is bound to the form.

In a multi-record screen displayed in a data grid, the data grid manages a current position:

  • In edit mode: it corresponds to the line being edited
  • In read-only mode: it initially corresponds to the first line after loading the data. Then, wen the user interacts with the grid, it corresponds to the line on which the user has clicked.

The line at the current position is marked with a particular style.
If the data source does not contain any elements, the position is -1.

Note

The Position property can be read and modified by code.

DatasourceCurrent

DatasourceCurrent refers to the data source element at the current position, so the element data-bound to the form screen or the element data-bound to the current row of the data grid.
It is equivalent to Datasource[Position].
If the position is -1, DatasourceCurrent is null.

Note

Property DatasourceCurrent is available in every expression, event, method, action, ... in every UI views because it is a view model property.

Warning

Keep in mind that DatasourceCurrent is always independent of the context of execution of an event rule. It is therefore not a reliable tool for accessing items impacted by an event rule.
You should always be very careful when using DatasourceCurrent and most of the time prioritize using the Item property if available.

What is Item ?

In some expressions and events triggered for a particular data source element you have access to an Item property. This property represents the element on which the expression or event is triggered. Some events are triggered once for multiple items at the same time and offer an Items (or a variation like CreatedAndModifiedItems) property instead of Item.

Important

Depending on the type of expression or event and the moment of execution, Item can represent a different item from DatasourceCurrent. Therefore, you need to pay close attention to the property you are using.

DatasourceCurrent versus Item

In event rules

It is important to understand the difference between DatasourceCurrent and Item in an event rule and to know which tool is available in which rule.
For that, you can check this article that describes all UI view event rules.

In validation rules and pre-validation rules

Item refers to item being validated.

Important

Since you have no control over when a validation rule is triggered, never assume that DatasourceCurrent refers to the item being validated.

In a UI method

A UI method is a class method of the view model. DatasourceCurrent can therefore be used in a UI method.

Warning

In a UI method, DatasourceCurrent should only be used if you specifically need to access the current element of the datasource.

To avoid problems, when you create a UI method that works with a data source item, we recommend to always pass the item as a parameter (use type {RootNamespaceOfTheCluster}).CSharpAbstractions.{NameOfTheUIView}).
This way the code calling the method can pass the correct item in its context, whether it is DatasourceCurrent or another item.

The view model exposes a set of methods and properties to programmatically change the current Position:

  • MoveToNextPositionAsync() / MoveToPreviousPositionAsync()
  • MoveToFirstPositionAsync() / MoveToLastPositionAsync()
  • CanMoveNextPosition / CanMovePreviousPosition

These methods move Position (and therefore DatasourceCurrent) to another element, and return a value indicating whether the position has actually changed.

Displayed order versus raw datasource order

Important

These methods navigate the displayed order of the data source, not necessarily its raw order.

The displayed order takes into account:

  • Any active client-side filter (elements filtered out are skipped).
  • Any active client-side sort (items are ordered according to the active sort criteria).
  • Any active grouping: navigation moves across expanded groups' items, following the order in which they appear on screen, rather than the underlying raw order.

As a consequence, MoveToNextPositionAsync() from the last item of an expanded group moves to the first item of the next expanded group, not to the next raw element of the data source. Collapsed groups are skipped entirely, since their items are not currently displayed.

Note

CanMoveNextPosition / CanMovePreviousPosition reflect this same displayed order. They should be used to determine whether a "next"/"previous" navigation button should be enabled, rather than comparing Position to 0 or Datasource.Count - 1.

Server-side pagination

Warning

When the data source is paginated server-side and a group is only partially loaded (e.g. 20 out of 30 items loaded), navigating past the last locally-loaded item of that group does not currently trigger loading of the remaining items, even though totalRecordCount indicates more items exist. Depending on the situation, navigation may silently stop or move to a different group instead.

This is a known limitation. Do not rely on MoveToNextPositionAsync() / MoveToPreviousPositionAsync() to automatically page through a partially-loaded server-side group.

Relationship with DatasourceCurrent

Since these methods change Position, they change DatasourceCurrent as a side effect. The usual precautions around DatasourceCurrent documented above still apply — in particular, avoid relying on DatasourceCurrent inside an event rule to represent the item being navigated to or from; use Item when available instead.