mirror of https://github.com/abpframework/abp
Merge pull request #9682 from abpframework/auto-merge/rel-4-4/500
Merge branch dev with rel-4.4pull/9690/head
Mehmet Erim
4 years ago
committed by
GitHub
commit
286da27520
@ -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
|
||||
|
||||
|
||||
|
||||
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:
|
||||
|
||||
|
||||
|
||||
### 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)
|
||||
@ -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:
|
||||
|
||||
|
||||
|
||||
And the same page is shown below with the [Lepton Theme](https://commercial.abp.io/themes) application layout:
|
||||
|
||||
|
||||
|
||||
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 `<router-outlet>`)
|
||||
|
||||
## 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**
|
||||
|
||||
|
||||
|
||||
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: `
|
||||
<input type="search" placeholder="Search" class="bg-transparent border-0 color-white" />
|
||||
`,
|
||||
})
|
||||
export class MySearchInputComponent {}
|
||||
|
||||
|
||||
@Component(/* component metadata */)
|
||||
export class AppComponent {
|
||||
constructor(private navItems: NavItemsService) {
|
||||
navItems.addItems([
|
||||
{
|
||||
id: 'MySearchInput',
|
||||
order: 1,
|
||||
component: MySearchInputComponent,
|
||||
},
|
||||
{
|
||||
id: 'SignOutIcon',
|
||||
html: '<i class="fas fa-sign-out-alt fa-lg text-white m-2"><i>',
|
||||
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.
|
||||
|
After Width: | Height: | Size: 45 KiB |
Loading…
Reference in new issue