From 2706a137a042b4bf932b0ace9934914f290605f3 Mon Sep 17 00:00:00 2001 From: Jacky Zhao Date: Tue, 8 Aug 2023 20:18:31 -0700 Subject: [PATCH] guide to creating components --- content/advanced/architecture.md | 2 +- content/advanced/creating components.md | 117 ++++++++++++++++++++++-- 2 files changed, 108 insertions(+), 11 deletions(-) diff --git a/content/advanced/architecture.md b/content/advanced/architecture.md index f30331c18..06a670b6c 100644 --- a/content/advanced/architecture.md +++ b/content/advanced/architecture.md @@ -12,7 +12,7 @@ This question is best answered by tracing what happens when a user (you!) runs ` 2. This file has a [shebang]() line at the top which tells npm to execute it using Node. 3. `bootstrap-cli.mjs` is responsible for a few things: 1. Parsing the command-line arguments using [yargs](http://yargs.js.org/). - 2. Transpiling and bundling the rest of Quartz (which is in Typescript) to regular JavaScript using [esbuild](https://esbuild.github.io/). The `esbuild` configuration here is slightly special as it also handles `.scss` file imports using [esbuild-sass-plugin v2](https://www.npmjs.com/package/esbuild-sass-plugin). Additionally, we bundle 'inline' client-side scripts (any `.inline.ts` file) that components declare usiong a custom `esbuild` plugin that runs another instance of `esbuild` that bundles for the browser instead of `node`. Modules of both types are imported as plain text. + 2. Transpiling and bundling the rest of Quartz (which is in Typescript) to regular JavaScript using [esbuild](https://esbuild.github.io/). The `esbuild` configuration here is slightly special as it also handles `.scss` file imports using [esbuild-sass-plugin v2](https://www.npmjs.com/package/esbuild-sass-plugin). Additionally, we bundle 'inline' client-side scripts (any `.inline.ts` file) that components declare using a custom `esbuild` plugin that runs another instance of `esbuild` that bundles for the browser instead of `node`. Modules of both types are imported as plain text. 3. Running the local preview server if `--serve` is set. This starts two servers: 1. A WebSocket server on port 3001 to handle hot-reload signals. This tracks all inbound connections and sends a 'rebuild' message a server-side change is detected (either content or configuration). 2. An HTTP file-server on a user defined port (normally 8080) to serve the actual website files. diff --git a/content/advanced/creating components.md b/content/advanced/creating components.md index 95c71fd6f..a9070138d 100644 --- a/content/advanced/creating components.md +++ b/content/advanced/creating components.md @@ -20,9 +20,6 @@ However, HTML doesn't let you create reusable templates. If you wanted to create In effect, components allow you to write a JavaScript function that takes some data and produces HTML as an output. **While Quartz doesn't use React, it uses the same component concept to allow you to easily express layout templates in your Quartz site.** -> [!hint] -> For those coming from React, Quartz components are different from React components in that it only uses JSX for templating and layout. Hooks like `useEffect`, `useState`, etc. are not rendered. - ## An Example Component ### Constructor @@ -90,11 +87,11 @@ Note that inlined styles **must** be plain vanilla CSS. ```tsx {6-10} title="quartz/components/YourComponent.tsx" export default (() => { function YourComponent() { - return

Example Component

+ return

Example Component

} YourComponent.css = ` - p { + p.red-text { color: red; } ` @@ -124,14 +121,114 @@ export default (() => { ### Scripts and Interactivity -- listening for the nav event - - best practice: anything here should unmount any existing event handlers to prevent memory leaks +What about interactivity? Suppose you want to add an-click handler for example. Like the `.css` property on the component, you can also declare `.beforeDOMLoaded` and `.afterDOMLoaded` properties that are strings that contain the script. -### Using a Component +```tsx title="quartz/components/YourComponent.tsx" +export default (() => { + function YourComponent() { + return + } -#### In a layout + YourComponent.beforeDOM = ` + console.log("hello from before the page loads!") + ` -#### In the configuration + YourComponent.afterDOM = ` + document.getElementById('btn').onclick = () => { + alert('button clicked!') + } + ` + return YourComponent +}) satisfies QuartzComponentConstructor + +``` + +> [!hint] +> For those coming from React, Quartz components are different from React components in that it only uses JSX for templating and layout. Hooks like `useEffect`, `useState`, etc. are not rendered and other properties that accept functions like `onClick` handlers will not work. Instead, do it using a regular JS script that modifies the DOM element directly. + +As the names suggest, the `.beforeDOMLoaded` scripts are executed *before* the page is done loading so it doesn't have access to any elements on the page. This is mostly used to prefetch any critical data. + +The `.afterDOMLoaded` script executes once the page has been completely loaded. This is a good place to setup anything that should last for the duration of a site visit (e.g. getting something saved from local storage). + +If you need to create an `afterDOMLoaded` script that depends on *page specific* elements that may change when navigating to a new page, you can listen for the `"nav"` event that gets fired whenever a page loads (which may happen on navigation if [[SPA Routing]] is enabled). + +```ts +document.addEventListener("nav", () => { + // do page specific logic here + // e.g. attach event listeners + const toggleSwitch = document.querySelector("#switch") as HTMLInputElement + toggleSwitch.removeEventListener("change", switchTheme) + toggleSwitch.addEventListener("change", switchTheme) +}) +``` + +It is best practice to also unmount any existing event handlers to prevent memory leaks. +#### Importing Code +Of course, it isn't always practical (nor desired!) to write your code as a string literal in the component. + +Quartz supports importing component code through `.inline.ts` files. + +```tsx title="quartz/components/YourComponent.tsx" +// @ts-ignore: typescript doesn't know about our inline bundling system +// so we need to silence the error +import script from "./scripts/graph.inline" + +export default (() => { + function YourComponent() { + return + } + + YourComponent.afterDOM = script + return YourComponent +}) satisfies QuartzComponentConstructor + +``` + +```ts title="quartz/components/scripts/graph.inline.ts" +// any imports here are bundled for the browser +import * as d3 from "d3" + +document.getElementById('btn').onclick = () => { + alert('button clicked!') +} +``` + +Additionally, like what is shown in the example above, you can import packages in `.inline.ts` files. This will be bundled by Quartz and included in the actual script. +### Using a Component +After creating your custom component, re-export it in `quartz/components/index.ts`: + +```ts title="quartz/components/index.ts" {4,10} +import ArticleTitle from "./ArticleTitle" +import Content from "./pages/Content" +import Darkmode from "./Darkmode" +import YourComponent from "./YourComponent" + +export { + ArticleTitle, + Content, + Darkmode, + YourComponent +} +``` + +Then, you can use it like any other component in `quartz.layout.ts` via `Component.YourComponent()`. See the [[configuration#Layout|layout]] section for more details. + +As Quartz components are just functions that return React components, you can compositionally use them in other Quartz components. + +```tsx title="quartz/components/AnotherComponent.tsx" +import YourComponent from "./YourComponent" + +export default (() => { + function AnotherComponent(props: QuartzComponentProps) { + return
+

It's nested!

+ +
+ } + + return AnotherComponent +}) satisfies QuartzComponentConstructor +``` > [!hint] > Look in `quartz/components` for more examples of components in Quartz as reference for your own components!