Custom queries

[wjohnsto]

Okay, it was not my intent for this to be a big PR, but here it goes:

1. BH-850 DONE

2. BH-852 DONE

3. Queries to get Posts and a Content Node can be customized using fragments and variables

   • This customization can occur with calls to the hooks, services, or during getServerSideProps or getStaticProps
   • There is a doc now that explains how queries work

4. All Next-specific functionality is extracted into a /packages/headless/src/next directory

   • You can import it as import ... from '@wpengine/headless/next';

5. All React-specific (non-Next) functionality is extracted into a /packages/headless/src/react directory

   • You can import it as import ... from '@wpengine/headless/react';

6. There is now a generic React TemplateLoader that will work outside of Next. There is also a NextTemplateLoader that allows Templates to specify getStaticProps and getServerSideProps

7. Theme components should now export getServerSideProps and getStaticProps methods if they want to make extra server-side requests (@see /examples/getting-started/wp-templates/single)

   • Either getServerSideProps or getStaticProps will be called depending upon whether the app is using getServerSideProps or getStaticProps

8. Custom queries can be made directly within getServerSideProps or getStaticProps of pages and theme components as follows:

   import { getApolloClient } from '@wpengine/headless';
   import { gql } from '@apollo/client';
   import { GetStaticPropsContext } from 'next';
   
   // ...
   
   export async function getStaticProps(context: GetStaticPropsContext) {
     const client = getApolloClient(context);
     client.query({
           query: gql`...`
     });
    
     return getNextStaticProps(context);
   }

   • These queries, if made prior to calling getNextStaticProps or getNextServerSideProps, will be cached and available client-side

9. There is a generic authorizeHandler middleware function that only authorizes a user and sets a cookie. in @wpengine/headless/next there is a previewHandler that will set preview data and call on the authorizeHandler

BREAKING CHANGES:

1. initializeNextStaticProps is now getNextStaticProps and is in @wpengine/headless/next
2. initializeNextServerSideProps is now getNextServerSideProps and is in @wpengine/headless/next
3. getPropsMiddleware on Templates is now replaced by getStaticProps and getServerSideProps
   • The function signature for the new functions is the same as the Next.js variants, so you have access to context only (you can import and call for other things you might need)
4. usePosts now returns a WPGraphQL.RootQueryToPostConnection, so the list of posts will be found on the nodes or edges properties
5. All Next.js functions are in @wpengine/headless/next and not exported from @wpengine/headless. This includes:
   • NextTemplateLoader
   • WPHead
   • getNextServerSideProps
   • getNextStaticPaths
   • getNextStaticProps
   • previewHandler
   • usePost (the Next-specific variant)
   • useUriInfo (the Next-specific variant)
6. All non-Next React functions are in @wpengine/headless/react and not exported from @wpengine/headless. This includes:
   • HeadlessContext
   • HeadlessProvider
   • Menu
   • MenuList
   • TemplateLoader
   • useApollo
   • useGeneralSettings
   • usePost
   • usePosts
   • useUriInfo
7. The following objects are no longer exported from core:
   • gql (can be imported from @apollo/client)
   • useQuery (can be imported from @apollo/client)
   • useMutation (can be imported from @apollo/client)

[mindctrl]

@wjohnsto woot! Glad to see the ability to customize queries. There's a pretty big merge conflict here now. Can you fix that up before we get too deep in reviewing?

[nickcernis]

@wjohnsto Thank you for your work on this.

Can you help me to better understand how passing variables to adjust a query should work, please?

I read the docs and amended packages/headless/src/next/serverSide.ts like this:

  if (pageInfo.isPostsPage) {
    await getPosts(client, options.posts);
  }

+  if (pageInfo.isArchive) {
+    await getPosts(client, {
+      variables: {
+        where: { categoryName: 'uncategorized' }, // Hard-coding the category name for now.
+      },
+    });
+  }

I expected to see posts from the uncategorized category (default for WP posts) at http://localhost:3000/category/uncategorized. Instead I see no posts. GraphiQL in Chrome shows no categoryName variable was passed to getPosts.

[mindctrl]

I did the same as Nick, but I get different results. At first the category page is empty, and about 3 seconds later all posts are rendered instead of the ones related to the category I requested. 🤷

[wjohnsto]

@wjohnsto Thank you for your work on this.

Can you help me to better understand how passing variables to adjust a query should work, please?

I read the docs and amended packages/headless/src/next/serverSide.ts like this:

  if (pageInfo.isPostsPage) {
    await getPosts(client, options.posts);
  }

+  if (pageInfo.isArchive) {
+    await getPosts(client, {
+      variables: {
+        where: { categoryName: 'uncategorized' }, // Hard-coding the category name for now.
+      },
+    });
+  }

I expected to see posts from the uncategorized category (default for WP posts) at http://localhost:3000/category/uncategorized. Instead I see no posts. GraphiQL in Chrome shows no categoryName variable was passed to getPosts.

@nickcernis Can you show me the contents of the file in question?

[nickcernis]

@wjohnsto Added here: https://gist.github.com/nickcernis/8bbc03ecd60cff974435b7bf790dcc72

[wjohnsto]

@nickcernis Have you confirmed that the call is being made and the results are missing posts? Something like:

  if (pageInfo.isArchive) {
    console.log('making call for archive posts')
    const result = await getPosts(client, {
      variables: {
        where: { categoryName: 'uncategorized' }, // Hard-coding the category name for now.
      },
    });
    console.log(result);
  }

Something to think about, this same call would need to be made client-side in order to work. You would not be able to call usePosts() and expect the archived posts.

[nickcernis]

Have you confirmed that the call is being made and the results are missing posts?

Yes, it's firing although the result is not missing posts.

Something to think about, this same call would need to be made client-side in order to work. You would not be able to call usePosts() and expect the archived posts.

Thanks, it sounds like this is the likely cause. I'll look into creating a category template with a matching query.

With that in mind I'm happy to approve and merge and address anything else in follow-ups. Thanks again for your work, @wjohnsto!

[mi4l]

@wjohnsto hi there, just a random passerby here, but is this a typical union with a prepended | or is there something more going on that I may be misunderstanding?

[wjohnsto]

I don't think there is anything more going on, it's possible this was the output from eslint/prettier as I do not remember writing this specifically. The outcome is the same as let localApolloClient: ApolloClient<NormalizedCacheObject>.

[mi4l]

Awesome, thanks for clearing that up!