Customizing modifiers

This tutorial shows you how you can customize your variable modifiers

Introduction

Appmixer is shipped with predefined modifiers which allows you to transform the variables in your flow on 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, you should get a response with 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 whole modifiers definition, like the one we obtained previously, in addition to desired modifications. So to add the modifier, we will add a new key under the modifiers 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) }"
}

Note three things in this definition:

• The name property has been deprecated and is no longer required.

• The isHash property in the argument determines if this 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 this points, the following form is equivalent:

"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, format, { hash: { format }, helpers }) { return helpers.moment(value).format(format) }"
}

With our modifications to modifiers definition, we send the request with the whole definition as the body to the PUT /modifiers endpoint. We should receive as a response the modifiers definition, including the 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 on our flows:

Something important to note, is 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 modifiers is a string apples, the modifier will return apples, since the value is not a valid date and the helperFn will fail, so try to make sure that the modifiers are applied always on valid values.

30KB

modifiers-4.0.1.json

Open

Default modifiers in 4.0.1