Bouw een Nextcloud-app op de Conduction-stack, Deel 1: Scaffold

Dit is Deel 1 van een zesdelige tutorial waarin we DeskDesk bouwen, een flexibele bureau-reserveringsapp voor een open-kantoor-omgeving, op de volledige Conduction Nextcloud-stack. Het eindproduct: kies een bureau op een verdieping, boek een slot, zie je boeking in je Nextcloud Calendar, en haal zone-specifieke kennisartikelen uit xWiki op naast de boeking. Elk onderdeel hergebruikt wat @conduction/nextcloud-vue en OpenRegister je al gratis geven.

In Deel 1 zet je de app op, hernoem je hem, bouw je hem, en zie je het canonieke app-chassis op je scherm. Geen data, nog geen integraties. We krijgen eerst het skelet goed.

Wat we bouwen, over alle zes delen heen

Dezelfde vorm, twee repos:

• App-broncode: ConductionNL/deskdesk, de daadwerkelijke Nextcloud-app die je vanuit de template forkt.
• Tutorial-broncode: ConductionNL/conduction-website, de post die je nu leest.

Stap 1: Gebruik de template

ConductionNL/nextcloud-app-template is een GitHub repository template. De knop "Use this template" geeft je een verse repo met de volledige starter kit: Vue 2 + Pinia-frontend, PHP-backend, OpenRegister-bedrading, kwaliteitspijplijn, OpenSpec-scaffolding, GitHub Actions.

gh repo create ConductionNL/deskdesk \
  --template ConductionNL/nextcloud-app-template \
  --public \
  --description "Flexible desk booking for open-office environments"

Kloon hem daarna naast je andere Nextcloud-apps. De meeste workspaces houden ze in één apps-extra/-map die de dev-container mount.

cd /path/to/your/nextcloud/workspace/apps-extra
git clone https://github.com/ConductionNL/deskdesk.git
cd deskdesk

Je hebt nu een directory met de volledige template-inhoud onder de nieuwe naam. Binnenin is nog niets hernoemd. De map heet deskdesk/, maar elk bestand zegt nog app-template, AppTemplate, OCA\AppTemplate. Stap 2 lost dat op.

Stap 2: Hernoem de app

Nextcloud vereist dat drie identifiers overeenkomen:

• De directorynaam (deskdesk/) ✅ klaar
• De <id> in appinfo/info.xml
• De PHP-namespace (OCA\AppTemplate → OCA\DeskDesk)

Plus een handvol ondersteunende bestanden die naar het oude id verwijzen. De volledige lijst is klein genoeg om met de hand te doen, en met de hand doen is hier de juiste keuze. Project-geheugen: gebruik nooit sed of scripted edits op code-bestanden, gebruik een echte editor met project-aware refactoring, of lees elk bestand één keer voor je het wijzigt.

2a. De boot-kritische bestanden

Dit zijn degene die voorkomen dat Nextcloud de app überhaupt opstart. Bewerk elk met Find & replace all in je editor: AppTemplate → DeskDesk en app-template → deskdesk:

2b. De "kan later"-bestanden

Tests (tests/Unit/AppTemplateTest.php, de integratie-Postman-collectie), phpcs.xml / phpmd.xml / REUSE.toml headers, en de .github/ workflow-inputs. Die verwijzen alleen in metadata naar het template-id; de app start prima zonder dat je ze aanraakt. Fix ze als je CI opzet.

2c. Eén Nextcloud-versie compatibiliteitsfix

De lib/AppInfo/Application.php van de template registreert een repair step at runtime:

$context->registerRepairStep(InitializeSettings::class);

registerRepairStep() ontbreekt op IRegistrationContext in een paar Nextcloud-builds (je ziet Call to undefined method in nextcloud.log). Verplaats het naar appinfo/info.xml in plaats daarvan, zelfde effect, beter draagbaar:

<repair-steps>
    <install>
        <step>OCA\DeskDesk\Repair\InitializeSettings</step>
    </install>
    <post-migration>
        <step>OCA\DeskDesk\Repair\InitializeSettings</step>
    </post-migration>
</repair-steps>

Haal daarna de registerRepairStep()-regel en de use OCA\DeskDesk\Repair\InitializeSettings; import weg uit lib/AppInfo/Application.php.

Stap 3: Bouwen en activeren

De template levert zijn build-output ongecommit. Het eerste in een verse kloon is dus dependencies installeren en de JS-bundels bouwen, anders is de app-UI gewoon een lege <div id="content">.

composer install --no-dev
composer dump-autoload
npm install --legacy-peer-deps
npm run build

Zorg daarna dat je Nextcloud-container de directory kan zien. In een typische Docker-setup is de apps-extra/ host-directory gemount op /var/www/html/custom_apps/ in de container. Gebruikt je compose-file één bind-mount per app, voeg dan een regel toe voor deskdesk en restart. Anders:

docker cp ./deskdesk nextcloud:/var/www/html/custom_apps/
docker exec -u root nextcloud chown -R www-data:www-data /var/www/html/custom_apps/deskdesk

Nu activeren:

docker exec nextcloud php occ app:enable deskdesk

Je zou moeten zien:

deskdesk 0.1.0 enabled

Open http://localhost:8080/apps/deskdesk/ en log in. Je ziet een placeholder-dashboard met voorbeeld-KPI-kaarten, twee lege panelen, drie nav-items (Dashboard / Items / Documentation) en een Settings-entry vastgezet onderaan de rail. Dat is het chassis.

Het chassis: de hele bedoeling van Deel 1

Elke Conduction-app, DeskDesk, OpenRegister, OpenCatalogi, Procest, MyDash, de dozijn anderen, ziet er op het eerste gezicht hetzelfde uit. Dezelfde vijf structurele stukken, dezelfde plek, hetzelfde gedrag. Die herkenbaarheid is wat @conduction/nextcloud-vue afdwingt: een gebruiker die één app leerde, navigeert de volgende zonder docs.

Het chassis is één vorm, vijf atomen. Elke kaart hieronder focust op één atoom: de gefocuste zone staat op volledige dekking met een KNVB-oranje rand, de rest vervaagt naar 25% zodat je ziet waar het atoom zit.

In Deel 2 leer je hoe manifest.json plus een JSON-schema deze atomen vult met echte data. De placeholder Items-nav-entry, het lege dashboard, en het "article"-schema dat je op het scherm zag, worden allemaal bureaus, boekingen, en een echt bezettings-dashboard, zonder dat je één atoom met de hand uitlegt.

Troubleshooting

Wat volgt