update: Vendor dashboard menu override for react templates based on Template override conditions

docs/feature-override/readme.md

@@ -0,0 +1,148 @@
+# How to define a menu is available in `React` and its `PHP` override information.
+
+- [Introduction](#introduction)
+- [1. Declare a menu is available in `React`.](#1-declare-a-menu-is-available-in-react)
+  - [Declare `React` menu in **Dokan Lite.**](#declare-react-menu-in-dokan-lite)
+  - [Declare `React` menu in **Dokan Pro** or **External Plugin**.](#declare-react-menu-in-dokan-pro-or-external-plugin)
+- [2. Declare the Override templates for a React route.](#2-declare-the-override-templates-for-a-react-route) 
+    - [Define the override templates for a React route in Dokan Lite.](#define-the-override-templates-for-a-react-route-in-dokan-lite)
+    - [Define the override templates for a React route in **Dokan Pro** or **External Plugin**.](#define-the-override-templates-for-a-react-route-in-dokan-pro-or-external-plugin)
+    - [Define the override templates array structure.](#define-the-override-templates-array-structure)
+
+## Introduction
+This document will help you to define a menu is available in `React` and its `PHP` override information.
+
+
+## 1. Declare a menu is available in `React`.
+To declare a menu is available in `React`, you need to define `route` property during the menu registration.
+
+### Declare `React` menu in **Dokan Lite**.
+```php
+// includes/functions-dashboard-navigation.php#L27-L66
+$menus = [
+        'dashboard' => [
+            'title'      => __( 'Dashboard', 'dokan-lite' ),
+            'icon'       => '<i class="fas fa-tachometer-alt"></i>',
+            'url'        => dokan_get_navigation_url(),
+            'pos'        => 10,
+            'permission' => 'dokan_view_overview_menu',
+            'route'      => '/', // <-- Define the route here
+        ],
+        'products'  => [
+            'title'      => __( 'Products', 'dokan-lite' ),
+            'icon'       => '<i class="fas fa-briefcase"></i>',
+            'url'        => dokan_get_navigation_url( 'products' ),
+            'pos'        => 30,
+            'permission' => 'dokan_view_product_menu',
+            'route'      => 'products', // <-- Define the route here
+        ],
+        'orders'    => [
+            'title'      => __( 'Orders', 'dokan-lite' ),
+            'icon'       => '<i class="fas fa-shopping-cart"></i>',
+            'url'        => dokan_get_navigation_url( 'orders' ),
+            'pos'        => 50,
+            'permission' => 'dokan_view_order_menu',
+            'route'      => 'orders', // <-- Define the route here
+        ],
+        'withdraw'  => [
+            'title'      => __( 'Withdraw', 'dokan-lite' ),
+            'icon'       => '<i class="fas fa-upload"></i>',
+            'url'        => dokan_get_navigation_url( 'withdraw' ),
+            'pos'        => 70,
+            'permission' => 'dokan_view_withdraw_menu',
+        ],
+        'settings'  => [
+            'title' => __( 'Settings', 'dokan-lite' ),
+            'icon'  => '<i class="fas fa-cog"></i>',
+            'url'   => dokan_get_navigation_url( 'settings/store' ),
+            'pos'   => 200,
+        ],
+    ];
+```
+In the above example, the `route` property is defined for each menu which we are indicating that the react route is available. 
+This will be used to determine if the menu is pointing to the react Application or to the Legacy PHP Route.
+
+The `route` property should be the same as the route defined in the `React` application in Router Array.
+
+It is important to note that the `route` property should be defined for the menu which is available in the `React` application. 
+If the `route` key is not defined for the menu, then the menu will be considered as a legacy menu and will be rendered using the PHP template.
+
+
+### Declare `React` menu in **Dokan Pro** or **External Plugin**.
+
+```php
+add_filter( 'dokan_get_dashboard_nav', function ( $menus ) {
+    $menus['products'] = [
+        'title'      => __( 'Products', 'dokan-lite' ),
+        'icon'       => '<i class="fas fa-briefcase"></i>',
+        'url'        => dokan_get_navigation_url( 'products' ),
+        'pos'        => 30,
+        'permission' => 'dokan_view_product_menu',
+        'route'      => 'products', // <-- Define the route here
+    ];
+
+    return $menus;
+} );
+```
+
+
+## 2. Declare the Override templates for a React route.
+If you are writing a new feature or modifying an existing feature in the `React` application, you do not need to define the override templates for the `React` route.
+But if you are modifying or migrating an existing feature written in PHP to the `React` application and you want that if some of the PHP template is overridden by the existing PHP template then the legacy PHP page will be displayed, then you need to define the override templates for the `React` route.
+### Define the override templates for a React route in Dokan Lite.
+```php
+// VendorNavMenuChecker.php#L13-L26
+protected array $template_dependencies = [
+        '' => [
+            [ 'slug' => 'dashboard/dashboard' ],
+            [ 'slug' => 'dashboard/orders-widget' ],
+            [ 'slug' => 'dashboard/products-widget' ],
+        ],
+        'products' => [
+            [ 'slug' => 'products/products' ],
+            [
+				'slug' => 'products/products',
+				'name' => 'listing',
+			],
+        ],
+    ];
+```
+
+In the above example, the `template_dependencies` property is defined for each route which we are indicating that the override templates are available for the route. This will be used to determine if the override templates are available for the route or not.
+
+### Define the override templates for a React route in **Dokan Pro** or **External Plugin**.
+From Dokan Pro, we can add dependencies by using the filter `dokan_get_dashboard_nav_template_dependency`.
+
+```php
+add_filter( 'dokan_get_dashboard_nav_template_dependency', function ( array $dependencies ) {
+    $dependencies['products'] = [
+        [ 'slug' => 'products/products' ],
+        [
+            'slug' => 'products/products',
+            'name' => 'listing',
+        ],
+    ];
+
+    return $dependencies;
+} );
+```
+### Define the override templates array structure.
+```php
+/**
+* @var array $template_dependencies Array of template dependencies for the route.
+ */
+
+[ 
+    'route_name' => [ 
+            [
+                'slug' => 'template-slug', 
+                'name' => 'template-name' // (Optional),
+                'args' = [] // (Optional)
+            ], 
+        ]
+]
+```
+
+- **Slug:** The slug of the template file which is used to display the php content.
+- **Name:** The name of the template file which is used to display the php content. (Optional)
+- **Args:** The arguments which are passed to the template file in `dokan_get_template_part()` function. (Optional)

includes/DependencyManagement/Providers/CommonServiceProvider.php

@@ -3,6 +3,7 @@
 namespace WeDevs\Dokan\DependencyManagement\Providers;
 
 use WeDevs\Dokan\DependencyManagement\BaseServiceProvider;
+use WeDevs\Dokan\VendorNavMenuChecker;
 
 class CommonServiceProvider extends BaseServiceProvider {
     /**
@@ -65,5 +66,8 @@ public function register(): void {
 		$this->getContainer()
             ->addShared( \WeDevs\Dokan\Privacy::class, \WeDevs\Dokan\Privacy::class )
             ->addTag( self::TAG );
+		$this->getContainer()
+            ->addShared( VendorNavMenuChecker::class, VendorNavMenuChecker::class )
+            ->addTag( self::TAG );
     }
 }

includes/VendorNavMenuChecker.php

@@ -0,0 +1,225 @@
+<?php
+
+namespace WeDevs\Dokan;
+
+class VendorNavMenuChecker {
+
+    /**
+     * @since DOKAN_SINCE
+     *
+     * @var array $template_dependencies List of template dependencies.
+     * [ 'route' => [ ['slug' => 'template-slug', 'name' => 'template-name' (Optional), 'args' = [] (Optional)  ] ] ]
+     */
+    protected array $template_dependencies = [
+        '' => [
+            [ 'slug' => 'dashboard/dashboard' ],
+            [ 'slug' => 'dashboard/orders-widget' ],
+            [ 'slug' => 'dashboard/products-widget' ],
+        ],
+        'products' => [
+            [ 'slug' => 'products/products' ],
+            [
+				'slug' => 'products/products',
+				'name' => 'listing',
+			],
+        ],
+    ];
+
+    /**
+     * Constructor.
+     */
+
+    public function __construct() {
+        add_filter( 'dokan_get_dashboard_nav', [ $this, 'convert_to_react_menu' ], 999 );
+        add_filter( 'dokan_admin_notices', [ $this, 'display_notice' ] );
+    }
+
+    /**
+     * Get template dependencies.
+     *
+     * @since DOKAN_SINCE
+     *
+     * @return array
+     */
+    public function get_template_dependencies(): array {
+        return apply_filters( 'dokan_get_dashboard_nav_template_dependency', $this->template_dependencies );
+    }
+
+    /**
+     * Convert menu items to react menu items
+     *
+     * @since DOKAN_SINCE
+     *
+     * @param array $menu_items Menu items.
+     *
+     * @return array
+     */
+
+    public function convert_to_react_menu( array $menu_items ): array {
+        return array_map(
+            function ( $item ) {
+                if ( ! empty( $item['route'] ) && $this->is_dependency_cleared( $item['route'] ) ) {
+                    $item['url'] = $this->get_url_for_route( $item['route'] );
+                }
+                if ( isset( $item['submenu'] ) ) {
+                    $item['submenu'] = $this->convert_to_react_menu( $item['submenu'] );
+                }
+
+                return $item;
+            }, $menu_items
+        );
+    }
+
+    /**
+     * Check if the dependency is cleared or not.
+     *
+     * @since DOKAN_SINCE
+     *
+     * @param string $route Route.
+     *
+     * @return bool
+     */
+    protected function is_dependency_cleared( string $route ): bool {
+        $dependencies = $this->get_template_dependencies_resolutions();
+        if ( ! empty( $dependencies[ trim( $route, '/' ) ] ) ) {
+            return false;
+        }
+
+        return true;
+    }
+
+    /**
+     * Get URL for the route.
+     *
+     * @since DOKAN_SINCE
+     *
+     * @param string $route Route.
+     *
+     * @return string
+     */
+    protected function get_url_for_route( string $route ): string {
+        $route = apply_filters( 'dokan_get_url_for_react_route', $route );
+
+        return dokan_get_navigation_url() . '#' . trim( $route, '/' );
+    }
+
+    /**
+     * Get template dependencies resolutions.
+     *
+     * @since DOKAN_SINCE
+     *
+     * @return array
+     */
+    protected function get_template_dependencies_resolutions(): array {
+        $dependencies = $this->get_template_dependencies();
+
+        $resolved_dependencies = array_map(
+            fn( $dependency_array ): array => array_filter(
+                array_map(
+                    fn( $dependency ) => $this->get_overridden_template(
+                        $dependency['slug'],
+                        $dependency['name'] ?? '',
+                        $dependency['args'] ?? []
+                    ),
+                    $dependency_array
+                )
+            ),
+            $dependencies
+        );
+
+        return apply_filters( 'dokan_get_dashboard_nav_template_dependency_resolutions', $resolved_dependencies );
+    }
+
+    /**
+     * Get overridden template part path.
+     *
+     * @since DOKAN_SINCE
+     *
+     * @param string $slug Template slug.
+     * @param string $name Template name.
+     * @param array $args Arguments.
+     *
+     * @return false|string Returns the template file if found otherwise false.
+     */
+    protected function get_overridden_template( string $slug, string $name = '', array $args = [] ) {
+        $defaults         = [ 'pro' => false ];
+        $args             = wp_parse_args( $args, $defaults );
+        $template         = '';
+        $default_template = '';
+
+        // Look in yourtheme/dokan/slug-name.php and yourtheme/dokan/slug.php
+        $template_path = ! empty( $name ) ? "{$slug}-{$name}.php" : "{$slug}.php";
+        $template      = locate_template( [ dokan()->template_path() . $template_path ] );
+
+        /**
+         * Change template directory path filter
+         *
+         * @since 2.5.3
+         */
+        $template_path = apply_filters( 'dokan_set_template_path', dokan()->plugin_path() . '/templates', $template, $args );
+
+        // Get default slug-name.php
+        if ( ! $template && $name && file_exists( $template_path . "/{$slug}-{$name}.php" ) ) {
+            $template         = $template_path . "/{$slug}-{$name}.php";
+            $default_template = $template;
+        }
+
+        if ( ! $template && ! $name && file_exists( $template_path . "/{$slug}.php" ) ) {
+            $template         = $template_path . "/{$slug}.php";
+            $default_template = $template;
+        }
+
+        // Allow 3rd party plugin filter template file from their plugin
+        $template = apply_filters( 'dokan_get_template_part', $template, $slug, $name );
+
+        return $template && $default_template !== $template ? $template : false;
+    }
+
+    /**
+     * List overridden templates.
+     *
+     * @since DOKAN_SINCE
+     *
+     * @return array
+     */
+    public function list_overridden_templates(): array {
+        $dependencies = $this->get_template_dependencies_resolutions();
+        $overridden_templates = [];
+        foreach ( $dependencies as $dependency ) {
+            $overridden_templates = array_merge( $overridden_templates, $dependency );
+        }
+
+        return $overridden_templates;
+    }
+
+    /**
+     * Display notice if templates are overridden.
+     *
+     * @since DOKAN_SINCE
+     *
+     * @param array $notices Notices.
+     *
+     * @return array
+     */
+    public function display_notice( array $notices ): array {
+        $overridden_templates = $this->list_overridden_templates();
+
+        if ( empty( $overridden_templates ) ) {
+            return $notices;
+        }
+
+        $notice = sprintf(
+            /* translators: %s: overridden templates */
+            __( 'The following templates are overridden:<br><code>%s</code>', 'dokan-lite' ),
+            implode( ',<br>', $overridden_templates )
+        );
+
+        $notices[] = [
+            'type'        => 'alert',
+            'title'       => esc_html__( 'Some of Dokan Templates are overridden which limit new features.', 'dokan-lite' ),
+            'description' => $notice,
+        ];
+
+        return $notices;
+    }
+}