Skip to content

Commit

Permalink
docs(next-drupal): updated docs (#787)
Browse files Browse the repository at this point in the history 
Co-authored-by: Marco Monti <[email protected]>
Co-authored-by: Brian Perry <[email protected]>
  • Loading branch information
@MontiMarco92 @backlineint
3 people authored Oct 11, 2024
1 parent 1cda615 commit f377da8
Show file tree
Hide file tree
Showing 56 changed files with 876 additions and 459 deletions.
40 changes: 14 additions & 26 deletions www/config/docs.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,8 +49,8 @@ export const docsConfig: DocsConfig = {
href: "/docs/environment-variables",
},
{
title: "Preview Mode",
href: "/docs/preview-mode",
title: "Draft Mode",
href: "/docs/draft-mode",
},
{
title: "TypeScript",
Expand Down Expand Up @@ -108,8 +108,8 @@ export const docsConfig: DocsConfig = {
href: "/docs/fetcher",
},
{
title: "Serializer",
href: "/docs/serializer",
title: "Deserializer",
href: "/docs/deserializer",
},
{
title: "Caching",
Expand All @@ -124,10 +124,6 @@ export const docsConfig: DocsConfig = {
title: "getResource",
href: "/docs/reference/getresource",
},
{
title: "getResourceFromContext",
href: "/docs/reference/getresourcefromcontext",
},
{
title: "getResourceByPath",
href: "/docs/reference/getresourcebypath",
Expand All @@ -136,10 +132,6 @@ export const docsConfig: DocsConfig = {
title: "getResourceCollection",
href: "/docs/reference/getresourcecollection",
},
{
title: "getResourceCollectionFromContext",
href: "/docs/reference/getresourcecollectionfromcontext",
},
{
title: "createResource",
href: "/docs/reference/createresource",
Expand All @@ -157,28 +149,20 @@ export const docsConfig: DocsConfig = {
href: "/docs/reference/deleteresource",
},
{
title: "getStaticPathsFromContext",
href: "/docs/reference/getstaticpathsfromcontext",
title: "getResourceCollectionPathSegments",
href: "/docs/reference/getresourcecollectionpathsegments",
},
{
title: "translatePath",
href: "/docs/reference/translatepath",
},
{
title: "translatePathFromContext",
href: "/docs/reference/translatepathfromcontext",
},
{
title: "getPathFromContext",
href: "/docs/reference/getpathfromcontext",
},
{
title: "getEntryForResourceType",
href: "/docs/reference/getentryforresourcetype",
title: "constructPathFromSegment",
href: "/docs/reference/constructpathfromsegment",
},
{
title: "preview",
href: "/docs/reference/preview",
title: "buildEndpoint",
href: "/docs/reference/buildendpoint",
},
{
title: "getAccessToken",
Expand Down Expand Up @@ -208,6 +192,10 @@ export const docsConfig: DocsConfig = {
title: "deserialize",
href: "/docs/reference/deserialize",
},
{
title: "getAuthorizationHeader",
href: "/docs/reference/getauthorizationheader",
},
],
},
{
Expand Down
6 changes: 3 additions & 3 deletions www/config/tutorials.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,9 @@ export const tutorialsConfig = [
items: [],
},
{
title: "Preview Mode",
excerpt: "Implement Preview Mode for Entity Types.",
url: "/learn/preview-mode",
title: "Draft Mode",
excerpt: "Implement Draft Mode for Entity Types.",
url: "/learn/draft-mode",
items: [],
},
{
Expand Down
95 changes: 40 additions & 55 deletions www/content/docs/authentication.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
---
title: Authentication
excerpt: Making authenticated requests with DrupalClient.
excerpt: Making authenticated requests with NextDrupal.
---

The `DrupalClient` works with several auth types. You can use **Bearer** tokens, **Basic** tokens or bring your own authorization headers.
The `NextDrupal` client works with several auth types. You can use **Bearer** tokens, **Basic** tokens or bring your own authorization headers.

Authentication can be set globally on the client or custom per method.

Expand All @@ -16,9 +16,9 @@ This is the default authentication configured on the client.
**This is used most of the time for fetching and building static pages.**

```ts title=lib/drupal.ts
import { DrupalClient } from "next-drupal"
import { NextDrupal } from "next-drupal"

export const drupal = new DrupalClient(
export const drupal = new NextDrupal(
process.env.NEXT_PUBLIC_DRUPAL_BASE_URL,
{
auth: // Configure the global auth here.
Expand Down Expand Up @@ -59,15 +59,12 @@ You need to enable the `simple_oauth` module on Drupal.

```ts title=lib/drupal.ts
// Client
export const drupal = new DrupalClient(
process.env.NEXT_PUBLIC_DRUPAL_BASE_URL,
{
auth: {
clientId: process.env.DRUPAL_CLIENT_ID,
clientSecret: process.env.DRUPAL_CLIENT_SECRET,
},
}
)
export const drupal = new NextDrupal(process.env.NEXT_PUBLIC_DRUPAL_BASE_URL, {
auth: {
clientId: process.env.DRUPAL_CLIENT_ID,
clientSecret: process.env.DRUPAL_CLIENT_SECRET,
},
})

// Method
const article = drupal.getResource(
Expand All @@ -82,26 +79,23 @@ const article = drupal.getResource(
)
```

`DrupalClient` will fetch **Bearer** token and handle expiration for you.
`NextDrupal` client will fetch **Bearer** token and handle expiration for you.

If you need to customize the OAuth URL you can use the `url` option.

```ts title=lib/drupal.ts
export const drupal = new DrupalClient(
process.env.NEXT_PUBLIC_DRUPAL_BASE_URL,
{
auth: {
clientId: process.env.DRUPAL_CLIENT_ID,
clientSecret: process.env.DRUPAL_CLIENT_SECRET,
// highlight-start
url: `/oauth2/token`,
// highlight-end
},
}
)
export const drupal = new NextDrupal(process.env.NEXT_PUBLIC_DRUPAL_BASE_URL, {
auth: {
clientId: process.env.DRUPAL_CLIENT_ID,
clientSecret: process.env.DRUPAL_CLIENT_SECRET,
// highlight-start
url: `/oauth2/token`,
// highlight-end
},
})
```

By default, `DrupalClient` uses `/oauth/token` as the default URL.
By default, `NextDrupal` uses `/oauth/token` as the default URL.

---

Expand All @@ -117,15 +111,12 @@ You need to enable the `basic_auth` module on Drupal.

```ts
// Client.
export const drupal = new DrupalClient(
process.env.NEXT_PUBLIC_DRUPAL_BASE_URL,
{
auth: {
username: process.env.DRUPAL_USERNAME,
password: process.env.DRUPAL_PASSWORD,
},
}
)
export const drupal = new NextDrupal(process.env.NEXT_PUBLIC_DRUPAL_BASE_URL, {
auth: {
username: process.env.DRUPAL_USERNAME,
password: process.env.DRUPAL_PASSWORD,
},
})

// Method
const articles = await drupal.getResourceCollection("node--article", {
Expand All @@ -144,14 +135,11 @@ You can also provide a custom callback for authentication. The callback must ret

```ts
// Client
export const drupal = new DrupalClient(
process.env.NEXT_PUBLIC_DRUPAL_BASE_URL,
{
auth: () => {
// Do something and return an Authorization header.
},
}
)
export const drupal = new NextDrupal(process.env.NEXT_PUBLIC_DRUPAL_BASE_URL, {
auth: () => {
// Do something and return an Authorization header.
},
})

// Method
const users = await drupal.getResourceCollection("user--user", {
Expand All @@ -167,16 +155,13 @@ You can also pass in an access token.

```ts
// Client
export const drupal = new DrupalClient(
process.env.NEXT_PUBLIC_DRUPAL_BASE_URL,
{
auth: {
access_token: "ECYM594IlARGc3S8KgBHvTpki0rDtWx6...",
token_type: "Bearer",
expires_in: 3600,
},
}
)
export const drupal = new NextDrupal(process.env.NEXT_PUBLIC_DRUPAL_BASE_URL, {
auth: {
access_token: "ECYM594IlARGc3S8KgBHvTpki0rDtWx6...",
token_type: "Bearer",
expires_in: 3600,
},
})

// Method
const articles = await drupal.getResourceCollection("node--article", {
Expand All @@ -198,7 +183,7 @@ import { getSession } from "next-auth/react"
const session = getSession(...)

// Client
export const drupal = new DrupalClient(
export const drupal = new NextDrupal(
process.env.NEXT_PUBLIC_DRUPAL_BASE_URL,
{
auth: session.accessToken,
Expand Down
13 changes: 5 additions & 8 deletions www/content/docs/cache.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Caching
excerpt: Using a custom cache for resources.
---

The `DrupalClient` has support for caching resources.
The `NextDrupal` client has support for caching resources.

This is handy when dealing with global data: you can fetch data once and re-use during builds.

Expand All @@ -22,7 +22,7 @@ Note: as of `next-drupal 1.3.0`, only `getResource` and `getMenu` support cachin
</Callout>

```ts title=lib/drupal.ts
import { DrupalClient, DataCache } from "next-drupal"
import { NextDrupal, DataCache } from "next-drupal"
import Redis from "ioredis"

const redis = new Redis(process.env.REDIS_URL)
Expand All @@ -37,12 +37,9 @@ export const redisCache: DataCache = {
},
}

export const drupal = new DrupalClient(
process.env.NEXT_PUBLIC_DRUPAL_BASE_URL,
{
cache: redisCache,
}
)
export const drupal = new NextDrupal(process.env.NEXT_PUBLIC_DRUPAL_BASE_URL, {
cache: redisCache,
})
```

Now when you make a `getResource` or `getMenu` call you can tell the client to cache and re-use responses.
Expand Down
12 changes: 6 additions & 6 deletions www/content/docs/client.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
---
title: Drupal Client
title: NextDrupal Client
excerpt: A powerful JSON:API client for Drupal.
---

The `DrupalClient` is a powerful JSON:API client that ships with helpers for working with Drupal data.
The `NextDrupal` client is a powerful JSON:API client that ships with helpers for working with Drupal data.

You can use the `DrupalClient` to fetch JSON:API data from Drupal to build static pages.
You can use the `NextDrupal` client to fetch JSON:API data from Drupal to build static pages in advance, or server render pages on-demand.

It also comes with full support for JSON:API write operations which means you can create JSON:API resources from Next.js to Drupal.

Expand All @@ -27,10 +27,10 @@ It also comes with full support for JSON:API write operations which means you ca
## Usage

```ts
import { DrupalClient } from "next-drupal"
import { NextDrupal } from "next-drupal"

// Create a new DrupalClient.
const drupal = new DrupalClient("https://example.com")
// Create a new NextDrupal client.
const drupal = new NextDrupal("https://example.com")

// Fetch articles.
const articles = await drupal.getResourceCollection("node--article")
Expand Down
Loading

0 comments on commit f377da8

Please sign in to comment.