From c3d8bcd3c6fc3a871e3847e5386bd313c5a00129 Mon Sep 17 00:00:00 2001
From: dorian451 <112524240+dorian451@users.noreply.github.com>
Date: Mon, 22 Jul 2024 22:48:46 -0400
Subject: [PATCH] [Documentation:Developer] Add documentation about pages in
 Vue (#620)

This documentation goes over how to make a page using the new Vue.js
functionality provided in
https://github.com/Submitty/Submitty/pull/10715.

This documentation is added to the bottom of
`/developer/developing_the_php_site/view`, and details creating a new
Vue page from scratch and showing how to tell a PHP View to serve it
using `renderVue`.
---
 .../developer/developing_the_php_site/view.md | 45 ++++++++++++++++++-
 1 file changed, 43 insertions(+), 2 deletions(-)

diff --git a/_docs/developer/developing_the_php_site/view.md b/_docs/developer/developing_the_php_site/view.md
index 01007069..b1bec369 100644
--- a/_docs/developer/developing_the_php_site/view.md
+++ b/_docs/developer/developing_the_php_site/view.md
@@ -11,7 +11,7 @@ pattern.
 The [Controller](controller) will call the view.  Let's have a look at
 an example `UserView.php`. It might have a function in it like this:
 
-```PHP
+```php
 public function showUserDetails(UserModel $user) {
   $this->core->getOutput()->addInternalJs('user-details.js');
   $this->core->getOutput()->addInternalCss('user-details.css');
@@ -53,4 +53,45 @@ Finally, let's look at `UserDetails.twig`
 ```
 
 In this page, we use `user_id` and `favorite_color` to render information
-about the student.
\ No newline at end of file
+about the student.
+
+## Another option: Rendering with Vue
+
+Alternatively, instead of using Twig, we can use [Vue](https://vuejs.org/) instead.
+
+To do this, first make a Vue page in `site/vue/src/pages` (for example, `site/vue/src/pages/UserDetails.vue`): 
+```html
+<script setup lang='ts'>
+  import { inject } from 'vue';
+
+  const userId = inject<string>('user_id') ?? '<no user provided>';
+  const favoriteColor = inject<string>('favorite_color') ?? '<no color provided>';
+</script>
+
+<template>
+  <div class="content">
+    {% raw %}{{ userId }}'s favorite color is {{ favoriteColor }}.{% endraw %}
+  </div>
+</template>
+```
+
+
+To actually render this page, we will then need to use the `renderVue` function in our View (ex. `UserView.php`).
+
+The first paramater of the `renderVue` takes the name of the page (the name of the `.vue` file minus the extension, in this case `UserDetails`), and the second parameter is the same as in `renderTwig`, an associative array of variables that are passed to the Vue page.
+
+If we wanted our `UserView.php` example to render with Vue, it would have a function that might look like this:
+
+```php
+public function showUserDetails(UserModel $user) {
+  return $this->core->getOutput()->renderVue(
+    'UserDetails',
+      [
+        'user_id' => $user->getUserId(),
+        'favorite_color' => $user->getFavoriteColor()
+      ]
+  );
+}
+```
+
+To access the variables passed by the `renderVue` function in Vue, use [`inject`](https://vuejs.org/api/composition-api-dependency-injection.html#inject). The injection keys will be the same as the keys in the provided array. If the key provided to `inject` is not in the array passed to `renderVue`, it will return `undefined`.
\ No newline at end of file