From 39c1509f5aabee8539eb52915e88f48e975907ab Mon Sep 17 00:00:00 2001 From: Fran Agulto Date: Tue, 7 Jan 2025 15:41:14 -0600 Subject: [PATCH 1/3] added doc page on querying data on the browser --- .../query-data-in-the-browser/index.mdx | 45 +++++++++++++++++++ src/pages/docs/nav.json | 4 ++ 2 files changed, 49 insertions(+) create mode 100644 src/pages/docs/how-to/query-data-in-the-browser/index.mdx diff --git a/src/pages/docs/how-to/query-data-in-the-browser/index.mdx b/src/pages/docs/how-to/query-data-in-the-browser/index.mdx new file mode 100644 index 00000000..eb80daa3 --- /dev/null +++ b/src/pages/docs/how-to/query-data-in-the-browser/index.mdx @@ -0,0 +1,45 @@ +export const metadata = { + title: "Query Data in the Browser", + +} + +When you query data in the browser, you’re leveraging Apollo’s `useQuery` hook within your React components. This is client-side data fetching, which means the data is fetched after your page renders in the browser **_(rather than at build time or request time on the server)_**. + +## Steps + +### 1. Basic setup + +If you haven't already, follow the [Basic Setup](/docs/how-to/basic-setup/) steps to get Faust.js set up. + +## Using the client in components and pages + +You can use the client as usual in your components and pages. Take the following example of querying the `title` and `description` from `generalSettings` in your app: + +```js {12-18} title="page/SamplePage.js" +import { gql, useQuery } from '@apollo/client'; + +export default function Page(props) { + const { data } = useQuery(Page.query); + const { title, description } = data.generalSettings; + return( +

{title}

+

{description}

+ ) +} + +Page.query = gql` + query { + generalSettings { + title + description + } + } +` +``` + +It co-locates the GraphQL query within the same file. You can also import and use queries from a file. + +The benefit with Faust is that you don’t have to create the client object in your codebase. It is automatically created when you first import the `@faustwp-core package`. Instead you can customize it by using a plugin filter. + +> **NOTE** +> This data is not server-rendered. Since it is fetched at runtime in the user’s browser, it may have performance implications if the query is large or slow. diff --git a/src/pages/docs/nav.json b/src/pages/docs/nav.json index bcc877c9..7c2a9ece 100644 --- a/src/pages/docs/nav.json +++ b/src/pages/docs/nav.json @@ -31,6 +31,10 @@ { "title": "Create A Plugin", "route": "/docs/how-to/create-a-plugin/" + }, + { + "title": "Query Data in the Browser", + "route": "/docs/how-to/query-data-in-the-browser/" } ] }, From 4a21ebb865c9e0e0a119e359805d6f1452e0061b Mon Sep 17 00:00:00 2001 From: Alex Moon Date: Tue, 7 Jan 2025 17:12:25 -0800 Subject: [PATCH 2/3] docs: rewrite to have clear steps and make better use of callouts --- .../query-data-in-the-browser/index.mdx | 97 ++++++++++++++----- 1 file changed, 73 insertions(+), 24 deletions(-) diff --git a/src/pages/docs/how-to/query-data-in-the-browser/index.mdx b/src/pages/docs/how-to/query-data-in-the-browser/index.mdx index eb80daa3..37299055 100644 --- a/src/pages/docs/how-to/query-data-in-the-browser/index.mdx +++ b/src/pages/docs/how-to/query-data-in-the-browser/index.mdx @@ -3,43 +3,92 @@ export const metadata = { } -When you query data in the browser, you’re leveraging Apollo’s `useQuery` hook within your React components. This is client-side data fetching, which means the data is fetched after your page renders in the browser **_(rather than at build time or request time on the server)_**. +When you query data in the browser, you're leveraging Apollo's `useQuery` hook within your React components. -## Steps +> [!IMPORTANT] +> This is client-side data fetching, which means the data is fetched after your page renders in the browser **rather than at build time or request time on the server**. This can be very beneficial and powerful. It can also cause performance and SEO issues. Be sure to understand the implications of client-side data fetching before using it in your project. -### 1. Basic setup +## 0. Prerequisites If you haven't already, follow the [Basic Setup](/docs/how-to/basic-setup/) steps to get Faust.js set up. -## Using the client in components and pages +## 1. Create a new page -You can use the client as usual in your components and pages. Take the following example of querying the `title` and `description` from `generalSettings` in your app: +Create a new page in your Next.js app. For this example we'll create a new page called `client.js` in the `pages` directory. This client can also be used in any component. -```js {12-18} title="page/SamplePage.js" -import { gql, useQuery } from '@apollo/client'; +```js title="page/client.js" +export default function Page(props) { + return

Client Page

; +} +``` + +Make sure you can navigate to this page in your browser. + +## 2. Adding the Apollo Client + +To query data in the browser, you need to import the `useQuery` from the `@apollo/client` package. This hook will execute queries using the same client used by templates on the server. + +```js title="page/client.js" {1,4} +import { gql, useQuery } from "@apollo/client"; + +export default function Page(props) { + const { data } = useQuery(); + + return

Client Page

; +} +``` + +## 3. Adding a Query + +It's time to write our GraphQL query to fetch some data. For this example we'll be fetching the site title and description from your WP site's general settings. + +```js {4,9-17} title="page/client.js" +import { gql, useQuery } from "@apollo/client"; export default function Page(props) { - const { data } = useQuery(Page.query); - const { title, description } = data.generalSettings; - return( -

{title}

-

{description}

- ) + const { data } = useQuery(Page.query); + + return

Client Page

; } Page.query = gql` - query { - generalSettings { - title - description - } - } -` + query { + generalSettings { + title + description + } + } +`; ``` -It co-locates the GraphQL query within the same file. You can also import and use queries from a file. +## 4. Displaying the Data + +Now that we have our query, we can display the data on the page. + +```js {5, 7-12} title="page/client.js" +import { gql, useQuery } from "@apollo/client"; -The benefit with Faust is that you don’t have to create the client object in your codebase. It is automatically created when you first import the `@faustwp-core package`. Instead you can customize it by using a plugin filter. +export default function Page(props) { + const { data } = useQuery(Page.query); + const { title, description } = data.generalSettings; + + return ( + <> +

{title}

+

{description}

+ + ); +} + +Page.query = gql` + query { + generalSettings { + title + description + } + } +`; +``` -> **NOTE** -> This data is not server-rendered. Since it is fetched at runtime in the user’s browser, it may have performance implications if the query is large or slow. +> [!TIP]: +> While it's can be convinient to co-locate a GraphQL query within the same file. You can also import and use queries from an external file. From 12b8cb2432015a59506932acd737e65ecb3a93c9 Mon Sep 17 00:00:00 2001 From: Alex Moon Date: Tue, 7 Jan 2025 17:14:34 -0800 Subject: [PATCH 3/3] fix: move tip to correct step --- src/pages/docs/how-to/query-data-in-the-browser/index.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/pages/docs/how-to/query-data-in-the-browser/index.mdx b/src/pages/docs/how-to/query-data-in-the-browser/index.mdx index 37299055..bf19e59e 100644 --- a/src/pages/docs/how-to/query-data-in-the-browser/index.mdx +++ b/src/pages/docs/how-to/query-data-in-the-browser/index.mdx @@ -61,6 +61,9 @@ Page.query = gql` `; ``` +> [!TIP]: +> While it's can be convinient to co-locate a GraphQL query within the same file. You can also import and use queries from an external file. + ## 4. Displaying the Data Now that we have our query, we can display the data on the page. @@ -89,6 +92,3 @@ Page.query = gql` } `; ``` - -> [!TIP]: -> While it's can be convinient to co-locate a GraphQL query within the same file. You can also import and use queries from an external file.