Development.nl

🌐 English · Deutsch · Español · Français · 简体中文

Ontwikkeling

Deze pagina beschrijft hoe u een lokale ontwikkelomgeving opzet voor app/ zelf — in tegenstelling tot Installeren (de verpakte desktopversie draaien) of Implementeren (de gecontaineriseerde productievorm draaien). Lees eerst Architectuur voor hoe de onderdelen in elkaar passen.

Aan de slag

npm install                 # installeert de workspace (app/ + packages/gramps-date)
cp app/.env.example app/.env.local   # wijst naar een draaiende gramps-web-api-instantie
npm run dev -w app          # start de Vite-ontwikkelserver

app/ heeft een echte gramps-web-api-backend nodig om mee te praten — het is een pure client, er is geen modus met nepgegevens. De lichtste optie is dev-fixtures/layer2-local-cache/api-fixture-example/setup.sh (zie Dev-fixtures hieronder).

Elke fixture draait gramps-web-api vanuit een broncode-checkout in dezelfde Python-omgeving als het fixturescript, dus die omgeving heeft het volgende nodig:

pip install -e ~/gramps/gramps --no-deps          # gramps zelf
pip install -e ~/gramps/gramps-web-api --no-deps  # + de afhankelijkheden, zie hieronder
python3 deploy/webapi-requirements.py ~/gramps/gramps-web-api/pyproject.toml \
  | pip install -r /dev/stdin

const.py van gramps-web-api voert bij het importeren gi.require_version("Gtk", "3.0") uit, dus echte PyGObject en de GTK3-typelibs moeten aanwezig zijn (apt install python3-gi gir1.2-gtk-3.0, of conda install -c conda-forge pygobject gtk3); PyICU is optioneel maar onderdrukt een lokalisatiewaarschuwing en repareert het sorteren van namen.

Merk op dat de /api/<type>/query/-endpoints waarop app/ is gebouwd in de master van gramps-project/gramps-web-api zijn opgenomen — een oudere fork of branch geeft op elk daarvan een 404.

Dev-fixtures

dev-fixtures/ bevat echte gramps-web-api-backends om app/ lokaal tegen te draaien. Ze maken geen deel uit van het uitgeleverde product — ze maken alleen lokale ontwikkeling mogelijk zonder zelf met de hand een server te configureren. Lees een script voordat u het uitvoert — geen ervan is idempotent ten opzichte van een al gevulde stamboom. Elke fixture logt in als gramps/gramps.

• layer2-local-cache/api-fixture-example/ — de lichtste optie: een instantie met gewone SQLite op :5002, geladen met de officiële voorbeelddatabase example.gramps van Gramps zelf, handig voor echte variatie in datums (modificatoren, kwaliteit, bereiken/perioden). Zet VITE_API_BASE=http://localhost:5002 in app/.env.local om ernaar te verwijzen. Live synchronisatie werkt er ook mee, omdat het gewoon een poll op /api/transactions/history/ is, niet gebonden aan Postgres.
• layer2-local-cache/api-fixture/ — nog een instantie met gewone SQLite, in plaats daarvan geladen met synthetische gegevens die door gramps-bench zijn gegenereerd, om op schaal te testen tegen een grote stamboom.
• layer3-sync/api-fixture/ — een instantie met een echte Postgres (SharedPostgreSQL) als basis, handig om echt gelijktijdige bewerkingen door meerdere schrijvers op dezelfde stamboom te oefenen. Hiernaar wijst de standaard-VITE_API_BASE van app/.env.example, en het vereist een draaiende Postgres plus de add-on SharedPostgreSQL, naast alles wat de SQLite-fixtures nodig hebben.

Gramplet-wheels bouwen

Gramplets draaien Python in de browser onder Pyodide, met lokaal gebouwde wheels die de postinstall-stap van npm install overslaat (met een logregel) als ze er nog niet zijn — waardoor Gramplets tijdens het draaien mislukken met No known package with name 'gramps-gen-lib'. Bouw ze één keer:

python3 scripts/build-stub-wheels.py    # vervangers voor gi + orjson voor Pyodide
python3 scripts/build-gramps-wheel.py   # gramps.gen.lib als Pyodide-wheel
node app/scripts/copy-wasm.mjs          # registreert ze in public/pyodide/

Testen

npm run test -w app         # Vitest: pure store-/synclogica, geen weergave van de hele app
npm run typecheck -w app    # tsc --noEmit
npm run test -w packages/gramps-date
pytest tests/               # ingebouwde GOQL-filtervoorinstellingen vs. echte regels van gramps-core

De pytest-suite (tests/gql_presets/, zie de eigen README) controleert elke ingebouwde Filters-voorinstelling (app/src/data/gqlFilterPresets.ts) tegen de echte klasse Rule van gramps-core die ze moet nabootsen, uitgevoerd op de eigen meegeleverde voorbeeldstamboom van gramps-core — zodat niet alleen "compileert dit" wordt gecontroleerd, maar ook "selecteert het dezelfde rijen als de desktopregel zou doen". Vereist dat gramps/gramps-object-query-language importeerbaar zijn (wat overal waar gramps-web-api zelf draait al zo is); er is geen aparte stap nodig om de eigen JSON-momentopname van de voorinstellingen synchroon te houden, dat gebeurt automatisch.

Vertalingen

De UI-teksten van app/ gaan via t() (app/src/i18n/i18n.ts), dat de eigen aanpak van gramps-web volgt — een eenvoudige opzoeking {english: translated}, geen i18n-bibliotheek — samengevoegd uit twee bronnen per taal, gekozen op het moment van setLanguage() en in het geheugen bewaard tot de volgende taalwissel:

• De woordenschat van Gramps Desktop — live vertaald, per verzoek, door de teksten die daadwerkelijk worden gebruikt te POSTen naar het bestaande endpoint GET/POST /api/translations/<lang> van gramps-web-api, dat ze door de eigen gettext-catalogus van het geïnstalleerde gramps-pakket haalt. Geen statische kopie om synchroon te houden; altijd zo vers als de gramps-versie die de server heeft geïnstalleerd. De vaste lijst met op te vragen teksten uit de woordenschat van Desktop staat in de array desktopStrings van i18n.ts — met de hand uitgebreid, één item per tekst, telkens wanneer een nieuw ingepakte t()-aanroep echte Gramps-woordenschat blijkt te zijn in plaats van iets specifieks voor gramps-connect.
• De eigen UI-teksten van gramps-web, en teksten van Gramps-add-ons — als statische bestanden app/public/lang/{locale}.json opgezet (in git bijgehouden, zodat de app werkt zonder dat iemand een Weblate-verbinding nodig heeft) door scripts/bootstrap-translations.py, dat ../gramps-web/lang/ en ../addons-source/*/po/*-local.po leest — checkouts naast deze repository, geen netwerkaanroep. Voer het uit (python3 scripts/bootstrap-translations.py, vereist pip install polib) telkens wanneer die naastgelegen checkouts worden bijgewerkt en u de statische verzameling wilt vernieuwen; het is in geen enkele buildstap opgenomen, dus niets voert het automatisch uit. Veilig om opnieuw uit te voeren: zonder --force slaat het elke .json van een locale die al bestaat over, en zelfs met --force overschrijft het alleen bestanden onder app/public/lang/ — geen netwerkaanroepen, geen git-bewerkingen, en elk slecht resultaat is met een git checkout ongedaan te maken.

Meer van de eigen teksten van de app in t() inpakken is doorlopend, stapsgewijs werk — app/scripts/wrap-translations.mjs is een eenmalige codemod (bewaard als herbruikbaar hulpmiddel) die gewone JSX-tekst en een veilige toegestane lijst van attributen (label/title/placeholder) mechanisch inpakt; alles wat uit een variabele of een eigenschap van een object-literal komt (weergave-/kolomconfiguraties in app/src/store/views.ts, dynamische API-gegevens, aanroepen van notifications.show()) heeft in plaats daarvan een handmatige t(...) nodig in het component dat het weergeeft.

Bijdragen

De discussie vindt plaats op het Gramps Discourse-forum; issues en pull requests voor de gramps-connect-repository zijn welkom.

Licentie

AGPL-3.0-or-later, in lijn met gramps-web-api en gramps-web. packages/gramps-date vertaalt GPL-2.0-or-later-code uit de kern van Gramps naar de AGPL-3.0-or-later-codebase van dit project — zie de eigen README ervan (en Architectuur) voor hoe die twee licenties samengaan.