{"id":13472579,"url":"https://github.com/VirtusLab-Open-Source/strapi-plugin-navigation","last_synced_at":"2025-03-26T17:30:48.681Z","repository":{"id":36959591,"uuid":"301647629","full_name":"VirtusLab-Open-Source/strapi-plugin-navigation","owner":"VirtusLab-Open-Source","description":"A plugin for Strapi Headless CMS that provides navigation / menu builder feature with their possibility to control the audience and different output structure renderers like (flat, tree and RFR - ready for handling by Redux First Router)","archived":false,"fork":false,"pushed_at":"2024-10-28T17:41:43.000Z","size":5325,"stargazers_count":316,"open_issues_count":19,"forks_count":58,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-10-30T05:25:48.473Z","etag":null,"topics":["api","customizable","information-structures","menu","navigation","redux-first-router","rest","strapi","strapi-admin-panel","strapi-plugin"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VirtusLab-Open-Source.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-10-06T07:29:03.000Z","updated_at":"2024-10-25T12:19:55.000Z","dependencies_parsed_at":"2023-12-21T14:59:10.424Z","dependency_job_id":"431db0e3-46b0-4cd8-9870-1ad02688ca6f","html_url":"https://github.com/VirtusLab-Open-Source/strapi-plugin-navigation","commit_stats":null,"previous_names":["virtuslab/strapi-plugin-navigation"],"tags_count":89,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirtusLab-Open-Source%2Fstrapi-plugin-navigation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirtusLab-Open-Source%2Fstrapi-plugin-navigation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirtusLab-Open-Source%2Fstrapi-plugin-navigation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirtusLab-Open-Source%2Fstrapi-plugin-navigation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VirtusLab-Open-Source","download_url":"https://codeload.github.com/VirtusLab-Open-Source/strapi-plugin-navigation/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245702142,"owners_count":20658551,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","customizable","information-structures","menu","navigation","redux-first-router","rest","strapi","strapi-admin-panel","strapi-plugin"],"created_at":"2024-07-31T16:00:55.881Z","updated_at":"2025-03-26T17:30:48.675Z","avatar_url":"https://github.com/VirtusLab-Open-Source.png","language":"TypeScript","funding_links":[],"categories":["Strapi v3","TypeScript"],"sub_categories":["Plugin \u0026 Providers - v3"],"readme":"\u003cdiv align=\"center\" style=\"max-width: 10rem; margin: 0 auto\"\u003e\n  \u003cimg style=\"width: 150px; height: auto;\" src=\"https://www.sensinum.com/img/open-source/strapi-plugin-navigation/logo.png\" alt=\"Logo - Strapi Navigation plugin\" /\u003e\n\u003c/div\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003eStrapi - Navigation plugin\u003c/h1\u003e\n  \u003cp\u003eCreate consumable navigation with a simple and straightforward visual builder\u003c/p\u003e\n  \u003ca href=\"https://www.npmjs.org/package/strapi-plugin-navigation\"\u003e\n    \u003cimg alt=\"GitHub package.json version\" src=\"https://img.shields.io/github/package-json/v/VirtusLab-Open-Source/strapi-plugin-navigation?label=npm\u0026logo=npm\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.org/package/strapi-plugin-navigation\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/dm/strapi-plugin-navigation.svg\" alt=\"Monthly download on NPM\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://circleci.com/gh/VirtusLab/strapi-plugin-navigation\"\u003e\n    \u003cimg src=\"https://circleci.com/gh/VirtusLab-Open-Source/strapi-plugin-navigation.svg?style=shield\" alt=\"CircleCI\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://codecov.io/gh/VirtusLab/strapi-plugin-navigation\"\u003e\n    \u003cimg src=\"https://codecov.io/gh/VirtusLab/strapi-plugin-navigation/coverage.svg?branch=master\" alt=\"codecov.io\" /\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n---\n\n\u003cdiv style=\"margin: 20px 0\" align=\"center\"\u003e\n  \u003cimg style=\"width: 100%; height: auto;\" src=\"https://www.sensinum.com/img/open-source/strapi-plugin-navigation/preview.png\" alt=\"UI preview\" /\u003e\n\u003c/div\u003e\n\nStrapi Navigation Plugin provides a website navigation / menu builder feature for [Strapi Headless CMS](https://github.com/strapi/strapi) admin panel. Navigation has the possibility to control the audience and can be consumed by the website with different output structure renderers:\n\n- Flat\n- Tree (nested)\n- RFR (ready for handling by Redux First Router)\n\n### Table of Contents\n1. [💎 Versions](#-versions)\n2. [✨ Features](#-features)\n3. [⏳ Installation](#-installation)\n4. [🖐 Requirements](#-requirements)\n5. [🔧 Basic Configuration](#-configuration)\n    - [Settings page](#in-v203-and-newer)\n    - [Plugin file](#in-v202-and-older--default-configuration-state-for-v203-and-newer)\n6. [🔧 GraphQL Configuration](#-gql-configuration)\n7. [🌍 i18n](#-i18n)\n8. [👤 RBAC](#-rbac)\n9. [🔐 Authorization strategy](#-authorization-strategy)\n10. [🕸️ Public API specification](#%EF%B8%8F-public-api-specification)\n    - [REST API](#rest-api) \n    - [GraphQL API](#graphql-api)\n11. [🔌 Extensions](#-extensions)\n12. [🌿 Model lifecycle hooks](#model-life-cycle-hooks)\n13. [🧹 REST Cache](#rest-cache)\n14. [🧩 Examples](#-examples)\n15. [💬 FAQ](#-faq)\n16. [🤝 Contributing](#-contributing-to-the-plugin)\n17. [👨‍💻 Community support](#-community-support)\n\n## 💎 Versions\n\n- **Strapi v5** - (current) [v3.x](https://github.com/VirtusLab-Open-Source/strapi-plugin-navigation)\n- **Strapi v4** - [v2.x](https://github.com/VirtusLab-Open-Source/strapi-plugin-navigation/tree/strapi-v4)\n- **Strapi v3** - [v1.x](https://github.com/VirtusLab-Open-Source/strapi-plugin-navigation/tree/strapi-v3)\n\n## ✨ Features\n\n- **Navigation Public API:** Simple and ready for use API endpoint for consuming the navigation structure you've created\n- **Visual builder:** Elegant and easy to use visual builder\n- **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\n- **Different types of navigation items:** Create navigation with items linked to internal types, to external links or wrapper elements to keep structure clean \n- **Multiple navigations:** Create as many Navigation containers as you want, setup them and use in the consumer application\n- **Light / Dark mode compatible:** By design we're supporting Strapi ☀️ Light / 🌙 Dark modes \n- **Webhooks integration:** Changes to navigation will trigger 'entry.update' or 'entry.create' webhook events. \n- **Customizable:** Possibility to customize the options like: available Content Types, Maximum level for \"attach to menu\", Additional fields (audience)\n\n## ⏳ Installation\n\n### Via Strapi Marketplace\n\nAs 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.\n\n\u003cdiv style=\"margin: 20px 0\" align=\"center\"\u003e\n  \u003cimg style=\"width: 100%; height: auto;\" src=\"https://www.sensinum.com/img/open-source/strapi-plugin-navigation/marketplace.png\" alt=\"Strapi In-App Marketplace\" /\u003e\n\u003c/div\u003e\n\n### Via command line\n\nIt'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/).\n\n```bash\nyarn add strapi-plugin-navigation@latest\n```\n\nAfter successful installation you've to re-build your Strapi instance. To archive that simply use:\n\n```bash\nyarn build\nyarn develop\n```\n\nThe **UI Navigation** plugin should appear in the **Plugins** section of Strapi sidebar after you run app again.\n\nYou can manage your multiple navigation containers by going to the **Navigation** manage view by clicking \"Manage\" button.\n\n\u003cdiv style=\"margin: 20px 0\" align=\"center\"\u003e\n  \u003cimg style=\"width: 100%; height: auto;\" src=\"https://www.sensinum.com/img/open-source/strapi-plugin-navigation/manager-view.png\" alt=\"Navigation Manager View\" /\u003e\n\u003c/div\u003e\n\nAs a next step you must configure your the plugin by the way you want to. See [**Configuration**](#🔧-configuration) section.\n\nAll done. Enjoy 🎉\n\n## 🖐 Requirements\n\nComplete installation requirements are exact same as for Strapi itself and can be found in the documentation under \u003ca href=\"https://docs.strapi.io/dev-docs/installation/cli#preparing-the-installation\"\u003eInstallation Requirements\u003c/a\u003e.\n\n**Supported Strapi versions**:\n\n- Strapi v5.10.3 (recently tested)\n- Strapi v5.x\n\n\u003e This plugin is designed for **Strapi v5** and is not working with v4.x. To get version for **Strapi v4** install version [v4.x](https://github.com/VirtusLab-Open-Source/strapi-plugin-navigation/tree/strapi-v4).\n\n**We recommend always using the latest version of Strapi to start your new projects**.\n\n## 🔧 Configuration\n\nTo start your journey with **Navigation plugin** you must first setup it using the dedicated Settings page or for any version, put your configuration in `config/plugins.{js|ts}`. Anyway we're recommending the click-through option where your configuration is going to be properly validated.\n\n### Settings page\n\nOn 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.\n\n\u003cdiv style=\"margin: 20px 0\" align=\"center\"\u003e\n  \u003cimg style=\"width: 100%; height: auto;\" src=\"https://www.sensinum.com/img/open-source/strapi-plugin-navigation/configuration.png\" alt=\"Plugin configuration\" /\u003e\n\u003c/div\u003e\n\n\u003e *Note*\n\u003e 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.\n\n### File\n\nConfig for this plugin is stored as a part of the `config/plugins.{js|ts}` or `config/\u003cenv\u003e/plugins.{js|ts}` file. You can use the following snippet to make sure that the config structure is correct. If you've got already configurations for other plugins stores by this way, you can use the `navigation` along with them. \n\n\n```ts\n    module.exports = ({ env }) =\u003e ({\n        // ...\n        navigation: {\n            enabled: true,\n            config: {\n                additionalFields: ['audience', { name: 'my_custom_field', type: 'boolean', label: 'My custom field' }],\n                contentTypes: ['api::page.page'],\n                contentTypesNameFields: {\n                    'api::page.page': ['title']\n                },\n                pathDefaultFields: {\n                    'api::page.page': ['slug']\n                },\n                allowedLevels: 2,\n                gql: {...},\n            }\n        }\n    });\n```\n\n### Properties\n- `additionalFields` - Additional fields for navigation items. More **[ here ](#additional-fields)**\n- `allowedLevels` - Maximum level for which you're able to mark item as \"Menu attached\"\n- `contentTypes` - UIDs of related content types\n- `contentTypesNameFields` - Definition of content type title fields like `'api::\u003ccollection name\u003e.\u003ccontent type name\u003e': ['field_name_1', 'field_name_2']`, if not set titles are pulled from fields like `['title', 'subject', 'name']`. **TIP** - Proper content type uid you can find in the URL of Content Manager where you're managing relevant entities like: `admin/content-manager/collectionType/\u003c THE UID HERE \u003e?page=1\u0026pageSize=10\u0026sort=Title:ASC\u0026plugins[i18n][locale]=en`\n- `pathDefaultFields` - The attribute to copy the default path from per content type. Syntax: `'api::\u003ccollection name\u003e.\u003ccontent type name\u003e': ['url_slug', 'path']`\n- `gql` - If you're using GraphQL that's the right place to put all necessary settings. More **[ here ](#gql-configuration)**\n- `i18nEnabled` - should you want to manage multi-locale content via navigation set this value `Enabled`. More **[ here ](#i18n)**\n- `cascadeMenuAttached` - If you don't want \"Menu attached\" to cascade on child items set this value `Disabled`.\n\n### Properties\n\n### Additional Fields\nIt is advised to configure additional fields through the plugin's Settings Page. There you can find the table of custom fields and toggle input for the audience field. When enabled, the audience field can be customized through the content manager. Custom fields can be added, edited, toggled, and removed with the use of the table provided on the Settings Page. When removing custom fields be advised that their values in navigation items will be lost. Disabling the custom fields will not affect the data and can be done with no consequence of loosing information. \n\nCreating configuration for additional fields with the `config.(js|ts)` file should be done with caution. Config object contains the `additionalFields` property of type `Array\u003cCustomField | 'audience'\u003e`, where CustomField is of type `{ type: 'string' | 'boolean' | 'media', name: string, label: string, enabled?: boolean }`. When creating custom fields be advised that the `name` property has to be unique. When editing a custom field it is advised not to edit its `name` and `type` properties. After config has been restored the custom fields that are not present in `config.js` file will be deleted and their values in navigation items will be lost.\n\n## 🔧 GQL Configuration\nUsing navigation with GraphQL requires both plugins to be installed and working. You can find installation guide for GraphQL plugin **[here](https://docs.strapi.io/dev-docs/plugins/graphql#graphql)**.  To properly configure GQL to work with navigation you should provide `gql` prop. This should contain union types that will be used to define GQL response format for your data while fetching:\n\n\u003e **Important!**\n\u003e If you're using `config/plugins.js` to configure your plugins , please put `navigation` property before `graphql`. Otherwise types are not going to be properly added to GraphQL Schema. That's because of dynamic types which base on plugin configuration which are added on `bootstrap` stage, not `register`. This is not valid if you're using `graphql` plugin without any custom configuration, so most of cases in real.\n\n```gql\nmaster: Int\nitems: [NavigationItem]\nrelated: NavigationRelated\n```\n\nThis prop should look as follows:   \n\n```ts\ngql: {\n    navigationItemRelated: ['\u003cyour GQL related content types\u003e'],\n},\n```\n\nfor example:   \n\n```ts\ngql: {\n    navigationItemRelated: ['Page', 'UploadFile'],\n},\n```\nwhere `Page` and `UploadFile` are your type names for the **Content Types** you're referring by navigation items relations. \n\n## 🌍 i18n\n\nFully integrated and follows the **[official i18n Strapi patterns](https://docs.strapi.io/dev-docs/i18n)**.\n\n## 👤 RBAC\nPlugin provides granular permissions based on **Strapi RBAC** functionality within the editorial interface \u0026amp; **Admin API**. Those settings are editable via the _Setings_ -\u003e _Administration Panel_ -\u003e _Roles_.\n\nFor any role different than **Super Admin**, to access the **Navigation panel** you must set following permissions:\n\n### Mandatory permissions\n- _Plugins_ -\u003e _Navigation_ -\u003e _Read_ - gives you the access to **Navigation Panel**\n\n### Other permissions\n- _Plugins_ -\u003e _Navigation_ -\u003e _Update_ - with this permission user is able to change Navigation structure\n- _Plugins_ -\u003e _Navigation_ -\u003e _Settings_ - special permission for users that should be able to change plugin settings\n\n## 🔐 Authorization strategy\nIs applied for **Public API** both for REST and GraphQL. You can manage is by two different ways. Those settings are editable via the _Setings_ -\u003e _Users \u0026amp; Permissions Plugin_ -\u003e _Roles_. \n\n## User based\n- _Public_ - as per description it's default role for any not authenticated user. By enabling **Public API** of the plugin here you're making it **fully public**, without **any permissions check**.\n- _Authenticated_ - as per description this is default role for Strapi Users. If you enable **Public API** here, for any call made you must use the User authentication token as `Bearer \u003ctoken\u003e`.\n\n## Token based\n- _Full Access_ - gives full access to every Strapi Content API including our plugin endpoints as well.\n- _Custom_ - granural access management to every Strapi Content API endpoints as well as plugin **Public API** - _(recomended approach)_\n\n\u003e _Note: Token usage \u0026amp Read-Only tokens_\n\u003e If you're aiming to use token based approach, for every call you must provide proper token in headers as `Bearer \u003ctoken\u003e`.\n\u003e\n\u003e Important: As the Read-Only tokens are dedicated to support just `find` and `findAll` endpoints from Strapi Content API, they are not covering access to plugin **Public API** `render` and `renderChild` endpoints. We recommend to use the `Custom` token type for fully granural and secured approach instead of `Full Access` ones.\n\u003e\n\u003e Reference: [Strapi - API Tokens](https://docs.strapi.io/dev-docs/configurations/api-tokens#usage)\n\n## Base Navigation Item model\n\n### Flat\n```json\n{\n    \"id\": 1,\n    \"documentId\": \"njx99iv4p4txuqp307ye8625\",\n    \"title\": \"News\",\n    \"type\": \"INTERNAL\",\n    \"path\": \"news\",\n    \"externalPath\": null,\n    \"uiRouterKey\": \"News\",\n    \"menuAttached\": false,\n    \"parent\": 8, // Parent Navigation Item 'id', null in case of root level\n    \"master\": 1, // Navigation 'id'\n    \"createdAt\": \"2020-09-29T13:29:19.086Z\",\n    \"updatedAt\": \"2020-09-29T13:29:19.128Z\",\n    \"related\": {/*\u003cContent Type model \u003e*/ },\n    \"audience\": []\n}\n```\n\n### Tree\n```json\n{\n    \"title\": \"News\",\n    \"menuAttached\": true,\n    \"path\": \"/news\",\n    \"type\": \"INTERNAL\",\n    \"uiRouterKey\": \"news\",\n    \"slug\": \"benefits\",\n    \"external\": false,\n    \"related\": {\n        // \u003cContent Type model \u003e\n    },\n    \"items\": [\n        {\n            \"title\": \"External url\",\n            \"menuAttached\": true,\n            \"path\": \"http://example.com\",\n            \"type\": \"EXTERNAL\",\n            \"uiRouterKey\": \"generic\",\n            \"external\": true\n        },\n       //  \u003c Tree Navigation Item models \u003e\n    ]\n}\n```\n\n### RFR\n```json\n{\n    \"id\": \"News\",\n    \"title\": \"News\",\n    \"related\": {\n        \"contentType\": \"page\",\n        \"collectionName\": \"pages\",\n        \"id\": 1\n    },\n    \"path\": \"/news\",\n    \"slug\": \"news\",\n    \"parent\": null, // Parent Navigation Item 'id', null in case of root level\n    \"menuAttached\": true\n}\n```\n\n## 🕸️ Public API specification\n\nPlugin supports both **REST API** and **GraphQL API** exposed by Strapi.\n\n**Query Params**\n\n- `navigationIdOrSlug` - ID or slug for which your navigation structure is generated like for REST API:\n\n  \u003e `https://localhost:1337/api/navigation/render/njx99iv4p4txuqp307ye8625`\n  \u003e `https://localhost:1337/api/navigation/render/main-menu`\n\n- `type` - Enum value representing structure type of returned navigation:\n  \u003e `https://localhost:1337/api/navigation/render/njx99iv4p4txuqp307ye8625?type=FLAT`\n\n- `menu` (`menuOnly` for GQL) - Boolean value for querying only navigation items that are attached to menu should be rendered eg.\n  \u003e `https://localhost:1337/api/navigation/render/njx99iv4p4txuqp307ye8625?menu=true`\n\n- `path` - String value for querying navigation items by its path:\n  \u003e `https://localhost:1337/api/navigation/render/njx99iv4p4txuqp307ye8625?path=/home/about-us`\n\n### REST API\n\n`GET \u003chost\u003e/api/navigation/?locale=\u003clocale\u003e\u0026orderBy=\u003corderBy\u003e\u0026orderDirection=\u003corderDirection\u003e`\n\nNOTE: All params are optional\n\n**Example URL**: `https://localhost:1337/api/navigation?locale=en`\n\n**Example response body**\n\n```json\n[\n  {\n    \"id\": 383,\n    \"documentId\": \"njx99iv4p4txuqp307ye8625\",\n    \"name\": \"Floor\",\n    \"slug\": \"floor-pl\",\n    \"visible\": true,\n    \"createdAt\": \"2023-09-29T12:45:54.399Z\",\n    \"updatedAt\": \"2023-09-29T13:44:08.702Z\",\n    \"locale\": \"pl\"\n  },\n  {\n    \"id\": 384,\n    \"documentId\": \"njx99iv4p4txuqp307ye8625\",\n    \"name\": \"Floor\",\n    \"slug\": \"floor-fr\",\n    \"visible\": true,\n    \"createdAt\": \"2023-09-29T12:45:54.399Z\",\n    \"updatedAt\": \"2023-09-29T13:44:08.725Z\",\n    \"locale\": \"fr\"\n  },\n  {\n    \"id\": 382,\n    \"documentId\": \"njx99iv4p4txuqp307ye8625\",\n    \"name\": \"Floor\",\n    \"slug\": \"floor\",\n    \"visible\": true,\n    \"createdAt\": \"2023-09-29T12:45:54.173Z\",\n    \"updatedAt\": \"2023-09-29T13:44:08.747Z\",\n    \"locale\": \"en\"\n  },\n  {\n    \"id\": 374,\n    \"documentId\": \"njx99iv4p4txuqp307ye8625\",\n    \"name\": \"Main navigation\",\n    \"slug\": \"main-navigation-pl\",\n    \"visible\": true,\n    \"createdAt\": \"2023-09-29T12:22:30.373Z\",\n    \"updatedAt\": \"2023-09-29T13:44:08.631Z\",\n    \"locale\": \"pl\"\n  },\n  {\n    \"id\": 375,\n    \"documentId\": \"njx99iv4p4txuqp307ye8625\",\n    \"name\": \"Main navigation\",\n    \"slug\": \"main-navigation-fr\",\n    \"visible\": true,\n    \"createdAt\": \"2023-09-29T12:22:30.373Z\",\n    \"updatedAt\": \"2023-09-29T13:44:08.658Z\",\n    \"locale\": \"fr\"\n  },\n  {\n    \"id\": 373,\n    \"documentId\": \"njx99iv4p4txuqp307ye8625\",\n    \"name\": \"Main navigation\",\n    \"slug\": \"main-navigation\",\n    \"visible\": true,\n    \"createdAt\": \"2023-09-29T12:22:30.356Z\",\n    \"updatedAt\": \"2023-09-29T13:44:08.680Z\",\n    \"locale\": \"en\"\n  }\n]\n```\n\n`GET \u003chost\u003e/api/navigation/render/\u003cnavigationIdOrSlug\u003e?type=\u003ctype\u003e`\n\nReturn a rendered navigation structure depends on passed type (`TREE`, `RFR` or nothing to render as `FLAT`).\n\n**Example URL**: `https://localhost:1337/api/navigation/render/njx99iv4p4txuqp307ye8625`\n\n**Example response body**\n\n```json\n[\n    {\n        \"id\": 1,\n        \"documentId\": \"njx99iv4p4txuqp307ye8625\",\n        \"title\": \"News\",\n        \"type\": \"INTERNAL\",\n        \"path\": \"news\",\n        \"externalPath\": null,\n        \"uiRouterKey\": \"News\",\n        \"menuAttached\": false,\n        \"parent\": null,\n        \"master\": 1,\n        \"created_at\": \"2020-09-29T13:29:19.086Z\",\n        \"updated_at\": \"2020-09-29T13:29:19.128Z\",\n        \"related\": {\n            \"__contentType\": \"Page\",\n            \"id\": 1,\n            \"documentId\": \"njx99iv4p4txuqp307ye8625\",\n            \"title\": \"News\",\n            // ...\n        }\n    },\n    // ...\n]\n```\n\n**Example URL**: `https://localhost:1337/api/navigation/render/njx99iv4p4txuqp307ye8625?type=TREE`\n\n**Example response body**\n\n```json\n[\n    {\n        \"title\": \"News\",\n        \"menuAttached\": true,\n        \"path\": \"/news\",\n        \"type\": \"INTERNAL\",\n        \"uiRouterKey\": \"news\",\n        \"slug\": \"benefits\",\n        \"external\": false,\n        \"related\": {\n            \"__contentType\": \"Page\",\n            \"id\": 1,\n            \"title\": \"News\",\n            // ...\n        },\n        \"items\": [\n            {\n                \"title\": \"External url\",\n                \"menuAttached\": true,\n                \"path\": \"http://example.com\",\n                \"type\": \"EXTERNAL\",\n                \"uiRouterKey\": \"generic\",\n                \"external\": true\n            },\n            // ...\n        ]\n    },\n    // ...\n]\n```\n\n**Example URL**: `https://localhost:1337/api/navigation/render/njx99iv4p4txuqp307ye8625?type=RFR`\n\n**Example response body**\n\n```json\n{\n    \"pages\": {\n        \"News\": {\n            \"id\": \"News\",\n            \"title\": \"News\",\n            \"related\": {\n                \"contentType\": \"page\",\n                \"collectionName\": \"pages\",\n                \"id\": 1\n            },\n            \"path\": \"/news\",\n            \"slug\": \"news\",\n            \"parent\": null,\n            \"menuAttached\": true\n        },\n        \"Community\": {\n            \"id\": \"Community\",\n            \"title\": \"Community\",\n            \"related\": {\n                \"contentType\": \"page\",\n                \"collectionName\": \"pages\",\n                \"id\": 2\n            },\n            \"path\": \"/community\",\n            \"slug\": \"community\",\n            \"parent\": null,\n            \"menuAttached\": true\n        },\n        \"Highlights\": {\n            \"id\": \"Highlights\",\n            \"title\": \"Highlights\",\n            \"related\": {\n                \"contentType\": \"page\",\n                \"collectionName\": \"pages\",\n                \"id\": 3\n            },\n            \"path\": \"/community/highlights\",\n            \"slug\": \"community-highlights\",\n            \"parent\": \"Community\",\n            \"menuAttached\": false\n        },\n        // ...\n    },\n    \"nav\": {\n        \"root\": [\n            {\n                \"label\": \"News\",\n                \"type\": \"internal\",\n                \"page\": \"News\"\n            },\n            {\n                \"label\": \"Community\",\n                \"type\": \"internal\",\n                \"page\": \"Community\"\n            },\n            {\n                \"label\": \"External url\",\n                \"type\": \"external\",\n                \"url\": \"http://example.com\"\n            },\n            // ...\n        ],\n        \"Community\": [\n            {\n                \"label\": \"Highlights\",\n                \"type\": \"internal\",\n                \"page\": \"Highlights\"\n            },\n            // ...\n        ],\n        // ...\n    }\n}\n```\n\n### GraphQL API\n\nSame as [**REST API**](#rest-api) returns a rendered navigation structure depends on passed type (`TREE`, `RFR` or nothing to render as `FLAT`).\n\n**Example request**\n\n```graphql\nquery {\n  renderNavigation(\n    navigationIdOrSlug: \"main-navigation\"\n    type: TREE\n    menuOnly: false\n  ) {\n    id\n    title\n    path\n    related {\n      id\n      __typename\n\n      ... on Page {\n        Title\n      }\n\n      ... on WithFlowType {\n        Name\n      }\n    }\n    items {\n      id\n      title\n      path\n      related {\n        id\n        __typename\n\n        ... on Page {\n          Title\n        }\n\n        ... on WithFlowType {\n          Name\n        }\n      }\n    }\n  }\n}\n```\n\n**Example response**\n\n```json\n{\n  \"data\": {\n    \"renderNavigation\": [\n      {\n        \"id\": 8,\n        \"title\": \"Test page\",\n        \"path\": \"/test-path\",\n        \"related\": {\n          \"id\": 3,\n          \"__typename\": \"WithFlowType\",\n          \"Name\": \"Test\"\n        },\n        \"items\": [\n          {\n            \"id\": 11,\n            \"title\": \"Nested\",\n            \"path\": \"/test-path/nested-one\",\n            \"related\": {\n              \"id\": 1,\n              \"__typename\": \"Page\",\n              \"Title\": \"Eg. Page title\"\n            }\n          }\n        ]\n      },\n      {\n        \"id\": 10,\n        \"title\": \"Another page\",\n        \"path\": \"/another\",\n        \"related\": {\n          \"__typename\": \"Page\",\n          \"Title\": \"Eg. Page title\"\n        },\n        \"items\": []\n      }\n    ]\n  }\n}\n```\n\n## 🔌 Extensions\n\n### Slug generation\n\nSlug generation is available as a controller and service. If you have custom requirements outside of what this plugin provides you can add your own logic with [plugins extensions](https://docs.strapi.io/developer-docs/latest/development/plugins-extension.html).\n\nFor example:\n\n```ts\n// path: /admin/src/index.js\n\nmodule.exports = {\n  // ...\n  bootstrap({ strapi }) {\n    const navigationCommonService = strapi.plugin(\"navigation\").service(\"common\");\n    const originalGetSlug = navigationCommonService.getSlug;\n    const preprocess = (q) =\u003e {\n      return q + \"suffix\";\n    };\n\n    navigationCommonService.getSlug = (query) =\u003e {\n      return originalGetSlug(preprocess(query));\n    };\n  },\n};\n```\n\n## Model lifecycle hooks\n\nNavigation plugin allows to register lifecycle hooks for `Navigation` and `NavigationItem` content types.\n\nYou can read more about lifecycle hooks [here](https://docs.strapi.io/dev-docs/backend-customization/models#lifecycle-hooks). (You can set a listener for all of the hooks).\n\nLifecycle hooks can be register either in `register()` or `bootstrap()` methods of your server. You can register more than one listener for a specified lifecycle hook. For example: you want to do three things on navigation item creation and do not want to handle all of these actions in one big function. You can split logic in as many listeners as you want.\n\nListeners can by sync and `async`.\n\n\u003eBe aware that lifecycle hooks registered in `register()` may be fired by plugin's bootstrapping. If you want listen to events triggered after server's startup use `bootstrap()`.\n\nExample:\n\n```ts\n  const navigationCommonService = strapi\n    .plugin(\"navigation\")\n    .service(\"common\");\n\n  navigationCommonService.registerLifecycleHook({\n    callback: async ({ action, result }) =\u003e {\n      const saveResult = await logIntoSystem(action, result);\n\n      console.log(saveResult);\n    },\n    contentTypeName: \"navigation\",\n    hookName: \"afterCreate\",\n  });\n\n  navigationCommonService.registerLifecycleHook({\n    callback: async ({ action, result }) =\u003e {\n      const saveResult = await logIntoSystem(action, result);\n\n      console.log(saveResult);\n    },\n    contentTypeName: \"navigation-item\",\n    hookName: \"afterCreate\",\n  });\n```\n\n## 🧹 REST Cache\n\n\u003e Note: Yet using the `4.x` compatible version of the plugin. Integration migration expected once the maintenance team release their `5.x` compatible version.\n\nIf your strapi server uses [REST Cache plugin](https://strapi-community.github.io/strapi-plugin-rest-cache/) this plugin can take integrate with it. All you need to do is to enable it in configuration of Navigation plugin. After integration is enabled all client calls will be wrapped with caching middleware.\n\nIn admin panel new controls will be available. Cache clearing is done manually or after cache will timeout(`rest-cache` plugin's settings are used).\n\nNavigation edit screen will have **\"Clear cache\"** button.\n\nNavigation management modal items will also have icon button for clearing the cache.\n\n## 🧩 Examples\n\nLive example of plugin usage can be found in the [VirtusLab Strapi Examples](https://github.com/VirtusLab/strapi-examples/tree/master/strapi-plugin-navigation) repository.\n\n## 💬 FAQ\n\n### GraphQL tricks\n\n**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?\n\n**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|ts}` file and put there following lines (put `graphql` at the end):\n\n```ts\nmodule.exports = {\n  'navigation': { enabled: true },\n  'graphql': { enabled: true },\n};\n```\n\nIf you already got it, make sure that `navigation` plugin is inserted before `graphql`. That should do the job.\n\n## 🤝 Contributing to the plugin\n\n### How to start?\n\nFeel free to fork and make a Pull Request to this plugin project. All the input is warmly welcome!\n\n1. Clone repository\n\n   ```\n   git clone git@github.com:VirtusLab-Open-Source/strapi-plugin-navigation.git\n   ```\n\n2. Run `install` \u0026 `watch:link` command\n\n   ```ts\n   // Install all dependencies\n   yarn install\n\n   // Watch for file changes using `plugin-sdk` and follow the instructions provided by this official Strapi developer tool\n   yarn watch:link\n   ```\n\n3. Within the Strapi project, modify `config/plugins.{js|ts}` for `imgix`\n\n```ts\n//...\n'navigation': {\n  enabled: true,\n  //...\n}\n//...\n```\n\n4. Run your Strapi instance\n\n### :octocat: Core team\n[@CodeVoyager](https://github.com/CodeVoyager) [@cyp3rius](https://github.com/cyp3rius)\n\n### 🌟 Strapi Community\n[@jorrit](https://github.com/jorrit)\n\n## 👨‍💻 Community support\n\nFor general help using Strapi, please refer to [the official Strapi documentation](https://strapi.io/documentation/). For additional help, you can use one of these channels to ask a question:\n\n- [Discord](https://discord.strapi.io/) We're present on official Strapi Discord workspace. Find us by `[VirtusLab]` prefix and DM.\n- [Slack - VirtusLab Open Source](https://virtuslab-oss.slack.com) We're present on a public channel #strapi-molecules\n- [GitHub](https://github.com/VirtusLab/strapi-plugin-navigation/issues) (Bug reports, Contributions, Questions and Discussions)\n- [E-mail](mailto:strapi@virtuslab.com) - we will respond back as soon as possible\n\n## 📝 License\n\n[MIT License](LICENSE.md) Copyright (c) [VirtusLab Sp. z o.o.](https://virtuslab.com/) \u0026amp; [Strapi Solutions](https://strapi.io/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FVirtusLab-Open-Source%2Fstrapi-plugin-navigation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FVirtusLab-Open-Source%2Fstrapi-plugin-navigation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FVirtusLab-Open-Source%2Fstrapi-plugin-navigation/lists"}