[Baidu amis] Data Mapping

Posted on Edited on In , , Views: Word count in article: 12k Reading time ≈ 11 mins.

Data Mapping

Data Mapping allows users to obtain the value of a variable in the current Data Chain through ${xxx} or $xxx to achieve flexible data configuration functions. It is mainly used in scenarios such as template strings and custom api request data body formats.

Template string

1
my name is rick
1
2
3
4
5
6
7
8
9
10
{
  "type": "page",
  "data": {
    "name": "rick"
  },
  "body": {
    "type": "tpl",
    "tpl": "my name is ${name}"
  }
}

Tip:

By default, when amis is parsing the template string, it will try to parse the variable and replace the template variable when it encounters the $ character. If you want to output plain text ${xxx} or $xxx, you need to precede the $ Add the escape character \\, that is, \\${xxx}.

1
2
3

```html
my name is ${name}
1
2
3
4
5
6
7
8
9
10
{
  "type": "page",
  "data": {
    "name": "rick"
  },
  "body": {
    "type": "tpl",
    "tpl": "my name is \\${name}"
  }
}

Support chain value

You can use . For chain value.

1
my name is rick, I work for baidu
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "type": "page",
  "data": {
    "name": "rick",
    "company": {
      "name": "baidu",
      "department": "it"
    }
  },
  "body": {
    "type": "tpl",
    "tpl": "my name is ${name}, I work for ${company.name}"
  }
}

Custom API request body data format

In the form submission interface, the default request body data format of amis may not meet your expectations. Don’t worry, you can use Data Mapping to customize the data format you want:

Look at the following scenario:

1
2
3
4
Form

Name:
Mail:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "type": "page",
  "body": {
    "type": "form",
    "api": "https://3xsw4ap8wah59.cfc-execute.bj.baidubce.com/api/amis-mock/mock2/form/saveForm",
    "body": [
      {
        "type": "input-text",
        "name": "name",
        "label": "姓名："
      },
      {
        "name": "email",
        "type": "input-text",
        "label": "邮箱："
      }
    ]
  }
}

After entering name: rick and email: [email protected], the form gets the current data field, and the data format submitted to the back-end interface should look like this:

1
2
3
4
{
  "name": "rick",
  "email": "[email protected]"
}

Unfortunately, your back-end API only supports the following input data structures and cannot be modified:

1
2
3
4
{
  "userName": "xxx",
  "userEmail": "[email protected]"
}

At this time, in addition to directly changing the name attribute of your name form item and mailbox form item to the corresponding field, you can configure the data attribute of the api, and use Data Mapping to easily customize the data format:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "type": "page",
  "body": {
    "type": "form",
    "api": {
      "method": "post",
      "url": "https://3xsw4ap8wah59.cfc-execute.bj.baidubce.com/api/amis-mock/mock2/form/saveForm",
      "data": {
        "userName": "${name}",
        "userEmail": "${email}"
      }
    },
    "body": [
      {
        "type": "input-text",
        "name": "name",
        "label": "姓名："
      },
      {
        "name": "email",
        "type": "input-text",
        "label": "邮箱："
      }
    ]
  }
}

You can check the Network panel, the data body sent to the back-end API should have been successfully modified to:

1
2
3
4
{
  "userName": "rick",
  "userEmail": "[email protected]"
}

Complex configuration

Expand the configured data

You can use & as the Data Mapping key to expand the configured variables, for example:

In the following example, we want to add all the variables e, f, g under c in addition to the name and email variables when submitting, but according to what we said before, the api should be configured like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
  "type": "page",
  "body": {
    "type": "form",
    "data": {
      "a": "1",
      "b": "2",
      "c": {
        "e": "3",
        "f": "4",
        "g": "5"
      }
    },
    "api": {
      "url": "https://3xsw4ap8wah59.cfc-execute.bj.baidubce.com/api/amis-mock/mock2/form/saveForm",
      "method": "post",
      "data": {
        "name": "${name}",
        "email": "${email}",
        "e": "${c.e}",
        "f": "${c.f}",
        "g": "${c.g}"
      }
    },
    "body": [
      {
        "type": "input-text",
        "name": "name",
        "label": "姓名："
      },
      {
        "name": "email",
        "type": "input-text",
        "label": "邮箱："
      }
    ]
  }
}

Click Submit to view the network panel data, you will find that the data is in line with expectations:

1
2
3
4
5
6
7
{
  "name": "rick",
  "email": "[email protected]",
  "e": "3",
  "f": "4",
  "g": "5"
}

But when there are too many variable fields, you need to map the configuration one by one, which may be a bit troublesome, so you can use the & identifier to expand the configured variables:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
  "type": "page",
  "body": {
    "type": "form",
    "data": {
      "a": "1",
      "b": "2",
      "c": {
        "e": "3",
        "f": "4",
        "g": "5"
      }
    },
    "api": {
      "url": "https://3xsw4ap8wah59.cfc-execute.bj.baidubce.com/api/amis-mock/mock2/form/saveForm",
      "method": "post",
      "data": {
        "name": "${name}",
        "email": "${email}",
        "&": "${c}"
      }
    },
    "body": [
      {
        "type": "input-text",
        "name": "name",
        "label": "姓名："
      },
      {
        "name": "email",
        "type": "input-text",
        "label": "邮箱："
      }
    ]
  }
}

In the above example, our api.data configuration is as follows:

1
2
3
4
5
"data": {
  "name": "${name}",
  "email": "${email}",
  "&": "${c}"
}

The & identifier will expand and concatenate the value of the configured c variable in data. Looking at the Network panel, you can see the data as follows:

1
2
3
4
5
6
7
{
  "name": "rick",
  "email": "[email protected]",
  "e": "3",
  "f": "4",
  "g": "5"
}

Array extraction value

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
{
  "type": "page",
  "body": {
    "type": "form",
    "api": {
      "method": "post",
      "url": "https://3xsw4ap8wah59.cfc-execute.bj.baidubce.com/api/amis-mock/mock2/form/saveForm",
      "data": {
        "items": {
          "$table": {
            "a": "${a}",
            "c": "${c}"
          }
        }
      }
    },
    "body": [
      {
        "type": "input-table",
        "name": "table",
        "label": "table",
        "columns": [
          {
            "label": "A",
            "name": "a"
          },
          {
            "label": "B",
            "name": "b"
          },
          {
            "label": "C",
            "name": "c"
          }
        ],
        "value": [
          {
            "a": "a1",
            "b": "b1",
            "c": "c1"
          },
          {
            "a": "a2",
            "b": "b2",
            "c": "c2"
          },
          {
            "a": "a3",
            "b": "b3",
            "c": "c3"
          }
        ]
      }
    ]
  }
}

The data configuration format of the api in the above example is as follows:

1
2
3
4
5
6
7
8
"data": {
    "items": {
      "$table": {
        "a": "${a}",
        "c": "${c}"
      }
    }
}

This configuration means that only the a variable and the c variable in the table array are extracted to form a new array and assigned to the items variable

Click Submit and check the web panel of the browser to find that the submitted data structure of the form is as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "items": [
    {
      "a": "a1",
      "c": "c1"
    },
    {
      "a": "a2",
      "c": "c2"
    },
    {
      "a": "a3",
      "c": "c3"
    }
  ]
}

Namespace

Since 1.1.6

The default value is to fetch data from the current component context Data Chain, but some data may not be in this Data Chain, such as some data in global variables, and some data in localstorage.

Starting from version 1.1.6, a new syntax is supported, such as: ${window:document.title} which means to take the title of the page from the global variable.

There are currently the following three namespaces

  • window is a global variable

  • ls is localStorage. If the value is a json object, it can be used directly as an object. For example: ${ls:xxxxxlocalStrorageKey.xxxx}

  • ss is sessionStorage, ibid.

1
The current page title is: amis-low-code front-end framework
1
2
3
4
{
  "type": "page",
  "body": "The title of the current page is: <span class='label label-info'>${window:document[title]}</span>"
}

Filter

Filter is an enhancement to Data Mapping. Its function is to do some processing on the acquired data. The basic usage is as follows:

1
${xxx [|filter1 |filter2...]}

See Data Mapping | amis - 低代码前端框架 - https://baidu.github.io/amis/zh-CN/docs/concepts/data-mapping#%E8%BF%87%E6%BB%A4%E5%99%A8 to learn more Filter.

Use filters in chain

Using a single filter may not meet all your needs. Fortunately, amis supports the use of filters in series, and the value of the previous filter will be used as the input parameter of the next filter for the next step. The syntax is as follows:

1
${xxx|filter1|filter2|...}
1
2
3
4
5
6
7
8
9
10
{
  "type": "page",
  "data": {
    "value": "a,b,c"
  },
  "body": {
    "type": "tpl",
    "tpl": "${value|split|first}"
  }
}

In the above example, ${value|split|first} will go through the following steps:

  • The split filter will be executed first to split the strings a, b, c into arrays ["a", "b", "c"];

  • Then pass the data to the next filter first, execute the filter, and get the first element of the array, which is a

  • Output a

Custom filter

The registerFilter method is exposed in the amis npm package, through which you can add your own filter logic.

like:

1
2
3
4
5
import {registerFilter} from'amis';

registerFilter('count', (input: string) =>
   typeof input ==='string'? input.length: 0
);

After registration, you can pass ${xxx|count} to return the length of the string.

If your filter still supports parameters, you can refer to this example.

1
2
3
4
5
import {registerFilter} from'amis';

registerFilter('my-replace', (input: string, search: string, repalceWith) =>
   typeof input ==='string'? input.replace(search, repalceWith): input
);

The usage is ${xxxx|my-replace:aaaa:bbbb}

Custom filter in JS SDK

1
2
3
4
5
let amisLib = amisRequire('amis');

amisLib.registerFilter('count', function (input) {
   return typeof input ==='string'? input.length: 0;
});

References

[1] Data Mapping | amis - 低代码前端框架 - https://baidu.github.io/amis/zh-CN/docs/concepts/data-mapping

[2] Template | amis - 低代码前端框架 - https://baidu.github.io/amis/zh-CN/docs/concepts/template

[2] Data Domain and Data Chain | amis - 低代码前端框架 - https://baidu.github.io/amis/zh-CN/docs/concepts/datascope-and-datachain

[3] API | amis - 低代码前端框架 - https://baidu.github.io/amis/zh-CN/docs/types/api

[6] baidu/amis: 前端低代码框架，通过 JSON 配置就能生成各种页面。 - https://github.com/baidu/amis

[7] amis - 低代码前端框架 - https://baidu.gitee.io/amis/