tessl/pypi-bootstrap-flask

Bootstrap 4 & 5 helper for Flask projects providing Jinja macros for forms, tables, navigation, and utilities.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Flash Messages and Utilities

Name: tessl/pypi-bootstrap-flask
Author: tessl

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

Capabilities

Flash Message Rendering

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

def render_messages(messages=None, container=False, 
                   transform={'critical': 'danger', 'error': 'danger', 'info': 'info',
                            'warning': 'warning', 'debug': 'primary', 'notset': 'primary',
                            'message': 'primary'}, 
                   default_category='primary', dismissible=False, dismiss_animate=False):
    """
    Render Flask flash messages as Bootstrap alerts.
    
    Args:
        messages (list): Custom message list (defaults to get_flashed_messages())
        container (bool): Wrap messages in container div
        transform (dict): Message category to Bootstrap alert class mapping
        default_category (str): Default category for messages without category
        dismissible (bool): Add close button to alerts
        dismiss_animate (bool): Add fade animation to dismissible alerts
        
    Returns:
        Rendered HTML alerts with Bootstrap styling
        
    Message Categories:
        - critical/error → danger (red alert)
        - warning → warning (yellow alert)  
        - info → info (blue alert)
        - debug/notset/message → primary (default color)
        
    Bootstrap Versions:
        - Bootstrap 4: Uses btn-close button
        - Bootstrap 5: Uses updated btn-close with data-bs-dismiss
        
    Config Variables Used:
        BOOTSTRAP_MSG_CATEGORY: Default message category
    """

Icon Rendering System

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

def render_icon(name, size='1em', color=None, title=None, desc=None, 
               classes=None, font=False):
    """
    Render Bootstrap icons as SVG or font icons.
    
    Args:
        name (str): Bootstrap icon name (e.g., 'heart-fill', 'star', 'check-circle')
        size (str): Icon size CSS value (default: '1em')
        color (str): Icon color - Bootstrap color name or CSS color value
        title (str): Accessibility title attribute
        desc (str): Accessibility description for screen readers
        classes (str): Additional CSS classes for icon element
        font (bool): Use font icons instead of SVG (default: False)
        
    Returns:
        Rendered HTML icon element (SVG or font-based)
        
    Color Options:
        - Bootstrap colors: 'primary', 'secondary', 'success', 'danger', 'warning', 'info'
        - CSS colors: '#ff0000', 'red', 'rgb(255,0,0)', etc.
        
    Size Options:
        - Relative: '1em', '1.5em', '2em'
        - Absolute: '16px', '24px', '32px'
        - Bootstrap utilities: 'fs-1', 'fs-2', etc.
        
    Icon Types:
        - SVG (default): Scalable, customizable, better performance
        - Font: Compatible with older browsers, easier CSS styling
        
    Config Variables Used:
        BOOTSTRAP_ICON_SIZE: Default icon size
        BOOTSTRAP_ICON_COLOR: Default icon color
        BOOTSTRAP_ICON_USE_FONT: Default icon type (SVG vs font)
    """

Static Resource Rendering

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

def render_static(type, filename_or_url, local=True):
    """
    Render static resource links (CSS, JS, favicon).
    
    Args:
        type (str): Resource type - 'css', 'js', or 'icon'
        filename_or_url (str): Static file path or external URL
        local (bool): Use Flask url_for for local files (default: True)
        
    Returns:
        Rendered HTML link/script tag for resource
        
    Resource Types:
        - css: Generates <link rel="stylesheet"> tag
        - js: Generates <script src=""> tag  
        - icon: Generates <link rel="icon"> tag for favicon
        
    Usage:
        - Local files: Uses Flask's url_for('static', filename=...)
        - External URLs: Uses URL directly without url_for
    """

URL Generation Helper

Utility function for URL generation with parameter passing.

def arg_url_for(endpoint, base):
    """
    Generate URLs with endpoint and base parameters.
    
    Args:
        endpoint (str): Flask endpoint name
        base (dict): Base parameters for URL generation
        
    Returns:
        Generated URL with parameters
        
    Usage:
        - Passes additional keyword arguments to url_for()
        - Useful for complex URL generation in templates
    """

Flash Message Features

Message Categories

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

# Default category mapping
transform = {
    'critical': 'danger',   # Red alert
    'error': 'danger',      # Red alert
    'info': 'info',         # Blue alert
    'warning': 'warning',   # Yellow alert
    'debug': 'primary',     # Theme color alert
    'notset': 'primary',    # Theme color alert
    'message': 'primary'    # Theme color alert
}

Dismissible Alerts

Messages can be made dismissible with close buttons:

<!-- Non-dismissible -->
{{ render_messages() }}

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

<!-- Dismissible with fade animation -->
{{ render_messages(dismissible=True, dismiss_animate=True) }}

Container Wrapping

Messages can be wrapped in a container for layout purposes:

<!-- Wrapped in container -->
{{ render_messages(container=True) }}

Icon System Features

Icon Naming

Bootstrap Icons use descriptive names with optional fill variants:

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

Color System

Icons support both Bootstrap color names and custom CSS colors:

<!-- Bootstrap colors -->
{{ render_icon('heart-fill', color='danger') }}
{{ render_icon('check-circle', color='success') }}

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

Size Management

Icons can be sized using various CSS units:

<!-- Relative sizing -->
{{ render_icon('home', size='1.5em') }}

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

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

Usage Examples

Basic Flash Messages

# Flask view
@app.route('/login', methods=['POST'])
def login():
    if authenticate_user(request.form):
        flash('Successfully logged in!', 'success')
        return redirect(url_for('dashboard'))
    else:
        flash('Invalid credentials. Please try again.', 'error')
        return render_template('login.html')

<!-- Template -->
{% from 'bootstrap5/utils.html' import render_messages %}

<div class="container">
    {{ render_messages() }}
    
    <!-- Login form -->
</div>

Customized Flash Messages

{{ render_messages(
    dismissible=True,
    dismiss_animate=True,
    container=True,
    transform={
        'success': 'success',
        'error': 'danger', 
        'warning': 'warning',
        'info': 'info'
    }
) }}

Custom Message Display

# Custom messages instead of Flask flash
custom_messages = [
    ('Welcome to our site!', 'info'),
    ('Your trial expires in 3 days.', 'warning')
]

{{ render_messages(messages=custom_messages, dismissible=True) }}

Icon Usage Examples

{% from 'base/utils.html' import render_icon %}

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

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

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

<!-- Large icons -->
<div class="text-center">
    {{ render_icon('trophy-fill', size='4em', color='warning') }}
    <h2>Congratulations!</h2>
</div>

Icon with Accessibility

{{ render_icon('info-circle', 
    title='Information',
    desc='Additional information is available',
    color='info'
) }}

Font Icons vs SVG Icons

<!-- SVG icons (default) -->
{{ render_icon('heart', font=False) }}

<!-- Font icons -->
{{ render_icon('heart', font=True) }}

Static Resource Loading

{% from 'base/utils.html' import render_static %}

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

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

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

<!-- Favicon -->
{{ render_static('icon', 'favicon.ico') }}

Alert Layouts

<!-- Stacked alerts -->
<div class="alerts-container">
    {{ render_messages() }}
</div>

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

<!-- Toast-style notifications -->
<div class="toast-container position-fixed top-0 end-0 p-3">
    {% for message in get_flashed_messages(with_categories=True) %}
        <div class="toast show" role="alert">
            <div class="toast-header">
                {{ render_icon('info-circle', color=message[0]) }}
                <strong class="me-auto">Notification</strong>
                <button type="button" class="btn-close" data-bs-dismiss="toast"></button>
            </div>
            <div class="toast-body">
                {{ message[1] }}
            </div>
        </div>
    {% endfor %}
</div>

Icon Button Patterns

<!-- Icon buttons -->
<button class="btn btn-outline-primary">
    {{ render_icon('download') }} Download
</button>

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

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

<button class="btn btn-sm btn-outline-danger" title="Delete">
    {{ render_icon('trash') }}
</button>

Status Indicators

<!-- Status badges with icons -->
<span class="badge bg-success">
    {{ render_icon('check-circle', color='white', size='0.8em') }} Active
</span>

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

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

List Items with Icons

<ul class="list-unstyled">
    <li class="mb-2">
        {{ render_icon('check', color='success') }} Feature A included
    </li>
    <li class="mb-2">
        {{ render_icon('check', color='success') }} Feature B included
    </li>
    <li class="mb-2">
        {{ render_icon('x', color='danger') }} Feature C not included
    </li>
</ul>

Navigation with Icons

<nav class="nav nav-pills flex-column">
    <a class="nav-link" href="/dashboard">
        {{ render_icon('speedometer2') }} Dashboard
    </a>
    <a class="nav-link" href="/users">
        {{ render_icon('people') }} Users
    </a>
    <a class="nav-link" href="/settings">
        {{ render_icon('gear') }} Settings
    </a>
</nav>

Configuration Variables

Several Flask configuration variables control utility behavior:

# Flash message defaults
app.config['BOOTSTRAP_MSG_CATEGORY'] = 'primary'

# Icon defaults  
app.config['BOOTSTRAP_ICON_SIZE'] = '1em'
app.config['BOOTSTRAP_ICON_COLOR'] = None
app.config['BOOTSTRAP_ICON_USE_FONT'] = False

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

Install with Tessl CLI