diff --git a/docs/en/UI/Angular/Modifying-the-Menu.md b/docs/en/UI/Angular/Modifying-the-Menu.md new file mode 100644 index 0000000000..9de3750569 --- /dev/null +++ b/docs/en/UI/Angular/Modifying-the-Menu.md @@ -0,0 +1,207 @@ +## Modifying the Menu + +The menu is inside of the `ApplicationLayoutComponent` that is in the @abp/ng.theme.basic package. There are several methods to modify the menu elements. This document covers these methods. If you would like to replace all menu. Please refer to [Component Replacement documentation](./Component-Replacement.md) to learn how to replace a layout. + + + + + +### How to Add Logo + +`logoUrl` property in environment is the url of the logo. + +You can add your logo to `src/assets` folder and set the `logoUrl` as shown below: + +```js +export const environment = { + // other configurations + application: { + name: 'MyProjectName', + logoUrl: 'assets/logo.png', + }, + // other configurations +}; +``` + +### How to Add a Navigation Element + +#### Via `routes` object in the `AppRoutingModule` + +You can define your routes by adding the `routes` object to the `data` object of a route in the `app-routing.module`. The `@abp/ng.core` package organizes your routes and stores them in the `ConfigState`. `ApplicationLayoutComponent` gets routes and displays on the menu. + +You can add `routes` object like below: + +```js +import { ABP } from '@abp/ng.core'; +{ +// ... + path: 'your-path', + data: { + routes: { + name: 'Your navigation', + order: 3, + iconClass: 'fas fa-question-circle', + requiredPolicy: 'permission key here', + children: [ + { + path: 'child', + name: 'Your child navigation', + order: 1, + requiredPolicy: 'permission key here', + }, + ], + } as ABP.Route, + } +} +``` + +- `name` is the label of navigation element. A localization key or localization object can be passed. +- `order` is order of the navigation element. +- `iconClass` is the class of the `i` tag, which is placed to the left of the navigation label. +- `requiredPolicy` is the permission key to access the page. See the [Permission Management document](./Permission-Management.md) +- `children` is an array that child navigation elements are able to declare. The `path` property in an element of children array will be placed as a child route. Its url will be set as `'/your-path/child'`. + +After adding the routes object above, the navigation menu looks like this: + +![navigation-menu-via-app-routing](./images/navigation-menu-via-app-routing.png) + +#### Via ConfigState + +The `dispatchAddRoute` method of `ConfigStateService` adds a new navigation element to the menu. + +```js +// this.config is instance of ConfigStateService + +const newRoute: ABP.Route = { + name: 'My New Page', + iconClass: 'fa fa-dashboard', + path: 'page', + invisible: false, + order: 2, + requiredPolicy: 'MyProjectName.MyNewPage', + } as Omit; + + this.config.dispatchAddRoute(newRoute); +// returns a state stream which emits after dispatch action is complete +``` + +The `newRoute` will be placed as at root level, i.e. without any parent routes and its url will be stored as `'/path'`. + +If you want **to add a child route, you can do this:** + +```js +import { ConfigStateService } from '@abp/ng.core'; +import { eIdentityRouteNames } from '@abp/ng.identity'; + +constructor(private config: ConfigStateService) {} + +const newRoute: ABP.Route = { + parentName: eIdentityRouteNames.IdentityManagement, + name: 'My New Page', + iconClass: 'fa fa-dashboard', + path: 'page', + invisible: false, + order: 3, + requiredPolicy: 'MyProjectName.MyNewPage' +} as Omit; + +this.config.dispatchAddRoute(newRoute); +// returns a state stream which emits after dispatch action is complete +``` + +The `newRoute` will then be placed as a child of the parent route named `eIdentityRouteNames.IdentityManagement` and its url will be set as `'/identity/page'`. + +The new route will be added like below: + +![navigation-menu-via-config-state](./images/navigation-menu-via-config-state.png) + +### How to Patch a Navigation Element + +The `dispatchPatchRouteByName` finds a route by its name and replaces its configuration in the `Store` with the new configuration passed as the second parameter. + +```js +import { ConfigStateService } from '@abp/ng.core'; +import { eIdentityRouteNames } from '@abp/ng.identity'; + +constructor(private config: ConfigStateService) {} + +const newRouteConfig: Partial = { + iconClass: 'fas fa-home', + parentName: eIdentityRouteNames.Administration, + order: 0, + children: [ + { + name: 'Dashboard', + path: 'dashboard', + }, + ], +}; + +this.config.dispatchPatchRouteByName('::Menu:Home', newRouteConfig); +// returns a state stream which emits after dispatch action is complete +``` + +* Moved the home navigation to under the _Administration_ dropdown by passing `parentName`. +* Added an icon. +* Specified the order. +* Added a child route named _Dashboard_ + +After the patching above, navigation elements looks like below: + +![navigation-menu-after-patching](./images/navigation-menu-after-patching.png) + + +### How to Add an Element to Right Part of the Menu + +The right part elements are stored in the `LayoutState` that is in the @abp/ng.theme.basic package. + +The `dispatchAddNavigationElement` method of the `LayoutStateService` adds an element to the right part of the menu. + +You can add an element by adding your template to `app.component` and call the `dispatchAddNavigationElement` method: + +```js +import { Layout, LayoutStateService } from '@abp/ng.theme.basic'; // added this line + +@Component({ + selector: 'app-root', + template: ` + + + + `, +}) +export class AppComponent { + // Added ViewChild + @ViewChild('search', { static: false, read: TemplateRef }) searchElementRef: TemplateRef; + + constructor(private layout: LayoutStateService) {} // injected LayoutStateService + +// Added ngAfterViewInit + ngAfterViewInit() { + const newElement = { + name: 'Search', + element: this.searchElementRef, + order: 1, + } as Layout.NavigationElement; + + this.layout.dispatchAddNavigationElement(newElement); + } +} +``` + +We added the search input to the menu. + +The final UI looks like below: + +![navigation-menu-search-input](./images/navigation-menu-search-input.png) + +### How to Remove an Element From Right Part of the Menu + +TODO + + +## What's Next + +* [Component Replacement](./Component-Replacement.md) \ No newline at end of file diff --git a/docs/en/UI/Angular/images/navigation-menu-after-patching.png b/docs/en/UI/Angular/images/navigation-menu-after-patching.png new file mode 100644 index 0000000000..2f6bf08c88 Binary files /dev/null and b/docs/en/UI/Angular/images/navigation-menu-after-patching.png differ diff --git a/docs/en/UI/Angular/images/navigation-menu-search-input.png b/docs/en/UI/Angular/images/navigation-menu-search-input.png new file mode 100644 index 0000000000..ebdc05e3e0 Binary files /dev/null and b/docs/en/UI/Angular/images/navigation-menu-search-input.png differ diff --git a/docs/en/UI/Angular/images/navigation-menu-via-app-routing.png b/docs/en/UI/Angular/images/navigation-menu-via-app-routing.png new file mode 100644 index 0000000000..4d5f61301c Binary files /dev/null and b/docs/en/UI/Angular/images/navigation-menu-via-app-routing.png differ diff --git a/docs/en/UI/Angular/images/navigation-menu-via-config-state.png b/docs/en/UI/Angular/images/navigation-menu-via-config-state.png new file mode 100644 index 0000000000..19944f154d Binary files /dev/null and b/docs/en/UI/Angular/images/navigation-menu-via-config-state.png differ diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index 53caea554b..c0515c18de 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -352,6 +352,10 @@ "text": "Config State", "path": "UI/Angular/Config-State.md" }, + { + "text": "Modifying the Menu", + "path": "UI/Angular/Modifying-the-Menu.md" + }, { "text": "Component Replacement", "path": "UI/Angular/Component-Replacement.md" @@ -398,7 +402,7 @@ "text": "Data Access", "items": [ { - "text": "Overall", + "text": "Overall", "path": "Data-Access.md" }, {