designtopack/README.md

The project is based on Kirby CMS, Vite + Vue and Pinia as a state manager. Vue is used following the composition API approach.

Development

Development environment

First setup :

• From the /public directory, install the Kirby dependencies : composer install
• From the root directory, install the Node dependencies : npm install
• Replace the public/site/plugins/kqlplugins by its last version, downloaded from the official GitHub repo.
• Launch the servers (see below).
• Create the first user to the Kirby panel through http://localhost:8888/panel.
• In the root directory, create an .env file containing your user's connexion informations :

VITE_USERNAME=mail@example.com
VITE_PASSWORD=your-private-password

Servers

• From the /public directory, launch the PHP server : php -S localhost:8888 kirby/router.php.
• In another terminal tab, from the root directory, launch the Vite server : vite.

Code

Rules and conventions

• All .vue files' names are written in PascalCase : ✗ sidenav.vue ✗ sideNav.vue ✔ SideNav.vue ✔ Home.vue
• Stores files' names, located in /src/stores/, are written in camelCase and doesn't include the word "Store" : ✗ Api.js ✗ ApiStore.js ✗ apiStore.js ✔ api.js ✔ pageData.js

Creating a page

Templates are managed through Vue (/src/views). Thus, the process for creating new pages differs from the Kirby usual one. In addition to the blueprint (/public/site/blueprints/pages/example.yml) and template (/public/site/templates/example.php) files, it needs at least a content representation (/public/site/templates/example.json.php) and a view component (/src/views/example.vue) ones.

1. Create the blueprint as usual.
2. Create the corresponding template. Distincts templates are needed, but all of them should contain this same single line of code (that you can also find in /public/site/templates/example.php) : <?php snippet('generic-template') ?>.
3. Create the corresponding content representation following this code (also in /public/site/templates/example.json.php) :

<?php

$specificData = [
  "exampleField" => $page->exampleField(),
  "exampleHardData" => 'Example hard value'
];

$data = array_merge($genericData, $specificData);

echo json_encode($data);

$genericData are defined in the /public/site/controllers/site.php controllers. By default, it contains a simple representation of the page object.

4. Create the corresponding views in /src/views/. It's just a simple vue component that heritates data through the props (also in /src/views/Example.vue) :

<template>
  <h1>{{ data.content.title }}</h1>
  <!-- ... -->
</template>
<script setup>
const { data } = defineProps({
  data: Object,
});

// ....
</script>

5. Import the view in the /src/App.vue root component :

<script setup>
...
import example from "./views/Example.vue";

const components = {
  example
};

...
</script>

The name of the component should be exactly the same as the name of the template, including its case. This project follows the Vue convention to use pascal case