mirror of https://github.com/abpframework/abp
Ilkay Ilknur
5 years ago
commit
4b42d9bf9d
@ -0,0 +1,47 @@
|
||||
# ABP Framework & ABP Commercial 3.3 Final Have Been Released
|
||||
|
||||
ABP Framework & ABP Commercial 3.3.0 have been released today.
|
||||
|
||||
Since all the new features are already explained in details with the [3.3 RC Announcement Post](https://blog.abp.io/abp/ABP-Framework-ABP-Commercial-v3.3-RC-Have-Been-Released), I will not repeat all the details again. Please read [the RC post](https://blog.abp.io/abp/ABP-Framework-ABP-Commercial-v3.3-RC-Have-Been-Released) for **new feature and changes** you may need to do for your solution while upgrading to the version 3.3.
|
||||
|
||||
## Creating New Solutions
|
||||
|
||||
You can create a new solution with the ABP Framework version 3.3 by either using the `abp new` command or using the **direct download** tab on the [get started page](https://abp.io/get-started).
|
||||
|
||||
> See the [getting started document](https://docs.abp.io/en/abp/latest/Getting-Started) for details.
|
||||
|
||||
## How to Upgrade an Existing Solution
|
||||
|
||||
### Install/Update the ABP CLI
|
||||
|
||||
First of all, install the ABP CLI or upgrade to the latest version.
|
||||
|
||||
If you haven't installed yet:
|
||||
|
||||
````bash
|
||||
dotnet tool install -g Volo.Abp.Cli
|
||||
````
|
||||
|
||||
To update an existing installation:
|
||||
|
||||
```bash
|
||||
dotnet tool update -g Volo.Abp.Cli
|
||||
```
|
||||
|
||||
### ABP UPDATE Command
|
||||
|
||||
[ABP CLI](https://docs.abp.io/en/abp/latest/CLI) provides a handy command to update all the ABP related NuGet and NPM packages in your solution with a single command:
|
||||
|
||||
````bash
|
||||
abp update
|
||||
````
|
||||
|
||||
Run this command in the root folder of your solution. After the update command, check [the RC blog post](https://blog.abp.io/abp/ABP-Framework-ABP-Commercial-v3.3-RC-Have-Been-Released) to learn if you need to make any changes in your solution.
|
||||
|
||||
> You may want to see the new [upgrading document](https://docs.abp.io/en/abp/latest/Upgrading).
|
||||
|
||||
## About the Next Version: 4.0
|
||||
|
||||
The next version will be 4.0 and it will be mostly related to completing the Blazor UI features and upgrading the ABP Framework & ecosystem to the .NET 5.0.
|
||||
|
||||
The goal is to complete the version 4.0 with a stable Blazor UI with the fundamental features implemented and publish it just after the Microsoft lunches .NET 5 in this November. The planned 4.0 preview release date is November 11th.
|
||||
@ -0,0 +1,27 @@
|
||||
# WPF Application Startup Template
|
||||
|
||||
This template is used to create a minimalist WPF application project.
|
||||
|
||||
## How to Start With?
|
||||
|
||||
First, install the [ABP CLI](../CLI.md) if you haven't installed before:
|
||||
|
||||
````bash
|
||||
dotnet tool install -g Volo.Abp.Cli
|
||||
````
|
||||
|
||||
Then use the `abp new` command in an empty folder to create a new solution:
|
||||
|
||||
````bash
|
||||
abp new Acme.MyWpfApp -t wpf
|
||||
````
|
||||
|
||||
`Acme.MyWpfApp` is the solution name, like *YourCompany.YourProduct*. You can use single level, two-levels or three-levels naming.
|
||||
|
||||
## Solution Structure
|
||||
|
||||
After you use the above command to create a solution, you will have a solution like shown below:
|
||||
|
||||
|
||||
|
||||
* `HelloWorldService` is a sample service that implements the `ITransientDependency` interface to register this service to the [dependency injection](../Dependency-Injection.md) system.
|
||||
@ -1,3 +1,2 @@
|
||||
## Basic Theme
|
||||
This document has been moved to [here](../UI/AspNetCore/Basic-Theme.md).
|
||||
|
||||
TODO
|
||||
@ -1,3 +1,37 @@
|
||||
# Angular UI: Features
|
||||
# Features
|
||||
|
||||
> This document explains how to get feature values in an Angular application. See the [Features document](../../Features.md) to learn the feature system.
|
||||
You can get the value of a feature on the client-side using the [config state service](./Config-State.md) if it is allowed by the feature definition on the server-side.
|
||||
|
||||
> This document explains how to get feature values in an Angular application. See the [Features document](../../Features.md) to learn the feature system.
|
||||
|
||||
## Before Use
|
||||
|
||||
To use the `ConfigStateService`, you must inject it in your class as a dependency. You do not have to provide the service explicitly, because it is already **provided in root**.
|
||||
|
||||
```js
|
||||
import { ConfigStateService } from '@abp/ng.core';
|
||||
|
||||
@Component({
|
||||
/* class metadata here */
|
||||
})
|
||||
class DemoComponent {
|
||||
constructor(private config: ConfigStateService) {}
|
||||
}
|
||||
```
|
||||
|
||||
## How to Get a Specific Feature
|
||||
|
||||
You can use the `getFeature` method of `ConfigStateService` to get a specific feature from the configuration state. Here is an example:
|
||||
|
||||
```js
|
||||
// this.config is instance of ConfigStateService
|
||||
|
||||
const defaultLang = this.config.getFeature("Identity.TwoFactor");
|
||||
// 'Optional'
|
||||
```
|
||||
|
||||
You can then check the value of the feature to perform your logic. Please note that **feature keys are case-sensitive**.
|
||||
|
||||
## What's Next?
|
||||
|
||||
- [Permission Management](./Permission-Management.md)
|
||||
|
||||
@ -1,3 +1,59 @@
|
||||
# Angular UI: Settings
|
||||
# Settings
|
||||
|
||||
> This document explains how to get setting values in an Angular application. See the [settings document](../../Settings.md) to learn the setting system.
|
||||
You can get settings on the client-side using the [config state service](./Config-State.md) if they are allowed by their setting definition on the server-side.
|
||||
|
||||
> This document only explains how settings work in the Angular UI projects. See the [settings document](../../../Settings.md) to understand the ABP setting system.
|
||||
|
||||
## Before Use
|
||||
|
||||
To use the `ConfigStateService`, you must inject it in your class as a dependency. You do not have to provide the service explicitly, because it is already **provided in root**.
|
||||
|
||||
```js
|
||||
import { ConfigStateService } from '@abp/ng.core';
|
||||
|
||||
@Component({
|
||||
/* class metadata here */
|
||||
})
|
||||
class DemoComponent {
|
||||
constructor(private config: ConfigStateService) {}
|
||||
}
|
||||
```
|
||||
|
||||
## How to Get a Specific Setting
|
||||
|
||||
You can use the `getSetting` method of `ConfigStateService` to get a specific setting from the configuration state. Here is an example:
|
||||
|
||||
```js
|
||||
// this.config is instance of ConfigStateService
|
||||
|
||||
const defaultLang = this.config.getSetting("Abp.Localization.DefaultLanguage");
|
||||
// 'en'
|
||||
```
|
||||
|
||||
### How to Get All Settings From the Store
|
||||
|
||||
You can use the `getSettings` method of `ConfigStateService` to obtain all settings as an object where the object properties are setting names and property values are setting values.
|
||||
|
||||
```js
|
||||
// this.config is instance of ConfigStateService
|
||||
|
||||
const settings = this.config.getSettings();
|
||||
// all settings as a key value pair
|
||||
```
|
||||
|
||||
Additionally, the method lets you search settings by **passing a keyword** to it.
|
||||
|
||||
```js
|
||||
const localizationSettings = this.config.getSettings("Localization");
|
||||
/*
|
||||
{
|
||||
'Abp.Localization.DefaultLanguage': 'en'
|
||||
}
|
||||
*/
|
||||
```
|
||||
|
||||
Beware though, **settings search is case-sensitive**.
|
||||
|
||||
## What's Next?
|
||||
|
||||
- [Features](./Features.md)
|
||||
|
||||
@ -0,0 +1,90 @@
|
||||
# ASP.NET Core MVC / Razor Pages: The Basic Theme
|
||||
|
||||
The Basic Theme is a theme implementation for the ASP.NET Core MVC / Razor Pages 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.
|
||||
|
||||
The Basic Theme has RTL (Right-to-Left language) support.
|
||||
|
||||
> 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 [Volo.Abp.AspNetCore.Mvc.UI.Theme.Basic](https://www.nuget.org/packages/Volo.Abp.AspNetCore.Mvc.UI.Theme.Basic) NuGet package to your web project.
|
||||
* Add `AbpAspNetCoreMvcUiBasicThemeModule` into the `[DependsOn(...)]` attribute for your [module class](../../Module-Development-Basics.md) in the web project.
|
||||
* Install the [@abp/aspnetcore.mvc.ui.theme.basic](https://www.npmjs.com/package/@abp/aspnetcore.mvc.ui.theme.basic) NPM package to your web project (e.g. `npm install @abp/aspnetcore.mvc.ui.theme.basic` or `yarn add @abp/aspnetcore.mvc.ui.theme.basic`).
|
||||
* Run `gulp` command in a command line terminal in the web project's folder.
|
||||
|
||||
## Layouts
|
||||
|
||||
The Basic Theme implements the standard layouts. All the layouts implement the following parts;
|
||||
|
||||
* Global [Bundles](Bundling-Minification.md)
|
||||
* [Page Alerts](Page-Alerts.md)
|
||||
* [Layout Hooks](Layout-Hooks.md)
|
||||
* [Widget](Widgets.md) Resources
|
||||
|
||||
### The Application Layout
|
||||
|
||||
|
||||
|
||||
Application Layout implements the following parts, in addition to the common parts mentioned above;
|
||||
|
||||
* Branding
|
||||
* Main [Menu](Navigation-Menu.md)
|
||||
* Main [Toolbar](Toolbars.md) with Language Selection & User Menu
|
||||
|
||||
### The Account Layout
|
||||
|
||||
|
||||
|
||||
Application Layout implements the following parts, in addition to the common parts mentioned above;
|
||||
|
||||
* Branding
|
||||
* Main [Menu](Navigation-Menu.md)
|
||||
* Main [Toolbar](Toolbars.md) with Language Selection & User Menu
|
||||
* Tenant Switch Area
|
||||
|
||||
### Empty Layout
|
||||
|
||||
Empty layout is empty, as its name stands for. However, it implements the common parts mentioned above.
|
||||
|
||||
## Customization
|
||||
|
||||
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;
|
||||
|
||||
#### Override the Styles
|
||||
|
||||
1. Create a CSS file in the `wwwroot` folder of your project:
|
||||
|
||||
|
||||
|
||||
2. Add the style file to the global bundle, in the `ConfigureServices` method of your [module](../../Module-Development-Basics.md):
|
||||
|
||||
````csharp
|
||||
Configure<AbpBundlingOptions>(options =>
|
||||
{
|
||||
options.StyleBundles.Configure(BasicThemeBundles.Styles.Global, bundle =>
|
||||
{
|
||||
bundle.AddFiles("/styles/global-styles.css");
|
||||
});
|
||||
});
|
||||
````
|
||||
|
||||
#### Override the Components
|
||||
|
||||
See the [User Interface Customization Guide](Customization-User-Interface.md) to learn how you can replace components, customize and extend the user interface.
|
||||
|
||||
### Copy & Customize
|
||||
|
||||
You can download the [source code](https://github.com/abpframework/abp/tree/dev/framework/src/Volo.Abp.AspNetCore.Mvc.UI.Theme.Basic) of the Basic Theme, copy the project content into your solution, re-arrange the package/module dependencies (see the Installation section above to understand how it was installed to the project) and freely customize the theme based on your application requirements.
|
||||
|
||||
## See Also
|
||||
|
||||
* [Theming](Theming.md)
|
||||
@ -0,0 +1,3 @@
|
||||
# ASP.NET Core MVC / Razor Pages: Branding
|
||||
|
||||
TODO
|
||||
@ -0,0 +1,263 @@
|
||||
# ASP.NET Core MVC / Razor Pages: Data Tables
|
||||
|
||||
A Data Table (aka Data Grid) is a UI component to show tabular data to the users. There are a lot of Data table components/libraries and **you can use any one you like** with the ABP Framework. However, the startup templates come with the [DataTables.Net](https://datatables.net/) library as **pre-installed and configured**. ABP Framework provides adapters for this library and make it easy to use with the API endpoints.
|
||||
|
||||
An example screenshot from the user management page that shows the user list in a data table:
|
||||
|
||||
|
||||
|
||||
## DataTables.Net Integration
|
||||
|
||||
First of all, you can follow the official documentation to understand how the [DataTables.Net](https://datatables.net/) works. This section will focus on the ABP addons & integration points rather than fully covering the usage of this library.
|
||||
|
||||
### A Quick Example
|
||||
|
||||
You can follow the [web application development tutorial](https://docs.abp.io/en/abp/latest/Tutorials/Part-1?UI=MVC) for a complete example application that uses the DataTables.Net as the Data Table. This section shows a minimalist example.
|
||||
|
||||
You do nothing to add DataTables.Net library to the page since it is already added to the global [bundle](Bundling-Minification.md) by default.
|
||||
|
||||
First, add an `abp-table` as shown below, with an `id`:
|
||||
|
||||
````html
|
||||
<abp-table striped-rows="true" id="BooksTable"></abp-table>
|
||||
````
|
||||
|
||||
> `abp-table` is a [Tag Helper](Tag-Helpers/Index.md) defined by the ABP Framework, but a simple `<table...>` tag would also work.
|
||||
|
||||
Then call the `DataTable` plugin on the table selector:
|
||||
|
||||
````js
|
||||
var dataTable = $('#BooksTable').DataTable(
|
||||
abp.libs.datatables.normalizeConfiguration({
|
||||
serverSide: true,
|
||||
paging: true,
|
||||
order: [[1, "asc"]],
|
||||
searching: false,
|
||||
ajax: abp.libs.datatables.createAjax(acme.bookStore.books.book.getList),
|
||||
columnDefs: [
|
||||
{
|
||||
title: l('Actions'),
|
||||
rowAction: {
|
||||
items:
|
||||
[
|
||||
{
|
||||
text: l('Edit'),
|
||||
action: function (data) {
|
||||
///...
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
title: l('Name'),
|
||||
data: "name"
|
||||
},
|
||||
{
|
||||
title: l('PublishDate'),
|
||||
data: "publishDate",
|
||||
render: function (data) {
|
||||
return luxon
|
||||
.DateTime
|
||||
.fromISO(data, {
|
||||
locale: abp.localization.currentCulture.name
|
||||
}).toLocaleString();
|
||||
}
|
||||
},
|
||||
{
|
||||
title: l('Price'),
|
||||
data: "price"
|
||||
}
|
||||
]
|
||||
})
|
||||
);
|
||||
````
|
||||
|
||||
The example code above uses some ABP integration features those will be explained in the next sections.
|
||||
|
||||
### Configuration Normalization
|
||||
|
||||
`abp.libs.datatables.normalizeConfiguration` function takes a DataTables configuration and normalizes to simplify it;
|
||||
|
||||
* Sets `scrollX` option to `true`, if not set.
|
||||
* Sets `target` index for the column definitions.
|
||||
* Sets the `language` option to [localize](../../Localization.md) the table in the current language.
|
||||
|
||||
#### Default Configuration
|
||||
|
||||
`normalizeConfiguration` uses the default configuration. You can change the default configuration using the `abp.libs.datatables.defaultConfigurations` object. Example:
|
||||
|
||||
````js
|
||||
abp.libs.datatables.defaultConfigurations.scrollX = false;
|
||||
````
|
||||
|
||||
Here, the all configuration options;
|
||||
|
||||
* `scrollX`: `false` by default.
|
||||
* `dom`: Default value is `<"dataTable_filters"f>rt<"row dataTable_footer"<"col-auto"l><"col-auto"i><"col"p>>`.
|
||||
* `language`: A function that returns the localization text using the current language.
|
||||
|
||||
### AJAX Adapter
|
||||
|
||||
DataTables.Net has its own expected data format while getting results of an AJAX call to the server to get the table data. They are especially related how paging and sorting parameters are sent and received. ABP Framework also offers its own conventions for the client-server [AJAX](JavaScript-API/Ajax.md) communication.
|
||||
|
||||
The `abp.libs.datatables.createAjax` method (used in the example above) adapts request and response data format and perfectly works with the [Dynamic JavaScript Client Proxy](Dynamic-JavaScript-Client-Proxies.md) system.
|
||||
|
||||
This works automatically, so most of the times you don't need to know how it works. See the [DTO document](../../Data-Transfer-Objects.md) if you want to learn more about `IPagedAndSortedResultRequest`, `IPagedResult` and other standard interfaces and base DTO classes those are used in client to server communication.
|
||||
|
||||
### Row Actions
|
||||
|
||||
`rowAction` is an option defined by the ABP Framework to the column definitions to show a drop down button to take actions for a row in the table.
|
||||
|
||||
The example screenshot below shows the actions for each user in the user management table:
|
||||
|
||||
|
||||
|
||||
`rowAction` is defined as a part of a column definition:
|
||||
|
||||
````csharp
|
||||
{
|
||||
title: l('Actions'),
|
||||
rowAction: {
|
||||
//TODO: CONFIGURATION
|
||||
}
|
||||
},
|
||||
````
|
||||
|
||||
**Example: Show *Edit* and *Delete* actions for a book row**
|
||||
|
||||
````js
|
||||
{
|
||||
title: l('Actions'),
|
||||
rowAction: {
|
||||
items:
|
||||
[
|
||||
{
|
||||
text: l('Edit'),
|
||||
action: function (data) {
|
||||
//TODO: Open a modal to edit the book
|
||||
}
|
||||
},
|
||||
{
|
||||
text: l('Delete'),
|
||||
confirmMessage: function (data) {
|
||||
return "Are you sure to delete the book " + data.record.name;
|
||||
},
|
||||
action: function (data) {
|
||||
acme.bookStore.books.book
|
||||
.delete(data.record.id)
|
||||
.then(function() {
|
||||
abp.notify.info("Successfully deleted!");
|
||||
data.table.ajax.reload();
|
||||
});
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
````
|
||||
|
||||
#### Action Items
|
||||
|
||||
`items` is an array of action definitions. An action definition can have the following options;
|
||||
|
||||
* `text`: The text (a `string`) for this action to be shown in the actions drop down.
|
||||
* `action`: A `function` that is executed when the user clicks to the action. The function takes a `data` argument that has the following fields;
|
||||
* `data.record`: This is the data object related to the row. You can access the data fields like `data.record.id`, `data.record.name`... etc.
|
||||
* `data.table`: The DataTables instance.
|
||||
* `confirmMessage`: A `function` (see the example above) that returns a message (`string`) to show a dialog to get a confirmation from the user before executing the `action`. Example confirmation dialog:
|
||||
|
||||
|
||||
|
||||
You can use the [localization](JavaScript-API/Localization.md) system to show a localized message.
|
||||
|
||||
* `visible`: A `bool` or a `function` that returns a `bool`. If the result is `false`, then the action is not shown in the actions dropdown. This is generally combined by the [authorization](JavaScript-API/Auth.md) system to hide the action if the user has no permission to take this action. Example:
|
||||
|
||||
````js
|
||||
visible: abp.auth.isGranted('BookStore.Books.Delete');
|
||||
````
|
||||
|
||||
If you define a `function`, then the `function` has two arguments: `record` (the data object of the related row) and the `table` (the DataTable instance). So, you can decide to show/hide the action dynamically, based on the row data and other conditions.
|
||||
|
||||
* `iconClass`: Can be used to show a font-icon, like a [Font-Awesome](https://fontawesome.com/) icon (ex: `fas fa-trash-alt`), near to the action text. Example screenshot:
|
||||
|
||||
|
||||
|
||||
* `enabled`: A `function` that returns a `bool` to disable the action. The `function` takes a `data` object with two fields: `data.record` is the data object related to the row and `data.table` is the DataTables instance.
|
||||
* `displayNameHtml`: Set this to `true` is the `text` value contains HTML tags.
|
||||
|
||||
There are some rules with the action items;
|
||||
|
||||
* If none of the action items is visible then the actions column is not rendered.
|
||||
|
||||
### Data Format
|
||||
|
||||
#### The Problem
|
||||
|
||||
See the *Creation Time* column in the example below:
|
||||
|
||||
````js
|
||||
{
|
||||
title: l('CreationTime'),
|
||||
data: "creationTime",
|
||||
render: function (data) {
|
||||
return luxon
|
||||
.DateTime
|
||||
.fromISO(data, {
|
||||
locale: abp.localization.currentCulture.name
|
||||
}).toLocaleString(luxon.DateTime.DATETIME_SHORT);
|
||||
}
|
||||
}
|
||||
````
|
||||
|
||||
The `render` is a standard DataTables option to render the column content by a custom function. This example uses the [luxon](https://moment.github.io/luxon/) library (which is installed by default) to write a human readable value of the `creationTime` in the current user's language. Example output of the column:
|
||||
|
||||
|
||||
|
||||
If you don't define the render option, then the result will be ugly and not user friendly:
|
||||
|
||||
|
||||
|
||||
However, rendering a `DateTime` is almost same and repeating the same rendering logic everywhere is against to the DRY (Don't Repeat Yourself!) principle.
|
||||
|
||||
#### dataFormat Option
|
||||
|
||||
`dataFormat` column option specifies the data format that is used to render the column data. The same output could be accomplished using the following column definition:
|
||||
|
||||
````js
|
||||
{
|
||||
title: l('CreationTime'),
|
||||
data: "creationTime",
|
||||
dataFormat: 'datetime'
|
||||
}
|
||||
````
|
||||
|
||||
`dataFormat: 'datetime'` specifies the data format for this column. There are a few pre-defined `dataFormat`s:
|
||||
|
||||
* `boolean`: Shows a `check` icon for `true` and `times` icon for `false` value and useful to render `bool` values.
|
||||
* `date`: Shows date part of a `DateTime` value, formatted based on the current culture.
|
||||
* `datetime`: Shows date & time (excluding seconds) of a `DateTime` value, formatted based on the current culture.
|
||||
|
||||
### Default Renderers
|
||||
|
||||
`abp.libs.datatables.defaultRenderers` option allows you to define new data formats and set renderers for them.
|
||||
|
||||
**Example: Render male / female icons based on the gender**
|
||||
|
||||
````js
|
||||
abp.libs.datatables.defaultRenderers['gender'] = function(value) {
|
||||
if (value === 'f') {
|
||||
return '<i class="fa fa-venus"></i>';
|
||||
} else {
|
||||
return '<i class="fa fa-mars"></i>';
|
||||
}
|
||||
};
|
||||
````
|
||||
|
||||
Assuming that the possible values for a column data is `f` and `m`, the `gender` data format shows female/male icons instead of `f` and `m` texts. You can now set `dataFormat: 'gender'` for a column definition that has the proper data values.
|
||||
|
||||
> You can write the default renderers in a single JavaScript file and add it to the [Global Script Bundle](Bundling-Minification.md), so you can reuse them in all the pages.
|
||||
|
||||
## Other Data Grids
|
||||
|
||||
You can use any library you like. For example, [see this article](https://community.abp.io/articles/using-devextreme-components-with-the-abp-framework-zb8z7yqv) to learn how to use DevExtreme Data Grid in your applications.
|
||||
@ -0,0 +1,58 @@
|
||||
# ASP.NET Core MVC / Razor Pages: Page Header
|
||||
|
||||
`IPageLayout` service can be used to set the page title, selected menu item and the breadcrumb items for a page. It's the [theme](Theming.md)'s responsibility to render these on the page.
|
||||
|
||||
## IPageLayout
|
||||
|
||||
`IPageLayout` can be injected in any page/view to set the page header properties.
|
||||
|
||||
### Page Title
|
||||
|
||||
Page Title can be set as shown in the example below:
|
||||
|
||||
````csharp
|
||||
@inject IPageLayout PageLayout
|
||||
@{
|
||||
PageLayout.Content.Title = "Book List";
|
||||
}
|
||||
````
|
||||
|
||||
* The Page Title is set to the HTML `title` tag (in addition to the [brand/application name](Branding.md)).
|
||||
* The theme may render the Page Title before the Page Content (not implemented by the Basic Theme).
|
||||
|
||||
### Breadcrumb
|
||||
|
||||
> **The [Basic Theme](Basic-Theme.md) currently doesn't implement the breadcrumbs.**
|
||||
|
||||
Breadcrumb items can be added to the `PageLayout.Content.BreadCrumb`.
|
||||
|
||||
**Example: Add Language Management to the breadcrumb items.**
|
||||
|
||||
````
|
||||
PageLayout.Content.BreadCrumb.Add("Language Management");
|
||||
````
|
||||
|
||||
The theme then renders the breadcrumb. An example render result can be:
|
||||
|
||||
|
||||
|
||||
* The Home icon is rendered by default. Set `PageLayout.Content.BreadCrumb.ShowHome` to `false` to hide it.
|
||||
* Current Page name (got from the `PageLayout.Content.Title`) is added as the last by default. Set `PageLayout.Content.BreadCrumb.ShowCurrent` to `false` to hide it.
|
||||
|
||||
Any item that you add is inserted between Home and Current Page items. You can add as many item as you need. `BreadCrumb.Add(...)` method gets three parameters:
|
||||
|
||||
* `text`: The text to show for the breadcrumb item.
|
||||
* `url` (optional): A URL to navigate to, if the user clicks to the breadcrumb item.
|
||||
* `icon` (optional): An icon class (like `fas fa-user-tie` for Font-Awesome) to show with the `text`.
|
||||
|
||||
### The Selected Menu Item
|
||||
|
||||
> **The [Basic Theme](Basic-Theme.md) currently doesn't implement the selected menu item since it is not applicable to the top menu which is the only option for the Basic Theme for now.**
|
||||
|
||||
You can set the Menu Item name related to this page:
|
||||
|
||||
````csharp
|
||||
PageLayout.Content.MenuItemName = "BookStore.Books";
|
||||
````
|
||||
|
||||
Menu item name should match a unique menu item name defined using the [Navigation / Menu](Navigation-Menu.md) system. In this case, it is expected from the theme to make the menu item "active" in the main menu.
|
||||
@ -1,3 +1,436 @@
|
||||
# ASP.NET Core MVC / Razor Pages Theming
|
||||
# ASP.NET Core MVC / Razor Pages: 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 NuGet/NPM packages, 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 [navigation menus](Navigation-Menu.md), [toolbars](Toolbars.md), [layout hooks](Layout-Hooks.md)... that is implemented by all the themes. So, the modules and the application to 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.
|
||||
|
||||
There are also some community-driven themes for the ABP Framework (you can search on the web).
|
||||
|
||||
## Overall
|
||||
|
||||
### The Base Libraries
|
||||
|
||||
All the themes must depend on the [@abp/aspnetcore.mvc.ui.theme.shared](https://www.npmjs.com/package/@abp/aspnetcore.mvc.ui.theme.shared) NPM package, so they are indirectly depending on the following libraries:
|
||||
|
||||
* [Twitter Bootstrap](https://getbootstrap.com/) as the fundamental HTML/CSS framework.
|
||||
* [JQuery](https://jquery.com/) for DOM manipulation.
|
||||
* [DataTables.Net](https://datatables.net/) for data grids.
|
||||
* [JQuery Validation](https://jqueryvalidation.org/) for client side & [unobtrusive](https://github.com/aspnet/jquery-validation-unobtrusive) validation
|
||||
* [FontAwesome](https://fontawesome.com/) as the fundamental CSS font library.
|
||||
* [SweetAlert](https://sweetalert.js.org/) to show fancy alert message and confirmation dialogs.
|
||||
* [Toastr](https://github.com/CodeSeven/toastr) to show toast notifications.
|
||||
* [Lodesh](https://lodash.com/) as a utility library.
|
||||
* [Luxon](https://moment.github.io/luxon/) for date/time operations.
|
||||
* [JQuery Form](https://github.com/jquery-form/form) for AJAX forms.
|
||||
* [bootstrap-datepicker](https://github.com/uxsolutions/bootstrap-datepicker) to show date pickers.
|
||||
* [Select2](https://select2.org/) for better select/combo boxes.
|
||||
* [Timeago](http://timeago.yarp.com/) to show automatically updating fuzzy timestamps.
|
||||
* [malihu-custom-scrollbar-plugin](https://github.com/malihu/malihu-custom-scrollbar-plugin) for custom scrollbars.
|
||||
|
||||
These libraries are selected as the base libraries and available to the applications and modules.
|
||||
|
||||
#### Abstractions / Wrappers
|
||||
|
||||
There are some abstractions in the ABP Framework to make your code independent from some of these libraries too. Examples;
|
||||
|
||||
* [Tag Helpers](Tag-Helpers/Index.md) makes it easy to generate the Bootstrap UIs.
|
||||
* JavaScript [Message](JavaScript-API/Message.md) and [Notification](JavaScript-API/Notify.md) APIs provides abstractions to use the Sweetalert and Toastr.
|
||||
* [Forms & Validation](Forms-Validation.md) system automatically handles the validation, so you mostly don't directly type any validation code.
|
||||
|
||||
### The Standard Layouts
|
||||
|
||||
The main responsibility of a theme is to provide the layouts. There are **three pre-defined layouts must be implemented by all the themes**:
|
||||
|
||||
* **Application**: The default layout which is used by the main application pages.
|
||||
* **Account**: Mostly used by the [account module](../../Modules/Account.md) for login, register, forgot password... pages.
|
||||
* **Empty**: The Minimal layout that has no layout components at all.
|
||||
|
||||
Layout names are constants defined in the `Volo.Abp.AspNetCore.Mvc.UI.Theming.StandardLayouts` class.
|
||||
|
||||
#### The Application Layout
|
||||
|
||||
This is the default layout which is used by the main application pages. 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;
|
||||
|
||||
* A [main menu](Navigation-Menu.md)
|
||||
* Main [Toolbar](Toolbars.md) with the following components;
|
||||
* User menu
|
||||
* Language switch dropdown
|
||||
* [Page alerts](Page-Alerts.md)
|
||||
* The page content (aka `RenderBody()`)
|
||||
* [Layout hooks](Layout-Hooks.md)
|
||||
|
||||
Some themes may provide more parts like breadcrumbs, page header & toolbar... etc. See the *Layout Parts* section.
|
||||
|
||||
#### The Account Layout
|
||||
|
||||
The Account layout is typically used by the [account module](../../Modules/Account.md) for login, register, forgot password... pages.
|
||||
|
||||
|
||||
|
||||
This layout typically provides the following parts;
|
||||
|
||||
* Language switch dropdown
|
||||
* Tenant switch area (if the application is [multi-tenant](../../Multi-Tenancy.md) and the current is resolved by the cookie)
|
||||
* [Page alerts](Page-Alerts.md)
|
||||
* The page content (aka `RenderBody()`)
|
||||
* [Layout hooks](Layout-Hooks.md)
|
||||
|
||||
The [Basic Theme](Basic-Theme.md) renders the top navigation bar for this layout too (as shown above)
|
||||
|
||||
Here, the account layout of the Lepton Theme:
|
||||
|
||||
|
||||
|
||||
The [Lepton Theme](https://commercial.abp.io/themes) shows the application logo and footer in this layout.
|
||||
|
||||
> You can override theme layouts completely or partially in an application to [customize](Customization-User-Interface.md) it.
|
||||
|
||||
#### The Empty Layout
|
||||
|
||||
The empty layout provides an empty page. It typically includes the following parts;
|
||||
|
||||
* [Page alerts](Page-Alerts.md)
|
||||
* The page content (aka `RenderBody()`)
|
||||
* [Layout hooks](Layout-Hooks.md)
|
||||
|
||||
## Implementing a Theme
|
||||
|
||||
### The Easy Way
|
||||
|
||||
The easiest way to create a new theme is to copy the [Basic Theme Source Code](https://github.com/abpframework/abp/tree/dev/framework/src/Volo.Abp.AspNetCore.Mvc.UI.Theme.Basic) and customize it. Once you get a copy of the theme in your solution, remove the `Volo.Abp.AspNetCore.Mvc.UI.Theme.Basic` NuGet package and reference to the local project.
|
||||
|
||||
### The ITheme Interface
|
||||
|
||||
`ITheme` interface is used by the ABP Framework to select the layout for the current page. A theme must implement this interface to provide the requested layout path.
|
||||
|
||||
This is the `ITheme` implementation of the [Basic Theme](Basic-Theme.md).
|
||||
|
||||
````csharp
|
||||
using Volo.Abp.AspNetCore.Mvc.UI.Theming;
|
||||
using Volo.Abp.DependencyInjection;
|
||||
|
||||
namespace Volo.Abp.AspNetCore.Mvc.UI.Theme.Basic
|
||||
{
|
||||
[ThemeName(Name)]
|
||||
public class BasicTheme : ITheme, ITransientDependency
|
||||
{
|
||||
public const string Name = "Basic";
|
||||
|
||||
public virtual string GetLayout(string name, bool fallbackToDefault = true)
|
||||
{
|
||||
switch (name)
|
||||
{
|
||||
case StandardLayouts.Application:
|
||||
return "~/Themes/Basic/Layouts/Application.cshtml";
|
||||
case StandardLayouts.Account:
|
||||
return "~/Themes/Basic/Layouts/Account.cshtml";
|
||||
case StandardLayouts.Empty:
|
||||
return "~/Themes/Basic/Layouts/Empty.cshtml";
|
||||
default:
|
||||
return fallbackToDefault
|
||||
? "~/Themes/Basic/Layouts/Application.cshtml"
|
||||
: null;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
````
|
||||
|
||||
* `[ThemeName]` attribute is required and a theme must have a unique name, `Basic` in this sample.
|
||||
* `GetLayout` method should return a path if the requested layout (`name`) is provided by the theme. *The Standard Layouts* should be implemented if the theme is aimed to be used by a standard application. It may implement additional layouts.
|
||||
|
||||
Once the theme implements the `ITheme` interface, it should add the theme to the `AbpThemingOptions` in the `ConfigureServices` method of the [module](../../Module-Development-Basics.md).
|
||||
|
||||
````csharp
|
||||
Configure<AbpThemingOptions>(options =>
|
||||
{
|
||||
options.Themes.Add<BasicTheme>();
|
||||
});
|
||||
````
|
||||
|
||||
#### The IThemeSelector Service
|
||||
|
||||
ABP Framework allows to use multiple themes together. This is why `options.Themes` is a list. `IThemeSelector` service selects the theme on the runtime. The application developer can set the `AbpThemingOptions.DefaultThemeName` to set the theme to be used, or replace the `IThemeSelector` service implementation (the default implementation is `DefaultThemeSelector`) to completely control the theme selection on runtime.
|
||||
|
||||
### Bundles
|
||||
|
||||
[Bundling system](Bundling-Minification.md) provides a standard way to import style & script files into pages. There are two standard bundles defined by the ABP Framework:
|
||||
|
||||
* `StandardBundles.Styles.Global`: The global bundle that includes the style files used in all the pages. Typically, it includes the CSS files of the Base Libraries.
|
||||
* `StandardBundles.Scripts.Global`: The global bundle that includes the script files used in all the pages. Typically, it includes the JavaScript files of the Base Libraries.
|
||||
|
||||
A theme generally extends these standard bundles by adding theme specific CSS/JavaScript files.
|
||||
|
||||
The best way to define new bundles, inherit from the standard bundles and add to the `AbpBundlingOptions` as shown below (this code is from the [Basic Theme](Basic-Theme.md)):
|
||||
|
||||
````csharp
|
||||
Configure<AbpBundlingOptions>(options =>
|
||||
{
|
||||
options
|
||||
.StyleBundles
|
||||
.Add(BasicThemeBundles.Styles.Global, bundle =>
|
||||
{
|
||||
bundle
|
||||
.AddBaseBundles(StandardBundles.Styles.Global)
|
||||
.AddContributors(typeof(BasicThemeGlobalStyleContributor));
|
||||
});
|
||||
|
||||
options
|
||||
.ScriptBundles
|
||||
.Add(BasicThemeBundles.Scripts.Global, bundle =>
|
||||
{
|
||||
bundle
|
||||
.AddBaseBundles(StandardBundles.Scripts.Global)
|
||||
.AddContributors(typeof(BasicThemeGlobalScriptContributor));
|
||||
});
|
||||
});
|
||||
````
|
||||
|
||||
`BasicThemeGlobalStyleContributor` and `BasicThemeGlobalScriptContributor` are bundle contributors. For example, `BasicThemeGlobalStyleContributor` is defined as shown below:
|
||||
|
||||
```csharp
|
||||
public class BasicThemeGlobalStyleContributor : BundleContributor
|
||||
{
|
||||
public override void ConfigureBundle(BundleConfigurationContext context)
|
||||
{
|
||||
context.Files.Add("/themes/basic/layout.css");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then the theme can render these bundles in a layout. For example, you can render the Global Styles as shown below:
|
||||
|
||||
````html
|
||||
<abp-style-bundle name="@BasicThemeBundles.Styles.Global" />
|
||||
````
|
||||
|
||||
See the [Bundle & Minification](Bundling-Minification.md) document to understand the Bundling system better.
|
||||
|
||||
### 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 toolbar item, to change the application name in the branding 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.
|
||||
|
||||
#### Branding
|
||||
|
||||
`IBrandingProvider` service should be used to get the name and the logo URL of the application to render in the Branding part.
|
||||
|
||||
The [Application Startup Template](../../Startup-Templates/Application.md) has an implementation of this interface to set the values by the application developer.
|
||||
|
||||
#### Main Menu
|
||||
|
||||
`IMenuManager` service is used to get the main menu items and render on the layout.
|
||||
|
||||
**Example: Get the Main Menu to render in a view component**
|
||||
|
||||
```csharp
|
||||
public class MainNavbarMenuViewComponent : AbpViewComponent
|
||||
{
|
||||
private readonly IMenuManager _menuManager;
|
||||
|
||||
public MainNavbarMenuViewComponent(IMenuManager menuManager)
|
||||
{
|
||||
_menuManager = menuManager;
|
||||
}
|
||||
|
||||
public async Task<IViewComponentResult> InvokeAsync()
|
||||
{
|
||||
var menu = await _menuManager.GetAsync(StandardMenus.Main);
|
||||
return View("~/Themes/Basic/Components/Menu/Default.cshtml", menu);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
See the [Navigation / Menus](Navigation-Menu.md) document to learn more about the navigation system.
|
||||
|
||||
#### Main Toolbar
|
||||
|
||||
`IToolbarManager` service is used to get the Main Toolbar items and render on the layout. Each item of this toolbar is a View Component, so it may include any type of UI elements. Inject the `IToolbarManager` and use the `GetAsync` to get the toolbar items:
|
||||
|
||||
````csharp
|
||||
var toolbar = await _toolbarManager.GetAsync(StandardToolbars.Main);
|
||||
````
|
||||
|
||||
> See the [Toolbars](Toolbars.md) document to learn more on the toolbar system.
|
||||
|
||||
The theme has a responsibility to add two pre-defined items to the main toolbar: Language Selection and User Menu. To do that, create a class implementing the `IToolbarContributor` interface and add it to the `AbpToolbarOptions` as shown below:
|
||||
|
||||
```csharp
|
||||
Configure<AbpToolbarOptions>(options =>
|
||||
{
|
||||
options.Contributors.Add(new BasicThemeMainTopToolbarContributor());
|
||||
});
|
||||
```
|
||||
|
||||
##### Language Selection
|
||||
|
||||
Language Selection toolbar item is generally a dropdown that is used to switch between languages. `ILanguageProvider` is used to get the list of available languages and `CultureInfo.CurrentUICulture` is used to learn the current language.
|
||||
|
||||
`/Abp/Languages/Switch` endpoint can be used to switch the language This endpoint accepts the following query string parameters:
|
||||
|
||||
* `culture`: The selected culture, like `en-US` or `en`.
|
||||
* `uiCulture`: The selected UI culture, like `en-US` or `en`.
|
||||
* `returnUrl` (optional): Can be used to return a given URL after switching the language.
|
||||
|
||||
`culture` and `uiCulture` should match one of the available languages. ABP Framework sets a culture cookie in the `/Abp/Languages/Switch` endpoint.
|
||||
|
||||
##### User Menu
|
||||
|
||||
User menu includes links related to the user account. `IMenuManager` is used just like the Main Menu, but this time with `StandardMenus.User` parameter like shown below:
|
||||
|
||||
````csharp
|
||||
var menu = await _menuManager.GetAsync(StandardMenus.User);
|
||||
````
|
||||
|
||||
[ICurrentUser](../../CurrentUser.md) and [ICurrentTenant](../../Multi-Tenancy.md) services can be used to obtain the current user and tenant names.
|
||||
|
||||
#### Page Alerts
|
||||
|
||||
`IAlertManager` service is used to get the current page alerts to render on the layout. Use the `Alerts` list of the `IAlertManager`. It is generally rendered just before the page content (`RenderBody()`).
|
||||
|
||||
See the [Page Alerts](Page-Alerts.md) document to learn more.
|
||||
|
||||
#### Layout Hooks
|
||||
|
||||
Since the Layout is in the theme package, the final application or any module can't directly manipulate the layout content. The [Layout Hook](Layout-Hooks.md) system allows to inject components to some specific points of the layout.
|
||||
|
||||
The theme is responsible to render the hooks in the correct place.
|
||||
|
||||
**Example: Render the `LayoutHooks.Head.First` Hook in the Application Layout**
|
||||
|
||||
````html
|
||||
<head>
|
||||
@await Component.InvokeLayoutHookAsync(LayoutHooks.Head.First, StandardLayouts.Application)
|
||||
...
|
||||
````
|
||||
|
||||
See the [Layout Hook](Layout-Hooks.md) document to learn the standard layout hooks.
|
||||
|
||||
#### Script / Style Sections
|
||||
|
||||
Every layout should render the following optional sections:
|
||||
|
||||
* `styles` section is rendered in the end of the `head`, just before the `LayoutHooks.Head.Last`.
|
||||
* `scripts` section is rendered in the end of the `body`, just before the `LayoutHooks.Body.Last`.
|
||||
|
||||
In this way, the page can import styles and scripts to the layout.
|
||||
|
||||
**Example: Render the `styles` section**
|
||||
|
||||
````csharp
|
||||
@await RenderSectionAsync("styles", required: false)
|
||||
````
|
||||
|
||||
#### Content Toolbar Section
|
||||
|
||||
Another pre-defined section is the Content Toolbar section which can be used by the pages to add code just before the page content. The Basic Theme renders it as shown below:
|
||||
|
||||
````html
|
||||
<div id="AbpContentToolbar">
|
||||
<div class="text-right mb-2">
|
||||
@RenderSection("content_toolbar", false)
|
||||
</div>
|
||||
</div>
|
||||
````
|
||||
|
||||
The container div's id must be `AbpContentToolbar`. This section should come before the `RenderBody()`.
|
||||
|
||||
#### Widget Resources
|
||||
|
||||
The [Widget System](Widgets.md) allows to define reusable widgets with their own style/script files. All the layouts should render the widget style and scripts.
|
||||
|
||||
**Widget Styles** is rendered as shown below, just before the `styles` section, after the global style bundle:
|
||||
|
||||
````csharp
|
||||
@await Component.InvokeAsync(typeof(WidgetStylesViewComponent))
|
||||
````
|
||||
|
||||
**Widget Scripts** is rendered as shown below, just before the `scripts` section, after the global script bundle:
|
||||
|
||||
````csharp
|
||||
@await Component.InvokeAsync(typeof(WidgetScriptsViewComponent))
|
||||
````
|
||||
|
||||
#### ABP Scripts
|
||||
|
||||
ABP has some special scripts those should be included into every layout. They are not included in the global bundles since they are dynamically created based on the current user.
|
||||
|
||||
ABP scripts (`ApplicationConfigurationScript` and `ServiceProxyScript`) should be added just after the global script bundle, as shown below:
|
||||
|
||||
````html
|
||||
<script src="~/Abp/ApplicationConfigurationScript"></script>
|
||||
<script src="~/Abp/ServiceProxyScript"></script>
|
||||
````
|
||||
|
||||
#### Page Title, Selected Menu Item and Breadcrumbs
|
||||
|
||||
`IPageLayout` service can be injected by any page to set the Page Title, the selected menu item name and the breadcrumb items. Then the theme can use this service to get these values and render on the UI.
|
||||
|
||||
The Basic Theme doesn't implement this service, but the Lepton Theme implements:
|
||||
|
||||
|
||||
|
||||
See the [Page Header](Page-Header.md) document for more.
|
||||
|
||||
#### Tenant Switch
|
||||
|
||||
The Account Layout should allow the user to switch the current tenant if the application is multi-tenant and the tenant was resolved from the cookies. See the [Basic Theme Account Layout](https://github.com/abpframework/abp/blob/dev/framework/src/Volo.Abp.AspNetCore.Mvc.UI.Theme.Basic/Themes/Basic/Layouts/Account.cshtml) as an example implementation.
|
||||
|
||||
### Layout Classes
|
||||
|
||||
The Standard Layouts (`Application`, `Account` and `Empty`) should add the following CSS classes to the `body` tag:
|
||||
|
||||
* `abp-application-layout` for the `Application` layout.
|
||||
* `abp-account-layout` for the `Account` layout.
|
||||
* `abp-empty-layout` for the `Empty` layout.
|
||||
|
||||
In this way, applications or modules can have selectors based on the current layout.
|
||||
|
||||
### RTL
|
||||
|
||||
To support Right-To-Left languages, the Layout should check the current culture and add `dir="rtl"` to the `html` tag and `rtl` CSS class the the `body` tag.
|
||||
|
||||
You can check `CultureInfo.CurrentUICulture.TextInfo.IsRightToLeft` to understand if the current language is a RTL language.
|
||||
|
||||
### The NPM Package
|
||||
|
||||
A theme should have a NPM package that depends on the [@abp/aspnetcore.mvc.ui.theme.shared](https://www.npmjs.com/package/@abp/aspnetcore.mvc.ui.theme.shared) package. In this way, it inherits all the Base Libraries. If the theme requires additional libraries, then it should define these dependencies too.
|
||||
|
||||
Applications use the [Client Side Package Management](Client-Side-Package-Management.md) system to add client side libraries to the project. So, if an application uses your theme, it should add dependency to your theme's NPM package as well as the NuGet package dependency.
|
||||
|
||||
TODO
|
||||
@ -1,3 +1,74 @@
|
||||
# Toolbars
|
||||
|
||||
TODO
|
||||
The Toolbar system is used to define **toolbars** on the user interface. Modules (or your application) can add **items** to a toolbar, then the [theme](Theming.md) renders the toolbar on the **layout**.
|
||||
|
||||
There is only one **standard toolbar** named "Main" (defined as a constant: `StandardToolbars.Main`). The [Basic Theme](Basic-Theme) renders the main toolbar as shown below:
|
||||
|
||||
|
||||
|
||||
In the screenshot above, there are two items added to the main toolbar: Language switch component & user menu. You can add your own items here.
|
||||
|
||||
## Example: Add a Notification Icon
|
||||
|
||||
In this example, we will add a **notification (bell) icon** to the left of the language switch item. A item in the toolbar should be a **view component**. So, first, create a new view component in your project:
|
||||
|
||||
|
||||
|
||||
**NotificationViewComponent.cs**
|
||||
|
||||
````csharp
|
||||
public class NotificationViewComponent : AbpViewComponent
|
||||
{
|
||||
public async Task<IViewComponentResult> InvokeAsync()
|
||||
{
|
||||
return View("/Pages/Shared/Components/Notification/Default.cshtml");
|
||||
}
|
||||
}
|
||||
````
|
||||
|
||||
**Default.cshtml**
|
||||
|
||||
````xml
|
||||
<div id="MainNotificationIcon" style="color: white; margin: 8px;">
|
||||
<i class="far fa-bell"></i>
|
||||
</div>
|
||||
````
|
||||
|
||||
Now, we can create a class implementing the `IToolbarContributor` interface:
|
||||
|
||||
````csharp
|
||||
public class MyToolbarContributor : IToolbarContributor
|
||||
{
|
||||
public Task ConfigureToolbarAsync(IToolbarConfigurationContext context)
|
||||
{
|
||||
if (context.Toolbar.Name == StandardToolbars.Main)
|
||||
{
|
||||
context.Toolbar.Items
|
||||
.Insert(0, new ToolbarItem(typeof(NotificationViewComponent)));
|
||||
}
|
||||
|
||||
return Task.CompletedTask;
|
||||
}
|
||||
}
|
||||
````
|
||||
|
||||
This class adds the `NotificationViewComponent` as the first item in the `Main` toolbar.
|
||||
|
||||
Finally, you need to add this contributor to the `AbpToolbarOptions`, in the `ConfigureServices` of your [module](../../Module-Development-Basics.md):
|
||||
|
||||
````csharp
|
||||
Configure<AbpToolbarOptions>(options =>
|
||||
{
|
||||
options.Contributors.Add(new MyToolbarContributor());
|
||||
});
|
||||
````
|
||||
|
||||
That's all, you will see the notification icon on the toolbar when you run the application:
|
||||
|
||||
|
||||
|
||||
`NotificationViewComponent` in this sample simply returns a view without any data. In real life, you probably want to **query database** (or call an HTTP API) to get notifications and pass to the view. If you need, you can add a `JavaScript` or `CSS` file to the global [bundle](Bundling-Minification.md) for your toolbar item.
|
||||
|
||||
## IToolbarManager
|
||||
|
||||
`IToolbarManager` is used to render the toolbar. It returns the toolbar items by a toolbar name. This is generally used by the [themes](Theming.md) to render the toolbar on the layout.
|
||||
|
After Width: | Height: | Size: 47 KiB |
|
After Width: | Height: | Size: 76 KiB |
|
After Width: | Height: | Size: 64 KiB |
|
After Width: | Height: | Size: 31 KiB |
|
After Width: | Height: | Size: 9.6 KiB |
|
After Width: | Height: | Size: 12 KiB |
|
After Width: | Height: | Size: 16 KiB |
|
After Width: | Height: | Size: 49 KiB |
|
After Width: | Height: | Size: 41 KiB |
|
After Width: | Height: | Size: 12 KiB |
|
After Width: | Height: | Size: 19 KiB |
|
After Width: | Height: | Size: 14 KiB |
|
After Width: | Height: | Size: 89 KiB |
|
After Width: | Height: | Size: 211 KiB |
@ -1,194 +1,160 @@
|
||||
## 在AspNet Core MVC Web Application中使用ABP
|
||||
|
||||
本教程将介绍如何开始以最少的依赖关系开始使用ABP开发.
|
||||
|
||||
通常情况下你需要下载一个 ***[启动模板](Getting-Started-AspNetCore-MVC-Template.md)***
|
||||
|
||||
### 创建一个新项目
|
||||
|
||||
1. 使用Visual Studio创建一个空的AspNet Core Web Application:
|
||||
|
||||
|
||||
|
||||
2. 选择空模板
|
||||
|
||||
|
||||
|
||||
你可以选择其它模板,但是我想要从一个简洁的项目演示它.
|
||||
|
||||
### 安装 Volo.Abp.AspNetCore.Mvc 包
|
||||
|
||||
Volo.Abp.AspNetCore.Mvc是ABP集成AspNet Core MVC的包,请安装它到你项目中:
|
||||
|
||||
````
|
||||
Install-Package Volo.Abp.AspNetCore.Mvc
|
||||
````
|
||||
|
||||
### 创建ABP模块
|
||||
|
||||
ABP是一个模块化框架,它需要一个**启动 (根) 模块**继承自``AbpModule``:
|
||||
|
||||
````C#
|
||||
using Microsoft.AspNetCore.Builder;
|
||||
using Microsoft.Extensions.Hosting;
|
||||
using Volo.Abp;
|
||||
using Volo.Abp.AspNetCore.Mvc;
|
||||
using Volo.Abp.Modularity;
|
||||
|
||||
namespace BasicAspNetCoreApplication
|
||||
{
|
||||
[DependsOn(typeof(AbpAspNetCoreMvcModule))]
|
||||
public class AppModule : AbpModule
|
||||
{
|
||||
public override void OnApplicationInitialization(
|
||||
ApplicationInitializationContext context)
|
||||
{
|
||||
var app = context.GetApplicationBuilder();
|
||||
var env = context.GetEnvironment();
|
||||
|
||||
if (env.IsDevelopment())
|
||||
{
|
||||
app.UseDeveloperExceptionPage();
|
||||
}
|
||||
else
|
||||
{
|
||||
app.UseExceptionHandler("/Error");
|
||||
}
|
||||
|
||||
app.UseStaticFiles();
|
||||
app.UseRouting();
|
||||
app.UseConfiguredEndpoints();
|
||||
}
|
||||
}
|
||||
}
|
||||
````
|
||||
|
||||
``AppModule`` 是应用程序启动模块的好名称(建议你的启动模块也使用这个命名).
|
||||
|
||||
ABP的包定义了这个模块类,模块可以依赖其它模块.在上面的代码中 ``AppModule`` 依赖于 ``AbpAspNetCoreMvcModule`` (模块存在于Volo.Abp.AspNetCore.Mvc包中). 安装新的ABP的包后添加``DependsOn``是很常见的做法.
|
||||
|
||||
我们在此模块类中配置ASP.NET Core管道,而不是Startup类中.
|
||||
|
||||
### 启动类
|
||||
|
||||
接下来修改启动类集成ABP模块系统:
|
||||
|
||||
````C#
|
||||
using System;
|
||||
using Microsoft.AspNetCore.Builder;
|
||||
using Microsoft.Extensions.DependencyInjection;
|
||||
|
||||
namespace BasicAspNetCoreApplication
|
||||
{
|
||||
public class Startup
|
||||
{
|
||||
public IServiceProvider ConfigureServices(IServiceCollection services)
|
||||
{
|
||||
services.AddApplication<AppModule>();
|
||||
|
||||
return services.BuildServiceProviderFromFactory();
|
||||
}
|
||||
|
||||
public void Configure(IApplicationBuilder app)
|
||||
{
|
||||
app.InitializeApplication();
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
````
|
||||
|
||||
修改``ConfigureServices``方法的返回值为``IServiceProvider``(默认是``void``).这个修改允许我们替换AspNet Core的依赖注入框架. (参阅下面的Autofac集成部分). ``services.AddApplication<AppModule>()``添加了所有模块中定义的全部服务.
|
||||
|
||||
``app.InitializeApplication()`` 调用 ``Configure`` 方法初始化并启动应用程序
|
||||
|
||||
### Hello World!
|
||||
|
||||
上面的应用程序没有什么功能,让我们创建一个MVC控制器实现一些功能:
|
||||
|
||||
````C#
|
||||
using Microsoft.AspNetCore.Mvc;
|
||||
using Volo.Abp.AspNetCore.Mvc;
|
||||
|
||||
namespace BasicAspNetCoreApplication.Controllers
|
||||
{
|
||||
public class HomeController : AbpController
|
||||
{
|
||||
public IActionResult Index()
|
||||
{
|
||||
return Content("Hello World!");
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
````
|
||||
|
||||
如果运行这个应用程序你会在页面中看到"Hello World!".
|
||||
|
||||
Derived ``HomeController`` from ``AbpController`` instead of standard ``Controller`` class. This is not required, but ``AbpController`` class has useful base properties and methods to make your development easier.
|
||||
|
||||
从``AbpController``派生``HomeController`` 而不是继承自``Controller``类.虽然这不是强制要求,但是``AbpController``类有很多有用的有属性和方法,使你的开发更容易.
|
||||
|
||||
### 使用 Autofac 依赖注入框架
|
||||
|
||||
虽然AspNet Core的依赖注入(DI)系统适用于基本要求,但Autofac提供了属性注入和方法拦截等高级功能,这些功能是ABP执行高级应用程序框架功能所必需的.
|
||||
|
||||
用Autofac取代AspNet Core的DI系统并集成到ABP非常简单.
|
||||
|
||||
1. 安装 Volo.Abp.Autofac 包
|
||||
|
||||
````
|
||||
Install-Package Volo.Abp.Autofac
|
||||
````
|
||||
|
||||
2. 添加 ``AbpAutofacModule`` 依赖
|
||||
|
||||
````C#
|
||||
[DependsOn(typeof(AbpAspNetCoreMvcModule))]
|
||||
[DependsOn(typeof(AbpAutofacModule))] // 在模块上添加依赖AbpAutofacModule
|
||||
public class AppModule : AbpModule
|
||||
{
|
||||
...
|
||||
}
|
||||
````
|
||||
|
||||
3. 修改在``Startup``类下的``services.AddApplication<AppModule>();``如下所示:
|
||||
|
||||
````C#
|
||||
services.AddApplication<AppModule>(options =>
|
||||
{
|
||||
options.UseAutofac(); // 集成 Autofac
|
||||
});
|
||||
````
|
||||
|
||||
4. 更新 `Program.cs`代码, 不再使用`WebHost.CreateDefaultBuilder()`方法(因为它使用默认的DI容器):
|
||||
|
||||
````csharp
|
||||
public class Program
|
||||
{
|
||||
public static void Main(string[] args)
|
||||
{
|
||||
/*
|
||||
https://github.com/aspnet/AspNetCore/issues/4206#issuecomment-445612167
|
||||
CurrentDirectoryHelpers 文件位于: \framework\src\Volo.Abp.AspNetCore.Mvc\Microsoft\AspNetCore\InProcess\CurrentDirectoryHelpers.cs
|
||||
当升级到ASP.NET Core 3.0的时候将会删除这个类.
|
||||
*/
|
||||
CurrentDirectoryHelpers.SetCurrentDirectory();
|
||||
|
||||
BuildWebHostInternal(args).Run();
|
||||
}
|
||||
public static IWebHost BuildWebHostInternal(string[] args) =>
|
||||
new WebHostBuilder()
|
||||
.UseKestrel()
|
||||
.UseContentRoot(Directory.GetCurrentDirectory())
|
||||
.UseIIS()
|
||||
.UseIISIntegration()
|
||||
.UseStartup<Startup>()
|
||||
.Build();
|
||||
}
|
||||
````
|
||||
|
||||
|
||||
### 源码
|
||||
|
||||
从[此处](https://github.com/abpframework/abp-samples/tree/master/BasicAspNetCoreApplication)获取本教程中创建的示例项目的源代码.
|
||||
# 在AspNet Core MVC Web Application中使用ABP
|
||||
|
||||
本教程将介绍如何开始以最少的依赖关系开始使用ABP开发.
|
||||
|
||||
通常情况下你需要下载一个 **[启动模板](Getting-Started-AspNetCore-MVC-Template.md)**
|
||||
|
||||
## 创建一个新项目
|
||||
|
||||
1. 使用Visual Studio 2019 (16.4.0+)创建一个新的AspNet Core Web Application:
|
||||
|
||||
|
||||
|
||||
2. 配置新的项目:
|
||||
|
||||
|
||||
|
||||
3. 完成创建:
|
||||
|
||||
|
||||
|
||||
|
||||
## 安装 Volo.Abp.AspNetCore.Mvc 包
|
||||
|
||||
Volo.Abp.AspNetCore.Mvc是ABP集成AspNet Core MVC的包,请安装它到你项目中:
|
||||
|
||||
````
|
||||
Install-Package Volo.Abp.AspNetCore.Mvc
|
||||
````
|
||||
|
||||
## 创建ABP模块
|
||||
|
||||
ABP是一个模块化框架,它需要一个**启动 (根) 模块**继承自``AbpModule``:
|
||||
|
||||
````C#
|
||||
using Microsoft.AspNetCore.Builder;
|
||||
using Microsoft.Extensions.Hosting;
|
||||
using Volo.Abp;
|
||||
using Volo.Abp.AspNetCore.Mvc;
|
||||
using Volo.Abp.Modularity;
|
||||
|
||||
namespace BasicAspNetCoreApplication
|
||||
{
|
||||
[DependsOn(typeof(AbpAspNetCoreMvcModule))]
|
||||
public class AppModule : AbpModule
|
||||
{
|
||||
public override void OnApplicationInitialization(
|
||||
ApplicationInitializationContext context)
|
||||
{
|
||||
var app = context.GetApplicationBuilder();
|
||||
var env = context.GetEnvironment();
|
||||
|
||||
if (env.IsDevelopment())
|
||||
{
|
||||
app.UseDeveloperExceptionPage();
|
||||
}
|
||||
else
|
||||
{
|
||||
app.UseExceptionHandler("/Error");
|
||||
}
|
||||
|
||||
app.UseStaticFiles();
|
||||
app.UseRouting();
|
||||
app.UseConfiguredEndpoints();
|
||||
}
|
||||
}
|
||||
}
|
||||
````
|
||||
|
||||
``AppModule`` 是应用程序启动模块的好名称.
|
||||
|
||||
ABP的包定义了这个模块类,模块可以依赖其它模块.在上面的代码中 ``AppModule`` 依赖于 ``AbpAspNetCoreMvcModule`` (模块存在于[Volo.Abp.AspNetCore.Mvc](https://www.nuget.org/packages/Volo.Abp.AspNetCore.Mvc)包中). 安装新的ABP的包后添加``DependsOn``是很常见的做法.
|
||||
|
||||
我们在此模块类中配置ASP.NET Core管道,而不是Startup类中.
|
||||
|
||||
### 启动类
|
||||
|
||||
接下来修改启动类集成ABP模块系统:
|
||||
|
||||
````C#
|
||||
using Microsoft.AspNetCore.Builder;
|
||||
using Microsoft.Extensions.DependencyInjection;
|
||||
|
||||
namespace BasicAspNetCoreApplication
|
||||
{
|
||||
public class Startup
|
||||
{
|
||||
public void ConfigureServices(IServiceCollection services)
|
||||
{
|
||||
services.AddApplication<AppModule>();
|
||||
}
|
||||
|
||||
public void Configure(IApplicationBuilder app)
|
||||
{
|
||||
app.InitializeApplication();
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
````
|
||||
|
||||
``services.AddApplication<AppModule>()``添加了所有``AppModule``模块中定义的全部服务.
|
||||
|
||||
``Configure``方法中的``app.InitializeApplication()``完成初始化并启动应用程序.
|
||||
|
||||
## 运行应用程序!
|
||||
|
||||
启动该应用，它将按预期运行.
|
||||
|
||||
## 使用 Autofac 依赖注入框架
|
||||
|
||||
虽然AspNet Core的依赖注入(DI)系统适用于基本要求,但[Autofac](https://autofac.org/)提供了属性注入和方法拦截等高级功能,这些功能是ABP执行高级应用程序框架功能所必需的.
|
||||
|
||||
用Autofac取代AspNet Core的DI系统并集成到ABP非常简单.
|
||||
|
||||
1. 安装 [Volo.Abp.Autofac](https://www.nuget.org/packages/Volo.Abp.Autofac) 包
|
||||
|
||||
````
|
||||
Install-Package Volo.Abp.Autofac
|
||||
````
|
||||
|
||||
2. 添加 ``AbpAutofacModule`` 依赖
|
||||
|
||||
````C#
|
||||
[DependsOn(typeof(AbpAspNetCoreMvcModule))]
|
||||
[DependsOn(typeof(AbpAutofacModule))] // 在模块上添加依赖AbpAutofacModule
|
||||
public class AppModule : AbpModule
|
||||
{
|
||||
...
|
||||
}
|
||||
````
|
||||
|
||||
3. 修改``Program.cs``以使用Autofac:
|
||||
|
||||
````C#
|
||||
using Microsoft.AspNetCore.Hosting;
|
||||
using Microsoft.Extensions.Hosting;
|
||||
|
||||
namespace BasicAspNetCoreApplication
|
||||
{
|
||||
public class Program
|
||||
{
|
||||
public static void Main(string[] args)
|
||||
{
|
||||
CreateHostBuilder(args).Build().Run();
|
||||
}
|
||||
|
||||
public static IHostBuilder CreateHostBuilder(string[] args) =>
|
||||
Host.CreateDefaultBuilder(args)
|
||||
.ConfigureWebHostDefaults(webBuilder =>
|
||||
{
|
||||
webBuilder.UseStartup<Startup>();
|
||||
})
|
||||
.UseAutofac(); // 添加这一行
|
||||
}
|
||||
}
|
||||
````
|
||||
|
||||
## 源码
|
||||
|
||||
从[此处](https://github.com/abpframework/abp-samples/tree/master/BasicAspNetCoreApplication)获取本教程中创建的示例项目的源代码.
|
||||
|
||||
@ -0,0 +1,27 @@
|
||||
# WPF应用程序启动模板
|
||||
|
||||
此模板用于创建一个最小的依赖关系的ABP WPF应用程序项目.
|
||||
|
||||
## 如何开始?
|
||||
|
||||
首先,如果你没有安装[ABP CLI](../CLI.md),请先安装它:
|
||||
|
||||
````bash
|
||||
dotnet tool install -g Volo.Abp.Cli
|
||||
````
|
||||
|
||||
在一个空文件夹使用 `abp new` 命令创建新解决方案:
|
||||
|
||||
````bash
|
||||
abp new Acme.MyWpfApp -t wpf
|
||||
````
|
||||
|
||||
`Acme.MyWpfApp` 是解决方案的名称, 如*YourCompany.YourProduct*. 你可以使用单级或多级名称.
|
||||
|
||||
## 解决方案结构
|
||||
|
||||
使用以上命令创建解决方案后,你会得到如下所示的解决方案:
|
||||
|
||||
|
||||
|
||||
* `HelloWorldService` 是一个实现了 `ITransientDependency` 接口的示例服务. 它会自动注册到[依赖注入](../Dependency-Injection.md)系统.
|
||||
|
After Width: | Height: | Size: 31 KiB |
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in new issue