Example DBBasic apps (an API, a blog and a microblog) and a template for new DBBasic modules.

0 downloads

dbbasic-examples/module-template
Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-examples.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-examples.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-examples.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

danq9 Add official module template for creating DBBasic packages 17cf88a 1 year, 1 month ago History
README.md

DBBasic Module Template

This is the official template for creating new DBBasic modules.

What This Template Provides

  • Complete module structure following DBBasic conventions
  • Admin interface integration
  • CRUD operations (Create, Read, Update, Delete)
  • TSV-based data storage with indexing
  • API handlers with proper routing
  • Test suite structure
  • Documentation template

Quick Start

# 1. Copy this template
cp -r module-template dbbasic-contacts

# 2. Rename the package directory
cd dbbasic-contacts
mv dbbasic_module dbbasic_contacts

# 3. Update all references
# Replace "module" with "contacts" in all files
# Replace "Module" with "Contacts" in all files
# Replace "THING" with "Contact" in all files

# 4. Install in development mode
pip install -e .

# 5. Run tests
pytest

# 6. Start development server
cd ../your-app
python manage.py serve

# 7. Visit admin interface
open http://localhost:8000/admin/contacts

Structure Explained

dbbasic-module/
├── dbbasic_module/          # Main package directory
│   ├── __init__.py          # Package exports
│   ├── admin.py             # Admin navigation config
│   ├── module.py            # Core API class
│   ├── api/                 # Admin HTTP handlers
│   │   └── module/
│   │       ├── __init__.py
│   │       ├── list.py      # List view (GET /admin/module)
│   │       ├── create.py    # Create form/handler (GET/POST /admin/module/create)
│   │       ├── edit.py      # Edit form/handler (GET/POST /admin/module/edit/[id])
│   │       └── delete.py    # Delete handler (POST /admin/module/delete/[id])
│   └── data/
│       └── module.meta      # Schema definition (optional)
├── tests/
│   ├── __init__.py
│   └── test_module.py       # Test suite
├── README.md                # Documentation
├── LICENSE                  # MIT by default
└── pyproject.toml          # Package configuration

Customization Guide

1. Update Package Metadata

Edit pyproject.toml:

  • Change name from "dbbasic-module" to your module name
  • Update description
  • Update author
  • Adjust version

2. Define Your Schema

Edit dbbasic_module/data/module.meta to define your fields:

{
  "table": "contacts",
  "fields": [
    {"name": "id", "type": "int", "primary": true, "auto": true},
    {"name": "name", "type": "string", "required": true},
    {"name": "email", "type": "email", "required": true, "unique": true},
    {"name": "created_at", "type": "timestamp", "auto": true}
  ],
  "indexes": ["email"]
}

3. Customize Admin Interface

Edit dbbasic_module/admin.py:

  • Change icon (use any emoji)
  • Update label
  • Adjust menu order (10=top, 100=bottom)

4. Implement Core API

Edit dbbasic_module/module.py:

  • Add custom methods beyond basic CRUD
  • Add validation logic
  • Add business logic

5. Customize Admin Handlers

Edit files in dbbasic_module/api/module/:

  • list.py - Customize table columns, filters, search
  • create.py - Customize create form fields
  • edit.py - Customize edit form fields
  • delete.py - Add deletion constraints or cascade logic

Publishing Your Module

1. Test Thoroughly

pytest

2. Build Package

python -m build

3. Publish to PyPI

python -m twine upload dist/*

4. (Optional) Submit to DBBasic Marketplace

Visit https://dbbasic.com/submit (coming soon)

Conventions

Naming

  • Package name: dbbasic-{feature} (lowercase, hyphens)
  • Module name: dbbasic_{feature} (lowercase, underscores)
  • Class name: {Feature} (PascalCase)
  • Admin route: /admin/{feature}/*

File Organization

  • Core API: {feature}.py in package root
  • Admin handlers: api/{feature}/ directory
  • Data files: data/ directory (created at runtime if needed)
  • Tests: tests/ directory

Admin Integration

  • Every module exports ADMIN_CONFIG in admin.py
  • Admin handlers use consistent URL patterns
  • Admin pages use consistent styling/layout

Data Storage

  • Use dbbasic-tsv for table operations
  • Store data in user's app data/ directory, not package directory
  • Create indexes for frequently queried fields
  • Use .meta files for schema validation (optional)

Examples

See existing modules for reference:

  • dbbasic-accounts - User authentication (complex)
  • dbbasic-admin - Admin dashboard (UI-heavy)
  • dbbasic-tsv - Data storage (low-level)

Support

  • Documentation: https://dbbasic.com/docs
  • Examples: https://github.com/dbbasic/dbbasic-examples
  • Issues: https://github.com/dbbasic/dbbasic-{module}/issues
  • Discord: https://discord.gg/dbbasic

License

MIT License - feel free to use this template for any purpose.