Rank type

Overview

This type is basically a string with some special features that make it useful when you need to allow users to rank records using drag and drop in the UI. For example you can use fields of this type in grid views or workflow views so users can rank records there.

Rank fields are automatically populated with a value. When users rank records, if the view is configured to use the field as rank, the value will be automatically updated so the lexical order is what the user sees in the UI. In order to make it possible the rank type provides three methods in the Javascript API: rankBefore(), rankAfter() and rankBetween(). This methods will automatically calculate the new value of the rank so the record stays in the desired position.

Available features

Type rules

Display options

REST API

Read format

The format is a simple string with the rank value:

"rank": "iiiii00000"

Write format

You should pass a string with the rank value:

"rank": "iiiii00000"

Javascript API

Read format

The val() method in the wrapper 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 pass a string with the rank value:

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

Wrapper

rankBefore(rank)

Updates the rank value so it is before the given value.

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);

rankAfter(rank)

Updates the rank value so it is after the given 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);

rankBetween(before, after)

Updates the rank value so it is between the two given values.

Parameters

Returns

string - The new rank value.

Exceptions

badRequest

If before or after 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

Please check the documentation for Query language for more information.

Available operators

Query formats

You should pass the rank value. For example:

• JS Query Map
• JS Query Builder
• REST API

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

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

finds a task with rank 'iiiii00000'

GET /data/tasks?rank=iiiii00000

Aggregate queries

Please check the documentation for Aggregate queries for more information.

Available operators

UI queries

Please check the documentation for UI queries for more information.

Matching of values

Available operators