Naslag
Codeconventies
Waar alles staat, naamgeving, componenten, styling en commits.
Een paar afspraken houden een Nimbly-project overzichtelijk, voor de developer die het schreef, de designer die het opmaakt en wie het daarna oppakt.
Waar alles staat
| Wat | Waar |
|---|---|
| Markup | Templates: ext/tpl/ voor herbruikbare stukken, ext/uri/ voor routes |
| Logica en datavoorbereiding | Libraries in ext/lib/ |
| De vorm van je data | Resourcedefinities in ext/data/<resource>/.meta |
| Styles | ext/theme.css en Tailwind-classes in templates |
| Kleuren en thema's | ext/tailwind.theme.js |
| Een verpakte feature | ext/modules/<name>/ |
Templates blijven zonder logica en libraries bevatten geen HTML. Dan kan een designer elk stuk interface aanpassen zonder PHP te lezen, en een developer een regel wijzigen zonder markup aan te raken.
Naamgeving
Templates: eerst het type, dan het onderwerp. Kaarten staan dan bij elkaar, secties ook, en pagina's ook:
| Type | Gebruikt voor | Voorbeeld |
|---|---|---|
page- |
De inhoud van één pagina | page-about, page-contact |
section- |
Een sectie binnen een pagina | section-home-hero |
card- |
Eén herhaald item | card-project, card-team-member |
form- |
Een formulier | form-newsletter |
icon- |
Een inline icoon | icon-arrow-right |
btn- |
Een knop of knopstijl | btn-preview |
Schrijf card-project, niet project-card.
PHP: overal snake_case. Functies, variabelen, parameters en bestandsnamen: prepare_projects_sc(), $project_count, ext/lib/prepare-projects.php. Het bestand van de library gebruikt streepjes, omdat het ook de naam van de shortcode is, [#prepare-projects#].
Resources en velden: kleine letters, meervoud voor de resource. projects, team-members; velden zoals title, title_slug, published, sort_order.
Componenten
Een component is een herbruikbare template met alles wat hij nodig heeft in zijn eigen map:
ext/tpl/photo-collage/index.tpl the markup
ext/tpl/photo-collage/style.css its own CSS, imported from ext/theme.css
- Op zichzelf staand. De pagina roept alleen
[#photo-collage#]aan; de component hangt niet af van de pagina eromheen. - Ingesteld door de aanroeper. Wat per gebruik verschilt, wordt vóór de aanroep gezet:
[#set collage_columns=3 overwrite#], dan[#photo-collage#]. - Overdraagbaar. Een goede component werkt als je hem naar een ander project kopieert.
De meeste stukken interface zijn componenten. Maak er alleen een module van als hij ook eigen data of routes meebrengt.
Opmaak
- Gebruik de kleuren van het thema (
primary,secondaryen de eigen tokens van het project) in plaats van vaste paletkleuren, zodat een nieuw ontwerp een wijziging op één plek is. - Herhaalt een lange classlijst zich op meerdere elementen, geef die dan een eigen kleine template en hergebruik die. Een paar classes blijven gewoon inline.
- Zet classlijsten die je in een variabele bewaart tussen aanhalingstekens,
[#set card-style="rounded-2xl bg-white"#], zodat de build ze vindt.
Codestijl
- Gebruik altijd accolades bij
if,else,forenwhile, ook rond één regel, in PHP en JavaScript. - Los de oorzaak op, niet het symptoom: mist een template data, repareer dan de plek waar de data wordt geladen; breekt een layout, repareer dan de layout in plaats van de overflow te verbergen.
- Houd het zo klein als de huidige behoefte toelaat. Geen velden, instellingen of abstracties "voor later".
Commits
Gebruik Conventional Commits: een type, een optionele scope en één duidelijke regel.
feat(projects): filter the overview by sector
fix(header): logo and menu no longer overlap on phones
style(cards): align the card titles
Helpt meer context, zet die dan na een lege regel. De eerste regel staat op zichzelf.