diff --git a/docs/en/UI/Angular/Basic-Theme.md b/docs/en/UI/Angular/Basic-Theme.md new file mode 100644 index 0000000000..7b6c98fdcc --- /dev/null +++ b/docs/en/UI/Angular/Basic-Theme.md @@ -0,0 +1,107 @@ +# Angular UI: Basic Theme + +The Basic Theme is a theme implementation for the Angular UI. It is a minimalist theme that doesn't add any styling on top of the plain [Bootstrap](https://getbootstrap.com/). You can take the Basic Theme as the **base theme** and build your own theme or styling on top of it. See the *Customization* section. + +> If you are looking for a professional, enterprise ready theme, you can check the [Lepton Theme](https://commercial.abp.io/themes), which is a part of the [ABP Commercial](https://commercial.abp.io/). + +> See the [Theming document](Theming.md) to learn about themes. + +## Installation + +**This theme is already installed** when you create a new solution using the [startup templates](../../Startup-Templates/Index.md). If you need to manually install it, follow the steps below: + +* Install the [@abp/ng.theme.basic](https://www.npmjs.com/package/@abp/ng.theme.basic) NPM package to your Angular project. +* Open the `src/app/app.module.ts` file, import `ThemeBasicModule` (it can be imported from `@abp/ng.theme.basic` package), and add `ThemeBasicModule.forRoot()` to the `imports` array. +* Open the `src/app/shared/shared.module` file, import `ThemeBasicModule` (it can be imported from `@abp/ng.theme.basic` package), and add `ThemeBasicModule` to the `imports` and `exports` array. + +The `ThemeBasicModule` is registered own layouts (`ApplicationLayoutComponent`, `AccountLayoutComponent`, `EmptyLayoutComponent`) to a service which is exposed by `@abp/ng.core` package on application initialization. + +## Application Layout + +![basic-theme-application-layout](../../images/basic-theme-application-layout.png) + +Application Layout implements the following parts, in addition to the common parts mentioned above; + +* Logo area +* Routes area +* Language selection & user menu +* [Page Alerts](Page-Alerts.md) + +See Application Layout components: + +![application layout components](./images/layout-components.png) + +### How to Use a Layout + +Routes should be added to the menu by calling `add` method `RoutesService`. A layout can be set in the object of your route. See the [modifying the menu](Modifying-the-Menu#how-to-add-a-navigation-element) for more information. + +## Customization + +You have two options two customize this theme: + +### Overriding Styles / Components + +In this approach, you continue to use the theme as an NPM package and customize the parts you need to. There are several ways to customize it; + +#### Override the Styles + +You can simply override the styles in the global styles (`src/styles.scss`) file of your application. + +#### Override the Components + +See the [Component Replacement](Component-Replacement.md) to learn how you can replace components, customize and extend the user interface. + +### Copy & Customize + +You can run the following [ABP CLI](../../CLI.md) command in **Angular** project directory to copy the source code to your solution: + +`abp add-package @abp/ng.theme.basic --with-source-code` + +---- + +Or, you can download the [source code](https://github.com/abpframework/abp/blob/dev/npm/ng-packs/packages/theme-basic) of the Basic Theme, manually copy the project content into your project (`projects/theme-basic` folder), open `angular.json` file and add configuration below to the `projects` object: + +```json +{ + "projects": { + ... + "theme-basic": { + "projectType": "library", + "root": "projects/theme-basic", + "sourceRoot": "projects/theme-basic/src", + "prefix": "abp", + "architect": { + "build": { + "builder": "@angular-devkit/build-ng-packagr:build", + "options": { + "tsConfig": "projects/theme-basic/tsconfig.lib.json", + "project": "projects/theme-basic/ng-package.json" + }, + "configurations": { + "production": { + "tsConfig": "projects/theme-basic/tsconfig.lib.prod.json" + } + } + } + } + } + } +} +``` + +Then, open the `tsconfig.json` file and add new paths as follows: + +```json +"paths": { + ... + "@abp/ng.theme.basic": ["projects/theme-basic/src/public-api.ts"], + "@abp/ng.theme.basic/testing": ["projects/theme-basic/testing/src/public-api.ts"] +} +``` + + +You can now freely customize the theme based on your application requirements. + +## See Also + +* [Theming](Theming.md) diff --git a/docs/en/UI/Angular/Theming.md b/docs/en/UI/Angular/Theming.md new file mode 100644 index 0000000000..21e28953f8 --- /dev/null +++ b/docs/en/UI/Angular/Theming.md @@ -0,0 +1,228 @@ +# Angular UI: Theming + +## Introduction + +ABP Framework provides a complete **UI Theming** system with the following goals: + +* Reusable [application modules](../../Modules/Index.md) are developed **theme-independent**, so they can work with any UI theme. +* UI theme is **decided by the final application**. +* The theme is distributed via an NPM package, so it is **easily upgradable**. +* The final application can **customize** the selected theme. + +In order to accomplish these goals, ABP Framework; + +* Determines a set of **base libraries** used and adapted by all the themes. So, module and application developers can depend on and use these libraries without depending on a particular theme. +* Provides a system that consists of layout parts (like navigation menus and toolbars) that is implemented by all the themes. So, the modules and the application contribute to the layout to compose a consistent application UI. + +### Current Themes + +Currently, two themes are **officially provided**: + +* The [Basic Theme](Basic-Theme.md) is the minimalist theme with the plain Bootstrap style. It is **open source and free**. +* The [Lepton Theme](https://commercial.abp.io/themes) is a **commercial** theme developed by the core ABP team and is a part of the [ABP Commercial](https://commercial.abp.io/) license. + +## Overall + +### The Base Libraries + +All the themes must depend on the [@abp/ng.theme.shared](https://www.npmjs.com/package/@abp/ng.theme.shared) NuGet package, so they are indirectly depending on the following libraries: + +* [Twitter Bootstrap](https://getbootstrap.com/) as the fundamental HTML/CSS framework. +* [FontAwesome](https://fontawesome.com/) as the fundamental CSS font library. +* [NG Bootstrap](https://ng-bootstrap.github.io/#/home) as a component library that supports the Bootstrap and adds extra components like modal and datepicker. +* [Ngx-Datatable](https://swimlane.gitbook.io/ngx-datatable/) as a datatable library. +* [ngx-validate](https://github.com/ng-turkey/ngx-validate) a dynamic validation of reactive forms library. +* [Chart.js](https://www.chartjs.org/) as a widget library. + +These libraries are selected as the base libraries and available to the applications and modules. + +> Bootstrap's JavaScript part is not used since the NG Bootstrap library already provides the necessary functionalities to the Bootstrap components in a native way. + +### The Layout + +All themes must define a layout for the application. The following image shows the user management page in the [Basic Theme](Basic-Theme.md) application layout: + +![basic-theme-application-layout](../../images/basic-theme-application-layout.png) + +And the same page is shown below with the [Lepton Theme](https://commercial.abp.io/themes) application layout: + +![lepton-theme-application-layout](../../images/lepton-theme-application-layout.png) + +As you can see, the page is the same, but the look is completely different in the themes above. + +The application layout typically includes the following parts; + +* Main menu +* Nav items area with the following components; + * User menu + * Language switch dropdown +* [Page alerts](Page-Alerts.md) +* The page content (aka ``) + +## Implementing a Theme + +A theme is simply an NPM package and comes with startup templates. + +### The Easy Way + +The easiest way to create a new theme is to add Basic Theme Source Code to your project via [ABP CLI](../../CLI.md) command and customize it. + +You can run the following command in **Angular** project directory to copy the source code to your solution: + +`abp add-package @abp/ng.theme.basic --with-source-code` + +### Global/Component Styles + +Angular can bundle global style files and component styles with components. +See the [component styles](https://angular.io/guide/component-styles) guide on Angular documentation for more information. + +### Layout Parts + +A typical layout consists of several parts. The theme should include the necessary parts in each layout. + +**Example: The Basic Theme has the following parts for the Application Layout** + +![basic-theme-application-layout-parts](images/basic-theme-application-layout-parts.png) + +The application code and the modules can only show contents in the Page Content part. If they need to change the other parts (to add a menu item, to add a nav item, to change the application name in the logo area...) they should use the ABP Framework APIs. + +The following sections explain the fundamental parts pre-defined by the ABP Framework and can be implemented by the themes. + +> It is a good practice to split the layout into components/partials, so the final application can override them partially for customization purpose. + +#### Logo + +The `application` object of an environment file should be configured to get the name and the logo URL of the application to render in the logo part. Additionally, `LogoComponent` can be replaced. See [Component Replacement](Component-Replacement.md) document for more. + +The [Application Startup Template](../../Startup-Templates/Application.md) has an implementation of this interface to set the values by the application developer. + +#### Main Menu / Routes + +`RoutesService` service is used to manage the main menu items and render them on the layout. + +**Example: Adding a route to the main menu** + +```ts +import { RoutesService, eLayoutType } from '@abp/ng.core'; +import { Component } from '@angular/core'; + +@Component(/* component metadata */) +export class AppComponent { + constructor(routes: RoutesService) { + routes.add([ + { + path: '/your-path', + name: 'Your navigation', + order: 101, + iconClass: 'fas fa-question-circle', + requiredPolicy: 'permission key here', + layout: eLayoutType.application, + }, + { + path: '/your-path/child', + name: 'Your child navigation', + parentName: 'Your navigation', + order: 1, + requiredPolicy: 'permission key here', + }, + ]); + } +} +``` + +See the [Modifying the Menu](Modifying-the-Menu.md) document to learn more about the navigation system. + +#### Toolbar / Nav Items + +`NavItemsService` service is used to get the menu's right part items and render on the layout. You can add an HTML content or Angular component as an element to render. + +**Example: Adding an element to right part of the menu** + +````ts +import { NavItemsService } from '@abp/ng.theme.shared'; +import { Component } from '@angular/core'; + +@Component({ + template: ` + + `, +}) +export class MySearchInputComponent {} + + +@Component(/* component metadata */) +export class AppComponent { + constructor(private navItems: NavItemsService) { + navItems.addItems([ + { + id: 'MySearchInput', + order: 1, + component: MySearchInputComponent, + }, + { + id: 'SignOutIcon', + html: '', + action: () => console.log('Clicked the sign out icon'), + order: 101, // puts as last element + }, + ]); + } +} +```` + +> See the [How to Add an Element to Right Part of the Menu](Modifying-the-Menu#how-to-add-an-element-to-right-part-of-the-menu) document to learn more on the nav items system. + +The theme has a responsibility to add two pre-defined items to the toolbar: Language Selection and User Menu. + +##### Language Selection + +Language Selection toolbar item is generally a dropdown that is used to switch between languages. `ConfigStateService` is used to get the list of available languages and `SessionStateService` is used to learn the current language. + +`SessionStateService` is used to get and set the current language. + +**Example: Get the currently selected language** + +````ts +import {SessionStateService} from '@abp/ng.core'; + +//... + +constructor(private sessionState: SessionStateService) { + const lang = this.sessionState.getLanguage() +} +```` + +**Example: Set the selected language** + +````ts +import {SessionStateService} from '@abp/ng.core'; + +//... + +constructor(private sessionState: SessionStateService) { + const lang = this.sessionState.setLanguage('en') +} +```` + +##### User Menu + +User menu is a component that can be replaceable. See an example to learn how can you replace it: + +````ts +import { eThemeBasicComponents } from '@abp/ng.theme.basic'; +import { NavItemsService } from '@abp/ng.theme.shared'; +import { Component } from '@angular/core'; + +@Component({/* component metadata */}) +export class AppComponent { + constructor(private navItems: NavItemsService) { + this.navItems.patchItem(eThemeBasicComponents.CurrentUser, { component: MyUserMenuComponent }); + } +} +```` + +[`ConfigStateService`](Config-State-Service.md) service can be used to obtain the `application-configuration` API response (e.g. getting current user or tenant). + +#### Page Alerts + +`PageAlertService` service is used to get the current page alerts to render on the layout. See the [Page Alerts](Page-Alerts.md) document to learn more. \ No newline at end of file diff --git a/docs/en/UI/Angular/images/basic-theme-application-layout-parts.png b/docs/en/UI/Angular/images/basic-theme-application-layout-parts.png new file mode 100644 index 0000000000..934b0e0528 Binary files /dev/null and b/docs/en/UI/Angular/images/basic-theme-application-layout-parts.png differ diff --git a/docs/en/UI/Blazor/Basic-Theme.md b/docs/en/UI/Blazor/Basic-Theme.md index 6a71e50c84..2c034f258a 100644 --- a/docs/en/UI/Blazor/Basic-Theme.md +++ b/docs/en/UI/Blazor/Basic-Theme.md @@ -38,7 +38,7 @@ You have two options two customize this theme: ### Overriding Styles / Components -In this approach, you continue to use the the theme as NuGet and NPM packages and customize the parts you need to. There are several ways to customize it; +In this approach, you continue to use the theme as NuGet and NPM packages and customize the parts you need to. There are several ways to customize it; #### Override the Styles diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index c946b8401c..5a2b18d365 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -365,8 +365,8 @@ "path": "Object-To-Object-Mapping.md" }, { - "text":"String Encryption", - "path":"String-Encryption.md" + "text": "String Encryption", + "path": "String-Encryption.md" }, { "text": "Text Templating", @@ -1025,6 +1025,19 @@ "text": "Customization Guide", "path": "UI/Angular/Customization-User-Interface.md" }, + { + "text": "Theming", + "items": [ + { + "text": "Overall", + "path": "UI/Angular/Theming.md" + }, + { + "text": "The Basic Theme", + "path": "UI/Angular/Basic-Theme.md" + } + ] + }, { "text": "Modifying the Menu", "path": "UI/Angular/Modifying-the-Menu.md"