# Sortable

The sortable feature is used to store and alter the order of the elements in a module. If the sortable feature is activated, the order of the elements is stored in the database. This order can then be altered by requests over the common APIs.

# Configuration

The sortable feature is activated by setting the sortable flag to true for a certain CEId field.


<field>
  <type>CEId</type>
  <sortable>true</sortable>
</field>

It is important to notice that the sortable flag is not set for the elements which are supposed to be ordered but to the entity that groups these elements. For example: If the contacts of a company shall be ordered, the sortable flag should be activated for the company field in the contact module. This groups the contacts by their company and assigns each group(company) an independent order.

# Write Requests with OrderTag

If a module has a field for which the sortable flag is activated, it automatically obtains a virtual field. The name of the virtual field is derived from the sortable field as _fieldname_order. For example would the sortable flag in the company field create the virtual field _company_order. The is virtual field allows to alter the order of the elements by sending set requests in which the virtual "_..._order" field holds one of the following values:

- at:first
- at:last
- at:[number]
- before:[ceid]
- after:[ceid]

The following shows a possible request for the configuration example in which the company field obtains the sortable flag. The request updates the position of the contact with the id 17 after the contact with the id 42. Both are expected to belong to the company with the id 4ALLPORTAL.

{
  "session": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "method": "set_single",
  "module_name": "contact",
  "parameter": {
    "value": {
      "id": "17",
      "company": {
        "value": "4ALLPORTAL"
      },
      "_company_order": {
        "value": "after:42"
      }
    }
  }
}

# Requests Ordered Data

The elements of a module can be retrieved in order by a request that references the rank field. The rank field holds a number value which represents the order of the elements in their group. The name of the rank field is derived from the sortable field as fieldname_rank. Sticking to the example above the contact module thus obtains a rank field with the name company_rank. The following request shows how to retrieve the contacts which have the id 4ALLPORTAL in their company field in the order of the sortable feature.

{
  "session": "",
  "method": "search",
  "module_name": "contact",
  "filter": [
    {
      "field": "company",
      "value": "4ALLPORTAL"
    }
  ],
  "parameters": {
    "order_by": "company_rank"
  }
}

# Read Requests

A request using the get_single or the get_multiple method to request the value of a sortable field, is automatically enriched with the values of rank field. Sticking to the example with the contact module the following request shows how to retrieve the company for a certain id.

{
  "session": "dfdf13c3-7d2a-435b-ace9-5d6821ef1b0a",
  "method": "get_single",
  "module_name": "contact",
  "parameter": {
    "id": "ed9559d5-4c09-4c43-817a-a83506e4a62f",
    "fields": [
      "company"
    ]
  }
}

The response to this request automatically holds also the value stored in the company_rank field.

{
  "id": "",
  "module_name": "contact",
  "properties": {
    "company": {
      "value": "db70952d-e3a7-4074-80e3-77004d35e947"
    },
    "company_rank": {
      "value": 2000000000000
    }
  }
}

# Subpanels

Your can sort your sortable fields in a subpanel as well.

Instead of setting relationName parameter you have to use the new parameter relationField
The sort field has to be the relation field with the _rank suffix
- by default or as an manual option

<import_layout layout_id="subpanel" module="TARGET_MODULE">
  <parameter>
    
    <!-- other parameters -->
    
    <!-- Your sortable CEId relation_field -->
    <entry key="relationField" class="string">MY_FIELD_NAME</entry>
    
    <!-- You can set your custom sort as a default  -->
    <entry key="defaultSortField">MY_FIELD_NAME_rank</entry>
    
    <!-- You can define your sort options, that can choose between your custom sort or any other field -->
    <entry class="array" key="sortFieldOptions">
        <value class="map">
            <entry key="label">custom sort</entry>
            <entry key="field">MY_FIELD_NAME_rank</entry>
        </value>
        <value>friendlyname</value>
    </entry>
  </parameter>
</import_layout>

← Search Comparator Configuration Template engine functions →