sboulahtit/orion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add comprehensive Jinja macros documentation

Browse Source 
New documentation:
- docs/frontend/shared/jinja-macros.md: Complete reference for all 94 macros
  - Alerts, Avatars, Badges, Buttons, Cards, Charts, Datepicker
  - Dropdowns, Forms, Headers, Modals, Pagination, Tables
  - Usage examples and parameter documentation
  - Complete page example showing all macros together

Updated documentation:
- docs/frontend/cdn-fallback-strategy.md:
  - Add Chart.js (v4.4.1) and Flatpickr (v4.6.13) sections
  - Document optional-libs.html loader macros
  - Update file structure and deployment checklist

- docs/frontend/shared/ui-components.md:
  - Add tip box recommending Jinja macros for new development
  - Update related documentation links

- mkdocs.yml:
  - Add Jinja Macros Library to navigation (top of Shared Components)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Samir Boulahtit
2025-12-06 19:15:27 +01:00
parent ffa15aee2b
commit dad0989948
4 changed files with 1288 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

140
docs/frontend/cdn-fallback-strategy.md
View File

@@ -13,11 +13,21 @@ All three frontends (Shop, Vendor, Admin) implement a robust CDN fallback strate
The following assets are loaded from CDN with automatic fallback to local copies: The following assets are loaded from CDN with automatic fallback to local copies:
### Core Assets (Always Loaded)
| Asset | CDN Source | Local Fallback | | Asset | CDN Source | Local Fallback |
|-------|-----------|----------------| |-------|-----------|----------------|
| **Tailwind CSS** | `https://cdn.jsdelivr.net/npm/tailwindcss@2.2.19/dist/tailwind.min.css` | `static/shared/css/tailwind.min.css` | | **Tailwind CSS** | `https://cdn.jsdelivr.net/npm/tailwindcss@2.2.19/dist/tailwind.min.css` | `static/shared/css/tailwind.min.css` |
| **Alpine.js** | `https://cdn.jsdelivr.net/npm/alpinejs@3.13.3/dist/cdn.min.js` | `static/shared/js/vendor/alpine.min.js` | | **Alpine.js** | `https://cdn.jsdelivr.net/npm/alpinejs@3.13.3/dist/cdn.min.js` | `static/shared/js/vendor/alpine.min.js` |
### Optional Assets (Loaded On Demand)
| Asset | CDN Source | Local Fallback | Used For |
|-------|-----------|----------------|----------|
| **Chart.js** | `https://cdn.jsdelivr.net/npm/chart.js@4.4.1/dist/chart.umd.min.js` | `static/shared/js/vendor/chart.umd.min.js` | Charts macros |
| **Flatpickr JS** | `https://cdn.jsdelivr.net/npm/flatpickr@4.6.13/dist/flatpickr.min.js` | `static/shared/js/vendor/flatpickr.min.js` | Datepicker macros |
| **Flatpickr CSS** | `https://cdn.jsdelivr.net/npm/flatpickr@4.6.13/dist/flatpickr.min.css` | `static/shared/css/vendor/flatpickr.min.css` | Datepicker styling |
## Implementation ## Implementation
### Tailwind CSS Fallback ### Tailwind CSS Fallback
@@ -71,25 +81,108 @@ Alpine.js uses dynamic script loading with error handling:
6. Creates new script element pointing to local copy 6. Creates new script element pointing to local copy
7. Appends fallback script to `<head>` 7. Appends fallback script to `<head>`
### Optional Libraries (Chart.js & Flatpickr)
Optional libraries are loaded on-demand using Jinja macros. This keeps page load times fast by only loading what's needed.
**Location:** `app/templates/shared/includes/optional-libs.html`
#### Loading Chart.js
In your page template:
```jinja
{% block chartjs_script %}
{% from 'shared/includes/optional-libs.html' import chartjs_loader %}
{{ chartjs_loader() }}
{% endblock %}
```
**Generated code:**
```html
<script>
(function() {
var script = document.createElement('script');
script.src = 'https://cdn.jsdelivr.net/npm/chart.js@4.4.1/dist/chart.umd.min.js';
script.onerror = function() {
console.warn('Chart.js CDN failed, loading local copy...');
var fallbackScript = document.createElement('script');
fallbackScript.src = '/static/shared/js/vendor/chart.umd.min.js';
document.head.appendChild(fallbackScript);
};
document.head.appendChild(script);
})();
</script>
```
#### Loading Flatpickr
Flatpickr requires both CSS and JS:
```jinja
{# In head - load CSS #}
{% block flatpickr_css %}
{% from 'shared/includes/optional-libs.html' import flatpickr_css_loader %}
{{ flatpickr_css_loader() }}
{% endblock %}
{# Before page scripts - load JS #}
{% block flatpickr_script %}
{% from 'shared/includes/optional-libs.html' import flatpickr_loader %}
{{ flatpickr_loader() }}
{% endblock %}
```
**Generated CSS code:**
```html
<link rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/flatpickr@4.6.13/dist/flatpickr.min.css"
onerror="this.onerror=null; this.href='/static/shared/css/vendor/flatpickr.min.css';">
```
#### Available Blocks in admin/base.html
| Block | Purpose | Location |
|-------|---------|----------|
| `flatpickr_css` | Flatpickr CSS | In `<head>` |
| `chartjs_script` | Chart.js | Before page scripts |
| `flatpickr_script` | Flatpickr JS | Before page scripts |
| `extra_scripts` | Page-specific JS | Last in body |
## File Structure ## File Structure
``` ```
static/ static/
├── shared/ ├── shared/
│ ├── css/ │ ├── css/
│ │ └── tailwind.min.css # 2.9M - Tailwind CSS v2.2.19 │ │ ├── tailwind.min.css # 2.9M - Tailwind CSS v2.2.19
│ │ └── vendor/
│ │ └── flatpickr.min.css # 16K - Flatpickr v4.6.13
│ └── js/ │ └── js/
│ └── vendor/ │ └── vendor/
│ └── alpine.min.js # 44K - Alpine.js v3.13.3 │ ├── alpine.min.js # 44K - Alpine.js v3.13.3
│ ├── chart.umd.min.js # 205K - Chart.js v4.4.1
│ └── flatpickr.min.js # 51K - Flatpickr v4.6.13
├── shop/ ├── shop/
│ └── css/ │ └── css/
│ └── shop.css # Shop-specific styles │ └── shop.css # Shop-specific styles
├── vendor/ ├── vendor/
│ └── css/ │ └── css/
│ └── tailwind.output.css # Vendor-specific overrides │ └── tailwind.output.css # Vendor-specific overrides
└── admin/ └── admin/
└── css/ └── css/
└── tailwind.output.css # Admin-specific overrides └── tailwind.output.css # Admin-specific overrides
app/templates/shared/
├── includes/
│ └── optional-libs.html # CDN fallback loaders for Chart.js & Flatpickr
└── macros/
├── charts.html # Chart.js wrapper macros
└── datepicker.html # Flatpickr wrapper macros
``` ```
## Frontend-Specific Implementations ## Frontend-Specific Implementations
@@ -217,7 +310,33 @@ cd static/shared/js/vendor
curl -o alpine.min.js https://cdn.jsdelivr.net/npm/alpinejs@3.13.3/dist/cdn.min.js curl -o alpine.min.js https://cdn.jsdelivr.net/npm/alpinejs@3.13.3/dist/cdn.min.js
``` ```
**Important:** Update both the local file AND the CDN URL in all three base templates. To update Chart.js:
```bash
cd static/shared/js/vendor
curl -o chart.umd.min.js https://cdn.jsdelivr.net/npm/chart.js@4.4.1/dist/chart.umd.min.js
```
To update Flatpickr:
```bash
# JavaScript
cd static/shared/js/vendor
curl -o flatpickr.min.js https://cdn.jsdelivr.net/npm/flatpickr@4.6.13/dist/flatpickr.min.js
# CSS
cd static/shared/css/vendor
curl -o flatpickr.min.css https://cdn.jsdelivr.net/npm/flatpickr@4.6.13/dist/flatpickr.min.css
```
**Important:** Update both the local file AND the CDN URL in the following locations:
| Asset | Update Location |
|-------|-----------------|
| Tailwind CSS | All three `base.html` templates |
| Alpine.js | All three `base.html` templates |
| Chart.js | `shared/includes/optional-libs.html` |
| Flatpickr | `shared/includes/optional-libs.html` |
## Production Deployment ## Production Deployment
@@ -226,6 +345,8 @@ curl -o alpine.min.js https://cdn.jsdelivr.net/npm/alpinejs@3.13.3/dist/cdn.min.
Before deploying to production, verify: Before deploying to production, verify:
- [ ] Local asset files exist in `static/shared/` - [ ] Local asset files exist in `static/shared/`
- [ ] Core assets: `tailwind.min.css`, `alpine.min.js`
- [ ] Optional assets: `chart.umd.min.js`, `flatpickr.min.js`, `flatpickr.min.css`
- [ ] File permissions are correct (readable by web server) - [ ] File permissions are correct (readable by web server)
- [ ] Static file serving is enabled in FastAPI - [ ] Static file serving is enabled in FastAPI
- [ ] CDN URLs are accessible from production network - [ ] CDN URLs are accessible from production network
@@ -239,9 +360,14 @@ Ensure local assets are included in Docker image:
# Dockerfile # Dockerfile
COPY static/ /app/static/ COPY static/ /app/static/
# Verify files exist # Verify core files exist
RUN test -f /app/static/shared/css/tailwind.min.css && \ RUN test -f /app/static/shared/css/tailwind.min.css && \
test -f /app/static/shared/js/vendor/alpine.min.js test -f /app/static/shared/js/vendor/alpine.min.js
# Verify optional library files exist
RUN test -f /app/static/shared/js/vendor/chart.umd.min.js && \
test -f /app/static/shared/js/vendor/flatpickr.min.js && \
test -f /app/static/shared/css/vendor/flatpickr.min.css
``` ```
### Static File Configuration ### Static File Configuration

1134
docs/frontend/shared/jinja-macros.md Normal file
View File

File diff suppressed because it is too large Load Diff

20
docs/frontend/shared/ui-components.md
View File

@@ -12,6 +12,22 @@ The admin panel uses a consistent set of UI components built with Tailwind CSS a
**Live Component Library:** Visit `/admin/components` in the admin panel to see all components with copy-paste ready code. **Live Component Library:** Visit `/admin/components` in the admin panel to see all components with copy-paste ready code.
!!! tip "Use Jinja Macros Instead"
For new development, prefer using the **[Jinja Macros Library](jinja-macros.md)** instead of copy-pasting HTML. Macros provide:
- **Consistency:** Same styling across all pages
- **Maintainability:** Update once, apply everywhere
- **Less code:** Parameters instead of full HTML
- **Type safety:** Built-in Alpine.js bindings
```jinja
{# Instead of 20 lines of HTML... #}
{% from 'shared/macros/buttons.html' import btn_primary %}
{{ btn_primary('Save Changes', icon='check', onclick='save()') }}
```
See [Jinja Macros Library](jinja-macros.md) for full documentation.
--- ---
## Page Layout Structure ## Page Layout Structure
@@ -462,6 +478,10 @@ function adminResourceList() {
## Related Documentation ## Related Documentation
- **[Jinja Macros Library](jinja-macros.md)** - Reusable macro components (recommended)
- [Pagination Guide](pagination.md)
- [CDN Fallback Strategy](../cdn-fallback-strategy.md)
- [Tailwind CSS](../tailwind-css.md) - [Tailwind CSS](../tailwind-css.md)
- [Icons Guide](../../development/icons-guide.md)
- [Tailwind CSS Official Docs](https://tailwindcss.com/docs) - [Tailwind CSS Official Docs](https://tailwindcss.com/docs)
- [Alpine.js Official Docs](https://alpinejs.dev/) - [Alpine.js Official Docs](https://alpinejs.dev/)

1
mkdocs.yml
View File

@@ -86,6 +86,7 @@ nav:
- CDN Fallback Strategy: frontend/cdn-fallback-strategy.md - CDN Fallback Strategy: frontend/cdn-fallback-strategy.md
- Tailwind CSS Build: frontend/tailwind-css.md - Tailwind CSS Build: frontend/tailwind-css.md
- Shared Components: - Shared Components:
- Jinja Macros Library: frontend/shared/jinja-macros.md
- UI Components: frontend/shared/ui-components.md - UI Components: frontend/shared/ui-components.md
- UI Components Quick Reference: frontend/shared/ui-components-quick-reference.md - UI Components Quick Reference: frontend/shared/ui-components-quick-reference.md
- Pagination: frontend/shared/pagination.md - Pagination: frontend/shared/pagination.md