Strapi Navigation Plugin

To contribute to the strapi-plugin-navigation project, fork the repository and follow these steps to set up a local development environment:

1. Clone the repository:

   git clone git@github.com:VirtusLab-Open-Source/strapi-plugin-navigation.git

2. Install dependencies and start the watch mode using plugin-sdk:

   yarn install
   yarn watch:link

3. In your local Strapi project, enable the plugin by modifying config/plugins.{js|ts}:

   'navigation': {
     enabled: true,
     //...
   }

4. Run your Strapi instance to test changes.

To migrate the strapi-plugin-navigation plugin to version 3.0.0, you must manually copy specific migration files into your project's database/migrations directory. The files required depend on your current version:

• If you are on any 2.x version:

  • migrations/strapi-plugin-navigation-3.0.0-no-1-related-id-to-documentid.js
  • migrations/strapi-plugin-navigation-3.0.0-no-4-additional-fields.js

• If you are on version < 3.0.0-beta.4:

  • migrations/strapi-plugin-navigation-3.0.0-no-2-locale-slug-regular-slug.js

• If you are on version < 3.0.0-beta.6:

  • migrations/strapi-plugin-navigation-3.0.0-no-3-morph-relation.js

After copying the files, refer to the Strapi 5 Documentation to apply the database migrations.

You can install the plugin via the Strapi Marketplace (verified) or via the command line using yarn. After installation, you must rebuild your Strapi instance to see the plugin in the sidebar.

Installation steps:

1. Install the package:

   yarn add strapi-plugin-navigation@latest

2. Rebuild and restart Strapi:

   yarn build
   yarn develop

Once running, the UI Navigation plugin will appear in the Plugins section of the Strapi sidebar. You can manage multiple navigation containers by clicking the "Manage" button in the Navigation view.

If your Strapi server uses the strapi-plugin-rest-cache, you can enable integration in the Navigation plugin configuration. Once enabled, all client calls to the navigation API will be wrapped with caching middleware.

Features in Admin Panel:

• A "Clear cache" button will appear on the Navigation edit screen.
• Icon buttons for clearing the cache will be available in the Navigation management modal items.

If you need help with Strapi or this plugin, you can use the following channels:

• Discord: Join the official Strapi Discord and look for users with the [VirtusLab] prefix.
• Slack: Join the VirtusLab Open Source Slack and visit the #strapi-molecules channel.
• GitHub: Open issues for bug reports, questions, or discussions.
• E-mail: Contact strapi@virtuslab.com.

The plugin integrates with Strapi's Role-Based Access Control (RBAC). To grant access to the Navigation panel for any role other than Super Admin, navigate to Settings -> Administration Panel -> Roles and configure the following permissions:

• Mandatory: Plugins -> Navigation -> Read (Required to see the Navigation Panel).
• Optional: Plugins -> Navigation -> Update (Allows changing the navigation structure).
• Optional: Plugins -> Navigation -> Settings (Allows changing plugin settings).

The plugin allows defining custom fields for navigation items. These fields can be of several types:

• select: A dropdown or multi-select field. Requires options (array of strings) and a multi boolean.
• boolean: A simple true/false field.
• string: A text input field.
• media: A field for selecting media assets (images, videos, etc.).

Custom field names must not contain spaces (otherwise a noSpaceError is thrown).

export const navigationItemCustomField = z.discriminatedUnion('type', [
  navigationItemCustomFieldPrimitive,
  navigationItemCustomFieldMedia,
  navigationItemCustomFieldSelect,
]);

To use the navigation plugin with GraphQL, you must provide a gql property in your plugin configuration. This property defines union types used to format the GraphQL response for related content.

Critical Configuration Order: If you are using config/plugins.js, you must place the navigation property before the graphql property. Because navigation types are dynamic and added during the bootstrap stage rather than register, placing navigation after graphql will prevent the types from being correctly added to the GraphQL Schema.

Use the navigationItemRelated key to list the names of your Content Types that are referenced via navigation item relations.

// config/plugins.js
module.exports = {
  navigation: {
    gql: {
      navigationItemRelated: ['Page', 'UploadFile'],
    },
  },
  graphql: {
    // ... graphql config
  },
};