forked from enviPath/enviPy
New Layout for parallel styling
Signed-off-by: Tobias O <tobias.olenyi@envipath.com>
This commit is contained in:
212
MIGRATION_GUIDE.md
Normal file
212
MIGRATION_GUIDE.md
Normal file
@ -0,0 +1,212 @@
|
||||
# Tailwind/DaisyUI Migration Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This project is using the **Strangler Fig Pattern** to incrementally migrate from Bootstrap 3.3.7 to Tailwind CSS v4 + DaisyUI v5.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Two Base Templates
|
||||
|
||||
1. **`framework.html`** - Legacy Bootstrap template (25 templates use this)
|
||||
2. **`framework_modern.html`** - Modern Tailwind/DaisyUI template (clean, no Bootstrap)
|
||||
|
||||
### Migrated Templates
|
||||
|
||||
✅ **index/index.html** - First template migrated to modern framework
|
||||
|
||||
### Migration Status
|
||||
|
||||
- **Total templates**: 110
|
||||
- **Templates extending framework**: 25
|
||||
- **Migrated to modern**: 1 (index.html)
|
||||
- **Remaining**: 24
|
||||
|
||||
## How to Migrate a Template
|
||||
|
||||
### Step 1: Change the extends statement
|
||||
|
||||
```django
|
||||
{# Old #}
|
||||
{% extends "framework.html" %}
|
||||
|
||||
{# New #}
|
||||
{% extends "framework_modern.html" %}
|
||||
```
|
||||
|
||||
### Step 2: Remove Bootstrap wrappers
|
||||
|
||||
```django
|
||||
{# Old #}
|
||||
<div class="legacy-bootstrap">
|
||||
<!-- content -->
|
||||
</div>
|
||||
|
||||
{# New #}
|
||||
<!-- content -->
|
||||
```
|
||||
|
||||
### Step 3: Convert Bootstrap classes to Tailwind/DaisyUI
|
||||
|
||||
Common conversions:
|
||||
|
||||
**Bootstrap → Tailwind/DaisyUI**
|
||||
|
||||
| Bootstrap | Tailwind/DaisyUI |
|
||||
|-----------|------------------|
|
||||
| `btn btn-primary` | `btn btn-primary` (DaisyUI keeps similar naming) |
|
||||
| `btn btn-default` | `btn` |
|
||||
| `container` | `container mx-auto` |
|
||||
| `row` | `flex flex-wrap` or `grid` |
|
||||
| `col-md-6` | `w-full md:w-1/2` |
|
||||
| `panel panel-default` | `card bg-base-100 shadow-xl` |
|
||||
| `alert alert-info` | `alert alert-info` |
|
||||
| `navbar navbar-default` | `navbar bg-neutral` |
|
||||
| `modal fade` | `modal` (see DaisyUI modal docs) |
|
||||
|
||||
### Step 4: Test functionality
|
||||
|
||||
- Verify navigation works
|
||||
- Test any JavaScript interactions
|
||||
- Check responsive behavior
|
||||
- Validate forms still submit correctly
|
||||
|
||||
### Step 5: Commit and deploy
|
||||
|
||||
Each template migration can be deployed independently since both frameworks coexist.
|
||||
|
||||
## Design System
|
||||
|
||||
### Color Tokens
|
||||
|
||||
Use semantic color tokens from the enviPath theme:
|
||||
|
||||
```css
|
||||
/* Base backgrounds */
|
||||
bg-base-100 /* Main background (very light blue-ish) */
|
||||
bg-base-200 /* Secondary background */
|
||||
bg-base-300 /* Tertiary background */
|
||||
|
||||
/* Brand colors */
|
||||
bg-primary /* Primary blue */
|
||||
bg-secondary /* Secondary teal */
|
||||
bg-accent /* Accent color */
|
||||
|
||||
/* Semantic colors */
|
||||
bg-success /* Green */
|
||||
bg-warning /* Yellow/Orange */
|
||||
bg-error /* Red */
|
||||
bg-info /* Blue */
|
||||
|
||||
/* Neutrals */
|
||||
bg-neutral /* Dark gray (used in navbar) */
|
||||
```
|
||||
|
||||
### Components
|
||||
|
||||
DaisyUI provides ready-to-use components:
|
||||
|
||||
- **Navigation**: `navbar`, `menu`, `dropdown`
|
||||
- **Content**: `card`, `collapse`, `badge`
|
||||
- **Actions**: `btn`, `modal`, `drawer`
|
||||
- **Forms**: `input`, `select`, `textarea`, `checkbox`, `radio`
|
||||
- **Feedback**: `alert`, `toast`, `loading`
|
||||
|
||||
See: https://daisyui.com/components/
|
||||
|
||||
## Priority Order for Migration
|
||||
|
||||
Suggested order based on user visibility:
|
||||
|
||||
1. ✅ **index/index.html** (Homepage) - DONE
|
||||
2. **search.html** (Search page)
|
||||
3. **objects/pathway.html** (Pathway detail)
|
||||
4. **objects/compound.html** (Compound detail)
|
||||
5. **objects/package.html** (Package overview)
|
||||
6. **collections/objects_list.html** (Generic list view)
|
||||
7. Other object detail pages
|
||||
8. Admin pages
|
||||
9. Error pages
|
||||
|
||||
## Known Issues
|
||||
|
||||
### Modals Need Conversion
|
||||
|
||||
The modal templates (`modals/*.html`) still use Bootstrap markup. They need to be converted to DaisyUI modals:
|
||||
|
||||
**Bootstrap Modal:**
|
||||
```html
|
||||
<div class="modal fade" id="myModal">
|
||||
<div class="modal-dialog">
|
||||
<div class="modal-content">...</div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
**DaisyUI Modal:**
|
||||
```html
|
||||
<dialog id="myModal" class="modal">
|
||||
<div class="modal-box">
|
||||
<h3 class="font-bold text-lg">Title</h3>
|
||||
<p class="py-4">Content</p>
|
||||
<div class="modal-action">
|
||||
<form method="dialog">
|
||||
<button class="btn">Close</button>
|
||||
</form>
|
||||
</div>
|
||||
</div>
|
||||
</dialog>
|
||||
```
|
||||
|
||||
### JavaScript Compatibility
|
||||
|
||||
- jQuery is still included for compatibility
|
||||
- Bootstrap JavaScript is NOT loaded in modern framework
|
||||
- Modal triggers will need updating from `data-toggle="modal"` to DaisyUI's approach
|
||||
|
||||
## CSS Build Process
|
||||
|
||||
After making changes to CSS files:
|
||||
|
||||
```bash
|
||||
# Development (watch mode)
|
||||
pnpm run dev
|
||||
|
||||
# Production build
|
||||
pnpm run build
|
||||
```
|
||||
|
||||
## Template Structure
|
||||
|
||||
### Base Templates
|
||||
- **`framework.html`** - Legacy Bootstrap base (for unmigrated pages)
|
||||
- **`framework_modern.html`** - Modern Tailwind/DaisyUI base (for new pages)
|
||||
|
||||
### Shared Includes
|
||||
- **`includes/navbar.html`** - Modern DaisyUI navbar (used in framework_modern.html)
|
||||
- **`includes/footer.html`** - Modern Tailwind footer (used in framework_modern.html)
|
||||
|
||||
These includes make it easy to maintain consistent navigation and footer across all migrated pages.
|
||||
|
||||
## Files Modified in Initial Migration
|
||||
|
||||
1. `static/css/daisyui-theme.css` - Fixed `--color-base-100: blue` bug
|
||||
2. `templates/framework_modern.html` - New modern base template
|
||||
3. `templates/includes/navbar.html` - Extracted navbar component
|
||||
4. `templates/includes/footer.html` - Extracted footer component
|
||||
5. `templates/index/index.html` - Migrated to use framework_modern.html
|
||||
6. `static/css/output.css` - Rebuilt with fixed theme
|
||||
|
||||
## Resources
|
||||
|
||||
- [Tailwind CSS v4 Docs](https://tailwindcss.com/)
|
||||
- [DaisyUI v5 Docs](https://daisyui.com/)
|
||||
- [DaisyUI Components](https://daisyui.com/components/)
|
||||
- [DaisyUI Themes](https://daisyui.com/docs/themes/)
|
||||
- [Strangler Fig Pattern](https://martinfowler.com/bliki/StranglerFigApplication.html)
|
||||
|
||||
## Questions?
|
||||
|
||||
Check the existing modern templates for examples:
|
||||
- `templates/framework_modern.html` - Base template structure
|
||||
- `templates/index/index.html` - First migrated page with hero section, cards, etc.
|
||||
Reference in New Issue
Block a user