Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(next-drupal): updated docs #787

Merged
merged 4 commits into from
Oct 11, 2024
Merged

docs(next-drupal): updated docs #787

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d67f2cf
docs(next-drupal): updated docs
Jul 9, 2024
6c0e389
docs(next-drupal): updated learn section
Jul 11, 2024
239b578
docs(next-drupal): requested changes
Sep 9, 2024
b3e6c77
Merge branch 'main' into docs/next-drupal-docs-update
backlineint Oct 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 14 additions & 26 deletions www/config/docs.ts
View file
Open in desktop
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
Open in desktop
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
103 changes: 48 additions & 55 deletions www/content/docs/authentication.mdx
View file
Open in desktop
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 @@ -192,13 +177,21 @@ const articles = await drupal.getResourceCollection("node--article", {

If you're using [NextAuth](https://next-auth.js.org) you can use the results from `getSession`:

<!--
MontiMarco92 marked this conversation as resolved.
Show resolved Hide resolved
************************************************************
* TODO: Remove this block before publishing.

* Comment: Need to corroborate this with NextAuth updates
************************************************************
-->

```ts
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
21 changes: 13 additions & 8 deletions www/content/docs/cache.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,22 @@ title: Caching
excerpt: Using a custom cache for resources.
---

The `DrupalClient` has support for caching resources.
The `NextDrupal` has support for caching resources.
MontiMarco92 marked this conversation as resolved.
Show resolved Hide resolved

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

You can provide your own cache implementation using the [`cache`](/docs/configuration#cache) option.

---

<!--
MontiMarco92 marked this conversation as resolved.
Show resolved Hide resolved
************************************************************
* TODO: Remove this block before publishing.

* Comment: Not sure how this cache option works with Next.js caching system
************************************************************
-->

## Example

Here's an example on how you can use Redis to cache resources.
Expand All @@ -22,7 +30,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 +45,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
Open in desktop
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` is a powerful JSON:API client that ships with helpers for working with Drupal data.
MontiMarco92 marked this conversation as resolved.
Show resolved Hide resolved

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.
MontiMarco92 marked this conversation as resolved.
Show resolved Hide resolved

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