1# HML
2
3
4HML is an HTML-like language that allows you to build pages based on components and events. HML pages provide advanced capabilities such as data binding, event binding, loop rendering, conditional rendering, and logic control.
5
6
7## Page Structure
8
9
10```html
11<!-- xxx.hml -->
12<div class="item-container">
13  <text class="item-title">Image Show</text>
14  <div class="item-content">
15    <image src="/common/xxx.png" class="image"></image>
16  </div>
17</div>
18```
19
20
21## Data Binding
22
23
24```html
25<!-- xxx.hml -->
26<div class="item-container">
27  <text>{{content}}</text>            <!-- Display Hello World!-->
28  <text>{{key1}} {{key2}}</text>       <!-- Display Hello World-->
29  <text>key1 {{key1}}</text>           <!-- Display key1 Hello-->
30  <text>{{flag1 && flag2}}</text>      <!-- Display false-->
31  <text>{{flag1 || flag2}}</text>      <!-- Display true-->
32  <text>{{!flag1}}</text>              <!-- Display false-->
33</div>
34```
35
36Declare the variables used in the XML file for service widgets in the **data** field in the JSON file.
37
38```json
39{
40  "data": {
41    "content": "Hello World!",
42    "key1": "Hello",
43    "key2": "World",
44    "flag1": true,
45    "flag2": false
46  }
47}
48```
49
50>  **NOTE**
51>  - When using data binding, you can use the object operator or array operator on a key to access the bound data, for example, **{{key.value}}** and **{{key[0]}}**.
52>
53>  - String concatenation, logical operations, and ternary expressions are supported.
54>   - String concatenation:
55>      - A variable can be followed by another variable, for example, **{{key1}}{{key2}}**.
56>      - A variable can also be followed by a constant, for example, **"my name is {{name}}, i am from {{city}}."    "key1 {{key1}}"**.
57>   - Logical operations:
58>      - AND: {{flag1 && flag2}} (The AND operation can only be performed on two Boolean variables.)
59>      - OR: {{flag1 || flag2}} (The OR operation can only be performed on two Boolean variables.)
60>      - NOT: {{! flag1}} (The NOT operation can only be performed on a Boolean variable.)
61>   - Ternary expressions:
62>      - {{flag? key1: key2}} (**flag** is a Boolean variable. **key1** and **key2** can be variables or constants.)
63>   - Notes
64>      - The default value is **false** when a Boolean-specific operation is performed on a non-Boolean variable.
65>      - The preceding variable and operation parsing do not support nesting.
66
67## Event Binding
68
69Declare the events for service widgets in the **actions** field in the JSON file. Service widgets support the common click event only. The event must be declared explicitly. The event definition must contain the **action** field to describe the event type. Service widgets support redirection events (**router**) and message events (**message**). A redirection event is used for switching to the application (the widget provider). A message event can transfer custom information to the widget provider. Event parameters can be variables, which are defined using **{{}}**. If the **params** field is defined in the redirection event, you can pass **params** to the **onStart** method (as **intent**) of the started application to access the value.
70
71- Redirection event properties
72
73  Define the **abilityName** and **params** fields to implement direct redirection to the target application.
74
75  | Selector        | Example    | Default Value     | Description                                    |
76  | ----------- | ------ | -------- | ---------------------------------------- |
77  | action      | string | "router" | Event type.<br>- **"router"**: redirection event.<br>- **"message"**: message event.|
78  | abilityName | string | -        | Name of the ability to redirect to.                             |
79  | params      | Object | -        | Additional parameter passed during the redirection.                            |
80
81
82  ```json
83  {
84    "data": {
85      "mainAbility": "xxx.xxx.xxx"
86    },
87    "actions": {
88      "routerEvent": {
89        "action": "router",
90        "abilityName": "{{mainAbility}}",
91        "params":{}
92      }
93    }
94  }
95  ```
96
97- Message event properties
98
99  | Selector   | Example    | Default Value    | Description        |
100  | ------ | ------ | ------- | ------------ |
101  | action | string | message | Event type.     |
102  | params | Object | -       | Additional parameter passed during the redirection.|
103
104
105  ```json
106  {
107    "actions": {
108      "activeEvent": {
109        "action": "message",
110        "params": {}
111      }
112    }
113  }
114  ```
115
116- The following example shows two styles for binding the redirection event and message event:
117
118  ```html
119  <!-- xxx.hml -->
120  <div>
121    <!-- Regular format -->
122    <div onclick="activeEvent"></div>
123    <!-- Abbreviation -->
124    <div @click="activeEvent"></div>
125  </div>
126  ```
127
128
129## Loop Rendering
130
131
132```html
133<!-- xxx.hml -->
134<div class="array-container">
135  <!-- div loop rendering -->
136  <!-- By default, $item indicates the element in the array, and $idx indicates the index of the element in the array. -->
137  <div for="{{array}}" tid="id">
138    <text>{{$item.name}}</text>
139  </div>
140  <!-- Define the name for an element variable. -->
141  <div for="{{value in array}}" tid="id">
142    <text>{{value.name}}</text>
143  </div>
144  <!-- Define an element variable and its index name. -->
145  <div for="{{(index, value) in array}}" tid="id">
146    <text>{{value.name}}</text>
147  </div>
148</div>
149```
150
151
152```json
153{
154  "data": {
155    "array": [
156      {"id": 1, "name": "jack", "age": 18},
157      {"id": 2, "name": "tony", "age": 18}
158    ]
159  }
160}
161```
162
163The **tid** attribute accelerates the **for** loop and improves the re-rendering efficiency when data in a loop changes. The **tid** attribute specifies the unique ID of each element in the array. If it is not specified, the index of each element in the array is used as the ID. For example, **tid="id"** indicates that the **id** attribute of each element is its unique ID. The **for** loop supports the following statements:
164
165- for="array": **array** is an array object, whose element variable is **$item** by default.
166
167- for="v in array": **v** is a custom element variable, whose index is **$idx** by default.
168
169- for="(i, v) in array": **i** indicates the element index, and **v** indicates the element variable. All elements of the array object will be looped through.
170
171>  **NOTE**
172>  - Each element in the array must have the data attribute specified by **tid**. Otherwise, an exception may occur.
173>
174>  - The attribute specified by **tid** in the array must be unique. Otherwise, performance loss occurs. In the above example, only **id** and **name** can be used as **tid** because they are unique fields.
175>
176>  - The **tid** field does not support expressions.
177>
178>  - Nested **for** loops are not supported.
179>
180>  - When you use the **for** loop, ensure that the objects contained in the array are of the same type.
181
182
183## Conditional Rendering
184
185There are two ways to implement conditional rendering: **if-elif-else** or **show**.
186
187The **if-elif-else** statements must be used in sibling nodes. Otherwise, the compilation fails. The following example uses both ways to implement conditional rendering:
188
189
190```html
191<!-- xxx.hml -->
192<div>
193  <text if="{{show}}"> Hello-TV </text>
194  <text elif="{{display}}"> Hello-Wearable </text>
195  <text else> Hello-World </text>
196</div>
197```
198
199
200```json
201{
202  "data": {
203    "show": false,
204    "display": true
205  }
206}
207```
208
209If **show** is **true**, the node is rendered properly; if it is **false**, the display style will be **none**.
210
211
212```html
213<!-- xxx.hml -->
214<text show="{{visible}}"> Hello World </text>
215```
216
217
218```json
219{
220  "data": {
221    "visible": false
222  }
223}
224```
225
226
227## Logic Control Block
228
229**\<block>** makes loop rendering and conditional rendering more flexible. A **\<block>** will not be compiled as a real component. The **\<block>** supports the **if** attribute only.
230
231
232```html
233<!-- xxx.hml -->
234<div>
235  <block if="{{show}}">
236    <text>Hello</text>
237    <text>World</text>
238  </block>
239</div>
240```
241
242
243```json
244{
245  "data": {
246    "show": true
247  }
248}
249```
250