backend_driven_ui 0.2.1

Server-Driven UI framework for Flutter with ApiWidget - build data-driven interfaces without FutureBuilder boilerplate.

Backend-Driven UI

Flutter UIs That Update Themselves. Seriously.

Server-driven UI framework with ApiWidget - build data-driven interfaces without FutureBuilder boilerplate.

---

✨ Features

• 🎯 33 Built-in Widgets - Fully interactive apps from JSON
• ⚡ Zero App Releases - Update UI from backend JSON instantly
• 🔓 100% Open Source - MIT licensed, yours forever
• 📦 ApiWidget - FutureBuilder's smarter, faster cousin
• 🚀 Lightweight & Fast - Optimized parsing, lazy loading
• 💎 Production Ready - Buttons, lists, gestures, caching

---

🚀 Quick Start

Installation

dependencies:
  backend_driven_ui: ^0.2.0

Global Base URL (optional)

Set once at app startup to avoid repeating the full URL on every widget:

void main() {
  BduiConfig.baseUrl = 'https://api.myapp.com';
  runApp(MyApp());
}

All relative endpoints are then resolved automatically:

BackendDrivenScreen(endpoint: '/screens/home')  // → https://api.myapp.com/screens/home
ApiWidget(endpoint: '/products')                // → https://api.myapp.com/products

Full URLs (https://...) are always used as-is regardless of baseUrl.

---

📖 Documentation

Backend-Driven UI (the wow factor)

Render an entire screen from a JSON schema your backend returns. No app update needed — change the JSON, the UI changes instantly.

BackendDrivenScreen(
  endpoint: '/api/screens/home',
  cacheDuration: Duration(minutes: 5),
  onNavigate: (route, args) => Navigator.pushNamed(context, route),
)

Backend returns JSON → Flutter renders the UI:

{
  "type": "Column",
  "props": { "mainAxisAlignment": "center" },
  "children": [
    {
      "type": "Text",
      "props": { "text": "Hello from Backend!", "fontSize": 24, "color": "#1976D2" }
    },
    { "type": "SizedBox", "props": { "height": 16 } },
    {
      "type": "ElevatedButton",
      "props": { "text": "Shop Now" },
      "action": { "type": "navigate", "route": "/shop" }
    }
  ]
}

Colors in JSON

Three formats are supported — use whichever fits your backend:

Format	Example	Notes
Named	"color": "blue"	All Flutter Colors.* names
Colors.x	"color": "Colors.deepPurple"	Flutter notation directly
Hex #RRGGBB	"color": "#1976D2"	Standard CSS hex
Hex #AARRGGBB	"color": "#FF1976D2"	With alpha channel
ARGB int	"color": 4278190080	Raw Flutter int

Local Schema (no API call needed)

SchemaWidget.fromJson({
  "type": "Column",
  "children": [
    { "type": "Text", "props": { "text": "Hello from JSON!", "fontSize": 24 } }
  ]
})

---

ApiWidget

The declarative way to fetch and display API data.

ApiWidget(
  endpoint: '/api/products/featured',
  method: 'GET',

  // Optional: Headers
  headers: {'Authorization': 'Bearer $token'},

  // Optional: Request body (for POST/PUT)
  body: {'category': 'electronics'},

  // Optional: Cache duration
  cacheDuration: Duration(minutes: 5),

  // Optional: Max retry attempts
  maxRetries: 3,

  // Optional: Auto-refresh (polling)
  pollInterval: Duration(seconds: 30),

  // State widgets
  loadingWidget: CircularProgressIndicator(),

  successWidget: (data) {
    final products = data['products'] as List;
    return ProductGrid(products: products);
  },

  errorWidget: (error) {
    return ErrorCard(
      message: error,
      onRetry: () => setState(() {}),
    );
  },

  // Optional: Empty state
  emptyWidget: EmptyState(message: 'No products found'),

  // Optional: Callbacks
  onSuccess: (data) => print('Loaded ${data.length} products'),
  onError: (error) => print('Error: $error'),
)

Custom Widget Registration

Extend with your own widgets using SchemaParser.register:

final parser = SchemaParser();

parser.register('ProductCard', (schema, context) {
  final props = schema.props ?? {};
  return ProductCard(
    title: props['title'],
    price: props['price'],
    imageUrl: props['imageUrl'],
  );
});

Use it from backend:

{
  "type": "ProductCard",
  "props": {
    "title": "iPhone 15",
    "price": 79999,
    "imageUrl": "https://cdn.app.com/iphone15.jpg"
  }
}

---

🎯 Advanced Features

Action Handling

Execute actions from your backend schemas:

{
  "type": "navigate",
  "route": "/products"
}

Supported actions:

• navigate - Navigate to a route
• api - Make API calls
• showDialog - Show dialogs
• showSnackBar - Show snackbars
• pop - Go back
• launchUrl - Open a URL (requires onLaunchUrl callback)
• sequence - Execute multiple actions
• conditional - Conditional execution

Caching & Performance

// Enable widget caching
final parser = SchemaParser(enableCache: true);

// Clear cache when needed
parser.clearCache();

// API caching
ApiWidget(
  endpoint: '/api/products',
  cacheDuration: Duration(minutes: 5), // Cache for 5 minutes
)

Server-Controlled Caching

Let your backend control cache behavior per response:

{
  "cachePolicy": "cache",
  "cacheTTL": 300,
  "ui": {
    "type": "Column",
    "children": [...]
  }
}

Cache policies:

• cache - Cache response (default)
• noCache - Never cache, always fetch fresh
• refresh - Return cached data, refresh in background (stale-while-revalidate)

Handle background refresh:

ApiWidget(
  endpoint: '/api/live-data',
  onBackgroundRefresh: (newData) {
    // UI automatically updates with fresh data
    print('Data refreshed in background!');
  },
)

Auto-Retry & Error Handling

ApiWidget(
  endpoint: '/api/products',
  maxRetries: 3, // Retry up to 3 times
  showRetryButton: true, // Show retry button on error
  onError: (error) => logError(error),
)

---

📚 Schema Reference

See the Schema Reference for complete documentation of all 33 widgets, props, actions, and conditions — also available as SCHEMA_REFERENCE.md.

---

📱 Examples

Check out the example directory for complete samples:

• ApiWidget Examples - Basic & list API calls with caching
• Backend-Driven UI - JSON schema rendering
• Local Schema - Use JSON without API calls
• Conditional Rendering - Platform & theme-based UI

---

🤝 Contributing

Contributions are welcome! Feel free to open issues or submit pull requests on GitHub.

---

📄 License

MIT License - see LICENSE file for details.

---

🌟 Show Your Support

If you like this package, please give it a ⭐ on GitHub!

---

Built with ❤️ for the Flutter community