Model-config web apps: describe the app in configuration instead of writing code. Built on Polars and DuckDB.
PRESENTATION_LAYER.md · 7.3 KB · 319 lines
DBBasic Presentation Layer Architecture
🎯 Overview
The DBBasic Presentation Layer is a revolutionary approach to UI generation that separates data from presentation. Instead of mixing HTML strings in code, we define UI as pure data structures that can be rendered to any UI framework.
🏗️ Architecture
Core Concept
# Define UI as data
ui_structure = {
'type': 'page',
'components': [
{'type': 'navbar', 'brand': 'DBBasic'},
{'type': 'card', 'title': 'Hello', 'text': 'World'}
]
}
# Render to any framework
html = PresentationLayer.render(ui_structure, 'bootstrap') # or 'tailwind', 'material', etc.
Key Components
- Abstract UIRenderer Base Class
- Defines the interface all renderers must implement
- Handles routing of component types to render methods
- Provides default implementations for common patterns
- Framework-Specific Renderers
- BootstrapRenderer - Bootstrap 5.3 implementation
- TailwindRenderer - Tailwind CSS implementation
- (Future: MaterialRenderer, BulmaRenderer, etc.)
- PresentationLayer Manager
- Registry of available renderers
- Simple API:
PresentationLayer.render(data, framework) - Extensible:
PresentationLayer.add_renderer(name, renderer)
📊 Data Structure Specification
Component Types
Page
{
'type': 'page',
'title': 'Page Title',
'components': [...] # List of components
}
Navbar
{
'type': 'navbar',
'brand': 'Brand Name',
'links': [
'Simple Link', # String becomes /simple-link
{'text': 'Custom', 'url': '/custom-url'} # Dict for full control
]
}
Card
{
'type': 'card',
'title': 'Card Title',
'category': 'Optional Badge',
'description': 'Card content text',
'actions': ['button1', 'button2'] # Buttons in footer
}
Grid
{
'type': 'grid',
'columns': 3, # Number of columns
'items': [...] # List of components to place in grid
}
Hero
{
'type': 'hero',
'title': 'Big Title',
'subtitle': 'Supporting text'
}
Alert
{
'type': 'alert',
'message': 'Alert message',
'variant': 'info' # info, success, warning, danger
}
Button
{
'type': 'button',
'text': 'Click Me',
'variant': 'primary', # primary, secondary, success, danger, etc.
'onclick': 'jsFunction()' # Optional JavaScript
}
Container
{
'type': 'container',
'children': [...] # List of child components
}
🎨 Benefits
1. Framework Agnostic
- Write once, render anywhere
- Switch from Bootstrap to Tailwind with one parameter change
- Future-proof against framework changes
2. AI-Friendly
- AI can generate UI by creating simple data structures
- No need for AI to know HTML/CSS specifics
- Easy to validate and modify generated UI
3. Clean Code
- No HTML strings mixed with Python
- Business logic separated from presentation
- Testable UI structures (just test the data)
4. Customizable
- Users can add their own renderers
- Custom components can be added easily
- Override specific component rendering
5. DBBasic Philosophy
- Config-driven like everything else in DBBasic
- UI defined as YAML-compatible structures
- Consistent with DBBasic's declarative approach
💻 Usage Examples
Basic Usage
from presentation_layer import PresentationLayer
# Define UI
ui = {
'type': 'page',
'title': 'My App',
'components': [
{'type': 'navbar', 'brand': 'MyApp'},
{'type': 'hero', 'title': 'Welcome!'},
{'type': 'grid', 'columns': 3, 'items': [
{'type': 'card', 'title': 'Feature 1'},
{'type': 'card', 'title': 'Feature 2'},
{'type': 'card', 'title': 'Feature 3'}
]}
]
}
# Render to Bootstrap
html = PresentationLayer.render(ui, 'bootstrap')
# Or render to Tailwind
html = PresentationLayer.render(ui, 'tailwind')
Adding Custom Renderer
from presentation_layer import UIRenderer, PresentationLayer
class MaterialUIRenderer(UIRenderer):
def render_card(self, data):
# Material UI specific implementation
return f'<mat-card>...</mat-card>'
# Implement other required methods...
# Register the renderer
PresentationLayer.add_renderer('material', MaterialUIRenderer())
# Use it
html = PresentationLayer.render(ui, 'material')
Integration with CRUD Engine
# In dbbasic_crud_engine.py
ui_structure = {
'type': 'page',
'title': 'Template Marketplace',
'components': [
{'type': 'navbar', ...},
{'type': 'grid', 'items': [
{'type': 'card', 'title': t['name'], ...}
for t in templates
]}
]
}
return HTMLResponse(PresentationLayer.render(ui_structure, 'bootstrap'))
🔮 Future Enhancements
Planned Features
- More Component Types
- Forms with validation
- Tables with sorting/filtering
- Modals and dialogs
- Charts and graphs
- More Frameworks
- Material UI
- Bulma
- Foundation
- Semantic UI
- Custom/minimal CSS
- Advanced Features
- Theme customization
- Responsive breakpoints
- Animation support
- Component composition
- YAML Support
# Define UI in YAML
type: page
title: My App
components:
- type: navbar
brand: MyApp
- type: grid
columns: 3
items:
- type: card
title: Feature 1
- Visual Designer
- Drag-and-drop interface
- Generates data structures
- Live preview in multiple frameworks
🚀 Why This Matters
Traditional web frameworks mix presentation with logic:
# OLD WAY - HTML mixed with code
return f'''
<div class="card">
<h5>{title}</h5>
<p>{description}</p>
</div>
'''
DBBasic separates concerns completely:
# NEW WAY - Clean data structure
return {
'type': 'card',
'title': title,
'description': description
}
This approach:
- Makes code more maintainable
- Enables framework switching
- Allows AI to generate UI easily
- Keeps business logic clean
- Follows DBBasic's config-driven philosophy
📝 Implementation Status
✅ Completed
- Abstract UIRenderer base class
- BootstrapRenderer (Bootstrap 5.3)
- TailwindRenderer (Tailwind CSS)
- PresentationLayer manager
- Basic component types (page, navbar, card, grid, hero, alert, button)
- Integration with CRUD Engine
🔄 In Progress
- Complete Bootstrap component library
- Form components with validation
- Table components
📋 TODO
- Material UI renderer
- YAML configuration support
- Visual designer interface
- Advanced component types
- Theme customization system
🎯 Design Principles
- Data First: UI is data, not strings
- Framework Agnostic: No framework lock-in
- Simple API: One function to render any UI
- Extensible: Easy to add new components/frameworks
- Clean: No HTML in business logic
- Testable: Test data structures, not HTML
- AI-Ready: Perfect for AI generation/modification
This presentation layer is a game-changer for DBBasic, making UI as configurable and clean as the rest of the system. It's the perfect complement to DBBasic's config-driven architecture.