Merge branch 'rel-3.3' into dev

docs/en/UI/AspNetCore/Basic-Theme.md

@@ -38,7 +38,7 @@ Application Layout implements the following parts, in addition to the common par
 
 ### The Account Layout
 
-![basic-theme-account-layout](D:\Github\abp\docs\en\images\basic-theme-account-layout.png)
+![basic-theme-account-layout](../../images/basic-theme-account-layout.png)
 
 Application Layout implements the following parts, in addition to the common parts mentioned above;
 

docs/en/UI/AspNetCore/Breadcrumbs.md

@@ -1,3 +1,3 @@
-# Toolbars
+# Breadcrumbs
 
 TODO

docs/en/UI/AspNetCore/Data-Tables.md

@@ -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-example](../../images/datatables-example.png)
+
+## 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:
+
+![datatables-example](../../images/datatables-row-actions.png)
+
+`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:
+
+![datatables-row-actions-confirmation](../../images/datatables-row-actions-confirmation.png)
+
+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:
+
+![datatables-row-actions-confirmation](../../images/datatables-row-actions-icon.png)
+
+* `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:
+
+![datatables-custom-render-date](../../images/datatables-custom-render-date.png)
+
+If you don't define the render option, then the result will be ugly and not user friendly:
+
+![datatables-custom-render-date](../../images/datatables-default-render-date.png)
+
+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.

docs/en/UI/AspNetCore/Toolbars.md

@@ -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:
+
+![bookstore-toolbar-highlighted](../../images/bookstore-toolbar-highlighted.png)
+
+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:
+
+![bookstore-notification-view-component](../../images/bookstore-notification-view-component.png)
+
+**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:
+
+![bookstore-notification-icon-on-toolbar](../../images/bookstore-notification-icon-on-toolbar.png)
+
+`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.

docs/en/docs-nav.json

@@ -418,6 +418,10 @@
               "text": "Modals",
               "path": "UI/AspNetCore/Modals.md"
             },
+            {
+              "text": "Data Tables",
+              "path": "UI/AspNetCore/Data-Tables.md"
+            },
             {
               "text": "Page Alerts",
               "path": "UI/AspNetCore/Page-Alerts.md"
@@ -448,6 +452,10 @@
               "text": "Widgets",
               "path": "UI/AspNetCore/Widgets.md"
             },
+            {
+              "text": "Toolbars",
+              "path": "UI/AspNetCore/Toolbars.md"
+            },
             {
               "text": "Layout Hooks",
               "path": "UI/AspNetCore/Layout-Hooks.md"