# Kupola UI Toolkit - Integration Guide ## Table of Contents 1. [Flask Integration](#flask-integration) 2. [Django Integration](#django-integration) 3. [Static Site Integration](#static-site-integration) 4. [Python Helper Functions](#python-helper-functions) 5. [Production Deployment](#production-deployment) --- ## Flask Integration ### Step 1: Copy Files Copy the `kupola` directory to your Flask project's `static` folder: ``` your-flask-app/ ├── static/ │ └── kupola/ │ ├── css/ │ ├── js/ │ ├── icons/ ├── templates/ └── app.py ``` ### Step 2: Create Base Template Create `templates/base.html`: ```html {% block title %}Kupola{% endblock %} {% block content %}{% endblock %} {% block scripts %}{% endblock %} ``` ### Step 3: Use Components in Templates Create `templates/index.html`: ```html {% extends 'base.html' %} {% block title %}Dashboard{% endblock %} {% block content %}

Welcome

This is your dashboard

{% endblock %} ``` --- ## Django Integration ### Step 1: Copy Files Copy the `kupola` directory to your Django project's `static` folder: ``` your-django-app/ ├── your_app/ │ ├── static/ │ │ └── kupola/ │ │ ├── css/ │ │ ├── js/ │ │ ├── icons/ │ └── templates/ └── settings.py ``` ### Step 2: Configure Static Files In `settings.py`: ```python STATIC_URL = '/static/' STATICFILES_DIRS = [ os.path.join(BASE_DIR, 'your_app/static'), ] ``` ### Step 3: Create Base Template Create `templates/base.html`: ```html {% block title %}Kupola{% endblock %} {% block content %}{% endblock %} {% block scripts %}{% endblock %} ``` ### Step 4: Use Components in Templates Create `templates/index.html`: ```html {% extends 'base.html' %} {% block title %}Dashboard{% endblock %} {% block content %}

Welcome

This is your dashboard

{% endblock %} ``` ### Step 5: Register Custom Components (Optional) You can register custom components using `defineComponent`: ```js import { defineComponent } from '@kupola/kupola'; defineComponent('my-widget', { init(el) { // Your initialization logic el.addEventListener('click', () => console.log('clicked')); }, cleanup(el) { // Cleanup when removed }, dataAttribute: 'data-my-widget', cssClass: 'ds-my-widget' }); ``` Then use it in your template: ```html
Click me
``` Kupola's MutationObserver will automatically discover and initialize new elements. --- ## Static Site Integration ### Step 1: Copy Files Copy the `kupola` directory to your static site: ``` your-static-site/ ├── kupola/ │ ├── css/ │ ├── js/ │ └── icons/ └── index.html ``` ### Step 2: Create HTML Page Create `index.html`: ```html Kupola Dashboard

Welcome

``` --- ## Production Deployment ### Step 1: Build Files Run the build script to generate compressed files: ```bash cd kupola npm run build ``` ### Step 2: Use Compressed Files In production, use the minified files from the `dist/` directory: ```html ``` ### Step 3: CDN Deployment (Optional) Upload the `dist/` directory to a CDN and reference it: ```html ``` ### Step 4: Browser Caching Set appropriate caching headers for static assets: - CSS/JS files: `Cache-Control: public, max-age=31536000` - Icon files: `Cache-Control: public, max-age=31536000` --- ## Dashboard Integration ### Basic Dashboard Layout ```html
``` ### Complete Dashboard Example See `kupola/dashboard/dashboard.html` for a complete example. --- ## Tips 1. **Theme Switching**: Use `setTheme('light')` or `setTheme('dark')` to switch themes 2. **Brand Color**: Use `setBrand('zengqing')` to switch brand colors (default: 曾青 #535164) 3. **Validation**: Add `data-validate` attributes to form fields 4. **Tooltip**: Add `data-title` attributes to elements for tooltips 5. **Responsive**: The design system automatically adapts to different screen sizes --- ## Troubleshooting ### Icons Not Displaying Ensure the icons path is correct. The icons should be in `kupola/icons/` directory. ### Theme Not Applying Make sure the `data-theme` attribute is set on the `` element. ### JavaScript Not Working Kupola auto-bootstraps on DOMContentLoaded. If components don't initialize: 1. Ensure `kupola/dist/kupola.umd.js` is loaded 2. Call `kupolaBootstrap()` manually if loading dynamically 3. For dynamically added content, the MutationObserver handles auto-discovery 4. You can also call `bootstrapComponents(rootElement)` for a specific subtree ### CSS Not Loading Verify the CSS path is correct and the file exists. --- ## Support For issues or feature requests, please refer to the project documentation or create an issue.