designtopack/README.md

The project is based on [Kirby CMS](https://getkirby.com), [Vite](https://vitejs.dev/) + [Vue](https://fr.vuejs.org/) and [Pinia](https://pinia.vuejs.org/) 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/kql`plugins by its last version, downloaded from the [official GitHub repo](https://github.com/getkirby/kql/releases).
- 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 :

```bash
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](https://getkirby.com/docs/guide/templates/content-representations)** following this code (also in `/public/site/templates/example.json.php`) :

```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`) :

```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 :

```vue
<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