Rank type

Overview #

The rank type is essentially a string with additional features designed for enabling users to rank records through drag and drop interactions in the user interface. This type is particularly useful when you want to allow users to rearrange records using fields of this type in grid views or workflow views.

Rank fields are auto-populated with a value. When users rank records, and if the view is configured to use the field as a rank, the value will be automatically updated so that the lexical order matches the user’s desired arrangement in the UI. To facilitate this, the rank type provides three methods in the JavaScript API: rankBefore(), rankAfter(), and rankBetween(). These methods will automatically calculate the new rank value to ensure that the record maintains its intended position.

Available features #

REST API #

Read format #

The format is a simple string with the rank value:

"rank": "iiiii00000"

Write format #

You should provide a string with the rank value:

"rank": "iiiii00000"

JavaScript API #

Read format #

When using the val() method in the wrapper for a rank type field, it will return a string with the rank value.

// this will print something like "rank: iiiii00000"
log('rank: '+record.field('rank').val());

Write format #

You should provide a string with the rank value:

record.field('rank').val('iiiii00000');

Wrapper method:
rankBefore(rank) #

The rankBefore() method is used to update the rank value of a record so that it is positioned before the specified value in the ranking order.

Parameters #

Returns #

string - The new rank value.

Exceptions #

badRequest

If rank is invalid

Samples #

// moves a record to be before another one (when sorting by rank)
var task1 = sys.data.findOne('tasks', {number: 1});
var task2 = sys.data.findOne('tasks', {number: 2});
var newRank = task1.field('rank').rankBefore(task2.field('rank').val());
sys.data.save(task1);
log('new rank: '+newRank);

Wrapper method:
rankAfter(rank) #

The rankAfter() method updates the rank value so that it comes after the provided value.

Parameters #

Returns #

string - The new rank value.

Exceptions #

badRequest

If rank is invalid

Samples #

// moves a record to be after another one (when sorting by rank)
var task1 = sys.data.findOne('tasks', {number: 1});
var task2 = sys.data.findOne('tasks', {number: 2});
var newRank = task1.field('rank').rankAfter(task2.field('rank').val());
sys.data.save(task1);
log('new rank: '+newRank);

Wrapper method:
rankBetween(before, after) #

Updates the rank value to position it between the two specified values.

Parameters #

Returns #

string - The new rank value.

Exceptions #

badRequest

If the before or after values are invalid

Samples #

// puts a task in between other two tasks
var task1 = sys.data.findOne('tasks', {number: 1});
var task2 = sys.data.findOne('tasks', {number: 2});
var task3 = sys.data.findOne('tasks', {number: 3});
var newRank = task1.field('rank').rankBetween(task2.field('rank').val(), task3.field('rank').val());
sys.data.save(task1);
log('new rank: '+newRank);

Export/Import #

Export format #

The export format is a simple string:

"rankField1","rankField2"
"iiiii0001s","iiiii00za8"

Import format #

The import format is a simple string:

"rankField1","rankField2"
"iiiii0001s","iiiii00za8"

Queries #

For more information, please refer to the Query Language Documentation.

Available operators #

Query formats #

You should provide the rank value. For instance:

// finds a task with rank 'iiiii00000' 
var records_sample = sys.data.find('tasks', {'rank': 'iiiii00000'});
log('total: '+records_sample.count());
while (records_sample.hasNext()) {
    log(records_sample.next().label());
}

// finds a task with rank 'iiiii00000' 
var query_sample = sys.data.createQuery('tasks')
    .field('rank').equals('iiiii00000')
var records_sample = sys.data.find(query_sample);
log('total: '+records_sample.count());
while (records_sample.hasNext()) {
    log(records_sample.next().label());
}

// finds a task with rank 'iiiii00000' 
GET /data/contacts?rank=iiiii00000

Aggregate queries #

Please refer to the Aggregate Queries Documentation for more detailed information.

Available operators #

UI queries #

Please refer to the UI Queries Documentation for more detailed information.

Matching of values #

Available operators #