Add documentation for breaking change

demo-shell/src/app/components/files/filtered-search.component.ts

@@ -16,13 +16,11 @@
  */
 
 import { Component, Optional } from '@angular/core';
-import { SEARCH_QUERY_SERVICE_TOKEN, SearchFilterQueryBuilderService } from '@alfresco/adf-content-services';
 import { ActivatedRoute, Params } from '@angular/router';
 
 @Component({
     selector: 'app-filtered-search-component',
-    templateUrl: './filtered-search.component.html',
-    providers: [{ provide: SEARCH_QUERY_SERVICE_TOKEN, useClass: SearchFilterQueryBuilderService}]
+    templateUrl: './filtered-search.component.html'
 })
 export class FilteredSearchComponent {
 

docs/content-services/components/document-list.component.md

@@ -32,6 +32,7 @@ Displays the documents from a repository.
     -   [Location Column](#location-column)
     -   [Actions](#actions)
     -   [Navigation mode](#navigation-mode)
+    -   [Header filters](#header-filters)
 -   [Advanced usage and customization](#advanced-usage-and-customization)
     -   [Image Resolver and Row Filter functions](#image-resolver-and-row-filter-functions)
     -   [Custom 'empty folder' template](#custom-empty-folder-template)
@@ -84,6 +85,8 @@ Displays the documents from a repository.
 | where | `string` |  | Filters the [`Node`](https://github.com/Alfresco/alfresco-js-api/blob/develop/src/api/content-rest-api/docs/Node.md) list using the _where_ condition of the REST API (for example, isFolder=true). See the REST API documentation for more information. |
 | currentFolderId | `string` | null | The ID of the folder node to display or a reserved string alias for special sources |
 | rowFilter | [`RowFilter`](../../../lib/content-services/src/lib/document-list/data/row-filter.model.ts) |  | Custom function to choose whether to show or hide rows. See the [Row Filter Model](row-filter.model.md) page for more information. |
+| headerFilters | `boolean` | false | Toggles the header filters mode. |
+| filterValue | any | | Initial value for filter. |
 
 ### Events
 
@@ -95,7 +98,8 @@ Displays the documents from a repository.
 | nodeDblClick | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`NodeEntityEvent`](../../../lib/content-services/src/lib/document-list/components/node.event.ts)`>` | Emitted when the user double-clicks a list node |
 | nodeSelected | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`NodeEntry`](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/NodeEntry.md)`[]>` | Emitted when the node selection change |
 | preview | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`NodeEntityEvent`](../../../lib/content-services/src/lib/document-list/components/node.event.ts)`>` | Emitted when the user acts upon files with either single or double click (depends on `navigation-mode`). Useful for integration with the [Viewer component](../../core/components/viewer.component.md). |
-| ready | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`NodePaging`](https://github.com/Alfresco/alfresco-js-api/blob/develop/src/api/content-rest-api/docs/NodePaging.md)`>` | Emitted when the Document List has loaded all items and is ready for use |
+| ready | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`NodePaging`](https://github.com/Alfresco/alfresco-js-api/blob/develop/src/api/content-rest-api/docs/NodePaging.md)`>` | Emitted when the Document List has loaded all items and is ready for use. |
+| filterSelection | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`FilterSearch[]`](../../../lib/content-services/src/lib/search/filter-search.interface.ts)`>` | Emitted when a filter value is selected. |
 
 ## Details
 
@@ -686,6 +690,18 @@ The following example switches navigation to single clicks:
 </adf-document-list>
 ```
 
+### Header filters
+
+You can enable Header filters in your document list simply setting to true its `headerFilters` input.
+
+```html
+<adf-document-list 
+    currentFolderId="-my-" 
+    [headerFilters]="true">
+</adf-document-list>
+```
+![Header filters](../../docassets/images/header-filters.png)
+
 ## Advanced usage and customization
 
 ### Image Resolver and Row Filter functions

docs/upgrade-guide/upgrade40-41.md

@@ -0,0 +1,62 @@
+---
+Title: Upgrading from ADF v4.0 to v4.1
+---
+
+# Upgrading from ADF v4.0 to v4.1
+
+This guide explains how to upgrade your ADF v4.0 project to work with v4.1.
+
+Do not skip this task, if you want your application to be updated to a most recent version of ADF. 
+Upgrades of multiple versions of ADF cannot be done in one step only, but should follow the chain of sequential updates. 
+
+**Note:** the steps described below might involve making changes
+to your code. If you are working with a versioning system then you should
+commit any changes you are currently working on. If you aren't using versioning
+then be sure to make a backup copy of your project before going ahead with the
+upgrade.
+
+## Header Filters for Document List Components
+
+We released a new feature called Header Filters in ADF 4.0. It would allow users to filter the content of a folder by its columns properties. While this feature was working we noticed it was hard to implement. That is way we came up with a new way of enabling this feature.
+
+You will need to update your code to overcome this breaking change.
+
+ADF 4.0 implementation
+```html
+<adf-document-list 
+    currentFolderId="-my-">
+               <adf-custom-header-filter-template *ngIf="enableCustomHeaderFilter">
+                    <ng-template let-col>
+                        <adf-search-header [col]="col"              
+                                           [value]="paramValues"
+                                           [currentFolderNodeId]="currentFolderId"
+                                           [sorting]="filterSorting"
+                                           [maxItems]="pagination.maxItems"
+                                           [skipCount]="pagination.skipCount"
+                                           (update)="onFilterUpdate($event)"
+                                           (clear)="onAllFilterCleared()"
+                                           (selection)="onFilterSelected($event)">
+                        </adf-search-header>
+                    </ng-template>
+                </adf-custom-header-filter-template>
+</adf-document-list>
+```
+ADF 4.1 implementation
+```html
+<adf-document-list 
+    currentFolderId="-my-" 
+    [headerFilters]="true">
+</adf-document-list>
+```
+
+This is all you'll need to set it up in your app. Alternatively, you can also pass an initial value to the filters and listen to filter selection changes.
+
+```html
+<adf-document-list 
+    currentFolderId="-my-" 
+    [headerFilters]="true"
+    [filterValue]="paramValues"
+    (filterSelection)="onFilterSelected($event)">
+</adf-document-list>
+```
+Notice that for this feature in ADF 4.0 to work you also needed to overwrite the `SearchFilterQueryBuilderService` with `SEARCH_QUERY_SERVICE_TOKEN` at an app level to make it work. That is no longer the case with the new version. The component will handle everything for you.

lib/content-services/src/lib/document-list/components/filter-header/filter-header.component.ts

@@ -27,7 +27,8 @@ import { NodePaging, MinimalNode } from '@alfresco/js-api';
 
 @Component({
     selector: 'adf-filter-header',
-    templateUrl: './filter-header.component.html'
+    templateUrl: './filter-header.component.html',
+    providers: [{ provide: SEARCH_QUERY_SERVICE_TOKEN, useClass: SearchFilterQueryBuilderService}]
 })
 export class FilterHeaderComponent implements OnInit, OnChanges {
 
@@ -46,14 +47,13 @@ export class FilterHeaderComponent implements OnInit, OnChanges {
     isFilterServiceActive: boolean;
     private onDestroy$ = new Subject<boolean>();
 
-    constructor(
-        @Inject(DocumentListComponent) private documentList: DocumentListComponent,
-        @Inject(SEARCH_QUERY_SERVICE_TOKEN) private searchHeaderQueryBuilder: SearchFilterQueryBuilderService) {
-        this.isFilterServiceActive = this.searchHeaderQueryBuilder.isFilterServiceActive();
+    constructor(@Inject(DocumentListComponent) private documentList: DocumentListComponent,
+                @Inject(SEARCH_QUERY_SERVICE_TOKEN) private searchFilterQueryBuilder: SearchFilterQueryBuilderService) {
+        this.isFilterServiceActive = this.searchFilterQueryBuilder.isFilterServiceActive();
     }
 
     ngOnInit() {
-        this.searchHeaderQueryBuilder.executed
+        this.searchFilterQueryBuilder.executed
             .pipe(takeUntil(this.onDestroy$))
             .subscribe((newNodePaging: NodePaging) => {
                 this.documentList.node = newNodePaging;
@@ -72,36 +72,36 @@ export class FilterHeaderComponent implements OnInit, OnChanges {
     }
 
     onFilterSelectionChange() {
-        this.filterSelection.emit(this.searchHeaderQueryBuilder.getActiveFilters());
-        if (this.searchHeaderQueryBuilder.isNoFilterActive()) {
+        this.filterSelection.emit(this.searchFilterQueryBuilder.getActiveFilters());
+        if (this.searchFilterQueryBuilder.isNoFilterActive()) {
             this.documentList.node = null;
             this.documentList.reload();
         }
     }
 
     resetFilterHeader() {
-        this.searchHeaderQueryBuilder.resetActiveFilters();
+        this.searchFilterQueryBuilder.resetActiveFilters();
     }
 
     initDataPagination() {
         this.documentList.pagination
             .pipe(takeUntil(this.onDestroy$))
             .subscribe((newPagination: PaginationModel) => {
-                this.searchHeaderQueryBuilder.setupCurrentPagination(newPagination.maxItems, newPagination.skipCount);
+                this.searchFilterQueryBuilder.setupCurrentPagination(newPagination.maxItems, newPagination.skipCount);
             });
     }
 
     initDataSorting() {
         this.documentList.sortingSubject
             .pipe(takeUntil(this.onDestroy$))
             .subscribe((sorting: DataSorting[]) => {
-                this.searchHeaderQueryBuilder.setSorting(sorting);
+                this.searchFilterQueryBuilder.setSorting(sorting);
             });
     }
 
     private configureSearchParent(currentFolderId: string) {
-        if (this.searchHeaderQueryBuilder.isCustomSourceNode(currentFolderId)) {
-            this.searchHeaderQueryBuilder.getNodeIdForCustomSource(currentFolderId).subscribe((node: MinimalNode) => {
+        if (this.searchFilterQueryBuilder.isCustomSourceNode(currentFolderId)) {
+            this.searchFilterQueryBuilder.getNodeIdForCustomSource(currentFolderId).subscribe((node: MinimalNode) => {
                 this.initSearchHeader(node.id);
             });
         } else {
@@ -110,10 +110,10 @@ export class FilterHeaderComponent implements OnInit, OnChanges {
     }
 
     private initSearchHeader(currentFolderId: string) {
-        this.searchHeaderQueryBuilder.setCurrentRootFolderId(currentFolderId);
+        this.searchFilterQueryBuilder.setCurrentRootFolderId(currentFolderId);
         if (this.value) {
             Object.keys(this.value).forEach((columnKey) => {
-                this.searchHeaderQueryBuilder.setActiveFilter(columnKey, this.value[columnKey]);
+                this.searchFilterQueryBuilder.setActiveFilter(columnKey, this.value[columnKey]);
             });
         }
 

lib/content-services/src/lib/search/components/search-filter-container/search-filter-container.component.ts

@@ -68,13 +68,13 @@ export class SearchFilterContainerComponent implements OnInit, OnDestroy {
 
     private onDestroy$ = new Subject<boolean>();
 
-    constructor(@Inject(SEARCH_QUERY_SERVICE_TOKEN) private searchHeaderQueryBuilder: SearchFilterQueryBuilderService,
+    constructor(@Inject(SEARCH_QUERY_SERVICE_TOKEN) private searchFilterQueryBuilder: SearchFilterQueryBuilderService,
                 private translationService: TranslationService,
                 private focusTrapFactory: ConfigurableFocusTrapFactory) {
     }
 
     ngOnInit() {
-        this.category = this.searchHeaderQueryBuilder.getCategoryForColumn(this.col.key);
+        this.category = this.searchFilterQueryBuilder.getCategoryForColumn(this.col.key);
         this.initialValue = this.value && this.value[this.col.key] ? this.value[this.col.key] : undefined;
     }
 
@@ -92,7 +92,7 @@ export class SearchFilterContainerComponent implements OnInit, OnDestroy {
 
     onApply() {
         if (this.widgetContainer.hasValueSelected()) {
-            this.searchHeaderQueryBuilder.setActiveFilter(this.category.columnKey, this.widgetContainer.getCurrentValue());
+            this.searchFilterQueryBuilder.setActiveFilter(this.category.columnKey, this.widgetContainer.getCurrentValue());
             this.filterChange.emit();
             this.widgetContainer.applyInnerWidget();
         } else {
@@ -107,7 +107,7 @@ export class SearchFilterContainerComponent implements OnInit, OnDestroy {
 
     resetSearchFilter() {
         this.widgetContainer.resetInnerWidget();
-        this.searchHeaderQueryBuilder.removeActiveFilter(this.category.columnKey);
+        this.searchFilterQueryBuilder.removeActiveFilter(this.category.columnKey);
         this.filterChange.emit();
     }