Van eerste start tot hergebruik
Eén bibliotheek. Helder gedocumenteerd.
Django, Django-templates, Vanilla JavaScript en lokale assets. De documentatie en alle {{ components|length }} componenten zitten in hetzelfde downloadpakket.
1. Installeren en starten
Pak het volledige project uit en open een terminal in de map met manage.py en requirements.txt.
python -m venv .venv # Windows PowerShell: .venv\Scripts\Activate.ps1 # macOS / Linux: # source .venv/bin/activate python -m pip install -r requirements.txt python manage.py migrate python manage.py seed_projects python manage.py runserver
Open http://127.0.0.1:8000. Catalogus: /. Projecten met echte opslag: /projects/. Deze documentatie: /documentation/.
De online preview is statisch. De download bevat de Python-backend, schema’s, tests, lokale assets en documentatie.
Eigen CSS-host en pip-pakket
Download één zelfstandig dibos.css-bestand en plaats het op je eigen website. Pip kan geen eigen --css-url-optie verwerken. Installeer het pakket en gebruik daarna het meegeleverde configuratiecommando.
python -m pip install ./dibos_css-0.8.0-py3-none-any.whl # In je bestaande Django-project, met fluent_web in INSTALLED_APPS: python manage.py dibos_install --css-url https://jouw-domein.nl/assets/dibos.css # Productie: python manage.py collectstatic --noinput
De CSS wordt eenmalig gedownload naar BASE_DIR/static/dibos/dibos-<inhoudshash>.css. BASE_DIR/dibos.json bewaart de verwijzing; de bestaande assettags en demo gebruiken de lokale kopie automatisch. De AppConfig registreert hiervoor een beperkte Django staticfiles-finder. Er zijn geen externe CSS-imports of runtimeverzoeken naar de oorspronkelijke website. Een mislukte download behoudt de vorige configuratie. Terug naar standaard-CSS: python manage.py dibos_install --bundled.
Volledige demo vanuit pip
dibos demo --directory ./dibos-demo # Met eigen CSS, vóór of na het starten: dibos install --directory ./dibos-demo --css-url https://jouw-domein.nl/assets/dibos.css
De wheel bevat alle templates, 63 componenten, tien spinners, iconen, Chart.js, paleteditor en documentatie. Het commando maakt de lokale demo-database en start de app op http://127.0.0.1:8000/. Je eigen gegevens staan buiten het geïnstalleerde pakket.
Instellingen → Demo
Open Instellingen in de navigatie en kies Demo. Wijzig Demoscherm inschakelen en sla op. Deze keuze blijft in de Django-app centraal bewaard na vernieuwen en opnieuw starten. Uitgeschakeld verdwijnen de demo en documentatie uit de navigatie en krijgen directe demo-URL’s HTTP 404. Je projecten, downloads en herbruikbare componenten blijven beschikbaar. Instellingen blijven bereikbaar op /settings/, of bijvoorbeeld /ui/settings/ wanneer je de app onder ui/ opneemt.
python manage.py dibos_install --demo off python manage.py dibos_install --demo on
Bij DEBUG=False vereist de instellingenroute een aangemelde Django-gebruiker met is_staff=True; gebruik de authenticatie van je eigen applicatie. In de statische online preview geldt de schakelaar alleen voor de huidige browser. De volledige instructies staan in docs/INSTALLATION.md. Bewaar db.sqlite3, dibos.json en static/dibos/ bij updates.
2. CSS, toestanden en focus
De basislayout laadt één bibliotheekbestand: de meegeleverde dibos.css of je geïnstalleerde lokale kopie. Eigen pagina-CSS volgt daarna; focus.css staat als laatste. De afzonderlijke bronmodules blijven beschikbaar:
tokens.css # Kleuren, afstanden, typografie en beweging components.css # Herbruikbare fw-componenten fields.css # Labels boven, links of als placeholder spinners.css # Tien CSS-laadanimaties catalog.css # Alleen voor de catalogus, niet voor je eigen app projects.css # Alleen voor de voorbeeldwerkruimte focus.css # Centrale focusstijlen; altijd als laatste
Eén fijne rand, precies op de bestaande rand
Een invoerveld, tekstvak of selectveld heeft altijd dezelfde rand van 1 px. Bij focus verandert alleen de kleur van die rand. De hoekafronding, afmetingen en padding blijven gelijk. Er is geen buitenring, gloed of tweede onderlijn.
.fw-input,
.fw-select,
.fw-textarea {
border: 1px solid var(--fw-border-strong);
outline: none;
box-shadow: none;
}
.fw-input:focus,
.fw-select:focus,
.fw-textarea:focus {
border-color: var(--fw-focus-color);
}Focus blijft zichtbaar voor toetsenbordgebruikers. Buttons kleuren hun bestaande rand. Tabs krijgen een zachte achtergrond. Tekstlinks worden onderstreept. Checkboxes, radio’s, switches, sliders en kleurvelden gebruiken hun eigen fijne rand. Een ongeldig veld houdt één rode rand via aria-invalid="true"; disabled velden krijgen geen focus.
Waar stel je het label in?
Direct boven Text input & select staat nu de keuzelijst Veldlabel. Kies Boven, Links of Placeholder. De instelling staat ook rechts onder Veldlabels en in de componentpreview.
Veldomschrijving: boven, links of in het veld
Kies de standaardplaatsing onder Veldlabels in de catalogus, of kies een plaatsing per componentpreview. In je eigen template gebruik je label_position="top", "left" of "inside". De linkse plaatsing gebruikt een grid; een label in het veld wordt een placeholder wanneer het veld leeg is. Een verborgen label blijft beschikbaar voor schermlezers. Wisselen van plaatsing wist geen ingevulde waarden.
{% verbatim %}{% fw_component "inputs" label="Projectnaam" label_position="left" %}
{% fw_component "inputs" label="E-mailadres" label_position="inside" %}{% endverbatim %}Native datum- en tijdvelden ondersteunen geen placeholders; bij de inside-keuze blijft daar het label boven het veld staan. --fw-label-width en --fw-label-gap regelen de linkse labelkolom. Initialiseer dynamische velden met FW.configureFields(container).
Centrale tokens
| Token | Betekenis |
|---|---|
--fw-control-border-width | 1 px, voor normale én gefocuste controls |
--fw-focus-color | Volgt automatisch --fw-accent |
--fw-focus-on-accent | Leesbare rand op een gevulde primaire knop |
--fw-border-strong | Normale grijze controlrand |
--fw-radius | Gelijke afronding in elke toestand |
--fw-duration | Korte kleurtransitie, zonder maatverandering |
De CSS is leesbaar opgemaakt. Focusregels staan op één plek. Zet geen algemene *:focus-visible-buitenring of extra focus-shadow boven op deze regels. Voor Windows high contrast zijn systeemkleuren voorzien; verminderde beweging wordt gerespecteerd.
3. Alle componenten
Gebruik de template tag in een template die de basislayout uitbreidt. Deze laadt CSS, gedrag en demonstratiedialogen.
{% verbatim %}{% extends "fluent_web/base.html" %}
{% load fluent_ui %}
{% block content %}
{% fw_component "buttons" label="Opslaan" variant="primary" %}
{% fw_component "inputs" label="Projectnaam" name="project" required=True %}
{% endblock %}{% endverbatim %}Parameters
Velden ondersteunen label_position: top, left of inside.
Buttons: label, variant (primary, secondary, subtle), size (small, normal, large), disabled. Inputs: label, name, value, placeholder, required, disabled. Badges: label, tone (success, warning, danger, neutral, accent). Andere componenttemplates zijn samenstelbare voorbeelden; pas de inhoud en backendacties aan je eigen applicatie aan.
Elke instance krijgt unieke identifiers. Gewone tekstparameters worden door Django-templates geëscapet. Alleen geregistreerde namen en toegestane varianten worden geaccepteerd.
{{ c.name }} · {{ c.category_label }}
{{ c.usage }}
Varianten: {{ c.variants }}
{{ c.example }}Template: templates/components/{{ c.id }}.html
In de live catalogus kun je HTML, CSS, JavaScript en Django/Django-templates bekijken en kopiëren. De CSS-weergave bevat ook de centrale focusregels.
Zijbalk, bestanden, statistiekkaartjes en teksteditor
De navigatieknop linksboven klapt de linkerzijbalk in of uit. De knop blijft bereikbaar en de desktopkeuze wordt per apparaat bewaard. In Instellingen staat ook Linkerzijbalk zichtbaar. Gebruik .fw-shell met data-fw-sidebar op het paneel en een knop buiten het paneel met data-fw-sidebar-toggle en het bijbehorende aria-controls.
Bestanden kiezen of slepen
{% verbatim %}{% fw_component "file-upload" label="Bijlagen" name="files" multiple=True accept=".pdf,.png" max_files=5 max_size=5242880 %}
{% fw_component "file-dropzone" label="Documenten" name="files" multiple=True %}{% endverbatim %}Beide componenten tonen namen en groottes, laten bestanden verwijderen en controleren type, aantal en grootte. De demo selecteert bestanden lokaal; jouw multipart-formulier verstuurt ze naar je eigen Django-view via request.FILES.getlist('files').
Statistieken inkleuren en centreren
{% verbatim %}{% fw_component "kpi" value="128" label="Projecten" color="blue" card_style="soft" align="center" valign="center" %}
{% fw_component "kpi" value="94%" label="Afgerond" color="#007568" card_style="solid" align="center" valign="center" size="large" %}{% endverbatim %}Kaartstijlen: surface, soft, solid, outline. Kleuren: theme, blue, purple, green, rose, orange, neutral of #rrggbb. Horizontaal en verticaal: start, center, end. De galerij Statistiekkaartjes toont zes voorbeelden; Kaartje aanpassen werkt de gekopieerde code bij.
Wachtwoordveld met oogje
{% verbatim %}{% fw_component "inputs" input_type="password" label="Wachtwoord" name="password" %}
{% fw_component "password" label="Nieuw wachtwoord" autocomplete="new-password" clearable=True label_position="inside" %}{% endverbatim %}Open Wachtwoorden in de demo. Een wachtwoord is standaard gemaskeerd; het oogje toont of verbergt de invoer zonder de waarde te wijzigen. Een gewoon invoerveld krijgt deze functie via Veldtype → Wachtwoord in de componentpreview. De knop heeft een toegankelijke naam en werkt via het toetsenbord. Labelposities en het optionele wis-kruisje worden ondersteund; de fijne focusrand blijft behouden. Autocomplete is standaard current-password, of new-password voor een nieuw wachtwoord.
Wis-kruisje in een veld
{% verbatim %}{% fw_component "inputs" label="Projectnaam" clearable=True label_position="inside" %}{% endverbatim %}De knop verschijnt wanneer het veld inhoud heeft en wist met één klik. De focus keert terug naar het veld. Werkt met labels boven, links en in het veld, met dezelfde enkele focusrand.
HTML-toolbar met pixels en een zwevende stand
{% verbatim %}{% fw_component "rich-text" label="Omschrijving" name="description" toolbar="static" %}
{% fw_component "rich-text" label="Notities" name="notes" toolbar="sticky" %}{% endverbatim %}Lettertype, tekststijl, exacte grootte in pixels, tekstkleur, markering, vet/cursief/onderstrepen/doorhalen, subscript/superscript, uitlijnen, lijsten, inspringen, links, undo/redo, opmaak wissen en HTML-bron. Selecteer tekst en kies de opmaak. Kies in de componentpreview bij Toolbar tussen Vast boven het veld en Zwevend bij scrollen. De sticky-stand blijft binnen de editor; de bovenmarge is instelbaar via --fw-editor-sticky-top.
Een verborgen textarea levert de HTML aan je formulier. Geplakte HTML en broninvoer worden lokaal gefilterd. Filter HTML ook op de server voordat je deze opgemaakt weergeeft. Alles werkt met lokale assets. Zie docs/COMPONENT_EXTRAS.md voor de complete componenthandleiding.
Tien spinners om uit te kiezen
Open Spinners links in de catalogus. Vergelijk de tien live animaties, kies kleur, grootte en snelheid, en klik op een variant voor de eigen kleurkiezer en kopieerbare code. Beschikbaar: Fluent ring, Dubbele boog, Kleurenring, Springende bolletjes, Orbit, Pulserende ringen, Golfbalkjes, Kometenstaart, Dansende tegels en Elastische bol.
{% verbatim %}{% load fluent_ui %}
{% fw_component "spinner" variant="orbit" color="multi" size="large" speed="normal" label="Gegevens laden…" %}
{% fw_component "spinner" variant="dots" color="#007568" paused=True %}{% endverbatim %}Varianten: ring, dual, gradient, dots, orbit, ripple, bars, comet, tiles, blob. Kleuren: theme, multi, blue, purple, green, rose, orange of een volledige hexkleur. Grootte: small, normal, large. Snelheid: slow, normal, fast. paused=True pauzeert de animatie. Een zichtbare statusnaam blijft beschikbaar; de animatie is decoratief. Verminderde beweging schakelt animatie uit. Laad spinners.css na de componentstyles; de assettag doet dat automatisch. De animaties vereisen geen JavaScript. Zie ook docs/SPINNERS.md.
4. Thema’s en een eigen kleurenpalet
Basisthema’s: Fluent Default, Lavender, Sky Blue, Sage Green, Peach, Soft Rose en Dark. Activeer ze op het HTML-element met data-theme. Licht/donker gebruikt data-mode.
<html data-theme="lavender" data-mode="light">
Klik op Eigen palet samenstellen om accent, achtergrond, panelen en tekst te kiezen. Kleurkiezers en hexvelden werken samen. De preview toont je ontwerp voordat je het toepast. Hover, randen en ondersteunende tekstkleuren worden afgeleid.
Toepassen en CSS-export vereisen minimaal 4,5:1 voor tekst op de gekozen achtergrond en panelen. Dit is een gerichte tekstcontrastcontrole, geen volledige toegankelijkheidscertificering. De keuze wordt lokaal in de browser bewaard, ook voor de projectpagina. Annuleren laat het actieve palet staan.
Exporteer het palet als CSS en laad het na tokens.css. Gebruik de HTML-attributen die in het geëxporteerde bestand staan. De focuskleur volgt de nieuwe accentkleur automatisch; de rand blijft 1 px. Compacte bediening: data-density="compact".
5. Django, SQLite en je gegevens
Draai python manage.py migrate om de SQLite-tabellen in db.sqlite3 te maken. Je hoeft geen databasebestand te downloaden of handmatig te importeren. fluent_web/migrations/ definieert de initiële migratie. Voorbeelddata voeg je afzonderlijk toe.
python manage.py migrate # Controleert/maakt schema; wist geen gegevens python manage.py seed_projects # Voegt vier voorbeelden toe; mag opnieuw
Een project heeft id, name (1–80 tekens, uniek), owner (maximaal 100 tekens), status, created_at en updated_at. Status: Concept, Actief, In review of Afgerond. De projectpagina bewaart echte wijzigingen; de componentpreviews blijven geïsoleerde voorbeelden.
Voor een backup: stop de app en kopieer db.sqlite3. Plaats het bestand in dezelfde map van een andere installatie. Initialisatie behoudt bestaande data. Controleer je migraties bij het overzetten van een bestaande database.
6. JSON-API en JavaScript
| Methode | Route | Gedrag |
|---|---|---|
| GET | /api/projects | Lijst, zoeken, statusfilter en sortering |
| POST | /api/projects | Aanmaken, 201 bij succes |
| PATCH | /api/projects/<id> | Naam, eigenaar of status bijwerken |
| DELETE | /api/projects/<id> | Verwijderen, 204 bij succes |
Zoekparameters: q, status, sort (name, owner, status, created_at, updated_at) en direction (asc of desc). Mutaties gebruiken JSON en het X-CSRFToken en de bijbehorende CSRF-cookie. Ongeldige invoer: 400; ontbrekende CSRF: 403; niet gevonden: 404; dubbele naam: 409.
fluent.js gebruikt gedelegeerde data-fw-*-events. Publieke JavaScript-helpers: FW.toast(message), FW.copy(text), FW.openDialog(id), FW.mount(container) en FW.updateCharts(). Laad Chart.js vóór fluent.js wanneer je grafieken gebruikt. Normale HTML-controls hebben geen extra initialisatie nodig.
7. Integratie en projectstructuur
manage.py Django-commando’s demo/settings.py Voorbeeldinstellingen, inclusief SQLite fluent_web/models.py Projectmodel fluent_web/migrations/ Django-migraties fluent_web/views.py Catalogus, documentatie en JSON-API fluent_web/templatetags/ Herbruikbare componenttags fluent_web/templates/ Django-templates en 63 componenten fluent_web/static/fluent_web/ CSS, JavaScript en lokale iconen docs/ Offline HTML- en Markdown-handleidingen build_docs.py Documentatie opnieuw genereren tests/ Django-tests CHANGELOG.md Wijzigingen en versies QUALITY.md Uitgevoerde controles en beperkingen
De meegeleverde Django-app kan in een eigen Django-project worden opgenomen. Neem de fw-klassen en Django-templates over of gebruik de template tag. Laat catalogus-CSS weg wanneer je een eigen shell hebt. Voeg eigen pagina-CSS toe in het Django-templates-block styles; de basislayout laadt focus.css daarna als laatste. Gebruik servervalidatie, CSRF en applicatieautorisatie voor je eigen data-acties.
De voorbeeldapp bindt standaard op localhost en bevat geen inlogmodule. Gebruik een gedeelde DJANGO_SECRET_KEY en een geschikte WSGI-server voor je eigen productieomgeving. De meegeleverde ontwikkelsleutel is alleen bedoeld voor localhost. Runtimegegevens en sleutels zitten niet in de download.
Updates: pak een nieuwe versie naast je bestaande installatie uit en kopieer de database bewust over wanneer je die wilt behouden. Bewaar je bestaande database en eigen instellingen bij een update.
8. Controle, toegankelijkheid en licenties
python manage.py test tests
De focusstijl is gecontroleerd op één rand, gelijke afmetingen en zichtbare toetsenbordbediening in lichte, donkere en eigen paletten. Zie QUALITY.md voor de exacte uitgevoerde controles en beperkingen. Edge/Firefox en handmatige schermlezertests zijn niet volledig uitgevoerd.
De eigen code gebruikt MIT. Microsoft Fluent System Icons en Chart.js zijn lokaal meegeleverd onder MIT. Zie LICENSE en THIRD_PARTY_NOTICES.md. Dibos CSS-project is een zelfstandige implementatie.