Forem: Zac Gordon

How to Extend WPGraphQL for Custom Meta Boxes in WordPress Themes

Zac Gordon — Wed, 18 Dec 2019 15:21:50 +0000

If you like this post, please check out my Courses and Online Bootcamps at JavaScript for WordPress.

In the last two tutorials in this series we got up and running with React, GraphQL and Apollo in a WordPress theme. Now we are going to look at how we can extend the WPGraphQL plugin to expose custom meta boxes or meta fields in WordPress.

The example we will do involves adding a "Vote" meta field to WordPress that will eventually allow us to up and down vote WordPress posts in a Reddit style fashion.

You can see the final code we are working from in this repo, which is a TwentyTwenty child theme.

Revealing Custom Meta Boxes in the Gutenberg Block Editor

By default, custom meta boxes will no longer show up when editing posts in WordPress. To enable them we have to go to the options panel in the editor settings.

Then you can select to show "Custom Fields."

Finally you can add in a custom meta field called "votes" and add a value. I wouls suggest having one post with a vote value of "10" and edit a second post to have a custom "vote" value of "0". This will give us some different values to work with.

Now that we have these setup in WordPress we can expose them in WPGraphQL.

Exposing Custom Meta Fields in WPGraphQL

Interestingly, custom meta fields are not automatically exposed in WPGraphQL. We have to manually add them.

To do so we a WordPress hook called graphql_register_types along with a custom WPGraphQL function called register_graphql_field().

Together, these look like the following, which you can add to your functions.php file:

// Add Votes to Custom Meta Fields
add_action( 'graphql_register_types', function() {
    register_graphql_field( 'Post', 'votes', [
       'type' => 'Number',
       'description' => __( 'The number of votes', 'wp-graphql' ),
       'resolve' => function( $post ) {
         $votes = get_post_meta( $post->ID, 'votes', true );
         return ! empty( $votes ) ? $votes : 0;
       }
    ] );
  } );

What this will do is tell the GraphQL server that we have a meta field called "votes" that we want added to the Posts schema. We add a type and description and then a resolve function.

The resolve function called get_post_meta on our custom "votes" meta field and then returns that value or 0 if there is no value set already.

Technically you don't need to return a custom meta field here, you can return any custom WordPress data you want. So this is code you can use for other purposes in the future as needed.

Now when we look in WPGraphiQL we can see the votes field has been added.

Now we can turn our attention back to our custom template code and pull in the custom meta box values.

Querying Custom Meta Boxes with Apollo and React

For this tutorial I'm going to add a new component to our little theme code called "PostsWithVotes." So our theme JS structure should look like this now:

/src 
  /posts-w-votes
    index.js
  /posts
    index.js
  index.js

At the top of our /posts-w-votes/index.js file we're going to import useQuery and gpl.

import { useQuery } from "@apollo/react-hooks";
import { gql } from "apollo-boost";

Then we can write our GraphQL query to get our posts along with the votes:

const POSTS_QUERY = gql`
  {
    posts {
      nodes {
        id
        title(format: RENDERED)
        votes
      }
    }
  }
`;

Then finally we can write out component itself. It will look very similar to our component from the last part of this series.

However, we are going to sort our posts by the number of votes so the posts with more votes appear first.

const PostsWithVotes = () => {
  const { loading, error, data } = useQuery(POSTS_QUERY);

  if (loading) return <p>Loading posts...</p>;
  if (error) return <p>Error :(</p>;


  const posts = data.posts.nodes;

  const sortedPosts = posts
    .sort((a, b) => a.votes < b.votes)
    .map(({ id, title, votes }) => (
      <li key={id}>
        <div className="actions">
          {votes}
        </div>
        <h3>{title}</h3>
      </li>
    ));
  return <ul id="post-w-votes">{sortedPosts}</ul>;

};

export default PostsWithVotes;

This will cause our posts to display in the order we want. Now we have to load this component in our main index.js file.

Loading the Posts with Votes Component

To see all of this working, open the main src/index.js file and import the PostsWithVotes component:

import PostsWithVotes from "./components/post-w-votes";

Then call the component inside the main <App> component:

const { render } = wp.element;
import ApolloClient from "apollo-boost";
import { ApolloProvider } from "@apollo/react-hooks";

import PostsWithVotes from "./components/post-w-votes";

const client = new ApolloClient({
  uri: "http://react-dev.local/graphql"
});

const App = () => {
  return (
    <ApolloProvider client={client}>
      <div>
        <PostsWithVotes />
      </div>
    </ApolloProvider>
  );
};
render(<App />, document.getElementById(`react-app`));

You should now see the posts show up on the page using our custom template. The posts should also appear in the order of those with most votes first.

Before we wrap up, we will add in and style the buttons that will eventually allow us to vote on the posts.

Adding Up and Down Vote Buttons

For our buttons we are going to use the WordPress <Button> component.

To make these available in our theme, we have to update our enqueueing code in our functions.php file.

wp_enqueue_script(
  'my-theme-frontend',
  get_stylesheet_directory_uri() . '/build/index.js',
  ['wp-element', 'wp-components'],
  time(), //For production use wp_get_theme()->get('Version')        
  true
);

Notice that we have included wp-components as a dependency. This will ensure that we can use any of the WordPress React components, like the <Button> component.

Now at the top of our file "import" the <Button> component from the wp.components library in the global window object.

const { Button } = wp.components;

Then we can update the markup inside of <div className="actions"> to include two buttons:

<div className="actions">
  <Button onClick={() => upVote(votes)}>&#708;</Button>
  {votes}
  <Button onClick={() => downVote(votes)}>&#709;</Button>
</div>

And we will also include a mock upVote and downVote function like this:

const upVote = votes => {
  console.log(votes + 1);
};
const downVote = votes => {
  console.log(votes - 1);
};

Now when we click on the buttons we should see the next value for the vote displayed in the console. In the next tutorial in the series we will look at how to modify the actual value in the database.

To make everything look a little nicer, add the follow styles into the theme style.css file.

#post-w-votes {
  margin: 0;
  padding: 0;
}
#post-w-votes li {
  display: flex;
  margin: 1rem 0 2rem;
  position: relative;
}
#post-w-votes .actions {
  width: 50px;
  flex-direction: column;
  text-align: center;
}
#post-w-votes .actions button {
  width: 100%;
  padding: 0.5rem 1rem;
  margin: 0;
}
#post-w-votes .actions button:hover {
  text-decoration: none;
}
.entry-content #post-w-votes h3 {
  margin: 0 0 0 70px;
  position: absolute;
  top: 50%;
  transform: translateY(-50%);
  vertical-align: middle;
}

This should give us something that looks like this:

The Final Code for our PostsWithVotes Component

Here is the final code we have for our PostsWithVotes Component:

const { Button } = wp.components;

import { useQuery } from "@apollo/react-hooks";
import { gql } from "apollo-boost";

const POSTS_QUERY = gql`
  {
    posts {
      nodes {
        id
        title(format: RENDERED)
        votes
      }
    }
  }
`;

const upVote = votes => {
  console.log(votes + 1);
};
const downVote = votes => {
  console.log(votes - 1);
};

const PostsWithVotes = () => {
  const { loading, error, data } = useQuery(POSTS_QUERY);

  if (loading) return <p>Loading posts...</p>;
  if (error) return <p>Error :(</p>;


  const posts = data.posts.nodes;

  const sortedPosts = posts
    .sort((a, b) => a.votes < b.votes)
    .map(({ id, title, votes }) => (
      <li key={id}>
        <div className="actions">
          <Button onClick={() => upVote(votes)}>&#708;</Button>
          {votes}
          <Button onClick={() => downVote(votes)}>&#709;</Button>
        </div>
        <h3>{title}</h3>
      </li>
    ));
  return <ul id="post-w-votes">{sortedPosts}</ul>;
};

export default PostsWithVotes;

We are coming along nicely here! We have votes hooked up to WPGraphQL, we have the votes pulled in through Apollo and React, and we have some buttons mocked up ready to send the data back to WordPress.

In the next part of this series we will use GraphQL mutations to update the values of the buttons when we click on them.

Here is the final code we are working from.

If you like this post, please check out my Courses and Online Bootcamps at JavaScript for WordPress.

How to Use Apollo and GraphQL in a WordPress Theme

Zac Gordon — Tue, 10 Dec 2019 17:01:45 +0000

If you like this post, please check out my Courses and Online Bootcamps at JavaScript for WordPress.

In the last part of this series we looked at how to include React in a WordPress Theme. In this tutorial we are going to look at how to build on that and setup the WordPress GraphQL plugin and Apollo for making requests for data with our JavaScript.

Apollo & WPGraphQL vs. REST API & WP Fetch API

WordPress ships with a REST API. This is great and super easy to use with the Fetch API or other AJAX libraries. I have a nice tutorial and video on how to work with these two if you're interested. However, working with REST APIs is falling out of popularity largely because of common necessity for making multiple API calls to get the data you need.

The WP GraphQL plugin does not ship with WordPress Core, but does add a GraphQL endpoint to WordPress. GraphQL is the preferred method for getting data mostly due to its ease of use and ability to get with one query what would take multiple queries with a REST API.

Apollo is the go to library for making GraphQL requests so we will bundle that with our theme code.

Getting GraphQL Setup in WordPress

To get setup with GraphQL in WordPress we have to first install the WP GraphQL and WP GraphiQL plugins. The first one will enable the GraphQL server and the second one will give us an interface for making queries and looking through what data is available.

This what GraphiQL looks like when it is up and running (with a post request). If this is your first time using WP GraphQL, it is quite exciting to see everything that is available and be able to easily query it all via the Explorer.

Setting Up Apollo in Our Theme

You can see the example theme we are using here. We are going to pickup where we left off with the last tutorial.

The first thing we have to do is install Apollo and the related packages. Run this in the root of your theme:

npm install apollo-boost @apollo/react-hooks graphql

Now we are going to setup some new files that let us query some recent posts and display them on the page.

We are going to add in a components folder with a posts folder and an index.js file inside that.

/build
/src
-- /components
   -- /posts
      -- index.js
   -- index.js
functions.php
package.json
page-react.php
style.css
webpack.config.js

Inside the main /src/index.js file we are going to setup the Apollo client like this:

const { render } = wp.element;
import { ApolloProvider } from "@apollo/react-hooks";

const client = new ApolloClient({
  uri: "http://react-dev.local/graphql"
});

const App = () => {
  return (
    <ApolloProvider client={client}>
      <div>
        <h1>My First Apollo Theme!</h1>
      </div>
    </ApolloProvider>
  );
};
render(<App />, document.getElementById(`react-app`));

This sets up our Apollo client to ping the GraphQL endpoint on our WordPress site. You can change that URL to match the URL of your site.

Then we wrap our code inside the Apollo Provider, which will allow this client to be available to any components we include inside of it.

Now we can turn to looking at a how to create a Posts component that queries and displays posts.

Creating a List of WordPress Posts with Apollo

Now open the /src/components/posts/index.js file. The first thing we're going to do is import the necessary libraries for using React hooks and making GraphQL queries:

import { useQuery } from "@apollo/react-hooks";
import { gql } from "apollo-boost";

Then below that we can write out the query we will use to get our posts:

const POSTS_QUERY = gql`
  {
    posts {
      nodes {
        postId
        title(format: RENDERED)
      }
    }
  }
`;

This is a pretty straightforward query to get our post titles and IDs.

Next we can write our actual Posts component that will make the query, display a loading message, an error message if there is one, and then finally display our posts.

const Posts = () => {
  const { loading, error, data } = useQuery(POSTS_QUERY);

  if (loading) return <p>Loading Posts...</p>;
  if (error) return <p>Something wrong happened!</p>;

  const posts = data.posts.nodes;
  return posts.map(({ postId, title }) => <h3 key={postId}>{title}</h3>);
};

This is a pretty simple setup. Here is what it looks like all together

import { useQuery } from "@apollo/react-hooks";
import { gql } from "apollo-boost";

const POSTS_QUERY = gql`
  {
    posts {
      nodes {
        postId
        title(format: RENDERED)
      }
    }
  }
`;

const Posts = () => {
  const { loading, error, data } = useQuery(POSTS_QUERY);

  if (loading) return <p>Loading Posts...</p>;
  if (error) return <p>Something wrong happened!</p>;

  const posts = data.posts.nodes;
  return posts.map(({ postId, title }) => <h3 key={postId}>{title}</h3>);
};

export default Posts;

This is everything we need in this component. Now we can bring it into our src/index.js file and place it inside the <ApolloProvider> tags.

Rendering Our Posts Component

Update your src/index.js file so that it imports the Posts component and then displays it on the page.

const { render } = wp.element;
import ApolloClient from "apollo-boost";
import { ApolloProvider } from "@apollo/react-hooks";
import Posts from "./components/posts";

const client = new ApolloClient({
  uri: "http://react-dev.local/graphql"
});

const App = () => {
  return (
    <ApolloProvider client={client}>
      <div>
        <Posts />
      </div>
    </ApolloProvider>
  );
};
render(<App />, document.getElementById(`react-app`));

There we have it! You now have an Apollo client setup to Query WP GraphQL and make requests for posts.

From here you can modify this as needed to query anything that WP GraphQL gets for you.

Next up in the series we will look at how to extend WP GraphQL as well as make mutations to our data. To do this we will add a simple reddit style voting feature to our posts.

If you like this post, please check out my Courses and Online Bootcamps at JavaScript for WordPress.

How to Include React in a WordPress Theme

Zac Gordon — Wed, 04 Dec 2019 04:58:47 +0000

If you like this post, please check out my Courses and Online Bootcamps at JavaScript for WordPress.

React Ships with WordPress

Ever since WordPress 5.0, React (or an abstraction of it), now ships with WordPress.

WordPress takes the entire React and ReactDOM libraries and exports them onto a global window object named wp.element.

This is a little different from how most React apps work.

In a Normal React App We Import React, in WordPress We Don't

Normally, with a React app or project, you import React at the top of each file that uses React. On your main index page you would likely import ReactDOM as well.

// A Normal React App
import React from "react";
import ReactDOM from "react-dom";
import MyComponent from "./components/MyComponent";

ReactDOM.render(<MyComponent />, document.getElementById("root"));

In WordPress we do not import React or React DOM because they are made available in the global wp.element object.

So one important difference when you go to include React in your WordPress project is you do not import it into your files.

Another difference between using React normally and in a WordPress theme or plugin has to do with tooling.

Using WP Scripts Instead of Create React App

If you have built React apps before you probably use Create React App or a similar bundle of tools to run your development server and build your production code.

This tooling does not work as well for WordPress because React is loaded in the global window object wp.element rather than bundled with the code. Create React App does not officially support loading React from an external source without ejecting so that is not necessarily the best option for tooling.

Luckily, the WordPress team built a wp-scripts package based off of the react-scripts package used with Create React App.

WP Scripts includes develop, lint, test and build commands by default. You can also extend it with your own custom webpack config if you want to do something special, like compile SASS for instance.

We will look at how to setup WP Scripts below, but first let's get our basic theme setup with React loaded on the front end.

Enqueuing React in Your Theme

To make sure React is loaded, you will simply add wp-element as a dependency of your own JavaScript file.

The following would go in your functions.php file.

// Enqueue Theme JS w React Dependency
add_action( 'wp_enqueue_scripts', 'my_enqueue_theme_js' );
function my_enqueue_theme_js() {
  wp_enqueue_script(
    'my-theme-frontend',
    get_stylesheet_directory_uri() . '/build/index.js',
    ['wp-element'],
    time(), // Change this to null for production
    true
  );
}

For this to work you will need a file located at /build/index.js. WP Scripts will create this for us when we run the build command

Now wp.element will load on the front end of your theme.

How to Setup WP Scripts

Setting Up WP Scripts involves two steps: 1) install wp-scripts; 2) add the scripts to your package.json file.

If you have not setup a package.json file yet run the following command from the root of your WordPress theme:

npm init

You can either press return for each of the prompts or add in your own custom information.

Once your package.json file is created, run the following command:

npm install @wordpress/scripts --save-dev

This will download WP Scripts to your node_modules and make it available to use in the command line.

We can now do something like this:

wp-scripts start

However, to make this more universal and easy to use, we will map the WordPress Scripts to NPM scripts.

Open up your package.json file and replace the current "scripts" settings with the following:

{
  "name": "myreacttheme",
  "version": "1.0.0",
  "description": "My WordPress theme with React",
  "main": "src/index.js",
  "dependencies": {},
  "devDependencies": {
    "@wordpress/scripts": "^5.1.0"
  },
  "scripts": {
    "build": "wp-scripts build",
    "check-engines": "wp-scripts check-engines",
    "check-licenses": "wp-scripts check-licenses",
    "lint:css": "wp-scripts lint-style",
    "lint:js": "wp-scripts lint-js",
    "lint:pkg-json": "wp-scripts lint-pkg-json",
    "start": "wp-scripts start",
    "test:e2e": "wp-scripts test-e2e",
    "test:unit": "wp-scripts test-unit-js"
  },
  "author": "",
  "license": "1 GNU V2+, MIT"
}

If you do not need all of these, you can shorten it to just the start and build commands. However, the others can be useful to have as well.

Now we are able to run the following:

npm start

And it will call off the WP Scripts start command. This will look for any file imported from src/index.js and build it out to build/index.js any time a file is changed.

The build command does the same thing, but only once and does not watch for changes.

Adding React to a Custom Page Template

More and more of the display of content is controlled in WordPress through blocks. Blocks in WordPress are also based on React, but they are a little ecosystem in and of themselves and outside the scope of this particular blog post.

Here we are going to focus on adding some React to a custom page template. While everything we do could be built into a block, there are still going to be times when building a custom page template React serves as useful.

For this purpose I am going to make a Child Theme of the 2020 Default WordPress Theme. My basic theme structure looks like this:

/build
/src
-- index.js
functions.php
package.json
page-react.php
style.css

These are about the minimum requirements we will need.

Without too much explanation, here is the code for the functions.php file and the style.css file.

functions.php

<?php
add_action( 'wp_enqueue_scripts', 'my_theme_enqueue_styles' );
function my_theme_enqueue_styles() {

  $parent_style = 'twentytwenty-style'; 

  wp_enqueue_style( $parent_style, get_template_directory_uri() . '/style.css' );

  wp_enqueue_style( 'child-style',
    get_stylesheet_directory_uri() . '/style.css',
    [ $parent_style ],
    time() //wp_get_theme()->get('Version')
  );

  wp_enqueue_script(
    'my-theme-frontend',
    get_stylesheet_directory_uri() . '/build/index.js',
    ['wp-element'],
    time() //For production use wp_get_theme()->get('Version')        
  );

}

style.css

/*
 Theme Name:   Twenty Twenty Child
 Description:  Twenty Twenty Child Theme
 Author:       Zac Gordon
 Author URI:   https://javascriptforwp.com/
 Template:     twentytwenty
 Version:      0.9.0
 License:      GNU General Public License v2 or later
 License URI:  http://www.gnu.org/licenses/gpl-2.0.html
 Text Domain:  twentytwentychild
*/

We also have a very simple custom page template page-react.php that looks like this:

<?php
/**
 * Template Name: React Template
 */
get_header();
?>

<main id="site-content" role="main">
    <article class="post-2 page type-page status-publish hentry">
        <?php get_template_part( 'template-parts/entry-header' ); ?>
        <div class="post-inner thin">
            <div class="entry-content">             

                <div id="react-app"></div><!-- #react-app -->

            </div><!-- .entry-content -->
        </div><!-- .post-inner -->
    </article><!-- .post -->
</main><!-- #site-content -->

<?php get_template_part( 'template-parts/footer-menus-widgets' ); ?>
<?php get_footer(); ?>

This is basically a simplified page.php template from the parent theme with a <div id="react-app"></div> added for us to load our React code into.

It is possible to build larger sections of a theme with React, but we are going to just focus on loading it on a single template here.

To complete this setup process, create a new page and select the "React Template" as the page template.

Writing Our React

Inside of our src/index.js file we can start writing our React code and adding it to the page.

We will build on this over the course of this series, but for now we will add a simple component that lets you click a button to increase the number of votes for something.

file: /src/index.js

const { render, useState } = wp.element;

const Votes = () => {
  const [votes, setVotes] = useState(0);
  const addVote = () => {
    setVotes(votes + 1);
  };
  return (
    <div>
      <h2>{votes} Votes</h2>
      <p>
        <button onClick={addVote}>Vote!</button>
      </p>
    </div>
  );
};
render(<Votes />, document.getElementById(`react-app`));

A few important things of note here:

We are not importing React or ReactDOM on the page, but rather getting what we need from wp.element, which is already loaded for us.
ReactDOM.render() is also included in wp.element
Currently the state is not being saved in WordPress, but we will change that in future articles

From here you can start writing whatever React you want, as well as breaking code out into separate files and importing them as needed.

This is hopefully enough to get you up and running with adding React to your WordPress themes.

Setting Up Webpack Externals to Use Libraries Importing React

Most React packages that you use will be used to having React bundled with the final code and will include import React from "react" and things like that in their own code.

This will not work with WP Scripts by default. To get this to work we have to extend WP Scripts with our own webpack.config.js file and define React and ReactDOMs as external resources that will be available outside of the bundled code.

To do this, create a new webpack.config.js file in the root of your theme and add the following:

const defaults = require("@wordpress/scripts/config/webpack.config");

module.exports = {
  ...defaults,
  externals: {
    "react": "React",
    "react-dom": "ReactDOM"
  }
};

This will get the default configurations from WP Scripts and add them as the fallback configurations for Webpack. Then we can add in our customization of defining "react" and "react-dom" as being available as externals.

This will prevent errors from occurring when using third party React libraries that expect React to be imported.

Next Steps

From here can hopefully start building all the React you need for your themes. You may need to load your React in different places, like the header, sidebars or footer but the process is pretty similar.

In future articles we will go into more things you can do with React in WordPress Themes! You can find the main repo for this series here.

Please share how you're using React in your WordPress themes and projects!

If you like this post, please check out my Courses and Online Bootcamps at JavaScript for WordPress.