From 8c3dc1a0248afe434af244dce35389ca4ef9070a Mon Sep 17 00:00:00 2001 From: Owen Buckley Date: Thu, 23 Jan 2025 10:10:38 -0500 Subject: [PATCH] docs/clarify SSR body and layout APIs (#160) --- src/pages/docs/pages/layouts.md | 30 ++++++++++++++++++++++++ src/pages/docs/pages/server-rendering.md | 15 ++++++++---- 2 files changed, 41 insertions(+), 4 deletions(-) diff --git a/src/pages/docs/pages/layouts.md b/src/pages/docs/pages/layouts.md index 420f6a77..30539e61 100644 --- a/src/pages/docs/pages/layouts.md +++ b/src/pages/docs/pages/layouts.md @@ -91,3 +91,33 @@ As with Page layouts, App layouts are just HTML: ``` > When an app layout is present, Greenwood will merge the `` and `` tags for both app and page layouts into one HTML document structure for you. + +## Server Rendering + +Server rendered layouts can also be authored using Web Components: + +```js +// src/layouts/app.js +export default class AppLayout extends HTMLElement { + async connectedCallback() { + const year = new Date().getFullYear(); + + this.innerHTML = ` + + + + My App + + + +

My App

+ + + + + `; + } +} +``` + +> ⚠ This layout component will _only run once at build time_. Dynamic "runtime" layouts are [planned](https://github.com/ProjectEvergreen/greenwood/issues/1248). diff --git a/src/pages/docs/pages/server-rendering.md b/src/pages/docs/pages/server-rendering.md index 12afa4c1..4ba5f2e1 100644 --- a/src/pages/docs/pages/server-rendering.md +++ b/src/pages/docs/pages/server-rendering.md @@ -20,9 +20,9 @@ The above would serve content in a browser at the path _/users/_. ## Usage -In your page file, Greenwood supports the following functions that you can `export` for providing server rendered content and [frontmatter](/docs/resources/markdown/): +In your page file, Greenwood supports the following functions that you can `export` for providing server rendered content and [frontmatter](/docs/resources/markdown/) to produce the `` content for your page. -- **default** (recommended): Use the custom elements API to render out your page content, aka **Web (Server) Components** +- **default** (recommended): Use the custom elements API to render out your page content, aka **Web (Server) Components**. _This will take precedence over `getBody`_ and will also automatically track your custom element dependencies (in place of having to define frontmatter imports in `getFrontmatter`). - **getBody**: Return a string of HTML for the contents of the page - **getLayout**: Return a string of HTML to act as the [page's layout](/docs/pages/layouts/#pages) - **getFrontmatter**: Provide an object of [frontmatter](/docs/resources/markdown/#frontmatter) properties. Useful in conjunction with [content as data](/docs/content-as-data/), or otherwise setting static configuration / metadata through SSR. @@ -81,7 +81,12 @@ export default class UsersPage extends HTMLElement { }) .join(""); - this.innerHTML = html; + this.innerHTML = ` + +

Friends List

+ ${html} + + `; } } ``` @@ -134,7 +139,7 @@ export async function getBody(compilation, page, request) { ### Layouts -For creating a [layout](/docs/pages/layouts/) dynamically, you can provide a `getLayout` function and return the HTML you need. +Although global [layouts](/docs/pages/layouts/) exist, you can provide a `getLayout` function on a per page basis to override or set the layout for the given page. You can pull in data from Greenwood's [compilation](/docs/reference/appendix/#compilation) object as well as the specific route: @@ -165,6 +170,8 @@ export async function getLayout(compilation, route) { } ``` +> ⚠ This function is _only run once at build time_. Dynamic "runtime" layouts are [planned](https://github.com/ProjectEvergreen/greenwood/issues/1248). + ### Frontmatter Any Greenwood supported frontmatter can be returned here. _This is only run once when the server is started_ to populate pages metadata, which is helpful if you want your dynamic route to show up in a collection with other static pages. You can even define a `layout` and reuse all your existing [layouts](/docs/pages/layouts/), even for server routes!