0
# Flash Messages and Utilities
1

2
Flash message rendering with Bootstrap alert styling, comprehensive icon rendering system, and utility functions for static resource management and template helpers.
3

4
## Capabilities
5

6
### Flash Message Rendering
7

8
Render Flask flash messages as styled Bootstrap alerts with dismissible options and category mapping.
9

10
```python { .api }
11
def render_messages(messages=None, container=False, 
12
                   transform={'critical': 'danger', 'error': 'danger', 'info': 'info',
13
                            'warning': 'warning', 'debug': 'primary', 'notset': 'primary',
14
                            'message': 'primary'}, 
15
                   default_category='primary', dismissible=False, dismiss_animate=False):
16
    """
17
    Render Flask flash messages as Bootstrap alerts.
18
    
19
    Args:
20
        messages (list): Custom message list (defaults to get_flashed_messages())
21
        container (bool): Wrap messages in container div
22
        transform (dict): Message category to Bootstrap alert class mapping
23
        default_category (str): Default category for messages without category
24
        dismissible (bool): Add close button to alerts
25
        dismiss_animate (bool): Add fade animation to dismissible alerts
26
        
27
    Returns:
28
        Rendered HTML alerts with Bootstrap styling
29
        
30
    Message Categories:
31
        - critical/error → danger (red alert)
32
        - warning → warning (yellow alert)  
33
        - info → info (blue alert)
34
        - debug/notset/message → primary (default color)
35
        
36
    Bootstrap Versions:
37
        - Bootstrap 4: Uses btn-close button
38
        - Bootstrap 5: Uses updated btn-close with data-bs-dismiss
39
        
40
    Config Variables Used:
41
        BOOTSTRAP_MSG_CATEGORY: Default message category
42
    """
43
```
44

45
### Icon Rendering System
46

47
Comprehensive icon rendering supporting both SVG and font-based Bootstrap Icons with customization options.
48

49
```python { .api }
50
def render_icon(name, size='1em', color=None, title=None, desc=None, 
51
               classes=None, font=False):
52
    """
53
    Render Bootstrap icons as SVG or font icons.
54
    
55
    Args:
56
        name (str): Bootstrap icon name (e.g., 'heart-fill', 'star', 'check-circle')
57
        size (str): Icon size CSS value (default: '1em')
58
        color (str): Icon color - Bootstrap color name or CSS color value
59
        title (str): Accessibility title attribute
60
        desc (str): Accessibility description for screen readers
61
        classes (str): Additional CSS classes for icon element
62
        font (bool): Use font icons instead of SVG (default: False)
63
        
64
    Returns:
65
        Rendered HTML icon element (SVG or font-based)
66
        
67
    Color Options:
68
        - Bootstrap colors: 'primary', 'secondary', 'success', 'danger', 'warning', 'info'
69
        - CSS colors: '#ff0000', 'red', 'rgb(255,0,0)', etc.
70
        
71
    Size Options:
72
        - Relative: '1em', '1.5em', '2em'
73
        - Absolute: '16px', '24px', '32px'
74
        - Bootstrap utilities: 'fs-1', 'fs-2', etc.
75
        
76
    Icon Types:
77
        - SVG (default): Scalable, customizable, better performance
78
        - Font: Compatible with older browsers, easier CSS styling
79
        
80
    Config Variables Used:
81
        BOOTSTRAP_ICON_SIZE: Default icon size
82
        BOOTSTRAP_ICON_COLOR: Default icon color
83
        BOOTSTRAP_ICON_USE_FONT: Default icon type (SVG vs font)
84
    """
85
```
86

87
### Static Resource Rendering
88

89
Render static resource links with support for CSS, JavaScript, and favicon files.
90

91
```python { .api }
92
def render_static(type, filename_or_url, local=True):
93
    """
94
    Render static resource links (CSS, JS, favicon).
95
    
96
    Args:
97
        type (str): Resource type - 'css', 'js', or 'icon'
98
        filename_or_url (str): Static file path or external URL
99
        local (bool): Use Flask url_for for local files (default: True)
100
        
101
    Returns:
102
        Rendered HTML link/script tag for resource
103
        
104
    Resource Types:
105
        - css: Generates <link rel="stylesheet"> tag
106
        - js: Generates <script src=""> tag  
107
        - icon: Generates <link rel="icon"> tag for favicon
108
        
109
    Usage:
110
        - Local files: Uses Flask's url_for('static', filename=...)
111
        - External URLs: Uses URL directly without url_for
112
    """
113
```
114

115
### URL Generation Helper
116

117
Utility function for URL generation with parameter passing.
118

119
```python { .api }
120
def arg_url_for(endpoint, base):
121
    """
122
    Generate URLs with endpoint and base parameters.
123
    
124
    Args:
125
        endpoint (str): Flask endpoint name
126
        base (dict): Base parameters for URL generation
127
        
128
    Returns:
129
        Generated URL with parameters
130
        
131
    Usage:
132
        - Passes additional keyword arguments to url_for()
133
        - Useful for complex URL generation in templates
134
    """
135
```
136

137
## Flash Message Features
138

139
### Message Categories
140

141
Bootstrap-Flask maps Flask message categories to Bootstrap alert types:
142

143
```python
144
# Default category mapping
145
transform = {
146
    'critical': 'danger',   # Red alert
147
    'error': 'danger',      # Red alert
148
    'info': 'info',         # Blue alert
149
    'warning': 'warning',   # Yellow alert
150
    'debug': 'primary',     # Theme color alert
151
    'notset': 'primary',    # Theme color alert
152
    'message': 'primary'    # Theme color alert
153
}
154
```
155

156
### Dismissible Alerts
157

158
Messages can be made dismissible with close buttons:
159

160
```html
161
<!-- Non-dismissible -->
162
{{ render_messages() }}
163

164
<!-- Dismissible -->
165
{{ render_messages(dismissible=True) }}
166

167
<!-- Dismissible with fade animation -->
168
{{ render_messages(dismissible=True, dismiss_animate=True) }}
169
```
170

171
### Container Wrapping
172

173
Messages can be wrapped in a container for layout purposes:
174

175
```html
176
<!-- Wrapped in container -->
177
{{ render_messages(container=True) }}
178
```
179

180
## Icon System Features
181

182
### Icon Naming
183

184
Bootstrap Icons use descriptive names with optional fill variants:
185

186
- Basic icons: `heart`, `star`, `check`, `x`
187
- Filled icons: `heart-fill`, `star-fill`, `check-circle-fill`
188
- Directional: `arrow-up`, `arrow-down`, `chevron-left`, `chevron-right`
189
- UI elements: `gear`, `house`, `person`, `envelope`
190

191
### Color System
192

193
Icons support both Bootstrap color names and custom CSS colors:
194

195
```html
196
<!-- Bootstrap colors -->
197
{{ render_icon('heart-fill', color='danger') }}
198
{{ render_icon('check-circle', color='success') }}
199

200
<!-- Custom colors -->
201
{{ render_icon('star', color='#ffc107') }}
202
{{ render_icon('info-circle', color='rgb(13, 202, 240)') }}
203
```
204

205
### Size Management
206

207
Icons can be sized using various CSS units:
208

209
```html
210
<!-- Relative sizing -->
211
{{ render_icon('home', size='1.5em') }}
212

213
<!-- Absolute sizing -->
214
{{ render_icon('gear', size='24px') }}
215

216
<!-- Bootstrap font size utilities -->
217
{{ render_icon('person', classes='fs-3') }}
218
```
219

220
## Usage Examples
221

222
### Basic Flash Messages
223

224
```python
225
# Flask view
226
@app.route('/login', methods=['POST'])
227
def login():
228
    if authenticate_user(request.form):
229
        flash('Successfully logged in!', 'success')
230
        return redirect(url_for('dashboard'))
231
    else:
232
        flash('Invalid credentials. Please try again.', 'error')
233
        return render_template('login.html')
234
```
235

236
```html
237
<!-- Template -->
238
{% from 'bootstrap5/utils.html' import render_messages %}
239

240
<div class="container">
241
    {{ render_messages() }}
242
    
243
    <!-- Login form -->
244
</div>
245
```
246

247
### Customized Flash Messages
248

249
```html
250
{{ render_messages(
251
    dismissible=True,
252
    dismiss_animate=True,
253
    container=True,
254
    transform={
255
        'success': 'success',
256
        'error': 'danger', 
257
        'warning': 'warning',
258
        'info': 'info'
259
    }
260
) }}
261
```
262

263
### Custom Message Display
264

265
```python
266
# Custom messages instead of Flask flash
267
custom_messages = [
268
    ('Welcome to our site!', 'info'),
269
    ('Your trial expires in 3 days.', 'warning')
270
]
271
```
272

273
```html
274
{{ render_messages(messages=custom_messages, dismissible=True) }}
275
```
276

277
### Icon Usage Examples
278

279
```html
280
{% from 'base/utils.html' import render_icon %}
281

282
<!-- Basic icons -->
283
<h3>{{ render_icon('house') }} Home</h3>
284
<p>{{ render_icon('envelope') }} Contact us</p>
285

286
<!-- Styled icons -->
287
<button class="btn btn-success">
288
    {{ render_icon('check-circle', color='white') }} Save
289
</button>
290

291
<button class="btn btn-danger">
292
    {{ render_icon('trash', color='white') }} Delete
293
</button>
294

295
<!-- Large icons -->
296
<div class="text-center">
297
    {{ render_icon('trophy-fill', size='4em', color='warning') }}
298
    <h2>Congratulations!</h2>
299
</div>
300
```
301

302
### Icon with Accessibility
303

304
```html
305
{{ render_icon('info-circle', 
306
    title='Information',
307
    desc='Additional information is available',
308
    color='info'
309
) }}
310
```
311

312
### Font Icons vs SVG Icons
313

314
```html
315
<!-- SVG icons (default) -->
316
{{ render_icon('heart', font=False) }}
317

318
<!-- Font icons -->
319
{{ render_icon('heart', font=True) }}
320
```
321

322
### Static Resource Loading
323

324
```html
325
{% from 'base/utils.html' import render_static %}
326

327
<!-- Custom CSS -->
328
{{ render_static('css', 'custom.css') }}
329

330
<!-- External CSS -->
331
{{ render_static('css', 'https://fonts.googleapis.com/css2?family=Roboto', local=False) }}
332

333
<!-- Custom JavaScript -->
334
{{ render_static('js', 'app.js') }}
335

336
<!-- Favicon -->
337
{{ render_static('icon', 'favicon.ico') }}
338
```
339

340
### Alert Layouts
341

342
```html
343
<!-- Stacked alerts -->
344
<div class="alerts-container">
345
    {{ render_messages() }}
346
</div>
347

348
<!-- Fixed position alerts -->
349
<div class="position-fixed top-0 end-0 p-3" style="z-index: 1050">
350
    {{ render_messages(dismissible=True, dismiss_animate=True) }}
351
</div>
352

353
<!-- Toast-style notifications -->
354
<div class="toast-container position-fixed top-0 end-0 p-3">
355
    {% for message in get_flashed_messages(with_categories=True) %}
356
        <div class="toast show" role="alert">
357
            <div class="toast-header">
358
                {{ render_icon('info-circle', color=message[0]) }}
359
                <strong class="me-auto">Notification</strong>
360
                <button type="button" class="btn-close" data-bs-dismiss="toast"></button>
361
            </div>
362
            <div class="toast-body">
363
                {{ message[1] }}
364
            </div>
365
        </div>
366
    {% endfor %}
367
</div>
368
```
369

370
### Icon Button Patterns
371

372
```html
373
<!-- Icon buttons -->
374
<button class="btn btn-outline-primary">
375
    {{ render_icon('download') }} Download
376
</button>
377

378
<button class="btn btn-link p-0">
379
    {{ render_icon('pencil-square', color='primary') }}
380
</button>
381

382
<!-- Icon-only buttons -->
383
<button class="btn btn-sm btn-outline-secondary" title="Edit">
384
    {{ render_icon('pencil') }}
385
</button>
386

387
<button class="btn btn-sm btn-outline-danger" title="Delete">
388
    {{ render_icon('trash') }}
389
</button>
390
```
391

392
### Status Indicators
393

394
```html
395
<!-- Status badges with icons -->
396
<span class="badge bg-success">
397
    {{ render_icon('check-circle', color='white', size='0.8em') }} Active
398
</span>
399

400
<span class="badge bg-warning">
401
    {{ render_icon('clock', color='white', size='0.8em') }} Pending
402
</span>
403

404
<span class="badge bg-danger">
405
    {{ render_icon('x-circle', color='white', size='0.8em') }} Inactive
406
</span>
407
```
408

409
### List Items with Icons
410

411
```html
412
<ul class="list-unstyled">
413
    <li class="mb-2">
414
        {{ render_icon('check', color='success') }} Feature A included
415
    </li>
416
    <li class="mb-2">
417
        {{ render_icon('check', color='success') }} Feature B included
418
    </li>
419
    <li class="mb-2">
420
        {{ render_icon('x', color='danger') }} Feature C not included
421
    </li>
422
</ul>
423
```
424

425
### Navigation with Icons
426

427
```html
428
<nav class="nav nav-pills flex-column">
429
    <a class="nav-link" href="/dashboard">
430
        {{ render_icon('speedometer2') }} Dashboard
431
    </a>
432
    <a class="nav-link" href="/users">
433
        {{ render_icon('people') }} Users
434
    </a>
435
    <a class="nav-link" href="/settings">
436
        {{ render_icon('gear') }} Settings
437
    </a>
438
</nav>
439
```
440

441
## Configuration Variables
442

443
Several Flask configuration variables control utility behavior:
444

445
```python
446
# Flash message defaults
447
app.config['BOOTSTRAP_MSG_CATEGORY'] = 'primary'
448

449
# Icon defaults  
450
app.config['BOOTSTRAP_ICON_SIZE'] = '1em'
451
app.config['BOOTSTRAP_ICON_COLOR'] = None
452
app.config['BOOTSTRAP_ICON_USE_FONT'] = False
453
```
454

455
These settings provide default values that can be overridden at the template level.