Using scripts

The SDK of our product is packed with numerous features. However, custom coding becomes essential in every project at some stage. In dcupl projects, we emphasize maintaining data-manipulating code adjacent to the dcupl SDK. This integration allows your custom code to also function seamlessly within the dcupl Console, facilitating straightforward error handling and debugging processes, ensuring they are both comprehensible and repeatable.

To accommodate this need, we have introduced the concept of scripts.

A script is essentially a straightforward JavaScript function, but it's integrated within a unique context established by the SDK. These scripts can serve as Custom Query Operators, define Custom Sort Orders, aid in Data Transformations, or inject specific functionalities such as authentication or logging into your application. Below, you'll find several illustrative examples.

Example: Creating an Operator Script

To incorporate a custom operator script, place it at dcupl/scripts/custom_operator.script.js. The context available to you varies based on your requirements. For an operator script, the context includes:

• script_type: A constant element in any script context – here, it's 'operator'.
• query: This represents the current query statement where the operator is applied.
• item: Refers to the current line item being filtered.

// custom operator script that checks if the item key contains some special string
// an operator script must return true/false to indicate if a line item should be excluded or not
if (script_type !== 'operator') {
  throw new Error('unsupported script type: ', script_type);
}

console.log(script_type);
console.log(query);
console.log(item);

try {
  return item[query.attribute].contains(query.value);
} catch (e) {
  return true;
}

Loader Configuration

To add a script to your application, include it in your loader configuration with type: script. Use the scriptKey to call the script for various functions like operators, transformers, or sorting.

{
  "type": "script",
  "url": "${baseUrl}/scripts/custom_operator.script.js",
  "scriptKey": "my_custom_operator"
}

Using your script

You can use your custom operator script in your own query by referencing it's scriptKey.

projectDcupl.query.execute({
  modelKey: 'my-model',
  groupKey: 'root',
  groupType: 'and',
  queries: [
    {
      groupKey: 'my-group',
      groupType: 'or',
      queries: [
        {
          attribute: 'foo',
          value: 'bar',
          operator: 'my_custom_operator', // custom operator
        },
      ],
    },
  ],
});

Examples

Sorting

You can sort your query results however you like. The example sorts fruits based on a specific order and not alphabetically.

if (script_type !== "sort") {
  throw new Error("unsupported script type: ", script_type);
}

console.log(script_type);
console.log(options);
console.log(items);

// add your custom sorting logic here
// bananas should be sorted before apples and oranges...
const order = options.my_custom_order || [];
const customSort = (a, b) => {
  const aValue = order.indexOf(a.b?.name);
  const bValue = order.indexOf(b.b?.name);
  return aValue - bValue;
};

return items.sort(customSort);

const result = await dcupl.query.execute({
  modelKey: 'fruits',
  queries: [],
  sort: {
    attributes: [],
    order: [],
    script: { key: 'my_custom_sort_script', options: { my_custom_order: ['bananas', 'apples', 'oranges'] } },
  },
});