diff --git a/docs/components/app/icon/Modules.vue b/docs/components/app/icon/Modules.vue new file mode 100644 index 000000000..7d4370d72 --- /dev/null +++ b/docs/components/app/icon/Modules.vue @@ -0,0 +1,16 @@ + diff --git a/docs/content/guide/README.md b/docs/content/guide/README.md index 08029e764..51b04f82b 100644 --- a/docs/content/guide/README.md +++ b/docs/content/guide/README.md @@ -4,109 +4,42 @@ title: Introduction # DruxtJS -DruxtJS provides an easy connection to your Drupal JSON:API backend in your Nuxt.js frontend application. +## The Fully Decoupled Drupal Framework +### What is Druxt? -## Features +Druxt is a framework for building Fully Decoupled Drupal and Nuxt.js applications and sites. It allows you to leverage the content modelling and management power of Drupal, and build elegant user experiences with Nuxt.js. -- [Nuxt module](#nuxt-module) -- [JSON:API Client](#drupal-json-api-client) - - [DruxtClient](#druxtclient) - - [DruxtStore](#druxtstore) -- [Druxt components](#druxt-components) - - [Modules](#modules) - - [Theming](#theming) +> TL;DR: Druxt = DRUpal + nUXT. +* * * -## Nuxt module +## Getting started -The Druxt module provides Vue.js components, a JSON:API Client, a Vuex store and a Nuxt module, among other things. +### Make Druxt work for you: -The Nuxt module installs all required components and dependencies, however most components can be used individually in any Node project. +- If you want to build a fully decoupled Drupal site, see [Getting started with DruxtSite](/modules/site/getting-started). +- If you want to build a Nuxt application with Druxt modules, see [Getting started with Druxt](/guide/getting-started). +- If you want to use Druxt internals in your Node application, check out the [API Documentation](/api). -```js -module.exports = { - modules: ['druxt'], - druxt: { baseUrl: 'https://demo-api.druxtjs.org' }, -} -``` +* * * -See [Getting started](/guide/getting-started) and the [API documentation](/api) for more details. +## Modules +Druxt is built on two frameworks, Drupal and Nuxt.js, both with their own modules which can be used alongside Druxt modules. -## Drupal JSON:API client +Druxt modules provide Nuxt modules, plugins, components and more to bridge the gap and make Decoupled development easier. -Two methods of communication with the Drupal JSON:API are provided by Druxt, the **DruxtClient** and the **DruxtStore**. +- For Druxt modules, see the [Druxt modules list](/modules). +- For Drupal modules, see the [Drupal modules list](https://www.drupal.org/project/project_module). +- For Nuxt modules, see the [Nuxt modules list](https://modules.nuxtjs.org/). -### DruxtClient +* * * -The **DruxtClient** is a framework agnostic class, allowing access to Drupal's JSON:API resources and collections in your Node.js application. +## Theming Druxt components -**Example:** _Retrieve a collection of Page Node resources._ -```js -const { DruxtClient } = require('druxt') -new DruxtClient('https://demo-api.druxtjs.org') - .getCollection('node--page') - .then((res) => { - // Do the thing! - }) -``` +> Druxt is like a Vue.js theme layer for Drupal. -Get started with the [Guide](/guide/client) and [API Documentation](/api/packages/druxt/client). +Druxt components can be themed using **Wrapper components** alongside Vue.js **slots**, **$attrs** and **props**. -### DruxtStore - -The **DruxtStore** is a Vuex module that provides the **DruxtClient** with a caching layer, only requesting data from Drupal where it's not already available in the store. - -**Example:** _Retrieve a Page Node resources._ -```vue - -``` - -The DruxtStore is installed via the Nuxt module, see [getting started](/guide/getting-started). - -## Druxt components - -Druxt provides a Vue.js component system for easy access Drupal's JSON:API data, with a simple Slot based theming system. - -### Modules - -Druxt has a growing list of modules, providing access to different Drupal powered functionality. - -A module can be invoked either by setting the `module` and `props-data` properties of the `` component, or by using the module's component directly. - -_**Example:** Using the [DruxtEntity module](https://entity.druxtjs.org) to render a 'node--article' resource._ - -```vue - -``` - -```vue - -``` - -See the [Druxt module list](/guide/modules) for more information. - - -### Theming - -Druxt modules use a slot-based Wrapper component system to provide rich defaults while still allowing full control over all theming and functionality. - -See the [theming guide](/guide/theming) for more details. +* For more details, see the [Theming guide](/guide/theming). diff --git a/docs/content/guide/modules.md b/docs/content/guide/modules.md deleted file mode 100644 index 11f2fdac0..000000000 --- a/docs/content/guide/modules.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: Modules ---- - -# Modules - -Druxt has a growing list of modules, providing access to different Drupal powered functionality. - -- [DruxtBlocks](#druxtblocks) -- [DruxtBreadcrumb](#druxtbreadcrumb) -- [DruxtEntity](#druxtentity) -- [DruxtMenu](#druxtmenu) -- [DruxtRouter](#druxtrouter) -- [DruxtSchema](#druxtschema) -- [DruxtSite](#druxtsite) -- [DruxtViews](#druxtviews) - - -## DruxtBlocks - -The DruxtBlock module adds the ability to render Drupal Blocks and all blocks within a given Block region. - -```vue - -``` - -```vue - -``` - -![Example DruxtBlockRegion component](/images/druxt-block-region.png) - -See [blocks.druxtjs.org](https://blocks.druxtjs.org) for more details. - - -## DruxtBreadcrumb - -The DruxtBreadcrumb module uses hierarchical path data from the DruxtRouter module to render a themable breadcrumb. - -```vue - -``` - -See [breadcrumb.druxtjs.org](https://breadcrumb.druxtjs.org) for more details. - - -## DruxtEntity - -The DruxtEntity module uses the Drupals Display mode and formatter configuration to render Entities, Entity forms and fields. - -```vue - -``` - -![Example DruxtEntity component](/images/druxt-entity.png) - -```vue - -``` - -![Example DruxtEntityForm component](/images/druxt-entity-form.png) - -See [entity.druxtjs.org](https://entity.druxtjs.org) for more details. - - -## DruxtMenu - -The DruxtMenu module adds support for full Drupal menus via the Drupal [JSON:API Menu items](https://www.drupal.org/project/jsonapi_menu_items) module. - -```vue - -``` - -See [menu.druxtjs.org](https://menu.druxtjs.org) for more details. - - -## DruxtRouter - -The DruxtRouter module communicates with the Drupal [Decoupled Router](https://www.drupal.org/project/decoupled_router) module and serves the requested resource components. - -See [router.druxtjs.org](https://router.druxtjs.org) for more details. - - -## DruxtSchema - -The DruxtSchema module builds View and Form Field schema files that are used by the DruxtEntity module to render entities using Drupal's Display mode system. - -See [schema.druxtjs.org](https://schema.druxtjs.org) for more details. - - -## DruxtSite - -The DruxtJS Site module provides a simple out of the box, decoupled Drupal site experience. - -```vue - -``` - -![Example DruxtSite](/images/druxt-site-umami.png) - -See [site.druxtjs.org](https://site.druxtjs.org) for more details. - - -## DruxtViews - -The DruxtViews adds support for Drupal Views via the [JSON:API Views](https://www.drupal.org/project/jsonapi_views). - -```vue - -``` - -See [views.druxtjs.org](https://views.druxtjs.org) for more details. diff --git a/docs/content/guide/storybook.md b/docs/content/guide/storybook.md new file mode 100644 index 000000000..9c72c9539 --- /dev/null +++ b/docs/content/guide/storybook.md @@ -0,0 +1,31 @@ +--- +title: Storybook +--- + +> Druxt provides zero-config, auto generated Storybook integration with live data. + +![DruxtBlocks Storybook integration](/images/druxt-block-storybook.png) + +## Features + +* Access to Druxt components, modules, stores and more within Storybook. +* Auto-generated stories based on live data. +* Support for **Blocks**, **Entities**, **Menus** and **Views**. + +* * * + +## Getting started + +1. Install the [Nuxt Storybook module](https://storybook.nuxtjs.org). + + ```sh + npm i @nuxtjs/storybook + ``` + +2. Run Storybook: + + ```sh + npx nuxt storybook + ``` + +* * * diff --git a/docs/content/guide/theming.md b/docs/content/guide/theming.md index 55ab4b252..be56ec4a1 100644 --- a/docs/content/guide/theming.md +++ b/docs/content/guide/theming.md @@ -22,7 +22,7 @@ Component options can be seen on the `component.options` property of the Druxt m If there are no matching component names, a default `DruxtWrapper` component will be used to render the default output of the module. -See the [DruxtModule API documentation](/api/components/DruxtModule). +See the [DruxtModule API documentation](/api/packages/druxt/components/DruxtModule). ```vue diff --git a/docs/content/modules/README.md b/docs/content/modules/README.md new file mode 100644 index 000000000..e78f15ad9 --- /dev/null +++ b/docs/content/modules/README.md @@ -0,0 +1,7 @@ +--- +title: Druxt modules +--- + +Druxt is built on two frameworks, Drupal and Nuxt, both with their own modules which can be used alongside Druxt modules. + +Druxt modules provide Nuxt modules, plugins, components and more to bridge the gap and make Decoupled development easier. \ No newline at end of file diff --git a/docs/content/modules/blocks/README.md b/docs/content/modules/blocks/README.md new file mode 100644 index 000000000..14671ebf7 --- /dev/null +++ b/docs/content/modules/blocks/README.md @@ -0,0 +1,95 @@ +--- +title: Blocks +description: Drupal Block and Block Region Druxt components. +--- + +![Example DruxtBlockRegion component](/images/druxt-block-region.png) + + +## Features + +- Vue.js components: + - **DruxtBlock**: Render Drupal blocks by UUID or internal ID + - **DruxtBlockRegion**: Render all blocks within a region +- **Druxt settings**: Filter JSON:API fields +- **@nuxtjs/Storybook** integration + +* * * + +## Installation + +1. Download the module: + ```sh + npm i druxt-blocks + ``` + +2. Add the module to `nuxt.config.js`: + ```js + export default { + modules: ['druxt-blocks'], + } + ``` + +* * * + +## Vue.js components + +### DruxtBlock + +Renders a Drupal Block by UUID or Drupal's internal ID. + +```vue + +``` + +```vue + +``` + +- For more details, refer to the [DruxtBlock API documentation](/api/packages/blocks/components/DruxtBlock). + + +### DruxtBlockRegion + +Renders all visible blocks by theme and region name. + +```vue + +``` + +![Example DruxtBlockRegion component](/images/druxt-block-region.png) + +- For more details, refer to the [DruxtBlockRegion API documentation](/api/packages/blocks/components/DruxtBlockRegion). + +* * * + +## Settings + +### Reducing Block data + +The default behaviour of the Block module is to retrieve all available fields from the JSON:API. + +This behaviour is configurable using the modules `query` option, allowing for manually filtered `fields`. + +The default behaviour can be set via `nuxt.config.js`: +```js +druxt: { + blocks: { + query: { + fields: ['dependencies'], + }, + }, +} +``` + +* * * + +## Storybook + +DruxtBlocks provides zero-config, auto generated Storybook integration with a live data connnection to your Druxt backend. + +![DruxtBlocks Storybook integration](/images/druxt-block-storybook.png) + +- For more details, see the [Storybook guide](/guide/storybook). + +* * * diff --git a/docs/content/modules/breadcrumb/README.md b/docs/content/modules/breadcrumb/README.md new file mode 100644 index 000000000..fb2502985 --- /dev/null +++ b/docs/content/modules/breadcrumb/README.md @@ -0,0 +1,42 @@ +--- +title: Breadcrumb +description: Decoupled Router based Breadcrumb Druxt component. +--- + +![Example DruxtBreadcrumb component](/images/druxt-breadcrumb.png) + +## Features +- Vue.js components: + - **DruxtBreadcrumb**: Render Drupal breadcrumbs by route + +* * * + +## Installation + +1. Download the module: + ```sh + npm i druxt-breadcrumb + ``` + +2. Add the module to `nuxt.config.js`: + ```js + export default { + modules: ['druxt-breadcrumb'], + } + ``` + +* * * + +## Vue.js components + +### DruxtBreadcrumb + +Renders a list of breacrumbs based on the active route. + +```vue + +``` + +- For more details, refer to the [DruxtBreadcrumb API documentation](/api/packages/breadcrumb/components/DruxtBreadcrumb). + +* * * diff --git a/docs/content/modules/entity/README.md b/docs/content/modules/entity/README.md new file mode 100644 index 000000000..28ab08f9f --- /dev/null +++ b/docs/content/modules/entity/README.md @@ -0,0 +1,123 @@ +--- +title: Entity +description: Drupal Display Mode powered Entity, Form and Field Druxt components. +--- + +![Example DruxtEntity component](/images/druxt-entity.png) + +## Features + +- Vue.js components: + - **DruxtEntity**: Render a Drupal Content Entity by UUID + - **DruxtEntityForm**: Render a Drupal Content Entity form +- **Druxt settings**: Filter JSON:API fields +- **Druxt Router** integration +- **@nuxtjs/Storybook** integration + +* * * + +## Installation + +1. Download the module: + ```sh + npm i druxt-entity + ``` + +2. Add the module to `nuxt.config.js`: + ```js + export default { + modules: ['druxt-entity'], + } + ``` + +* * * + +## Vue.js Components + +### DruxtEntity + +Renders a Drupal Content Entity by JSON:API resource type, UUID, view mode and schema type. + +Fields are rendered as [DruxtField](/api/packages/entity/components/DruxtField) components, based on the Drupal display mode configuration. + +```vue + +``` + +- For more details, refer to the [DruxtEntity component API documentation](/api/packages/entity/components/DruxtEntity). + +### DruxtEntityForm + +Renders a Drupal Content Entity form with submission and validation support. + +```vue + +``` + +![Example DruxtEntityForm component](/images/druxt-entity-form.png) + +- For more details, refer to the [DruxtEntityForm component API documentation](/api/packages/entity/components/DruxtEntityForm). + +* * * + +## Settings + +### Reducing Entity data + +The default behaviour of the Entity module is to retrieve all available fields from the JSON:API. + +This behaviour is configurable using the modules `query` option, allowing for both manually filtered `fields`, automatically filtered fields using the Display mode `schema`, and a combination of the two as required. + +The default behaviour can be set via `nuxt.config.js`: +```js +druxt: { + entity: { + query: { + fields: ['path', 'title'], + schema: true, + }, + }, +} +``` + +Alternatively, the behaviour can be set directly on an Entity Wrapper component: +```vue + +``` + +* * * + +## Router support + +The DruxtEntity module provides a **DruxtRouterEntity** component that is used by the Druxt Router module to render a Content Entity route. + +- For more details, see the [Druxt Router module](/modules/router). + +* * * + +## Storybook + +DruxtEntity provides zero-config, auto generated Storybook integration with a live data connnection to your Druxt backend. + +- For more details, see the [Storybook guide](/guide/storybook). + +* * * diff --git a/packages/entity/docs/guide/deprecations.md b/docs/content/modules/entity/deprecations.md similarity index 100% rename from packages/entity/docs/guide/deprecations.md rename to docs/content/modules/entity/deprecations.md diff --git a/docs/content/modules/menu/README.md b/docs/content/modules/menu/README.md new file mode 100644 index 000000000..33a2be831 --- /dev/null +++ b/docs/content/modules/menu/README.md @@ -0,0 +1,98 @@ +--- +title: Menu +description: Drupal Menu and Menu item Druxt components, with support for the JSON:API Menu Items module. +--- + +![Example DruxtMenu component](/images/druxt-menu.png) + +## Features + +- Vue.js components: + - **DruxtMenu**: Render Drupal menu by name +- **Druxt settings**: Filter JSON:API fields +- **Drupal Menu blocks** +- **@nuxtjs/Storybook** integration + +* * * + +## Installation + +1. Download the module: + ```sh + npm i druxt-menu + ``` + +2. Add the module to `nuxt.config.js`: + ```js + export default { + modules: ['druxt-menu'], + } + ``` + +* * * + +## Vue.js Components + +### DruxtMenu + +Renders a Drupal menu using either the default Drupal content menus, or the full menu via the [JSON:API Menu Items](https://www.drupal.org/project/jsonapi_menu_items) module. + +```vue + +``` + +- For more details, refer to the [DruxtMenu API documentation](/api/packages/menu/components/DruxtMenu). + +* * * + +## Settings + +### Reducing JSON:API data + +The default behaviour of the Menu module is to retrieve all available fields from the JSON:API. + +This behaviour is configurable using the modules `query` option, allowing for manually filtered `fields` or automatically filtered fields using the `requiredOnly` option. + +The default behaviour can be set via `nuxt.config.js`: +```js +druxt: { + menu: { + query: { + fields: [], + requiredOnly: true, + }, + }, +} +``` + +Alternatively, the behaviour can be set directly on a Menu wrapper component: +```vue + +``` + +* * * + +## Menu blocks + +The DruxtMenu module provides a **DruxtBlockSystemMenuBlock** component that is used by the Druxt Block module to render Drupal menu blocks. + +- For more details, see the [Druxt Blocks module](/modules/blocks). + +* * * + +## Storybook + +DruxtMenu provides zero-config, auto generated Storybook integration with a live data connnection to your Druxt backend. + +- For more details, see the [Storybook guide](/guide/storybook). + +* * * diff --git a/docs/content/modules/router/README.md b/docs/content/modules/router/README.md new file mode 100644 index 000000000..bc04fd42a --- /dev/null +++ b/docs/content/modules/router/README.md @@ -0,0 +1,44 @@ +--- +title: Router +description: Drupal router for Nuxt, powered by the Drupal Decoupled Router module. +--- + +## Features + +- Vue.js components: + - **DruxtRouter**: Renders a Druxt component for the resolved Decoupled route +- Route providers: + - **Content entity** routes resolve **DruxtEntity** components + - **Drupal Views** page routes resolve **DruxtView** components + +* * * + +## Installation + +1. Download the module: + ```sh + npm i druxt-router + ``` + +2. Add the module to `nuxt.config.js`: + ```js + export default { + modules: ['druxt-router'], + } + ``` + +* * * + +## Vue.js components + +### DruxtRouter + +Renders a Druxt module router component based on the resolved route provided by the Drupal Decoupled Router module. + +```vue + +``` + +- For more details, refer to the [DruxtBlock API documentation](/api/packages/router/components/DruxtRouter). + +* * * diff --git a/docs/content/modules/schema/README.md b/docs/content/modules/schema/README.md new file mode 100644 index 000000000..63bdba8df --- /dev/null +++ b/docs/content/modules/schema/README.md @@ -0,0 +1,57 @@ +--- +title: Schema +description: Drupal Content Entity schema generator for Druxt with support for View and Form displays. +--- + +The Schema module uses the Drupal's Display mode configuration JSON:API data to build a Vuex Schema store. + +## Features + +- **Generates schemas on build** +- **Configurable schema filter** +- **View and Form schemas** + +* * * + +## Installation + +1. Download the module: + ```sh + npm i druxt-schema + ``` + +2. Add the module to `nuxt.config.js`: + ```js + export default { + modules: ['druxt-schema'], + } + ``` + +* * * + +## Settings + +### Filter schemas + +The Schema module will generate a schema for all available content entity type by bundle, display mode and schema type. + +This generated schemas can be filtered by providing a `druxt.schema.filter` setting in the `nuxt.config.js` file: + +```js +export default { + modules: ['druxt-schema'], + druxt: { + schema: { + filter: [ + // List specific schema files to generate. + 'node--page--default--view', + 'media--image--square--view', + // Or use a regular expression. + '.*?--form', + ] + } + } +} +``` + +* * * diff --git a/docs/content/modules/site/README.md b/docs/content/modules/site/README.md new file mode 100644 index 000000000..4215a62b1 --- /dev/null +++ b/docs/content/modules/site/README.md @@ -0,0 +1,48 @@ +--- +title: Site +description: Out of the box Decoupled Drupal sites with Druxt. +--- + +![Drupal Umami Parity demo](/images/umami.png) + +Using Drupal's built in Entity display modes and Field formatter system, Views, Blocks and more, the Druxt Site module provides the out of the box experience you expect. + + +## Features + +- **Router** with path alias and redirect support for Entity and Views pages. +- **Vuex** based, on-demand JSON:API resource loading. +- **Entity / Field** render system powered by Drupal display modes. +- **Block** region and **Content block** component rendering. +- **Views** and **Views blocks** via the [Drupal JSON:API Views module](https://www.drupal.org/project/jsonapi_views). +- **Breadcrumb**, **Menus** and more. + +* * * + +## Installation + +1. Download the module: + ```sh + npm i druxt-site + ``` + +2. Add the module to `nuxt.config.js`: + ```js + export default { + modules: ['druxt-site'], + } + ``` + +* * * + +## Vue.js components + +### DruxtSite + +Renders all available block regions based on the specified theme. + +```vue + +``` + +- For more details, refer to the [DruxtSite API documentation](/api/packages/site/components/DruxtSite). diff --git a/docs/content/modules/site/getting-started.md b/docs/content/modules/site/getting-started.md new file mode 100644 index 000000000..0e5831f29 --- /dev/null +++ b/docs/content/modules/site/getting-started.md @@ -0,0 +1,91 @@ +--- +title: Getting started with DruxtSite +--- + +> Druxt is a Fully Decoupled Drupal framework. + +The DruxtSite module gives you an out-of-the-box Drupal site experience with a Nuxt.js frontend. + +Think of the DruxtSite module as a distribution of Drupal, Nuxt and Druxt to provide Vue.js theme layer for Drupal. + +* * * + +## Quickstart - GitPod + +Try out a pre-installed, pre-configured DruxtSite install with GitPod. + +[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/druxt/quickstart-druxt-site) + + +* * * + +## Getting started + +All Druxt sites need both Drupal (backend) and Nuxt (frontend) to be installed. + +Each codebase can live in it's own directory within a single repository, or exist in seperate repositories. + +* For an example of a single repository, see the [Quickstart DruxtSite repository](https://github.com/druxt/quickstart-druxt-site). +* For an example of individual repositories, see: + * [Umami demo Nuxt repository](https://github.com/druxt/demo.druxtjs.org) + * [Umami demo Drupal repository](https://github.com/druxt/demo-api.druxtjs.org) + +* * * + +### Drupal + +1. [Install Drupal](https://www.drupal.org/docs/installing-drupal) + +2. Download the Drupal [Druxt module](https://www.drupal.org/project/druxt): + + ```sh + composer require drupal/druxt + ``` + +3. Install the module: + ![Install the module](/images/drupal-install.png) + +4. Add the "**access druxt resources**" permission to a user/role: + ![Install the module](/images/drupal-permissions.png) + +5. Enable and configure **CORS** in the your sites `services.yml` file. + +* * * + +## Nuxt + +1. [Install Nuxt](https://nuxtjs.org/guide/installation/) + + ```sh + npx create-nuxt-app [destination] + ``` + +2. Install the Site module: + + ```sh + npm i druxt-site + ``` + +3. Add the module and configuration to `nuxt.config.js`: + + ```js + module.exports = { + modules: [ + 'druxt-site' + ], + + druxt: { + baseUrl: 'https://demo-api.druxtjs.org' + } + } + ``` + + \* _**Note:** Replace `https://demo-api.druxtjs.org` with your own Drupal backend._ + +4. Add the `DruxtSite` component to your page or layout: + + ```vue +