diff --git a/www/config/docs.ts b/www/config/docs.ts index b4f70cb01..1bdbed9d7 100644 --- a/www/config/docs.ts +++ b/www/config/docs.ts @@ -162,7 +162,7 @@ export const docsConfig: DocsConfig = { }, { title: "buildEndpoint", - href: "/docs/reference/buildEndpoint", + href: "/docs/reference/buildendpoint", }, { title: "getAccessToken", diff --git a/www/content/docs/authentication.mdx b/www/content/docs/authentication.mdx index 89df6e708..76b5c6f10 100644 --- a/www/content/docs/authentication.mdx +++ b/www/content/docs/authentication.mdx @@ -177,14 +177,6 @@ const articles = await drupal.getResourceCollection("node--article", { If you're using [NextAuth](https://next-auth.js.org) you can use the results from `getSession`: - - ```ts import { getSession } from "next-auth/react" diff --git a/www/content/docs/cache.mdx b/www/content/docs/cache.mdx index 99b7f51ac..9089eadde 100644 --- a/www/content/docs/cache.mdx +++ b/www/content/docs/cache.mdx @@ -3,7 +3,7 @@ title: Caching excerpt: Using a custom cache for resources. --- -The `NextDrupal` 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. @@ -11,14 +11,6 @@ You can provide your own cache implementation using the [`cache`](/docs/configur --- - - ## Example Here's an example on how you can use Redis to cache resources. diff --git a/www/content/docs/client.mdx b/www/content/docs/client.mdx index ed25b0a74..5e6290805 100644 --- a/www/content/docs/client.mdx +++ b/www/content/docs/client.mdx @@ -3,9 +3,9 @@ title: NextDrupal Client excerpt: A powerful JSON:API client for Drupal. --- -The `NextDrupal` 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 `NextDrupal` client 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. diff --git a/www/content/docs/configuration.mdx b/www/content/docs/configuration.mdx index 26c3b21e9..3e5293afa 100644 --- a/www/content/docs/configuration.mdx +++ b/www/content/docs/configuration.mdx @@ -5,7 +5,7 @@ excerpt: Initialization and options for NextDrupal client. ## Initialization -To create a new `NextDrupal`, use the following initialization: +To create a new `NextDrupal` client, use the following initialization: ```ts import { NextDrupal } from "next-drupal" @@ -125,14 +125,6 @@ You can find more info about using a custom fetcher [here](/docs/fetcher). ### cache - - - **Default value**: `null` - **Required**: No @@ -181,14 +173,6 @@ Set whether the client should use authenticated requests by default. If set to ` --- - - ### headers - **Default value**: `{ "Content-Type": "application/vnd.api+json", Accept: "application/vnd.api+json" }` diff --git a/www/content/docs/creating-resources.mdx b/www/content/docs/creating-resources.mdx index bd3719410..d3e56379c 100644 --- a/www/content/docs/creating-resources.mdx +++ b/www/content/docs/creating-resources.mdx @@ -15,11 +15,11 @@ If you're working with JSON:API, be mindful to select the option: `Accept all JSON:API create, read, update, and delete operations.` -on the following path: `/admin/config/services/jsonapi` on Drupal. +on the following path: `/admin/config/services/jsonapi` in Drupal. -The `NextDrupal` client ships with a `createResource` and a `createFileResource` methods for creating JSON:API resources. +The `NextDrupal` client ships with `createResource` and `createFileResource` methods for creating JSON:API resources. --- diff --git a/www/content/docs/deleting-resources.mdx b/www/content/docs/deleting-resources.mdx index 79a55e994..473180f52 100644 --- a/www/content/docs/deleting-resources.mdx +++ b/www/content/docs/deleting-resources.mdx @@ -15,7 +15,7 @@ If you're working with JSON:API, be mindful to select the option: `Accept all JSON:API create, read, update, and delete operations.` -on the following path: `/admin/config/services/jsonapi` on Drupal. +on the following path: `/admin/config/services/jsonapi` in Drupal. diff --git a/www/content/docs/fetcher.mdx b/www/content/docs/fetcher.mdx index e124e5cb4..99cc4ffb4 100644 --- a/www/content/docs/fetcher.mdx +++ b/www/content/docs/fetcher.mdx @@ -7,7 +7,7 @@ excerpt: Using a custom fetcher with NextDrupal. ************************************************************ * TODO: Remove this block before publishing. -* Comment: Not sure how a custom fetcher will work because of the caching options of the Nextjs extended fetch API +* Comment: In order to support a custom fetcher and handle caching withouth the native polyfilled fetch, 'unstable_cache' from next should be used, but also the NextDrupal client should support passing revalidate options. ************************************************************ --> diff --git a/www/content/docs/fetching-resources.mdx b/www/content/docs/fetching-resources.mdx index 7c8aab964..70cd6bb19 100644 --- a/www/content/docs/fetching-resources.mdx +++ b/www/content/docs/fetching-resources.mdx @@ -168,10 +168,3 @@ const article = await drupal.getResourceCollection( // highlight-end ) ``` - - diff --git a/www/content/docs/pages.mdx b/www/content/docs/pages.mdx index 026dda7b1..2102032cd 100644 --- a/www/content/docs/pages.mdx +++ b/www/content/docs/pages.mdx @@ -3,15 +3,20 @@ title: Building Pages excerpt: How to build pages using JSON:API resources from Drupal. --- -In Next.js V14, data fetching has evolved significantly from previous versions. Instead of using `getStaticProps` and `getServerSideProps` you now use the native `fetch` function enhanced by Next.js to handle server-side data fetching. This allows you to configure caching and revalidation directly within your fetch requests. These can be used in Server Components, Route Handlers, and Server Actions. You can read more about it [here](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating) +In Next.js V14, data fetching has evolved significantly from previous versions. Instead of using `getStaticProps` and `getServerSideProps` you now use the native `fetch` function enhanced by Next.js to handle server-side data fetching. -The `NextDrupal` client provides several functions to help you query JSON:API resources from Drupal and manage these revalidation options on the `fetch` request level. +The `NextDrupal` client provides several functions to help you query JSON:API resources from Drupal. @@ -52,7 +57,7 @@ export default function AboutPage() { ## Dynamic pages -You can use Next.js [dynamic route](https://nextjs.org/docs/app/building-your-application/routing/dynamic-routes) to build static pages for Drupal entity types. +You can use Next.js [dynamic routes](https://nextjs.org/docs/app/building-your-application/routing/dynamic-routes) to build static pages for Drupal entity types. Start by creating a page at `/app/[...slug]/page.tsx`, where `[...slug]` maps to the **path alias** for an entity type (or content type) in Drupal. @@ -134,17 +139,17 @@ export default function Page({ params }) { params.addFields("node--article", ["title", "path", "body", "uid"]) } - const node = await drupal.getResourceByPath(path, { + const node = await drupal.getResource(path, path.entity.uuid { params: params.getQueryObject(), }) - // Render different Components based on Node type + // Render different Components based on Node type. if (node.type === "node--page") { - return + return } if (node.type === "node--article") { - return + return } return null diff --git a/www/content/docs/reference/buildEndpoint.mdx b/www/content/docs/reference/buildendpoint.mdx similarity index 72% rename from www/content/docs/reference/buildEndpoint.mdx rename to www/content/docs/reference/buildendpoint.mdx index 9369ae809..bf051289c 100644 --- a/www/content/docs/reference/buildEndpoint.mdx +++ b/www/content/docs/reference/buildendpoint.mdx @@ -48,12 +48,23 @@ const drupal = new DrupalClient(process.env.NEXT_PUBLIC_DRUPAL_BASE_URL, { ```ts // https://example.com/jsonapi/node/article. const url = await drupal.buildEndpoint({ resourceType: `node--article` }) -``` - +// https://example.com/jsonapi/en/node/article?include=field_image. +const url = await drupal.buildEndpoint({ + locale: `en`, + resourceType: `node--article`, + searchParams: `include=field_image`, +}) + +// https://example.com/jsonapi/en/views/articles/page_1. +const url = await drupal.buildEndpoint({ + locale: `en`, + path: `/views/articles/page_1`, +}) +``` diff --git a/www/content/docs/reference/fetch.mdx b/www/content/docs/reference/fetch.mdx index 304ada6ab..ae73e567b 100644 --- a/www/content/docs/reference/fetch.mdx +++ b/www/content/docs/reference/fetch.mdx @@ -14,11 +14,19 @@ const response = await drupal.fetch(input, init?): Promise - Optional - The fetch options with `withAuth`. - If `withAuth` is set, `fetch` will fetch an `Authorization` header before making the request. + + --- diff --git a/www/content/docs/reference/getentryforresourcetype.mdx b/www/content/docs/reference/getentryforresourcetype.mdx new file mode 100644 index 000000000..b9110c0fa --- /dev/null +++ b/www/content/docs/reference/getentryforresourcetype.mdx @@ -0,0 +1,40 @@ +--- +title: getEntryForResourceType +excerpt: Get the JSON:API entry for a resource type. +--- + +```ts +const url = await drupal.getEntryForResourceType(type, locale?): Promise +``` + +- `type: string` + - **Required** + - The resource type. Example: `node--article`. +- `locale: string` + - Optional + - The locale to fetch the index. Example: `es` or `fr`. + +--- + +## Notes + +By default, when retrieving resources in `getResource` or `getResourceCollection`, the `NextDrupalPages` make a request to Drupal to fetch the JSON:API resource entry.. + +Example: if you provide `node--article`, `NextDrupalPages` will make a request to `http://example.com/jsonapi/node/article`. + +If you would like to infer the entry from the resource type, use the [`useDefaultResourceTypeEntry`](/docs/configuration#usedefaultresourcetypeentry) option. + +```ts +const drupal = new NextDrupalPages(process.env.NEXT_PUBLIC_DRUPAL_BASE_URL, { + useDefaultResourceTypeEntry: true, +}) +``` + +--- + +## Examples + +```ts +// https://example.com/jsonapi/node/article. +const url = await drupal.getEntryForResourceType(`node--article`) +``` diff --git a/www/content/docs/reference/getmenu.mdx b/www/content/docs/reference/getmenu.mdx index f3f4971a6..521347953 100644 --- a/www/content/docs/reference/getmenu.mdx +++ b/www/content/docs/reference/getmenu.mdx @@ -20,7 +20,6 @@ const resource = await drupal.getMenu( defaultLocale, withCache, cacheKey, - next } ): Promise<{ items: T[] @@ -42,11 +41,6 @@ const resource = await drupal.getMenu( - `defaultLocale: string`: The default locale of the site. - `withCache: boolean`: Set `withCache` if you want to store and retrieve the menu from cache. - `cacheKey: string`: The cache key to use. - - `next: NextFetchRequestConfig` - - Set the `revalidate` option in seconds to configure [Time-based revalidation](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#time-based-revalidation). - Ex: `next: { revalidate: 3600 } // revalidate resource every hour` - - Set the `tags` option to confiure [Tag-based On demand revalidation](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#on-demand-revalidation). - Ex: `next: { tags: ['resource-tag'] }` --- @@ -79,10 +73,7 @@ const menu = await drupal.getMenu("main", { ************************************************************ * TODO: Remove this block before publishing. -* Comment: Don't know how this cache works with Nextjs caching system -************************************************************ ---> - +* Comment: commented example until revalidation props are supported. - Get the `main` menu with tag-based revalidation. ```ts @@ -90,3 +81,5 @@ const menu = await drupal.getMenu("main", { next: { tags: ["main--menu"] }, // revalidates resource when calling `revalidateTag('main--menu')` }) ``` +************************************************************ +--> diff --git a/www/content/docs/reference/getpathfromcontext.mdx b/www/content/docs/reference/getpathfromcontext.mdx new file mode 100644 index 000000000..cb847abd4 --- /dev/null +++ b/www/content/docs/reference/getpathfromcontext.mdx @@ -0,0 +1,32 @@ +--- +title: getPathFromContext +excerpt: Return the path (slug) from getStaticProps or getServerSideProps context. +--- + +```ts +const slug = drupal.getPathFromContext( + context, + options?: { + pathPrefix, + } +): string +``` + +- `context: GetStaticPropsContext | GetServerSidePropsContext` + - **Required** + - The context from `getStaticProps` or `getServerSideProps`. +- `options` + - Optional + - `pathPrefix: string`: Set the pathPrefix if you're calling from a subdir. Example: for `/articles/[...slug].tsx`, use `pathPrefix: "/articles"`. + +--- + +## Examples + +- Get the path (slug) from `getStaticProps` context. + +```ts +export async function getStaticProps(context) { + const slug = await drupal.getPathFromContext(context) +} +``` diff --git a/www/content/docs/reference/getresource.mdx b/www/content/docs/reference/getresource.mdx index dcceb2078..edc0d1da4 100644 --- a/www/content/docs/reference/getresource.mdx +++ b/www/content/docs/reference/getresource.mdx @@ -14,7 +14,6 @@ const resource = await drupal.getResource( locale, defaultLocale, withCache, - next } ): Promise ``` @@ -36,11 +35,6 @@ const resource = await drupal.getResource( - `defaultLocale: string`: The default locale of the site. - `withCache: boolean`: Set `withCache` if you want to store and retrieve the resource from cache. - `cacheKey: string`: The cache key to use. - - `next: NextFetchRequestConfig` - - Set the `revalidate` option in seconds to configure [Time-based revalidation](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#time-based-revalidation). - Ex: `next: { revalidate: 3600 } // revalidate resource every hour` - - Set the `tags` option to confiure [Tag-based On demand revalidation](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#on-demand-revalidation). - Ex: `next: { tags: ['resource-tag'] }` --- @@ -91,6 +85,11 @@ const article = await drupal.getResource("node--article", id, { }) ``` + --- diff --git a/www/content/docs/reference/getresourcebypath.mdx b/www/content/docs/reference/getresourcebypath.mdx index 86c6450a9..828033d9a 100644 --- a/www/content/docs/reference/getresourcebypath.mdx +++ b/www/content/docs/reference/getresourcebypath.mdx @@ -13,7 +13,6 @@ const resource = await drupal.getResourceByPath( locale, defaultLocale, isVersionable, - next, } ): Promise ``` @@ -31,11 +30,6 @@ const resource = await drupal.getResourceByPath( - `locale: string`: The locale to fetch the resource in. - `defaultLocale: string`: The default locale of the site. - `isVersionable: boolean`: Set to true if you're fetching the revision for a resource. _Automatically set to true for node entity types_. - - `next: NextFetchRequestConfig` - - Set the `revalidate` option in seconds to configure [Time-based revalidation](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#time-based-revalidation). - Ex: `next: { revalidate: 3600 } // revalidate resource every hour` - - Set the `tags` option to confiure [Tag-based On demand revalidation](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#on-demand-revalidation). - Ex: `next: { tags: ['resource-tag'] }` --- @@ -73,6 +67,11 @@ const node = await drupal.getResourceByPath("/blog/slug-for-article", { }) ``` + --- diff --git a/www/content/docs/reference/getresourcecollection.mdx b/www/content/docs/reference/getresourcecollection.mdx index 0ce08f9ed..a73f557ad 100644 --- a/www/content/docs/reference/getresourcecollection.mdx +++ b/www/content/docs/reference/getresourcecollection.mdx @@ -12,7 +12,6 @@ const resource = await drupal.getResourceCollection( deserialize, locale, defaultLocale, - next, } ): Promise ``` @@ -29,11 +28,6 @@ const resource = await drupal.getResourceCollection( - `deserialize: boolean`: Set to false to return the raw JSON:API response. - `locale: string`: The locale to fetch the resource in. - `defaultLocale: string`: The default locale of the site. - - `next: NextFetchRequestConfig` - - Set the `revalidate` option in seconds to configure [Time-based revalidation](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#time-based-revalidation). - Ex: `next: { revalidate: 3600 } // revalidate resource every hour` - - Set the `tags` option to confiure [Tag-based On demand revalidation](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#on-demand-revalidation). - Ex: `next: { tags: ['resource-tag'] }` --- @@ -63,6 +57,11 @@ const { data, meta, links } = await drupal.getResourceCollection("node--page", { }) ``` + --- diff --git a/www/content/docs/reference/getresourcecollectionfromcontext.mdx b/www/content/docs/reference/getresourcecollectionfromcontext.mdx new file mode 100644 index 000000000..da579209c --- /dev/null +++ b/www/content/docs/reference/getresourcecollectionfromcontext.mdx @@ -0,0 +1,78 @@ +--- +title: getResourceCollectionFromContext +excerpt: Fetch a collection of resources from getStaticProps or getServerSideProps context. +--- + +```ts +const resource = await drupal.getResourceCollectionFromContext( + type, + context, + options?: { + params, + withAuth, + deserialize, + locale, + defaultLocale, + } +): Promise +``` + +- `type: string` + - **Required** + - The resource type. Example: `node--article` or `user--user`. +- `context: GetStaticPropsContext | GetServerSidePropsContext` + - **Required** + - The context from `getStaticProps` or `getServerSideProps`. +- `options` + - Optional + - `params: JsonApiParams`: JSON:API params such as `filter`, `fields`, `include` or `sort`. + - `withAuth: boolean | NextDrupalAuth`: + - Set the authentication method to use. See the [authentication docs](/docs/authentication). + - Set to `true` to use the authentication method configured on the client. + - `deserialize: boolean`: Set to false to return the raw JSON:API response. + - `locale: string`: The locale to fetch the resource in. + - `defaultLocale: string`: The default locale of the site. + +--- + +## Notes + +- The localized resources will be fetched based on the `locale` and `defaultLocale` values from `context`. + +--- + +## Examples + +- Get all articles from context. + +```ts title=pages/[[...slug]].tsx +export async function getStaticProps(context) { + const articles = await drupal.getResourceCollectionFromContext( + "node--article", + context + ) + + return { + props: { + articles, + }, + } +} +``` + +--- + +## TypeScript + +- Using `DrupalNode` for a node entity type. + +```ts +import { DrupalNode } from "next-drupal" + +const nodes = await drupal.getResourceCollectionFromContext( + "node--article", + context +) +``` + +See the [TypeScript docs](/docs/typescript) for more built-in types. diff --git a/www/content/docs/reference/getresourcecollectionpathsegments.mdx b/www/content/docs/reference/getresourcecollectionpathsegments.mdx index af4f22f6b..2c0e51b2a 100644 --- a/www/content/docs/reference/getresourcecollectionpathsegments.mdx +++ b/www/content/docs/reference/getresourcecollectionpathsegments.mdx @@ -12,8 +12,6 @@ const paths = await drupal.getResourceCollectionPathSegments( pathPrefix, locale, defaultLocale, - next, - } ): Promise<{ path: string @@ -35,11 +33,6 @@ const paths = await drupal.getResourceCollectionPathSegments( - `pathPrefix: string`: Set the pathPrefix if you're calling from a subdir. Example: for `/articles/[...slug].tsx`, use `pathPrefix: "/articles"`. - `locale: string`: The locale to fetch the resource in. - `defaultLocale: string`: The default locale of the site. - - `next: NextFetchRequestConfig` - - Set the `revalidate` option in seconds to configure [Time-based revalidation](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#time-based-revalidation). - Ex: `next: { revalidate: 3600 } // revalidate resource every hour` - - Set the `tags` option to confiure [Tag-based On demand revalidation](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#on-demand-revalidation). - Ex: `next: { tags: ['resource-tag'] }` --- diff --git a/www/content/docs/reference/getresourcefromcontext.mdx b/www/content/docs/reference/getresourcefromcontext.mdx new file mode 100644 index 000000000..f317f7016 --- /dev/null +++ b/www/content/docs/reference/getresourcefromcontext.mdx @@ -0,0 +1,138 @@ +--- +title: getResourceFromContext +excerpt: Fetch a resource from getStaticProps or getServerSideProps context. +--- + +```ts +const resource = await drupal.getResourceFromContext( + input, + context, + options?: { + params, + withAuth, + deserialize, + locale, + defaultLocale, + pathPrefix, + isVersionable, + } +): Promise +``` + +- `input: string | DrupalTranslatedPath` + - **Required** + - The resource type `node--article` or the translated path from `translatePathFromContext`. +- `context: GetStaticPropsContext | GetServerSidePropsContext` + - **Required** + - The context from `getStaticProps` or `getServerSideProps`. +- `options` + - Optional + - `params: JsonApiParams`: JSON:API params such as `filter`, `fields`, `include` or `sort`. + - `withAuth: boolean | NextDrupalAuth`: + - Set the authentication method to use. See the [authentication docs](/docs/authentication). + - Set to `true` to use the authentication method configured on the client. + - `deserialize: boolean`: Set to false to return the raw JSON:API response. + - `locale: string`: The locale to fetch the resource in. + - `defaultLocale: string`: The default locale of the site. + - `pathPrefix: string`: Set the pathPrefix if you're calling from a subdir. Example: for `/articles/[...slug].tsx`, use `pathPrefix: "/articles"`. + - `isVersionable: boolean`: Set to true if you're fetching the revision for a resource. _Automatically set to true for node entity types_. + +--- + +## Notes + +- The localized resource will be fetched based on the `locale` and `defaultLocale` values from `context`. + +- If you pass in a `DrupalTranslatedPath` for input, `getResourceFromContext` will take the `type` and `id` from the path and make a `getResource` call to Drupal. + +```ts +export async function getStaticProps(context) { + const path = await drupal.translatePathFromContext(context) + + const node = await drupal.getResourceFromContext(path, context) + + return { + props: { + node, + }, + } +} +``` + +- If you pass in a `string` inout, such as `node--article`, `getResourceFromContext` will make a subrequest call to Drupal to translate the path and then fetch the resource. + + You will need both the [Subrequests](https://drupal.org/project/subrequests) and [Decoupled Router](https://drupal.org/project/decoupled_router) modules. + +```ts +export async function getStaticProps(context) { + const node = await drupal.getResourceFromContext("node--article", context) + + return { + props: { + node, + }, + } +} +``` + +--- + +## Examples + +- Fetch a resource from context. + +```ts title=pages/[[...slug]].tsx +export async function getStaticProps(context) { + const node = await drupal.getResourceFromContext("node--page", context) + + return { + props: { + node, + }, + } +} +``` + +- Fetch a resource from context in a sub directory. + +```ts title=pages/articles/[[...slug]].tsx +export async function getStaticProps(context) { + const node = await drupal.getResourceFromContext("node--page", context, { + pathPrefix: "/articles", + }) + + return { + props: { + node, + }, + } +} +``` + +--- + +## TypeScript + +- Using `DrupalNode` for a node entity type. + +```ts +import { DrupalNode } from "next-drupal" + +const node = await drupal.getResourceFromContext( + "node--page", + context +) +``` + +- Using `DrupalTaxonomyTerm` for a taxonomy term entity type. + +```ts +import { DrupalTaxonomyTerm } from "next-drupal" + +const term = await drupal.getResourceFromContext( + "taxonomy_term--tags", + context +) +``` + +See the [TypeScript docs](/docs/typescript) for more built-in types. diff --git a/www/content/docs/reference/getsearch.mdx b/www/content/docs/reference/getsearch.mdx index 146659f2d..4eef21ad3 100644 --- a/www/content/docs/reference/getsearch.mdx +++ b/www/content/docs/reference/getsearch.mdx @@ -18,7 +18,6 @@ const resources = await drupal.getSearchIndex( deserialize, locale, defaultLocale, - next } ): Promise ``` @@ -35,11 +34,6 @@ const resources = await drupal.getSearchIndex( - `deserialize: boolean`: Set to false to return the raw JSON:API response. - `locale: string`: The locale to fetch the view in. - `defaultLocale: string`: The default locale of the site. - - `next: NextFetchRequestConfig` - - Set the `revalidate` option in seconds to configure [Time-based revalidation](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#time-based-revalidation). - Ex: `next: { revalidate: 3600 } // revalidate resource every hour` - - Set the `tags` option to confiure [Tag-based On demand revalidation](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#on-demand-revalidation). - Ex: `next: { tags: ['resource-tag'] }` --- diff --git a/www/content/docs/reference/getstaticpathsfromcontext.mdx b/www/content/docs/reference/getstaticpathsfromcontext.mdx new file mode 100644 index 000000000..a0b7d4af7 --- /dev/null +++ b/www/content/docs/reference/getstaticpathsfromcontext.mdx @@ -0,0 +1,59 @@ +--- +title: getStaticPathsFromContext +excerpt: Return paths for getStaticPaths. +--- + +```ts +const paths = await drupal.getStaticPathsFromContext( + types, + context, + options?: { + params, + withAuth, + pathPrefix, + } +): Promise["paths"]> +``` + +- `types: string | string[]` + - **Required** + - The resource types. Example: `node--article` or `["taxonomy_term--tags", "user--user"]`. +- `context: GetStaticPathsContext` + - **Required** + - The context from `getStaticPaths`. +- `options` + - Optional + - `params: JsonApiParams`: JSON:API params such as `filter`, `fields`, `include` or `sort`. + - `withAuth: boolean | NextDrupalAuth`: + - Set the authentication method to use. See the [authentication docs](/docs/authentication). + - Set to `true` to use the authentication method configured on the client. + - `pathPrefix: string`: Set the pathPrefix if you're calling from a subdir. Example: for `/articles/[...slug].tsx`, use `pathPrefix: "/articles"`. + +--- + +## Examples + +- Return static paths for `node--page` resources. + +```ts +export async function getStaticPaths(context) { + return { + paths: await drupal.getStaticPathsFromContext("node--page", context), + fallback: "blocking", + } +} +``` + +- Return static paths for `node--page` and `node--article` resources. + +```ts +export async function getStaticPaths(context) { + return { + paths: await drupal.getStaticPathsFromContext( + ["node--page", "node--article"], + context + ), + fallback: "blocking", + } +} +``` diff --git a/www/content/docs/reference/getview.mdx b/www/content/docs/reference/getview.mdx index d1a337156..f16eddeb6 100644 --- a/www/content/docs/reference/getview.mdx +++ b/www/content/docs/reference/getview.mdx @@ -18,7 +18,6 @@ const view = await drupal.getView( deserialize, locale, defaultLocale, - next } ): Promise> ``` @@ -35,11 +34,6 @@ const view = await drupal.getView( - `deserialize: boolean`: Set to false to return the raw JSON:API response. - `locale: string`: The locale to fetch the view in. - `defaultLocale: string`: The default locale of the site. - - `next: NextFetchRequestConfig` - - Set the `revalidate` option in seconds to configure [Time-based revalidation](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#time-based-revalidation). - Ex: `next: { revalidate: 3600 } // revalidate resource every hour` - - Set the `tags` option to confiure [Tag-based On demand revalidation](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#on-demand-revalidation). - Ex: `next: { tags: ['resource-tag'] }` --- @@ -63,22 +57,6 @@ const view = await drupal.getView("articles--promoted", { }) ``` -- Get a view with time-based revalidation. - -```ts -const view = await drupal.getView("articles--promoted", { - next: { revalidate: 3600 }, // revalidate every hour` -}) -``` - -- Get a view with tag-based revalidation. - -```ts -const view = await drupal.getView("articles--promoted", { - next: { tags: ["article-view"] }, // revalidates resource when calling `revalidateTag('article-view')` -}) -``` - --- ## TypeScript diff --git a/www/content/docs/reference/preview.mdx b/www/content/docs/reference/preview.mdx new file mode 100644 index 000000000..f5ef8b677 --- /dev/null +++ b/www/content/docs/reference/preview.mdx @@ -0,0 +1,43 @@ +--- +title: preview +excerpt: Handle preview mode for resources. +--- + +```ts +await drupal.preview(request, response, options?: { + errorMessages?: { + secret, + slug, + } +}): Promise +``` + +- `request: NextApiRequest` + - **Required** + - The `request` from an API route. +- `response: NextApiResponse` + - **Required** + - The `response` from an API route. +- `options` + - Optional + - `errorMessages`: + - `secret`: The error message to display for an invalid secret. + - `slug`: The error message to display for an invalid slug. + +--- + +## Notes + +- The `preview` method should be called in an API route. + +--- + +## Examples + +```ts title=pages/api/preview.ts +import { drupal } from "lib/drupal" + +export default async function handler(req, res) { + return await drupal.preview(req, res) +} +``` diff --git a/www/content/docs/reference/translatepath.mdx b/www/content/docs/reference/translatepath.mdx index 0613f510d..38d5b43ed 100644 --- a/www/content/docs/reference/translatepath.mdx +++ b/www/content/docs/reference/translatepath.mdx @@ -8,7 +8,6 @@ const path = await drupal.translatePath( path, options?: { withAuth, - next } ): Promise ``` @@ -21,11 +20,6 @@ const path = await drupal.translatePath( - `withAuth: boolean | NextDrupalAuth`: - Set the authentication method to use. See the [authentication docs](/docs/authentication). - Set to `true` to use the authentication method configured on the client. - - `next: NextFetchRequestConfig` - - Set the `revalidate` option in seconds to configure [Time-based revalidation](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#time-based-revalidation). - Ex: `next: { revalidate: 3600 } // revalidate resource every hour` - - Set the `tags` option to confiure [Tag-based On demand revalidation](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#on-demand-revalidation). - Ex: `next: { tags: ['resource-tag'] }` --- diff --git a/www/content/docs/reference/translatepathfromcontext.mdx b/www/content/docs/reference/translatepathfromcontext.mdx new file mode 100644 index 000000000..3d8d4c9e8 --- /dev/null +++ b/www/content/docs/reference/translatepathfromcontext.mdx @@ -0,0 +1,42 @@ +--- +title: translatePathFromContext +excerpt: Fetch info about a Drupal path from getStaticProps or getServerSideProps context. +--- + +```ts +const path = await drupal.translatePathFromContext( + context, + options?: { + withAuth, + pathPrefix, + } +): Promise +``` + +- `context: GetStaticPropsContext | GetServerSidePropsContext` + - **Required** + - The context from `getStaticProps` or `getServerSideProps`. +- `options` + - Optional + - `withAuth: boolean | NextDrupalAuth`: + - Set the authentication method to use. See the [authentication docs](/docs/authentication). + - Set to `true` to use the authentication method configured on the client. + - `pathPrefix: string`: Set the pathPrefix if you're calling from a subdir. Example: for `/articles/[...slug].tsx`, use `pathPrefix: "/articles"`. + +--- + +## Notes + +- The [Decoupled Router](https://drupal.org/project/decoupled_router) module is required. + +--- + +## Examples + +- Get info about a path from `getStaticProps` context. + +```ts +export async function getStaticProps(context) { + const path = await drupal.translatePathFromContext(context) +} +``` diff --git a/www/content/docs/serializer.mdx b/www/content/docs/serializer.mdx new file mode 100644 index 000000000..5596fa09d --- /dev/null +++ b/www/content/docs/serializer.mdx @@ -0,0 +1,32 @@ +--- +title: Serializer +excerpt: Using a custom serializer with DrupalClient. +--- + +The `NextDrupalPages` uses [jsona](https://github.com/olosegres/jsona) as the default serializer for serializing and deserializing JSON:API data. + +You can provide your own using the [`serializer`](/docs/client/configuration#serializer) option. + +--- + +## Example + +Here's how you can replace the default serializer with [jsonapi-serializer](https://github.com/SeyZ/jsonapi-serializer). + +```ts title=lib/drupal.ts +import { NextDrupalPages } from "next-drupal" +import { Deserializer } from "jsonapi-serializer" + +// Create a custom serializer. +const customSerializer = new Deserializer({ + keyForAttribute: "camelCase", +}) + +// Pass the custom serializer to the client. +export const drupal = new NextDrupalPages( + process.env.NEXT_PUBLIC_DRUPAL_BASE_URL, + { + serializer: customSerializer, + } +) +``` diff --git a/www/content/tutorials/draft-mode/create-site.mdx b/www/content/tutorials/draft-mode/create-site.mdx index 000616f19..8dc4cfe72 100644 --- a/www/content/tutorials/draft-mode/create-site.mdx +++ b/www/content/tutorials/draft-mode/create-site.mdx @@ -5,7 +5,7 @@ weight: 105 group: Draft Mode --- -Start by creating a Next.js site so that we can render the draft on Drupal. +Start by creating a Next.js site so that we can render the draft in Drupal. 1. Visit `/admin/config/services/next`. 2. Click **Add Next.js site**. diff --git a/www/content/tutorials/on-demand-revalidation/configure-entity-types.mdx b/www/content/tutorials/on-demand-revalidation/configure-entity-types.mdx index 79d463919..3cbc86819 100644 --- a/www/content/tutorials/on-demand-revalidation/configure-entity-types.mdx +++ b/www/content/tutorials/on-demand-revalidation/configure-entity-types.mdx @@ -5,16 +5,6 @@ weight: 350 group: On-demand Revalidation --- - - Next, we need to configure on-demand revalidation for the entity types. To enable on-demand revalidation for an entity type, we need to configure a **revalidator** plugin. diff --git a/www/content/tutorials/quick-start/index.mdx b/www/content/tutorials/quick-start/index.mdx index 3c719d080..205ce5de0 100644 --- a/www/content/tutorials/quick-start/index.mdx +++ b/www/content/tutorials/quick-start/index.mdx @@ -5,7 +5,7 @@ weight: 10 group: Quick Start --- -This tutorial will help you get started with Next.js for Drupal using the [`NextDrupal`](/docs/client) and **JSON:API**. +This tutorial will help you get started with Next.js for Drupal using the [`NextDrupal Client`](/docs/client) and **JSON:API**.