Customizing modifiers

This tutorial shows you how you can customize the default set of modifiers (data transformation functions) that can be applied on variables in Appmixer flows.

Introduction

Appmixer is shipped with predefined set of modifiers which allows you to transform the variables in your flow in many different ways. The modifiers are organised in categories. Every modifier belongs to one or more categories.

When clicking on any variable, the Modifier Editor is opened, allowing you to apply one of more modifiers to the variable.

Changing existing modifiers

Let's add a new modifier to the existing ones. This new modifier will take a date as an input and return it in a format specified as another argument. We are going to use Appmixer API to accomplish this.

The first thing we need is the current modifiers definition. To obtain it, we are going to use the GET /modifiers endpoint. The response will contain the following structure:

{
    "categories": {
        "object": {
            "label": "Object",
            "index": 1
        },
        "list": {
            "label": "List",
            "index": 2
        },
        ...
    },
    "modifiers": {
        "g_stringify": {
            "name": "stringify",
            "label": "Stringify",
            "category": [
                "object",
                "list"
            ],
            "description": "Convert an object or list to a JSON string.",
            "arguments": [
                {
                    "name": "space",
                    "type": "number",
                    "isHash": true
                }
            ],
            "returns": {
                "type": "string"
            },
            "helperFn": "function(value, { hash }) {\n\n                return JSON.stringify(value, null, hash.space);\n            }"
        },
        "g_length": {
            "name": "length",
            "label": "Length",
            "category": [
                "list",
                "text"
            ],
            "description": "Find length of text or list.",
            "arguments": [],
            "returns": {
                "type": "number"
            },
            "helperFn": "function(value) {\n\n                return value && value.hasOwnProperty('length') ? value.length : 0;\n            }"
        },
        ...
    }
    
}

Next step is changing the modifiers definition. We need to use the PUT /modifiers endpoint. The request body must contain the entire modifiers definition, including all the existing modifiers. Therefore, we will add a new key under the modifiers section in the JSON containing all existing modifiers:

"formatDate": {
    "label": "Format Date",
    "category": ["date"],
    "description": "Transforms the value into given date format",
    "arguments": [
        { "name": "Format", "type": "string", "isHash": false }
    ],
    "returns": {
        "type": "string"
    },
    "helperFn": "function(value, format, { helpers }) { return helpers.moment(value).format(format) }"
}

Where:

• The isHash property in the arguments determines if the argument will be an ordinal argument in the helperFn or it will be included in the hash object of the last argument.

• The last argument is always an options object which includes a hash object with the hash arguments and the helpers. The helpers object includes the moment library for date manipulations.

To illustrate better the meaning of the isHash option, see how our definition would look like with isHash: true for our format argument:

"formatDate": {
    "label": "Format Date",
    "category": ["date"],
    "description": "Transforms the value into given date format",
    "arguments": [
        { "name": "format", "type": "string", "isHash": true }
    ],
    "returns": {
        "type": "string"
    },
    "helperFn": "function(value, { hash: { format }, helpers }) { return helpers.moment(value).format(format) }"
}

With our modifications to the modifiers definition, we send the request with the entire definition as the body to the PUT /modifiers endpoint. As a response, we should receive the modifiers definition, including our new modifier:

{
    "categories": {
        "object": {
            "label": "Object",
            "index": 1
        },
        "list": {
            "label": "List",
            "index": 2
        },
        ...
    },
    "modifiers": {
        "g_stringify": {
            "name": "stringify",
            "label": "Stringify",
            "category": [
                "object",
                "list"
            ],
            "description": "Convert an object or list to a JSON string.",
            "arguments": [
                {
                    "name": "space",
                    "type": "number",
                    "isHash": true
                }
            ],
            "returns": {
                "type": "string"
            },
            "helperFn": "function(value, { hash }) {\n\n                return JSON.stringify(value, null, hash.space);\n            }"
        },
        "g_length": {
            "name": "length",
            "label": "Length",
            "category": [
                "list",
                "text"
            ],
            "description": "Find length of text or list.",
            "arguments": [],
            "returns": {
                "type": "number"
            },
            "helperFn": "function(value) {\n\n                return value && value.hasOwnProperty('length') ? value.length : 0;\n            }"
        },
        ...
        // At some place inside the object
        "formatDate": {
            "label": "Format Date",
            "category": ["date"],
            "description": "Transforms the value into given date format",
            "arguments": [
                { "name": "Format", "type": "string", "isHash": false }
            ],
            "returns": {
                "type": "string"
            },
            "helperFn": "function(value, format, { helpers }) { return helpers.moment(value).format(format) }"
        }
    }
}

Now we can use our new modifier in our flows:

It's important to note that all modifiers will return the original value if there is a runtime error during the execution of the helperFn. For example, if the value we are applying our new modifier to is a string apples, the modifier will return apples, since the value is not a valid date and the helperFn will fail. Therefore, keep this behaviour in mind and try to make sure that your custom modifiers check the type of values they operate on and potential coerce types where possible.