badgui/BADGUI_COMPLETE_GUIDE.md

BadGUI Framework v0.2.0 - Complete Feature Summary

Overview

BadGUI is a Python web UI framework that generates Vue.js applications with Quasar components. It provides a simple, declarative API similar to NiceGUI but generates static Vue.js projects that can be deployed anywhere.

Core Framework Features

1. Component System

BadGUI provides both predefined components and a generic component method:

Predefined Components

import badgui as bg

# Basic components
bg.label("Hello World")
bg.button("Click Me").on_click('handleClick')
bg.input_("Enter text").bind_value('userText')

# Layout components
with bg.row():
    with bg.column():
        bg.label("Column content")

# Card components (simplified syntax)
with bg.card():
    bg.label("Card content")
    bg.button("Action")

Generic Component Method (NEW!)

# Create ANY Quasar component
rating = bg.component('q-rating', max=5, size='2em', color='amber')
rating.bind_value('userRating')

select = bg.component('q-select', 
                    filled=True, 
                    options=['Option 1', 'Option 2', 'Option 3'],
                    label='Choose one')
select.bind_value('selectedOption')

slider = bg.component('q-slider', min=0, max=100, step=10, markers=True)
slider.bind_value('volumeLevel')

# Container components
with bg.component('q-expansion-item', 
                label='Advanced Settings', 
                container=True) as expansion:
    bg.label("Nested content")
    bg.component('q-separator')

2. JavaScript Integration

BadGUI provides comprehensive JavaScript integration with Vue.js:

Script Component

# Inline JavaScript
bg.script("""
const userRating = ref(3);
const selectedOption = ref(null);

const updateDisplay = () => {
    console.log('Rating:', userRating.value);
};

onMounted(() => {
    console.log('Component mounted!');
});
""")

# External JavaScript files
bg.script("./my-script.js")

# ES6 Module imports (automatically copied to Vue app)
bg.script("./utils/helpers.js", import_mode=True)

Vue Ref Integration

# Create components with Vue template refs
button = bg.button("Click Me")
button.vue_ref('myButton')

# Access in JavaScript
bg.script("""
const { myButton } = getCurrentInstance().refs;

const focusButton = () => {
    myButton.value.$el.focus();
};
""")

3. Data Binding

BadGUI supports comprehensive Vue.js data binding:

# Two-way binding
input_field = bg.input_("Enter text")
input_field.bind_value('userInput')

# Text binding  
display = bg.label("")
display.bind_text('computedText')

# Event handling with .on() method pattern
button = bg.button("Submit")
button.on_click('submitForm')
button.on('mouseenter', 'handleHover')

4. Context Management

BadGUI uses Python context managers for clean layout structure:

with bg.page("/", "HomePage", "My App"):
    with bg.column().classes("q-pa-lg"):
        bg.label("Page Title").classes("text-h3")
        
        with bg.row().classes("q-gutter-md"):
            with bg.card():
                bg.label("Card 1")
            
            with bg.card():
                bg.label("Card 2")
        
        # Generic container components
        with bg.component('q-timeline', container=True):
            bg.component('q-timeline-entry', 
                        title='Event 1', 
                        subtitle='Description')

Complete API Reference

App Class Methods

# Page management
bg.page(route, name, title)

# Layout components
bg.row(**kwargs)
bg.column(**kwargs)
bg.div(**kwargs)

# Content components  
bg.label(text, **kwargs)
bg.button(text, **kwargs)
bg.input_(placeholder, **kwargs)
bg.card(**kwargs)

# Generic component creation
bg.component(quasar_component, container=False, **kwargs)

# JavaScript integration
bg.script(code_or_file, import_mode=False)

# Development server
bg.dev(port=3000, host='localhost')

Component Methods

# Styling
component.classes("q-pa-md text-h5")
component.style("color: red; font-size: 16px")

# Data binding
component.bind_value('variable_name')
component.bind_text('text_variable')

# Vue refs
component.vue_ref('ref_name')

# Event handling (.on() pattern)
component.on_click('function_name')
component.on('event_name', 'handler_function')

# Properties
component.props(disabled=True, color='primary')

Example Applications

1. Simple Form with Generic Components

import badgui as bg

with bg.page("/", "Form", "Advanced Form"):
    with bg.column().classes("q-pa-lg q-gutter-md"):
        bg.label("User Preferences").classes("text-h4")
        
        # Rating
        bg.label("Rate our service:")
        rating = bg.component('q-rating', max=5, size='2em')
        rating.bind_value('serviceRating')
        
        # Select
        category = bg.component('q-select',
                              options=['General', 'Technical', 'Billing'],
                              label='Category')
        category.bind_value('selectedCategory')
        
        # Slider
        bg.label("Priority Level:")
        priority = bg.component('q-slider', min=1, max=10, step=1)
        priority.bind_value('priorityLevel')
        
        # Toggle
        notifications = bg.component('q-toggle', 
                                   label='Email notifications')
        notifications.bind_value('emailEnabled')
        
        # Submit button
        bg.button("Submit Feedback").on_click('submitFeedback')

# JavaScript handling
bg.script("""
const serviceRating = ref(5);
const selectedCategory = ref('General');
const priorityLevel = ref(5);
const emailEnabled = ref(true);

const submitFeedback = () => {
    const feedback = {
        rating: serviceRating.value,
        category: selectedCategory.value,
        priority: priorityLevel.value,
        notifications: emailEnabled.value
    };
    
    console.log('Feedback submitted:', feedback);
    // Send to API...
};
""")

bg.dev(port=3030)

2. Dashboard with Container Components

import badgui as bg

with bg.page("/", "Dashboard", "Analytics Dashboard"):
    with bg.column().classes("full-width"):
        bg.label("Analytics Dashboard").classes("text-h3 q-pa-lg")
        
        with bg.row().classes("q-pa-md q-gutter-md"):
            # Stats cards
            with bg.card().classes("col"):
                bg.label("Total Users").classes("text-h6")
                user_count = bg.label("0")
                user_count.bind_text('totalUsers')
            
            with bg.card().classes("col"):
                bg.label("Revenue").classes("text-h6")
                revenue = bg.label("$0")
                revenue.bind_text('totalRevenue')
        
        # Expandable sections
        with bg.component('q-expansion-item',
                        label='Detailed Analytics',
                        icon='analytics',
                        container=True):
            
            # Progress indicators
            bg.label("Loading Progress:")
            bg.component('q-linear-progress', 
                        value=0.8, 
                        size='15px',
                        color='primary')
            
            # Data table (could be implemented as generic component)
            with bg.component('q-table',
                            title='Recent Activity',
                            columns=[{'name': 'date', 'label': 'Date'}],
                            container=True):
                pass  # Table rows would be added here

bg.script("""
const totalUsers = ref('1,234');
const totalRevenue = ref('$56,789');

onMounted(() => {
    // Simulate data loading
    console.log('Dashboard loaded');
});
""")

bg.dev(port=3031)

Framework Architecture

Generated Vue.js Structure

vue-app/
├── src/
│   ├── components/
│   │   └── BadGUIComponents.vue  # Generated components
│   ├── pages/
│   │   └── IndexPage.vue         # Generated pages
│   ├── utils/                    # ES6 modules (if using import_mode)
│   │   └── helpers.js
│   ├── App.vue
│   └── main.js
├── package.json
└── quasar.config.js

Key Benefits

1. Extensibility: Generic component() method allows access to entire Quasar library
2. Vue.js Integration: Full Vue 3 Composition API support with refs, reactive data, and lifecycle hooks
3. JavaScript Flexibility: Inline scripts, external files, and ES6 module imports
4. Clean Syntax: Context managers and method chaining for readable code
5. Static Generation: Produces deployable Vue.js applications
6. Type Safety: Python-based development with IDE support

Development Workflow

1. Write BadGUI Code: Use Python to define UI structure and behavior
2. Test with Dev Server: bg.dev() automatically generates and serves Vue app
3. Iterate Quickly: Changes to Python code regenerate the Vue app
4. Deploy: Generated Vue app can be built and deployed anywhere

BadGUI v0.2.0 combines the simplicity of Python-based UI frameworks with the power and flexibility of Vue.js and Quasar, making it perfect for rapid prototyping and production applications alike.