diff --git a/internal/website/docs/getting-started.mdx b/internal/website/docs/getting-started/setting-up-wordpress.mdx similarity index 61% rename from internal/website/docs/getting-started.mdx rename to internal/website/docs/getting-started/setting-up-wordpress.mdx index d25b788ee..20d0cb632 100644 --- a/internal/website/docs/getting-started.mdx +++ b/internal/website/docs/getting-started/setting-up-wordpress.mdx @@ -1,9 +1,11 @@ -# Getting Started +# Setting Up WordPress -## Prerequisites +## WordPress To create a headless WordPress site, you'll first need a WordPress instance! If you don't already have one, we recommend [Local](https://localwp.com/) to try things out locally, or you can use a live WordPress site. +## Plugins + You'll also need to download/activate two plugins for your WordPress site: 1. Download, upload, and activate the `wpe-headless` plugin. [(Download)](https://wp-product-info.wpesvc.net/v1/plugins/wpe-headless?download) @@ -19,8 +21,14 @@ The plugin ensures that your WordPress site runs smoothly as a headless CMS. Fro [WP GraphQL](https://wordpress.org/plugins/wp-graphql/) turns your WordPress site into a fully queryable GraphQL API. We use this API to communicate with the frontend. +### Set your headless frontend URL + +Now that you have the plugins installed, navigate to Settings -> Headless and set your Front-end site URL. This is the URL where your frontend will live. For local development this will usually be something like `http://localhost:3000` or `http://localhost:8000`. + +The Headless WordPress admin interface with a red rectangle around the front-end site URL field + ## Usage -We've made examples for you to easily get started with the frontend framework of your choice: +Now that you have WordPress setup to support headless, you can now use the framework! We've made guides to easily get you started with the frontend framework of your choice: - [Usage with Next.js](/next/getting-started) \ No newline at end of file diff --git a/internal/website/docs/guides/custom-post-types.mdx b/internal/website/docs/guides/custom-post-types.mdx new file mode 100644 index 000000000..aec43e163 --- /dev/null +++ b/internal/website/docs/guides/custom-post-types.mdx @@ -0,0 +1,258 @@ +# Interacting with custom post types + +Querying data in custom post types is just as easy as querying for posts or pages in the framework. + +Before we start, if you haven't already, [setup your WordPress site for headless](/getting-started/setting-up-wordpress). + +## Create a custom post type + +We'll be using the [Atlas Content Modeler](https://github.com/wpengine/atlas-content-modeler) plugin to create custom post types for this guide, but you can choose to create your custom post types in any way you'd like. + +Atlas Content Modeler is a WordPress plugin to create custom post types and fields for headless WordPress sites. Start by downloading the plugin and activating it on your WordPress site [(Download)](https://wp-product-info.wpesvc.net/v1/plugins/atlas-content-modeler?download) + +Now, navigate to WP Admin -> Content Modeler. + +The Atlas Content Modeler admin interface + +Let's create a custom post type for our team members. Click the "Get Started" button, and fill out the fields to create a new Content Model. Be sure to mark "API Visibility" to "Public" so we can query the data. + +The Atlas Content Modeler admin interface with fields for a team member content type + +## Create fields for your custom post type + +Now, that we've created our custom post type, let's add some fields to it. From WP Admin -> Content Modeler, select the Team Members custom post type. + +We'll add three fields: + +1. A Media field type. The name will be "Profile Pic" and the API identifier "profilePic" +2. A Text field type. The name will be "Full Name" and the API identifier "fullName". We'll also select "Use this field as the entry title" +3. A Rich Text field type. The name will be "Bio" and the API identifier "bio". + +The Atlas Content Modeler admin interface with filled custom fields + +## Create some team members + +Now that you have created a custom post type and fields, you can start entering data. Navigate to WP Admin -> Team Members to start creating! + +For this example, I've created two team members, Jane and Jonh Doe, with bios and profile pics: + +Atlas Content Modeler Custom Post Type interface for adding a new item + +## Create your starter headless project + +From here, you have your WordPress site setup with the necessary headless plugins, and data. Now, we need to create a frontend app to consume this data. + +We are going to use a starter project in Next.js, but the same concepts apply in other frontend frameworks. + +[Follow the steps in our Getting started with Next.js usage guide to create a frontend app.](/next/getting-started) + +Once your frontend app is created, the structure should look something like this: + +``` +my-app/ + src/ + client/ + .. + pages/ + .. + components/ + .. + scss/ + .. + public/ + .env.local + .env.local.sample + .env.test.sample + .eslintrc + .gitignore + gqless.config.js + next-env.d.ts + package.json + README.md + tsconfig.json +``` + +### Regenerate your schema + +Your schema is a TypeScript representation of your WordPress site. Since we have added some custom post types and fields, we'll want to regenerate this schema to ensure it's up to date. To regenerate your schema from the Next.js starter, simply run: + +```bash +npm run generate +``` + +[Learn more about generating your client/schema](next/generating-client) + +### Run the dev server + +Run the following command to start the dev server: + +```bash +npm run dev +``` + +You should now be able to access the starter project at [http://localhost:3000](http://localhost:3000) + +### Create a team page + +We'll create a team page in `src/pages/team.tsx` to display our team members: + +```tsx title="src/pages/team.tsx" +import Head from 'next/head'; +import { Header, Footer } from '../components'; +import { client } from '../client'; + +export default function Team() { + const { useGeneralSettings } = client; + const generalSettings = useGeneralSettings(); + + return ( + <> +
+ + + Custom Page - {generalSettings.title} + + +
+
+

Team Members

+
+
+ +