From df28a8e73b59e85d85d7a42a071707e5302e2bc7 Mon Sep 17 00:00:00 2001 From: bnymncoskuner Date: Thu, 1 Apr 2021 10:29:16 +0300 Subject: [PATCH 1/4] docs: add docs for page component --- docs/en/UI/Angular/Page-Component.md | 211 +++++++++++++++++++++++++++ docs/en/docs-nav.json | 9 ++ 2 files changed, 220 insertions(+) create mode 100644 docs/en/UI/Angular/Page-Component.md diff --git a/docs/en/UI/Angular/Page-Component.md b/docs/en/UI/Angular/Page-Component.md new file mode 100644 index 0000000000..a019990be1 --- /dev/null +++ b/docs/en/UI/Angular/Page-Component.md @@ -0,0 +1,211 @@ +# Page Component + +ABP provides a component that wraps your content with some built-in components to recude the amount of code you need to write. + +If the template of a component looks like as follows, you can utilize the `abp-page` components. + +E.g. + +`app.component.ts` + +```html +
+
+

{{ '::AppTitle' | abpLocalization }}

+
+ +
+ +
+
+ +
+ +
+``` + +## Page Parts + +PageComponent divides the template shown above into three parts, `title`, `breadcrumb`, `toolbar`. Each can be configured separately. + +## Usage + +Firstly, you need to import `PageModule` from `@abp/ng.components/page` as follows: + +`app.module.ts` + +```javascript +import { PageModule } from '@abp/ng.components/page'; +import { AppComponent } from './app.component'; + +@NgModule({ + declarations: [AppComponent], + imports: [PageModule] +}) +export class AppModule {} +``` + +And change the template of `app.component.ts` to the following: + +```html + +
+ +
+ +``` + +## Inputs + +* title: `string`: Will be be rendered within `h1.content-header-title`. If not provided, the parent `div` will not be rendered +* breadcrumb: `boolean`: Determines whether to render `abp-breadcrumb`. Default is `true`. +* toolbar: `any`: Will be passed into `abp-page-toolbar` component through `record` input. If your page does not contain `abp-page-toolbar`, you can simply omit this field. + +## Overriding template + +If you need to replace the template of any part, you can use following sub components. + +```html + + +
+

Custom Title

+
+ + + +
+ +
+ + + +
+ +
+ + +``` + +You do not have to provide them all. You can just use which one you need to replace. These components have priority over the inputs declared above. If you use these components, you can omit the inputs. + +## PagePartDirective + +`PageModule` provides a structural directive that is used internally within `PageComponent` and can also be used externally. + +`PageComponent` employs this directive internally as follows: + +```html +
+ +
+``` + +It also can take a context input as follows: + +```html +
+ +
+``` + +```javascript +enum PageParts { + title = 'PageTitleContainerComponent', + breadcrumb = 'PageBreadcrumbContainerComponent', + toolbar = 'PageToolbarContainerComponent', +} +``` + +It's render strategy can be provided through Angular's Depedency Injection system. + +It expects a service through the `PAGE_RENDER_STRATEGY` injection token that implements the following interface. + +```javascript +interface PageRenderStrategy { + shouldRender(type?: string): boolean | Observable; + onInit?(type?: string, injector?: Injector, context?: any): void; + onDestroy?(type?: string, injector?: Injector, context?: any): void; + onContextUpdate?(change?: SimpleChange): void; +} +``` + +* `shouldRender` (required): It takes a string input named `type` and expects a `boolean` or `Observable`. +* `onInit` (optional): Will be called when the directive is initiated. Three inputs will be passed into this method. + * `type`: type of the page part + * `injector`: injector of the directive which could be used to retrieve anything from directive's DI tree. + * `context`: whatever context is available at initialization phase. +* `onDestroy` (optional): Will be called when the directive is destroyed. The parameters are the same with `onInit` +* `onContextUpdate` (optional): Will be called when the context is updated. + * `change`: changes of the `context` will be passed through this method. + +Let's see everything in action. + +```javascript +import {  + PageModule, + PageRenderStrategy, + PageParts, + PAGE_RENDER_STRATEGY +} from '@abp/ng.components/page'; +@Injectable() +export class MyPageRenderStrategy implements PageRenderStrategy { + shouldRender(type: string) { + // meaning everything but breadcrumb will be rendered + return type !== PageParts.breadcrumb && type !== 'custom-part'; + } + + /** + * shouldRender can also return an Observable which means + * an async service can be used within. + + constructor(private service: SomeAsyncService) {} + + shouldRender(type: string) { + return this.service.checkTypeAsync(type).pipe(map(val => val.isTrue())); + } + */ + + onInit(type: string, injector: Injector, context: any) { + // this method will be called in ngOnInit of the directive + } + + onDestroy(type: string, injector: Injector, context: any) { + // this method will be called in ngOnDestroy of the directive + } + + onContextUpdate?(change?: SimpleChange) { + // this method will be called everytime context is updated within the directive + } +} + +@Component({ + selector: 'app-root', + template: ` + + + + + +
+

Inner Title

+
+ + ` +}) +export class AppComponent {} + +@NgModule({ + imports: [PageModule], + declarations: [AppComponent], + providers: [ + { + provide: PAGE_RENDER_STRATEGY, + useClass: MyPageRenderStrategy, + } + ] +}) +export class AppModule {} +``` diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index ec3341c623..a48afe8597 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -886,6 +886,15 @@ ] } ] + }, + { + "text": "Components", + "items": [ + { + "text": "Page", + "path": "UI/Angular/Page-Component.md" + } + ] } ] }, From 81ecdb45465bc9cd395a781dd78f897ee926fcd0 Mon Sep 17 00:00:00 2001 From: bnymncoskuner Date: Thu, 1 Apr 2021 11:49:31 +0300 Subject: [PATCH 2/4] docs: fix minor typos and improve page-comp docs --- docs/en/UI/Angular/Page-Component.md | 38 +++++++++++++++------------- 1 file changed, 21 insertions(+), 17 deletions(-) diff --git a/docs/en/UI/Angular/Page-Component.md b/docs/en/UI/Angular/Page-Component.md index a019990be1..3c9e557176 100644 --- a/docs/en/UI/Angular/Page-Component.md +++ b/docs/en/UI/Angular/Page-Component.md @@ -1,8 +1,8 @@ # Page Component -ABP provides a component that wraps your content with some built-in components to recude the amount of code you need to write. +ABP provides a component that wraps your content with some built-in components to reduce the amount of code you need to write. -If the template of a component looks like as follows, you can utilize the `abp-page` components. +If the template of a component looks as follows, you can utilize the `abp-page` component. E.g. @@ -22,13 +22,21 @@ E.g.
- +
``` ## Page Parts -PageComponent divides the template shown above into three parts, `title`, `breadcrumb`, `toolbar`. Each can be configured separately. +PageComponent divides the template shown above into three parts, `title`, `breadcrumb`, `toolbar`. Each can be configured separately. There, also, is an enum exported from the package that describes each part. + +```javascript +export enum PageParts { + title = 'PageTitleContainerComponent', + breadcrumb = 'PageBreadcrumbContainerComponent', + toolbar = 'PageToolbarContainerComponent', +} +``` ## Usage @@ -65,7 +73,7 @@ And change the template of `app.component.ts` to the following: ## Overriding template -If you need to replace the template of any part, you can use following sub components. +If you need to replace the template of any part, you can use the following sub-components. ```html @@ -111,15 +119,7 @@ It also can take a context input as follows: ``` -```javascript -enum PageParts { - title = 'PageTitleContainerComponent', - breadcrumb = 'PageBreadcrumbContainerComponent', - toolbar = 'PageToolbarContainerComponent', -} -``` - -It's render strategy can be provided through Angular's Depedency Injection system. +Its render strategy can be provided through Angular's Dependency Injection system. It expects a service through the `PAGE_RENDER_STRATEGY` injection token that implements the following interface. @@ -132,11 +132,11 @@ interface PageRenderStrategy { } ``` -* `shouldRender` (required): It takes a string input named `type` and expects a `boolean` or `Observable`. +* `shouldRender` (required): It takes a string input named `type` and expects a `boolean` or `Observable` in return. * `onInit` (optional): Will be called when the directive is initiated. Three inputs will be passed into this method. * `type`: type of the page part * `injector`: injector of the directive which could be used to retrieve anything from directive's DI tree. - * `context`: whatever context is available at initialization phase. + * `context`: whatever context is available at the initialization phase. * `onDestroy` (optional): Will be called when the directive is destroyed. The parameters are the same with `onInit` * `onContextUpdate` (optional): Will be called when the context is updated. * `change`: changes of the `context` will be passed through this method. @@ -153,7 +153,7 @@ import {  @Injectable() export class MyPageRenderStrategy implements PageRenderStrategy { shouldRender(type: string) { - // meaning everything but breadcrumb will be rendered + // meaning everything but breadcrumb and custom-part will be rendered return type !== PageParts.breadcrumb && type !== 'custom-part'; } @@ -209,3 +209,7 @@ export class AppComponent {} }) export class AppModule {} ``` + +## See Also + +- [Page Toolbar Extensions for Angular UI](./Page-Page-Toolbar-Extensions.md) From e99858ce404b6b8b0933b20a9c8b909505b33a65 Mon Sep 17 00:00:00 2001 From: bnymncoskuner Date: Mon, 5 Apr 2021 11:08:23 +0300 Subject: [PATCH 3/4] refactor: remove empty div if nothing is used in page-comp --- .../packages/components/page/src/page.component.html | 2 +- .../packages/components/page/src/page.component.ts | 11 +++++++++++ 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/npm/ng-packs/packages/components/page/src/page.component.html b/npm/ng-packs/packages/components/page/src/page.component.html index 71715fd82e..fe5aff2e58 100644 --- a/npm/ng-packs/packages/components/page/src/page.component.html +++ b/npm/ng-packs/packages/components/page/src/page.component.html @@ -1,4 +1,4 @@ -
+
diff --git a/npm/ng-packs/packages/components/page/src/page.component.ts b/npm/ng-packs/packages/components/page/src/page.component.ts index 49e884fb2c..24b6d18ccf 100644 --- a/npm/ng-packs/packages/components/page/src/page.component.ts +++ b/npm/ng-packs/packages/components/page/src/page.component.ts @@ -37,4 +37,15 @@ export class PageComponent { @ContentChild(PageBreadcrumbContainerComponent) customBreadcrumb: PageBreadcrumbContainerComponent; @ContentChild(PageToolbarContainerComponent) customToolbar: PageToolbarContainerComponent; + + get shouldRenderRow() { + return !!( + this.title || + this.toolbarVisible || + this.breadcrumbVisible || + this.customTitle || + this.customBreadcrumb || + this.customToolbar + ); + } } From 2a1c58fdcbeb4963e7afd9de72ce400b918c1dab Mon Sep 17 00:00:00 2001 From: bnymncoskuner Date: Mon, 5 Apr 2021 11:08:34 +0300 Subject: [PATCH 4/4] docs: improve page-component docs --- docs/en/UI/Angular/Page-Component.md | 41 +++++++++++++++------------- 1 file changed, 22 insertions(+), 19 deletions(-) diff --git a/docs/en/UI/Angular/Page-Component.md b/docs/en/UI/Angular/Page-Component.md index 3c9e557176..a9e9857142 100644 --- a/docs/en/UI/Angular/Page-Component.md +++ b/docs/en/UI/Angular/Page-Component.md @@ -4,14 +4,14 @@ ABP provides a component that wraps your content with some built-in components t If the template of a component looks as follows, you can utilize the `abp-page` component. -E.g. +Let's look at the following example without `abp-page` component. -`app.component.ts` +`dashboard.component.ts` ```html
-

{{ '::AppTitle' | abpLocalization }}

+

{{ '::Dashboard' | abpLocalization }}

-
- +
+
``` @@ -36,30 +36,32 @@ export enum PageParts { breadcrumb = 'PageBreadcrumbContainerComponent', toolbar = 'PageToolbarContainerComponent', } + +// You can import this enum from -> import { PageParts } from '@abp/ng.components/page'; ``` ## Usage Firstly, you need to import `PageModule` from `@abp/ng.components/page` as follows: -`app.module.ts` +`dashboard.module.ts` ```javascript import { PageModule } from '@abp/ng.components/page'; -import { AppComponent } from './app.component'; +import { DashboardComponent } from './dashboard.component'; @NgModule({ - declarations: [AppComponent], + declarations: [DashboardComponent], imports: [PageModule] }) -export class AppModule {} +export class DashboardModule {} ``` -And change the template of `app.component.ts` to the following: +And change the template of `dashboard.component.ts` to the following: ```html - -
+ +
@@ -150,6 +152,7 @@ import {  PageParts, PAGE_RENDER_STRATEGY } from '@abp/ng.components/page'; + @Injectable() export class MyPageRenderStrategy implements PageRenderStrategy { shouldRender(type: string) { @@ -182,24 +185,24 @@ export class MyPageRenderStrategy implements PageRenderStrategy { } @Component({ - selector: 'app-root', + selector: 'app-dashboard', template: ` - + - + -
+

Inner Title

` }) -export class AppComponent {} +export class DashboardComponent {} @NgModule({ imports: [PageModule], - declarations: [AppComponent], + declarations: [DashboardComponent], providers: [ { provide: PAGE_RENDER_STRATEGY, @@ -207,7 +210,7 @@ export class AppComponent {} } ] }) -export class AppModule {} +export class DashboardModule {} ``` ## See Also