verynicegui 1.0.0

A premium component-based SaaS framework built on top of NiceGUI

🌟 verynicegui

A premium, component-based SaaS boilerplate framework built on top of NiceGUI.

verynicegui empowers developers to focus entirely on building business logic and page content, automating layout structures, dynamic navigations, session authentication, role-based access control (RBAC), theme switching, multi-keyword tables, and seamless i18n localizations.

---

🚀 Key Features

• 🛡️ Out-of-the-Box Session Auth & RBAC: Session-based login/logout guards with category-based page access checks.
• 📱 Premium Responsive Layout (VeryNiceGUI / VeryNiceLayout): Complete SaaS layout including a Header, dynamic Left Drawer, Footer, and interactive Right Detail Drawer.
• 🌍 Zero-Flash Theme & i18n Switching: Anti-flash dynamic HTML theme classes and quick "TR / EN" segment button toggle in the drawer.
• 🏗️ One-Command CLI Scaffolding: Setup your entire project directory and files instantly using the built-in CLI.
• 📊 Enhanced Data Table (VeryNiceTable): Paging bounds (max_row), custom 12-column spans, row click triggers, and comma/space separated multi-keyword AND-logic search.
• 🎴 Justified Typography Cards (VeryNiceCard): Standalone stat cards or context manager wrapper cards with dynamic border strips and justified block text.

---

📦 Installation

To install verynicegui in your environment, run the following command:

pip install verynicegui

(For local/editable development):

pip install -e . --break-system-packages

---

🏗️ Quick Project Scaffold (CLI)

Get a fully structured, modular SaaS project up and running in seconds. Open an empty folder in your terminal and run:

verynicegui-init

or alternatively:

python -m verynicegui

Generated Project Structure:

my_saas_app/
│
├── main.py             # App settings, Header, Footer, Drawer configuration & Launcher
├── translations.py     # Separate dictionary file for multi-language terms
├── assets/             # Holds static files (e.g. logos, graphics)
│   └── logo.svg        # Default premium SVG logo
├── pages/              # Directory for modular page layouts
│   ├── __init__.py     # Exports all pages
│   ├── home.py         # Home page module
│   └── sales.py        # Sales page module (featuring VeryNiceTable)
└── data/
    └── users.json      # Built-in database file (automatically created on first run)

---

🛠️ API & Component Reference

1. VeryNiceGUI (App Configuration)

Used in main.py to bootstrap the application drawer, header, footer, static assets, and localization parameters.

# main.py
import sys
# Alias the entrypoint namespace as 'main' to prevent duplicate execution during circular imports
sys.modules['main'] = sys.modules[__name__]

from verynicegui import VeryNiceGUI
from translations import TRANSLATIONS

app = VeryNiceGUI(
    title="My SaaS App",
    header={
        "logo": "assets/logo.svg",  # SVG/PNG file path or Material Icon name
        "title": "SaaSApp",
        "show_theme_toggle": True
    },
    left_drawer={
        "title": "Navigation Menu",
        "menu": [
            {"category": "home", "title": "Home", "icon": "home", "route": "/"},
            {
                "category": "sales", 
                "title": "Sales", 
                "icon": "payments",
                "subcategories": [
                    {"title": "Daily", "route": "/sales/daily", "icon": "today"},
                    {"title": "Monthly", "route": "/sales/monthly", "icon": "calendar_month"}
                ]
            }
        ]
    },
    footer={
        "left": "© 2026 SaaSApp Inc.",
        "middle": "All Rights Reserved",
        "right": "System Status: Online"
    },
    translations=TRANSLATIONS
)

import pages

if __name__ in {"__main__", "__mp_main__"}:
    app.run(port=8080)

---

2. @app.page (Route & Guard Decorator)

Registers routes and applies RBAC categories to restrict pages to authorized users.

# pages/home.py
from nicegui import ui
from verynicegui import get_current_user, tr
from main import app

# Restricts this page to users having the 'home' category permission
@app.page("/", title="Home Page", allowed_categories=["home"])
def home_page():
    user = get_current_user()
    display_name = user.get("display_name") if user else "Guest"
    
    ui.label(tr("welcome", "Welcome, {name}!").format(name=display_name))

---

3. VeryNiceCard (Justified Content Cards)

A premium card container. Can be instantiated on a single line or as a context manager block.

A) Single-line Statistic Card

from verynicegui import VeryNiceCard

VeryNiceCard(title="Total Revenue", body="$124,500", column=4)

B) Context Manager Block Card

from verynicegui import VeryNiceCard
from nicegui import ui

with VeryNiceCard(title="Important Announcement", column=12, color="var(--mn-brand)"):
    ui.label("This paragraph text inside the card is automatically justified (aligned left and right).")
    ui.button("Read More")

Parameters:

• title: Title text. Shows smaller and grey in stats mode, bold and primary in content mode.
• body (Optional): Value string. Triggers immediate stats card formatting if provided.
• column (Optional): Width span in 12-column grids (e.g. 4 spans 1/3 of the row).
• color (Optional): Brand color for the decorative left border strip (e.g. "#3b82f6", "red").

---

4. VeryNiceTable (Advanced Paginated Grid)

Features scrollable headers, page pagination, multi-keyword search parsing, and custom action callbacks.

# pages/sales.py
from nicegui import ui
from verynicegui import VeryNiceTable, tr
from main import app

@app.page("/sales/daily", title="Daily Sales", allowed_categories=["sales"])
def daily_sales_page(drawer):
    transactions = [
        {"id": "#1001", "product": "Pro License", "amount": "99 USD", "desc": "Premium subscription key"},
        {"id": "#1002", "product": "Enterprise Setup", "amount": "1200 USD", "desc": "Custom server migration consulting"}
    ]

    VeryNiceTable(
        table_name="Transactions",
        columns=[
            {"name": "id", "label": "ID", "field": "id", "align": "left"},
            {"name": "product", "label": "Product", "field": "product", "align": "left"},
            {"name": "amount", "label": "Amount", "field": "amount", "align": "right"}
        ],
        rows=transactions,
        max_row=5,          # Maximum rows per page before paginating
        column=8,           # Span in the 12-column parent layout
        font_size="m",      # Options: 's', 'm', 'l'
        font_family="Outfit", # Options: 'Outfit', 'Inter'
        on_row_click=lambda row: drawer.toggle(row["desc"]) # Drawer action on row click
    )

🔍 Multi-Keyword Search AND Filter

The search box supports multiple keyword arguments separated by spaces ( ) or commas (,). For example, searching for Pro Premium matches records containing both "Pro" and "Premium".

---

5. RightDrawer (Details sidebar)

To instantiate the interactive right drawer, declare a parameter named drawer or right_drawer in your page function. The decorator will automatically inject the drawer.

# drawer control commands:
drawer.open("Content String or callback")
drawer.close()
drawer.toggle("Details info here...") # Toggles open if closed, or updates current drawer content

---

🌍 Localization & Multi-Language (i18n)

Define translation mappings in translations.py and supply them to VeryNiceGUI.

translations.py Schema:

TRANSLATIONS = {
    "tr": {
        "welcome": "Hoş geldiniz, {name}! 👋",
        "home_title": "Ana Sayfa",
        "btn_save": "Kaydet"
    },
    "en": {
        "welcome": "Welcome, {name}! 👋",
        "home_title": "Home Page",
        "btn_save": "Save"
    }
}

Usage:

Use the tr helper function inside pages to fetch translations for the user's active language choice.

from verynicegui import tr

# Simple translate
ui.label(tr("btn_save", "Save"))

# Formatted dynamic translate
ui.label(tr("welcome", "Welcome, {name}!").format(name=display_name))

---

🔑 Authentication Database (data/users.json)

On the first application launch, the directory data/ and users.json are created automatically. It contains default accounts:

• Admin (username: admin, password: admin123) -> Full access to all categories and /admin user management panels.
• Custom accounts can be registered and configured with page access permissions directly via the Admin panel.

---

🎨 Theme & Styles Override

Style overrides and color schemas are defined inside CSS variables in verynicegui/layout.py:

• --mn-bg: Master app background color.
• --mn-header-bg: Header navbar color.
• --mn-drawer-bg: Navigation sidebar color.
• --mn-card-bg: Card container background.
• --mn-brand: Brand indicator color (defaults to indigo purple).