Skip to content

Commit

Permalink
Merge branch 'canary' into site-dev
Browse files Browse the repository at this point in the history
  • Loading branch information
blakewilson committed Nov 17, 2021
2 parents edec7e0 + c2c6bba commit 731744a
Show file tree
Hide file tree
Showing 17 changed files with 4,677 additions and 1,890 deletions.
40 changes: 20 additions & 20 deletions docs/next/guides/authentication.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,13 @@ Authentication can be a cumbersome process when building headless WordPress site

## How It Works

**TL;DR**: Authentication in Faust.js can be boiled down to 5 main steps:
**TL;DR**: Authentication in Faust.js can happen in five main steps:

1. User initiates request to authenticated data
2. Faust.js facilitates the request for an authorization code from the WPE Headless plugin. This is a short lived token that is used to request a refresh and access token
3. Faust.js facilitates the request for a refresh and access token from the WPE Headless plugin using the authorization code
4. Faust.js stores the refresh token in a secure, http only cookie. The refresh token is used to request a new access token when the current one expires
5. Faust.js stores the access token in memory to be used in subsequent authenticated requests
1. User initiates request to authenticate data.
2. Faust.js facilitates the request for an authorization code from the WPE Headless plugin. This code is a short-lived token used to request a refresh and access token.
3. Faust.js facilitates a refresh and access token request from the WPE Headless plugin using the authorization code.
4. Faust.js stores the refresh token in a secure, HTTP-only cookie. The token refresh requests a new access token when the current one expires
5. Faust.js stores the access token in memory that you can use in subsequent authenticated requests.

## Initial Setup

Expand All @@ -29,7 +29,7 @@ export default apiRouter;

## Strategies

There are two authentication strategies available in Faust.js: `redirect` and `local`
There are two authentication strategies available in Faust.js: `redirect` and `local`.

### Redirect Based Authentication

Expand All @@ -40,9 +40,9 @@ There are two authentication strategies available in Faust.js: `redirect` and `l
/>
</a>

Redirect based authentication is the default strategy in Faust.js. This strategy involves the user being redirected to WordPress to authenticate. Once the user has authenticated, the user is redirected back to the Next.js application with an authorization code that is then used to request a refresh and access token, thus completing the login process.
Redirect-based authentication is the default strategy in Faust.js. This strategy involves the user being redirected to WordPress to authenticate. Once the user has shown, the user redirects back to the Next.js application with an authorization code you can then use to request a refresh and access token, thus completing the login process.

This strategy is great for use cases where your authenticated users are admins/editors/etc. and do not necessarily need a "white label" login/register experience. Typically, you would use the redirect strategy if your primary reason for authentication is previews.
This strategy is excellent for use cases where your authenticated users are admins/editors/etc. and do not necessarily need a "white label" login/register experience. Typically, you would use the redirect strategy if your primary reason for authentication is previewing.

Since Redirect based authentication is the default authentication method, there is no configuration needed on your end to use it. It comes out of the box, and you'll see it in action when using previews or the [`useAuth`](/docs/next/reference/hooks/useAuth) hook.

Expand All @@ -55,13 +55,13 @@ Since Redirect based authentication is the default authentication method, there
/>
</a>

Local Based Authentication is the second strategy available in Faust.js. This strategy involves the user initiating a login request from the Next.js application via the `useLogin` hook. Upon successful login, `useLogin` returns an authorization code that is then used to request a refresh and access token, thus completing the login process.
Local Based Authentication is the second strategy available in Faust.js. This strategy involves the user initiating a login request from the Next.js application via the `useLogin` hook. Upon successful login, `useLogin` returns an authorization code used to request a refresh and access token, thus completing the login process.

This strategy is great for use cases where you want to support a more "white label" login/register experience. This strategy routes un-authenticated requests to your specified Next.js login page. In addition, users who wish to login/register will not have to interact with WordPress or the WordPress backend at all, giving you the flexibility to implement and fine tune your user flow.
This strategy is excellent for use cases where you want to support a more "white label" login/register experience. This strategy routes un-authenticated requests to your specified Next.js login page. In addition, users who wish to login/register will not have to interact with WordPress or the WordPress backend at all, giving you the flexibility to implement and fine-tune your user flow.

To use this strategy, you'll need to configure your `faust.config.js` file to use the `local` authentication strategy, in addition to the route of your Next.js login page. Take the following `faust.config.js` file for example:
To use this strategy, you'll need to configure your `faust.config.js` file to use the `local` authentication strategy, in addition to the route of your Next.js login page. Take the following `faust.config.js` file, for example:

```tsx title=faust.config.js {15,16}
```TSX title=faust.config.js {15,16}
import { config as coreConfig } from '@faustjs/core';

if (!process.env.NEXT_PUBLIC_WORDPRESS_URL) {
Expand All @@ -81,7 +81,7 @@ export default coreConfig({
});
```

We define the `authType` to `local` to indicate to the Faust.js config that we want to use the `local` strategy for authentication. We also define the `loginPagePath` to `/login` to indicate the route of the Next.js login page. This means un-authenticated requests will be redirected to the `/login` route in your Next.js application.
We define the `authType` to `local` to indicate to the Faust.js config that we use the `local` strategy for authentication. We also describe the `loginPagePath` to `/login` to mark the route of the Next.js login page. This strategy redirects unauthenticated requests to the `/login` route in your Next.js application.

In your `login.tsx` page, you could take advantage of the `useLogin` hook to initiate a login request to the WordPress backend:

Expand Down Expand Up @@ -151,9 +151,9 @@ The `useLogin` hook exports an object with the following properties:

For a more detailed explanation of the `useLogin` hook, see the [`useLogin` hook docs](/docs/next/reference/hooks/useLogin) .

Upon a successful login, a refresh token will be stored in a secure, http only cookie, as well as the access token in memory to use for subsequent authenticated requests. A login request can be confirmed it succeeded by checking for the `code` property in the `data` object.
Upon successful login, a secure, HTTP only cookie stores a refresh token and the access token in memory for subsequent authenticated requests. You can confirm a login request succeeded by checking for the `code` property in the `data` object.

Additionally, if the login page URL contains a `redirect_uri` query parameter, the user will be redirected to the specified URL upon successful login.
Additionally, if the login page URL contains a `redirect_uri` query parameter, it will redirect the user to the specified URL upon successful login.

Finally, you can create a `logout.tsx` page to handle logout requests. This is done by using the `useLogout` hook:

Expand Down Expand Up @@ -202,7 +202,7 @@ The `useLogout` hook exports an object with the following properties:

## Making Authenticated Requests

In the Faust.js client, you can use `useQuery`, `usePost`, `usePage`, etc. to make a request to the WordPress backend.
In the Faust.js client, you can use `useQuery`, `usePost`, `usePage`, etc., to request the WordPress backend.

These are exported from the `client` like so:

Expand All @@ -220,9 +220,9 @@ export default function Page() {

Requests using the above methodology will be un-authenticated.

To make authenticated requests, use the `auth` property exported from the `client`. This is essentially a replica of the `client`, except every request gets called with an access token:
To make authenticated requests, use the `auth` property exported from the `client`. This property is essentially a replica of the `client`, except every request gets called with an access token:

```tsx {1,4,5}
```TSX {1,4,5}
import { client } from 'client';

export default function Page() {
Expand All @@ -241,4 +241,4 @@ export default function Page() {
}
```

**Note:** The [`useAuth`](/docs/next/reference/hooks/useAuth) hook fetches the applicable tokens and ensures that the user is authenticated. Therefore, you should check for `isAuthenticated` prior to making authenticated requests, as doing so too early will result in a request without a valid access token.
**Note:** The [`useAuth`](/docs/next/reference/hooks/useAuth) hook fetches the applicable tokens and ensures that the user is authenticated. Therefore, you should check for `isAuthenticated` before making authenticated requests, as doing so too early will result in a request without a valid access token.
26 changes: 13 additions & 13 deletions docs/next/guides/custom-post-types.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -26,33 +26,33 @@ Let's create a custom post type for team members. Click the "Get Started" button

## Create Fields for the Custom Post Type

Now, that we've created the custom post type, let's add some fields to it. From WP Admin -> Content Modeler, select the Team Members custom post type.
Now that we've created the 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"
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".

<img src="/docs/img/team-members-content-modeler-fields.png" alt="The Atlas Content Modeler admin interface with filled custom fields" />

## Add 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!
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 John Doe, with bios and profile pics:

<img src="/docs/img/content-modeler-add-team-member.png" alt="Atlas Content Modeler Custom Post Type interface for adding a new item" />

## Clone the Starter Headless Project

Thus far, you have created a WordPress site with the necessary headless plugins, and data. Now, we need to create a frontend app to consume this data.
Thus far, you have created a WordPress site with the necessary headless plugins and data. Now, we need to create a frontend app to consume this data.

We are going to use the getting started example project in Next.js, but the same concepts apply in other frontend frameworks.
We will use the getting started example project in Next.js, but the same concepts apply in other frontend frameworks.

[Follow the steps in the getting started with Next.js usage guide to create a frontend app](../getting-started.mdx)

Once your frontend app is created, the structure should look something like this:
Once your frontend app renders, the structure should look something like this:

```
my-app/
Expand Down Expand Up @@ -80,7 +80,7 @@ my-app/

### Regenerate the GraphQL 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 getting started example, simply run:
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 restore your schema from the Next.js getting started example, run:

```bash
npm run generate
Expand All @@ -92,13 +92,13 @@ npm run generate

##### "GraphQL introspection is not allowed"

If you run into the error message `GraphQL introspection is not allowed, but the query contained __schema or __type`, you will have to temporarily enable introspection.
If you run into the error message `GraphQL introspection is not allowed, but the query contained __schema or __type`, you will have to enable introspection temporarily.

[Introspection is disabled by default in WPGraphQL.](https://www.wpgraphql.com/docs/security/#introspection-disabled-by-default) To enable it, go to WP Admin -> GraphQL -> Enable Public Introspection.

If you are using something other than `WPGraphQL` you will need to refer to the documentation on how to enable introspection.
If you are using something other than `WPGraphQL` you will need to refer to the documentation to enable introspection.

Once the schema file has been generated, you can then disable introspection again.
Once the schema file generates, you can then disable introspection again.

### Run the Dev Server

Expand Down Expand Up @@ -151,7 +151,7 @@ This will look something like:

### Query for Team Members

When querying custom post types in Faust.js, you can leverage the `useQuery` hook that is exported from the client. This allows you to access all of WordPress' data. You'll also notice it's typed from your schema, making things super easy to find.
When querying custom post types in Faust.js, you can leverage the `useQuery` hook exported from the client. `useQuery` allows you to access all of WordPress' data. You'll also notice it's typed from your schema, making things super easy to find.

<img src="/docs/img/useQuery-typed.png" alt="A screenshot of the useQuery hook and its typings" />

Expand Down Expand Up @@ -261,7 +261,7 @@ export default function Team() {
}
```

Now, head back over to [http://localhost:3000/team](http://localhost:3000/team) to see your WordPress data come to life!
Now, head back to [http://localhost:3000/team](http://localhost:3000/team) to see your WordPress data come to life!

<img src="/docs/img/nextjs-team-page.png" alt="A web page with a list of team members" />

Expand Down
Loading

1 comment on commit 731744a

@headless-platform-by-wp-engine

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Branch site-dev was deployed successfully
Your environment Development of app faustjs-site was successfully updated
View build logs: https://my.wpengine.com/atlas#/faustjs-site/cixzyt38dn5ak04xxcqc36lf/7rb72653bf5d53g4mj67dgqt
View your environment URL: https://hcixzyt38dn5ak04xxcqc36lf.js.wpenginepowered.com

Please sign in to comment.