documentation - rules and conventions, creating a page

README.md

@@ -11,7 +11,7 @@ Vue is used following the composition API approach.
 - **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
+- 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
@@ -21,5 +21,77 @@ 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`
+- **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

public/site/templates/example.json.php

@@ -0,0 +1,10 @@
+<?php
+
+$specificData = [
+  "exampleField" => $page->exampleField(),
+  "exampleHardData" => 'Example hard value'
+];
+
+$data = array_merge($genericData, $specificData);
+
+echo json_encode($data);

public/site/templates/example.php

@@ -0,0 +1 @@
+<?php snippet('generic-template') ?>

src/views/Example.vue

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