askrobots / dbbasic-examples
Public
Example DBBasic apps (an API, a blog and a microblog) and a template for new DBBasic modules.
danq9
Add official module template for creating DBBasic packages
17cf88a
1 year, 1 month ago
History
README.md · 4.7 KB · 183 lines
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
namefrom "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, searchcreate.py- Customize create form fieldsedit.py- Customize edit form fieldsdelete.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}.pyin 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_CONFIGinadmin.py - Admin handlers use consistent URL patterns
- Admin pages use consistent styling/layout
Data Storage
- Use
dbbasic-tsvfor table operations - Store data in user's app
data/directory, not package directory - Create indexes for frequently queried fields
- Use
.metafiles 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.