LOGO

San API

Edit

Component Initialization

defineComponent

Description: defineComponent({Object}propertiesAndMethods)

Explanation:

Method. A shortcut to define components. Refer to Component Definition for details.

Usage:

1
2
3
4
5
6
7
8
9
var MyApp = san.defineComponent({
    template: '<ul><li s-for="item in list">{{item}}</li></ul>',

    initData: function () {
        return {
            list: ['san', 'er', 'esui', 'etpl', 'esl']
        };
    }
});

compileComponent

Version: >= 3.3.0 & < 3.9.0

Description: {void} compileComponent({Function}ComponentClass)

Explanation:

Method. Compile a component. The compilation mainly consists of parsing the template into ANodes and call .defineComponent() for plain object within the component.

Components will compile automatically on its first instantiation. Typically you won’t need to call this API to compile components manually, but it’s provided anyway in case you need ahead-of-time compilation.

Usage:

1
2
3
4
5
6
7
8
9
10
11
12
13
var MyApp = san.defineComponent({
    template: '<ul><li s-for="item in list">{{item}}</li></ul>',

    initData: function () {
        return {
            list: ['san', 'er', 'esui', 'etpl', 'esl']
        };
    }
});

typeof MyApp.prototype.aNode // undefined
san.compileComponent(MyApp);
typeof MyApp.prototype.aNode // object

Component

Type: Function

Explanation:

Property. The component class, from which the newly defined components will inherit. For most cases the san.defineComponent method should be used instead. Refer to Component Definition for details.

Usage:

1
2
3
4
5
6
7
8
9
10
import {Component} from 'san';

class HelloComponent extends Component {

    static template = '<p>Hello {{name}}!</p>';

    initData() {
        return {name: 'San'}
    }
}

inherits

Description: inherits({Function}SubClass, {Function}SuperClass)

Explanation:

Method. An util method to implement inheritance, which is the case when defining components (inherit from san.Component). Usually, to define a component we use san.defineComponent in ES5 and extends in ESNext.

It is not recommended to use .inherits() in most cases. Refer to Component Definition for details.

Server-Side Rendering

compileToRenderer

Version:>= 3.1.0

Description: {function(Object):string} compileToRenderer({Function}ComponentClass)

Explanation:

Method. Compile a component class into a renderer method. Refer to Server-Side Rendering for details.

Usage:

1
2
3
4
5
6
7
8
9
10
11
var MyApp = san.defineComponent({
    template: '<ul><li s-for="item in list">{{item}}</li></ul>',

    initData: function () {
        return {
            list: ['san', 'er', 'esui', 'etpl', 'esl']
        };
    }
});

var render = san.compileToRenderer(MyApp);

compileToSource

Version:>= 3.1.0

Description: {string} compileToRenderer({Function}ComponentClass)

Explanation:

Method. Compile a component class into a source file containing the renderer method. Refer to Server-Side Rendering for details.

Usage:

1
2
3
4
5
6
7
8
9
10
11
12
var MyApp = san.defineComponent({
    template: '<ul><li s-for="item in list">{{item}}</li></ul>',

    initData: function () {
        return {
            list: ['san', 'er', 'esui', 'etpl', 'esl']
        };
    }
});

var renderSource = san.compileToSource(MyApp);
fs.writeFileSync('your-module.js', 'exports = module.exports = ' + renderSource, 'UTF-8');

Template Compilation

ExprType

Version:>= 3.0.3

Type: Object

Explanation:

Property. An enum value representing the expression type, which helps to understand and use the compile output produced by San. Refer to ANode for details.

parseExpr

Version:>= 3.0.3

Description: {Object} parseExpr({string}source)

Explanation:

Method. Parse the source string into an expression object. Refer to ANode for details.

Usage:

1
2
3
4
5
6
7
8
9
10
11
12
13
var expr = san.parseExpr('!user.isLogin');
/*
expr = {
    type: ExprType.UNARY,
    expr: {
        type: ExprType.ACCESSOR,
        paths: [
            {type: ExprType.STRING, value: 'user'},
            {type: ExprType.STRING, value: 'isLogin'}
        ]
    }
}
*/

parseTemplate

Version:>= 3.0.3

Description: {ANode} parseTemplate({string}source)

Explanation:

Method. Parse the source string into an ANode object. The San template engine can be reused via this method. Refer to ANode for details.

Usage:

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
var aNode = san.parseTemplate('<p>Hello {{name}}!</p>');
/*
aNode = {
    "directives": {},
    "props": [],
    "events": [],
    "children": [
        {
            "directives": {},
            "props": [],
            "events": [],
            "children": [
                {
                    "textExpr": {
                        "type": 7,
                        "segs": [
                            {
                                "type": 1,
                                "value": "Hello "
                            },
                            {
                                "type": 5,
                                "expr": {
                                    "type": 4,
                                    "paths": [
                                        {
                                            "type": 1,
                                            "value": "name"
                                        }
                                    ]
                                },
                                "filters": []
                            }
                        ]
                    }
                }
            ],
            "tagName": "p"
        }
    ]
}
*/

parseComponentTemplate

Version: >= 3.9.0

Description: {ANode} parseComponentTemplate({Function}ComponentClass)

Explanation:

Method. Parse component template into ANode objects. Different from parseTemplate, this method extracts the first child node, attaches id/style/class attributes to it, and returns it as the root. Basically, parseComponentTemplate parses the template the same way as san parses component in runtime.

Usage:

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
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
var MyComponent = san.defineComponent({
    template: '<p>Hello {{name}}</p>'
});
var aNode = san.parseComponentTemplate(MyComponent);
/* aNode
{
    "directives": {},
    "props": [
        {
            "name": "class",
            "expr": {
                "type": 5,
                "expr": {
                    "type": 4,
                    "paths": [
                        {
                            "type": 1,
                            "value": "class"
                        }
                    ]
                },
                "filters": [
                    {
                        "type": 6,
                        "args": [],
                        "name": {
                            "type": 4,
                            "paths": [
                                {
                                    "type": 1,
                                    "value": "_class"
                                }
                            ]
                        }
                    }
                ]
            }
        },
        {
            "name": "style",
            "expr": {
                "type": 5,
                "expr": {
                    "type": 4,
                    "paths": [
                        {
                            "type": 1,
                            "value": "style"
                        }
                    ]
                },
                "filters": [
                    {
                        "type": 6,
                        "args": [],
                        "name": {
                            "type": 4,
                            "paths": [
                                {
                                    "type": 1,
                                    "value": "_style"
                                }
                            ]
                        }
                    }
                ]
            }
        },
        {
            "name": "id",
            "expr": {
                "type": 4,
                "paths": [
                    {
                        "type": 1,
                        "value": "id"
                    }
                ]
            }
        }
    ],
    "events": [],
    "children": [
        {
            "textExpr": {
                "type": 7,
                "segs": [
                    {
                        "type": 1,
                        "value": "Hello "
                    },
                    {
                        "type": 5,
                        "expr": {
                            "type": 4,
                            "paths": [
                                {
                                    "type": 1,
                                    "value": "name"
                                }
                            ]
                        },
                        "filters": []
                    }
                ]
            }
        }
    ],
    "tagName": "p"
}
*/

Data

Data container and expression evaluator in San components are also exposed. These classes can be useful to handle component-independent data such as application state.

Data

Version:>= 3.5.6

Type: Class Function

Explanation:

Data Container provides get, set, splice, push, pop, unshift, shift, merge and apply methods. Refer to Data Manipulation for details.

change event is fired when the data is changed via data manipulation methods. Handlers for the change event can be registered and unregistered via listen and unlisten methods respectively.

1
2
3
4
5
6
7
8
9
10
11
var data = new san.Data({
    num1: 1,
    num2: 2
});

data.listen(function (change) {
    console.log(change.value);
});

data.set('num2', 10);
// console 10

evalExpr

Version:>= 3.5.6

Description: {*} evalExpr({Object}expr, {Data}data, {Component=}owner)

Explanation:

Method. evalExpr is used to evaluate the value of an expression.

  • expr can be obtained via parseExpr method. For the supported expression types, refer to Expression
  • data can be either component’s data object, or any data object obtained by new Data
  • owner is used for evaluating filters in the expression, required when there’re custom filters in the expression, optional otherwise.
1
2
3
4
5
6
7
var data = new san.Data({
    num1: 1,
    num2: 2
});

san.evalExpr(san.parseExpr('num1 + num2'), data)
// console 3

Others

debug

Type: boolean

Explanation:

Property. Whether or not to enable debug functionalities. Before using Chrome DevTools to debug your San application, make sure the following conditions are matched:

  • the debug property of San module is set to true
  • the San loaded in the current page is built with DevTools functionality. Refer to San releases for details

version

Type: string

Explanation:

Property. The San version number.

LifeCycle

Version: < 3.3.0 (deprecated)

Type: Function

Explanation:

Property. Lifecycle Class is useful when you need to render and update components manually.

LifeCycle defines the following lifecycle states, some of which are mutually exclusive. In detail:

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
{
    compiled: {
        value: 1
    },

    inited: {
        value: 2
    },

    created: {
        value: 3
    },

    attached: {
        value: 4,
        mutex: 'detached'
    },

    detached: {
        value: 5,
        mutex: 'attached'
    },

    disposed: {
        value: 6,
        mutex: '*'
    }
}

The current state can be set via the .set() method of LifeCycle class, and can be tested via the is method.

Usage:

1
2
3
4
5
6
7
var lifeCycle = new san.LifeCycle();

lifeCycle.set('attached');
lifeCycle.is('attached'); // true

lifeCycle.set('detached');
lifeCycle.is('attached'); // false
© 2021 Baidu EFE