0
# Template System
1

2
The template system provides flexible formatting control through moment tokens, escape sequences, auto-localization markers, and dynamic template functions.
3

4
## Capabilities
5

6
### Moment Tokens
7

8
Duration values are represented using moment token characters that correspond to time units.
9

10
```javascript { .api }
11
// Duration tokens (case-insensitive alternatives where noted):
12
// Y or y: years
13
// M: months (no alternative - lowercase 'm' is minutes)
14
// W or w: weeks  
15
// D or d: days
16
// H or h: hours
17
// m: minutes (lowercase only)
18
// s: seconds (lowercase only)
19
// S: milliseconds (uppercase only)
20
```
21

22
**Usage Examples:**
23

24
```javascript
25
var duration = moment.duration({
26
    years: 1,
27
    months: 2, 
28
    days: 3,
29
    hours: 4,
30
    minutes: 5,
31
    seconds: 6,
32
    milliseconds: 789
33
});
34

35
// Basic token usage
36
duration.format("y M d h m s S");
37
// "1 2 3 4 5 6 789"
38

39
// Case variations where available
40
duration.format("Y y W w D d H h");
41
// "1 1 0 0 3 3 4 4"
42
```
43

44
### Token Length and Padding
45

46
Token length controls zero-padding for consistent output formatting.
47

48
```javascript { .api }
49
// Single token: no padding
50
// Multiple tokens: zero-padded to token length
51
// Examples: h vs hh vs hhh
52
```
53

54
**Usage Examples:**
55

56
```javascript
57
var duration = moment.duration(5, "minutes");
58

59
// Different padding levels
60
duration.format("m");      // "5"
61
duration.format("mm");     // "05" 
62
duration.format("mmm");    // "005"
63
duration.format("mmmm");   // "0005"
64

65
// Common time format patterns
66
moment.duration(3661, "seconds").format("h:mm:ss");    // "1:01:01"
67
moment.duration(3661, "seconds").format("hh:mm:ss");   // "01:01:01"
68

69
// Large value padding
70
moment.duration(1234, "minutes").format("hh:mm");      // "20:34"
71
moment.duration(1234, "minutes").format("hhh:mm");     // "020:34"
72
```
73

74
### Multiple Token Instances
75

76
Tokens can appear multiple times in a template, but all instances must share the same length.
77

78
```javascript
79
var duration = moment.duration(15, "seconds");
80

81
// All instances use the length of the first occurrence
82
duration.format("ssss sss ss s");        // "0015 0015 0015 0015"
83
duration.format("s ss sss ssss");        // "15 15 15 15"
84

85
// Mixed lengths in time formats
86
duration.format("h:mm h:m");             // "0:00 0:0" (mm forces 2-digit, m stays 1-digit)
87
```
88

89
### Milliseconds Special Case
90

91
Token length of 2 for milliseconds creates a special truncated output for timer displays.
92

93
```javascript
94
// SS token: pad to 3 digits, then truncate from left to show 2 digits
95
moment.duration(9, "milliseconds").format("mm:ss:SS");     // "00:00:00"
96
moment.duration(10, "milliseconds").format("mm:ss:SS");    // "00:00:01"
97
moment.duration(999, "milliseconds").format("mm:ss:SS");   // "00:00:99"
98
moment.duration(1011, "milliseconds").format("mm:ss:SS");  // "00:01:01"
99

100
// Compare with normal S and SSS tokens
101
moment.duration(1011, "milliseconds").format("S");         // "11"
102
moment.duration(1011, "milliseconds").format("SSS");       // "011"
103
```
104

105
### Escape Sequences
106

107
Square brackets escape literal text in templates, preventing token interpretation.
108

109
```javascript { .api }
110
// [text] - Escapes text, preventing moment token interpretation
111
// Escaped text appears literally in output
112
```
113

114
**Usage Examples:**
115

116
```javascript
117
var duration = moment.duration(123, "minutes");
118

119
// Basic escaping
120
duration.format("h [hours] m [minutes]");
121
// "2 hours 3 minutes"
122

123
// Escaping prevents token interpretation
124
duration.format("h [h] m [m]");  
125
// "2 h 3 m" (not "2 2 3 3")
126

127
// Complex text escaping
128
duration.format("h [hrs,] m [mins]");
129
// "2 hrs, 3 mins"
130

131
// Escaping special characters
132
duration.format("h[:]mm");
133
// "2:03"
134
```
135

136
### Auto-Localization Markers
137

138
Special markers that are replaced with localized content based on moment locale settings.
139

140
```javascript { .api }
141
// _ (single underscore): replaced with short duration labels
142
// __ (double underscore): replaced with standard duration labels
143
// _HMS_: replaced with localized hour:minute:second template
144
// _HM_: replaced with localized hour:minute template  
145
// _MS_: replaced with localized minute:second template
146
```
147

148
**Usage Examples:**
149

150
```javascript
151
// Unit label auto-localization
152
moment.duration(2, "minutes").format("m _");      // "2 mins"
153
moment.duration(2, "minutes").format("m __");     // "2 minutes"
154
moment.duration(1, "minute").format("m __");      // "1 minute" (auto-pluralized)
155

156
// Time notation templates
157
moment.duration(3661, "seconds").format("_HMS_"); // "1:01:01"
158
moment.duration(3661, "seconds").format("_HM_");  // "1:01"
159
moment.duration(61, "seconds").format("_MS_");    // "1:01"
160

161
// Combined usage
162
moment.duration(7322, "seconds").format("_HMS_ [total]");
163
// "2:02:02 total"
164
```
165

166
### Stop Trim Markers
167

168
The asterisk (*) prefix marks tokens where trimming should stop.
169

170
```javascript { .api }
171
// *token - Marks token as stopTrim, preventing further trimming
172
// Equivalent to adding token to stopTrim setting array
173
```
174

175
**Usage Examples:**
176

177
```javascript
178
var duration = moment.duration(23, "minutes");
179

180
// Without stop trim marker
181
duration.format("d[d] h:mm:ss");
182
// "23:00"
183

184
// With stop trim marker on hours
185
duration.format("d[d] *h:mm:ss"); 
186
// "0:23:00"
187

188
// Multiple stop trim markers
189
moment.duration(2, "hours").format("y [years], *d [days], h [hours], *m [minutes], s [seconds]", {
190
    trim: "both"
191
});
192
// "0 days, 2 hours, 0 minutes"
193
```
194

195
## Template Functions
196

197
### Dynamic Template Generation
198

199
Template functions enable runtime template selection based on duration values or other conditions.
200

201
```javascript { .api }
202
/**
203
 * Template function executed with 'this' bound to settings object
204
 * @returns Template string to use for formatting
205
 */
206
function templateFunction(): string;
207

208
// Available context:
209
// this.duration - The duration being formatted
210
// this.types - Array of token types
211
// All other settings properties available via 'this'
212
```
213

214
**Usage Examples:**
215

216
```javascript
217
function adaptiveTemplate() {
218
    var duration = this.duration;
219
    var totalSeconds = duration.asSeconds();
220
    
221
    if (totalSeconds < 60) {
222
        return "s [seconds]";
223
    } else if (totalSeconds < 3600) {
224
        return "m:ss";
225
    } else if (totalSeconds < 86400) {
226
        return "h:mm:ss";
227
    } else {
228
        return "d [days], h:mm:ss";
229
    }
230
}
231

232
// Usage with different duration magnitudes
233
moment.duration(30, "seconds").format(adaptiveTemplate);
234
// "30 seconds"
235

236
moment.duration(90, "seconds").format(adaptiveTemplate);  
237
// "1:30"
238

239
moment.duration(3661, "seconds").format(adaptiveTemplate);
240
// "1:01:01"
241

242
moment.duration(90061, "seconds").format(adaptiveTemplate);
243
// "1 days, 1:01:01"
244
```
245

246
### Settings-Based Templates
247

248
Template functions can access and modify settings dynamically:
249

250
```javascript
251
function conditionalTemplate() {
252
    var duration = this.duration;
253
    
254
    // Modify settings based on duration
255
    if (duration.asHours() >= 24) {
256
        this.trim = "both";
257
        return "w [weeks], d [days], h [hours]";
258
    } else {
259
        this.trim = "large";
260
        return "h:mm:ss";
261
    }
262
}
263

264
moment.duration(25, "hours").format(conditionalTemplate);
265
// "1 day, 1 hour" (with trim: "both")
266

267
moment.duration(2, "hours").format(conditionalTemplate);
268
// "2:00:00" (with trim: "large")
269
```
270

271
### Access to Token Types
272

273
Template functions can inspect available token types for decision making:
274

275
```javascript
276
function intelligentTemplate() {
277
    var types = this.types; // Available: ["escape", "years", "months", ...]
278
    var duration = this.duration;
279
    
280
    // Check what units the duration actually has
281
    var hasYears = duration.years() > 0;
282
    var hasMonths = duration.months() > 0;
283
    var hasDays = duration.days() > 0;
284
    
285
    if (hasYears || hasMonths) {
286
        return "y [years], M [months], d [days]";
287
    } else if (hasDays) {
288
        return "d [days], h:mm:ss";
289
    } else {
290
        return "h:mm:ss";
291
    }
292
}
293
```
294

295
## Template Processing Order
296

297
Templates are processed in the following sequence:
298

299
1. **Template Function Execution**: If template is a function, execute with settings context
300
2. **Time Template Replacement**: Replace `_HMS_`, `_HM_`, `_MS_` with locale templates
301
3. **Token Parsing**: Parse template for moment tokens and escape sequences
302
4. **Token Association**: Associate text tokens with moment tokens  
303
5. **Value Calculation**: Calculate values for each token type
304
6. **Formatting**: Apply number formatting and localization
305
7. **Trimming**: Apply trimming rules to remove zero-value tokens
306
8. **Label Processing**: Apply auto-localization and pluralization
307
9. **Output Assembly**: Combine tokens with their text to create final output