strapi-plugin-navigation 2.0.12 → 2.0.13

package/README.md

@@ -36,6 +36,21 @@ Strapi Navigation Plugin provides a website navigation / menu builder feature fo
 - Tree (nested)
 - RFR (ready for handling by Redux First Router)
 
+### Table of Contents
+1. [✨ Features](#-features)
+2. [⏳ Installation](#-installation)
+3. [🖐 Requirements](#-requirements)
+4. [🔧 Basic Configuration](#-configuration)
+   - [Settings page](#in-v203-and-newer)
+   - [Plugin file](#in-v202-and-older--default-configuration-state-for-v203-and-newer)
+5. [🔧 GraphQL Configuration](#-gql-configuration)
+6. [🕸️ Public API specification](#%EF%B8%8F-public-api-specification)
+   - [REST API](#rest-api) 
+   - [GraphQL API](#graphql-api)
+8. [💬 FAQ](#-faq)
+9. [🤝 Contributing](#-contributing)
+10. [👨‍💻 Community support](#-community-support)
+
 ## ✨ Features
 
 - **Navigation Public API:** Simple and ready for use API endpoint for consuming the navigation structure you've created
@@ -43,6 +58,7 @@ Strapi Navigation Plugin provides a website navigation / menu builder feature fo
 - **Any Content Type relation:** Navigation can by linked to any of your Content Types by default. Simply, you're controlling it and also limiting available content types by configuration props
 - **Different types of navigation items:** Create navigation with items linked to internal types, to external links or wrapper elements to keep structure clean 
 - **Multiple navigations:** Create as many Navigation containers as you want, setup them and use in the consumer application
+- **Light / Dark mode compatible:** By design we're supporting Strapi ☀️ Light / 🌙 Dark modes 
 - **Customizable:** Possibility to customize the options like: available Content Types, Maximum level for "attach to menu", Additional fields (audience)
 - **[Audit log](https://github.com/VirtusLab/strapi-molecules/tree/master/packages/strapi-plugin-audit-log):** integration with Strapi Molecules Audit Log plugin that provides changes track record
 
@@ -53,13 +69,23 @@ Strapi Navigation Plugin provides a website navigation / menu builder feature fo
 
 ## ⏳ Installation
 
+### Via Strapi Markerplace
+
+As a ✅ **verified** plugin by Strapi team we're available on the [**Strapi Marketplace**](https://market.strapi.io/plugins/strapi-plugin-navigation) as well as **In-App Marketplace** where you can follow the installation instructions.
+
+<div style="margin: 20px 0" align="center">
+  <img style="width: 100%; height: auto;" src="public/assets/marketplace.png" alt="Strapi In-App Marketplace" />
+</div>
+
+### Via command line
+
 It's recommended to use **yarn** to install this plugin within your Strapi project. [You can install yarn with these docs](https://yarnpkg.com/lang/en/docs/install/).
 
 ```bash
 yarn add strapi-plugin-navigation@latest
 ```
 
-After successful installation you've to build a fresh package that includes  plugin UI. To archive that simply use:
+After successful installation you've to re-build your Strapi instance. To archive that simply use:
 
 ```bash
 yarn build
@@ -74,7 +100,9 @@ yarn develop --watch-admin
 
 The **UI Navigation** plugin should appear in the **Plugins** section of Strapi sidebar after you run app again.
 
-Enjoy 🎉
+As a next step you must configure your the plugin by the way you want to. See [**Configuration**](#🔧-configuration) section.
+
+All done. Enjoy 🎉
 
 ## 🖐 Requirements
 
@@ -82,7 +110,7 @@ Complete installation requirements are exact same as for Strapi itself and can b
 
 **Supported Strapi versions**:
 
-- Strapi v4.1.5 (recently tested)
+- Strapi v4.1.8 (recently tested)
 - Strapi v4.x
 
 > This plugin is designed for **Strapi v4** and is not working with v3.x. To get version for **Strapi v3** install version [v1.x](https://github.com/VirtusLab-Open-Source/strapi-plugin-navigation/tree/strapi-v3).
@@ -91,9 +119,17 @@ Complete installation requirements are exact same as for Strapi itself and can b
 
 ## 🔧 Configuration
 
+To start your journey with **Navigation plugin** you must first setup it using the dedicated Settings page (`v2.0.3` and newer) or for any version, put your configuration in `config/plugins.js`. Anyway we're recommending the click-through option where your configuration is going to be properly validated.
+
 ### In `v2.0.3` and newer
 
-Version `2.0.3` introduces the intuitive **Settings** page which you can easily access via `Strapi Settings -> Section: Navigation Plugin -> Configuration`. On the dedicated page, you will be able to set up all crucial properties which drive the plugin and customize each individual collection for which **Navigation plugin** should be enabled.
+Version `2.0.3` introduces the intuitive **Settings** page which you can easily access via `Strapi Settings -> Section: Navigation Plugin -> Configuration`. 
+
+On the dedicated page, you will be able to set up all crucial properties which drive the plugin and customize each individual collection for which **Navigation plugin** should be enabled.
+
+<div style="margin: 20px 0" align="center">
+  <img style="width: 100%; height: auto;" src="public/assets/configuration.png" alt="Plugin configuration" />
+</div>
 
 > *Note*
 > The default configuration for your plugin is fetched from `config/plugins.js` or, if the file is not there, directly from the plugin itself. If you would like to customize the default state to which you might revert, please follow the next section.
@@ -169,7 +205,7 @@ For any role different than **Super Admin**, to access the **Navigation panel**
 ## Base Navigation Item model
 
 ### Flat
-```
+```json
 {
     "id": 1,
     "title": "News",
@@ -182,13 +218,13 @@ For any role different than **Super Admin**, to access the **Navigation panel**
     "master": 1, // Navigation 'id'
     "createdAt": "2020-09-29T13:29:19.086Z",
     "updatedAt": "2020-09-29T13:29:19.128Z",
-    "related": [ <Content Type model > ],
+    "related": {/*<Content Type model >*/ },
     "audience": []
 }
 ```
 
 ### Tree
-```
+```json
 {
     "title": "News",
     "menuAttached": true,
@@ -198,7 +234,7 @@ For any role different than **Super Admin**, to access the **Navigation panel**
     "slug": "benefits",
     "external": false,
     "related": {
-        <Content Type model >
+        // <Content Type model >
     },
     "items": [
         {
@@ -209,13 +245,13 @@ For any role different than **Super Admin**, to access the **Navigation panel**
             "uiRouterKey": "generic",
             "external": true
         },
-        < Tree Navigation Item models >
+       //  < Tree Navigation Item models >
     ]
 }
 ```
 
 ### RFR
-```
+```json
 {
     "id": "News",
     "title": "News",
@@ -234,33 +270,41 @@ For any role different than **Super Admin**, to access the **Navigation panel**
 
 ## 🕸️ Public API specification
 
-### Query Params 
+Plugin supports both **REST API** and **GraphQL API** exposed by Strapi.
 
-- `type` - Enum value representing structure type of returned navigation 
+**Query Params**
 
-    **Example URL**: `https://localhost:1337/api/navigation/render/1?type=FLAT`
+- `navigationIdOrSlug` - ID or slug for which your navigation structure is generated like for REST API:
 
-- `menu` - Boolean value for querying only navigation items that are attached to menu should be rendered eg.
+  > `https://localhost:1337/api/navigation/render/1`
+  > `https://localhost:1337/api/navigation/render/main-menu`
 
-    **Example URL**: `https://localhost:1337/api/navigation/render/1?menu=true`
+- `type` - Enum value representing structure type of returned navigation:
+  > `https://localhost:1337/api/navigation/render/1?type=FLAT`
 
-- `path` - String value for querying navigation items by its path 
+- `menu` (`menuOnly` for GQL) - Boolean value for querying only navigation items that are attached to menu should be rendered eg.
+  > `https://localhost:1337/api/navigation/render/1?menu=true`
 
-    **Example URL**: `https://localhost:1337/api/navigation/render/1?path=/home/about-us`
+- `path` - String value for querying navigation items by its path:
+  > `https://localhost:1337/api/navigation/render/1?path=/home/about-us`
 
-### Render
+### REST API
+
+> **Important!**
+> Version `v2.0.13` introduced breaking change!
+> All responses have changed their structure. Related field will now be of type ContentType instead of Array\<ContentType\>
 
-`GET <host>/api/navigation/render/<idOrSlug>?type=<type>`
+`GET <host>/api/navigation/render/<navigationIdOrSlug>?type=<type>`
 
 Return a rendered navigation structure depends on passed type (`tree`, `rfr` or nothing to render as `flat/raw`).
 
-*Note: The ID of navigation by default is `1`, that's for future extensions and multi-navigation feature.*
+> The ID of navigation by default is `1`, if you've got defined multiple navigations you must work with their IDs or Slugs to fetch.
 
 **Example URL**: `https://localhost:1337/api/navigation/render/1`
 
 **Example response body**
 
-```
+```json
 [
     {
         "id": 1,
@@ -274,14 +318,14 @@ Return a rendered navigation structure depends on passed type (`tree`, `rfr` or
         "master": 1,
         "created_at": "2020-09-29T13:29:19.086Z",
         "updated_at": "2020-09-29T13:29:19.128Z",
-        "related": [{
+        "related": {
             "__contentType": "Page",
             "id": 1,
             "title": "News",
-            ...
-        }]
+            // ...
+        }
     },
-    ...
+    // ...
 ]
 ```
 
@@ -289,7 +333,7 @@ Return a rendered navigation structure depends on passed type (`tree`, `rfr` or
 
 **Example response body**
 
-```
+```json
 [
     {
         "title": "News",
@@ -303,7 +347,7 @@ Return a rendered navigation structure depends on passed type (`tree`, `rfr` or
             "__contentType": "Page",
             "id": 1,
             "title": "News",
-            ...
+            // ...
         },
         "items": [
             {
@@ -314,10 +358,10 @@ Return a rendered navigation structure depends on passed type (`tree`, `rfr` or
                 "uiRouterKey": "generic",
                 "external": true
             },
-            ...
+            // ...
         ]
     },
-    ...
+    // ...
 ]
 ```
 
@@ -325,7 +369,7 @@ Return a rendered navigation structure depends on passed type (`tree`, `rfr` or
 
 **Example response body**
 
-```
+```json
 {
     "pages": {
         "News": {
@@ -370,7 +414,7 @@ Return a rendered navigation structure depends on passed type (`tree`, `rfr` or
             "parent": "Community",
             "menuAttached": false
         },
-        ...
+        // ...
     },
     "nav": {
         "root": [
@@ -389,7 +433,7 @@ Return a rendered navigation structure depends on passed type (`tree`, `rfr` or
                 "type": "external",
                 "url": "http://example.com"
             },
-            ...
+            // ...
         ],
         "Community": [
             {
@@ -397,10 +441,98 @@ Return a rendered navigation structure depends on passed type (`tree`, `rfr` or
                 "type": "internal",
                 "page": "Highlights"
             },
-            ...
+            // ...
         ],
-        ...
+        // ...
+    }
+}
+```
+
+### GraphQL API
+
+Same as [**REST API**](#rest-api) returns a rendered navigation structure depends on passed type (`tree`, `rfr` or nothing to render as `flat/raw`).
+
+**Example request**
+
+```graphql
+query {
+  renderNavigation(
+    navigationIdOrSlug: "main-navigation"
+    type: TREE
+    menuOnly: false
+  ) {
+    id
+    title
+    path
+    related {
+      __typename
+
+      ... on Page {
+        Title
+      }
+
+      ... on WithFlowType {
+        Name
+      }
+    }
+    items {
+      id
+      title
+      path
+      related {
+        __typename
+
+        ... on Page {
+          Title
+        }
+
+        ... on WithFlowType {
+          Name
+        }
+      }
     }
+  }
+}
+```
+
+**Example response**
+
+```json
+{
+  "data": {
+    "renderNavigation": [
+      {
+        "id": 8,
+        "title": "Test page",
+        "path": "/test-path",
+        "related": {
+          "__typename": "WithFlowType",
+          "Name": "Test"
+        },
+        "items": [
+          {
+            "id": 11,
+            "title": "Nested",
+            "path": "/test-path/nested-one",
+            "related": {
+              "__typename": "Page",
+              "Title": "Eg. Page title"
+            }
+          }
+        ]
+      },
+      {
+        "id": 10,
+        "title": "Another page",
+        "path": "/another",
+        "related": {
+          "__typename": "Page",
+          "Title": "dfdfdf"
+        },
+        "items": []
+      }
+    ]
+  }
 }
 ```
 
@@ -416,13 +548,22 @@ For single types a global name of this content type will be used as a template n
 
 Live example of plugin usage can be found in the [VirtusLab Strapi Examples](https://github.com/VirtusLab/strapi-examples/tree/master/strapi-plugin-navigation) repository.
 
-## 💬 Q&A
+## 💬 FAQ
+
+### GraphQL tricks
 
-### Content Types
+**Q:** I would like to use GraphQL schemas but I'm not getting renderNavigation query or even proper types as Navigation, NavigationItem etc. What should I do?
 
-**Q:** I've recognized **Navigation Item** and **Navigation** collection types in the Collections sidebar section, but they are not working properly. What should I do?
+**A:** There is a one trick you might try. Strapi by default is ordering plugins by the way which takes `strapi-plugin-graphql` to initialize earlier than other plugins so types might not be injected. If you don't have it yet, please create `config/plugins.js` file and put there at lease following lines:
+
+```js
+module.exports = {
+  'navigation': { enabled: true },
+  'graphql': { enabled: true },
+};
+```
 
-**A:** As an authors of the plugin we're not supporting any editing of mentioned content types via built-in Strapi Content Manager. Plugin delivers highly customized & extended functionality which might be covered only by dedicated editor UI accessible via **Plugins Section > UI Navigation**. Only issues that has been recognized there, are in the scope of support we've providing.
+If you already got it, make sure that `navigation` plugin is inserted before `graphql`. That should do the job.
 
 ## 🤝 Contributing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "strapi-plugin-navigation",
-  "version": "2.0.12",
+  "version": "2.0.13",
   "description": "Strapi - Navigation plugin",
   "strapi": {
     "name": "navigation",
@@ -17,7 +17,7 @@
     "test:unit": "jest --verbose --coverage"
   },
   "dependencies": {
-    "@strapi/utils": "^4.1.5",
+    "@strapi/utils": "^4.1.8",
     "uuid": "^8.3.0",
     "lodash": "^4.17.11",
     "react": "^16.9.0",

package/server/graphql/types/navigation-item.js

@@ -10,7 +10,7 @@ module.exports = ({ nexus }) =>
 			t.nonNull.string("uiRouterKey")
 			t.nonNull.boolean("menuAttached")
 			t.nonNull.int("order")
-			t.int("parent")
+			t.field("parent", { type: "NavigationItem" })
 			t.int("master")
 			t.list.field("items", { type: 'NavigationItem' })
 			t.field("related", { type: 'NavigationRelated' })

package/server/services/navigation.js

@@ -474,10 +474,10 @@ module.exports = ({ strapi }) => {
                 ...item,
                 audience: item.audience?.map(_ => _.key),
                 title: utilsFunctions.composeItemTitle(item, contentTypesNameFields, contentTypes),
-                related: item.related?.map(({ localizations, ...item }) => item),
+                related: last(item.related?.map(({ localizations, ...item }) => item)),
                 items: null,
               }));
-            return isNil(rootPath) ? items : utilsFunctions.filterByPath(publishedItems, rootPath).items;
+            return isNil(rootPath) ? publishedItems : utilsFunctions.filterByPath(publishedItems, rootPath).items;
         }
       }
       throw new NotFoundError();