56434: docs for search-filter, search-fixed-filter and search-configuration service; search-results, filtered-search-page and search-page components

src/app/+item-page/simple/field-components/specific-field/abstract/item-page-abstract-field.component.ts

@@ -7,16 +7,33 @@ import { ItemPageFieldComponent } from '../item-page-field.component';
     selector: 'ds-item-page-abstract-field',
     templateUrl: '../item-page-field.component.html'
 })
+/**
+ * This component is used for displaying the abstract (dc.description.abstract) of an item
+ */
 export class ItemPageAbstractFieldComponent extends ItemPageFieldComponent {
 
+    /**
+     * The item to display metadata for
+     */
     @Input() item: Item;
 
+    /**
+     * Separator string between multiple values of the metadata fields defined
+     * @type {string}
+     */
     separator: string;
 
+    /**
+     * Fields (schema.element.qualifier) used to render their values.
+     * In this component, we want to display values for metadata 'dc.description.abstract'
+     */
     fields: string[] = [
         'dc.description.abstract'
     ];
 
+    /**
+     * Label i18n key for the rendered metadata
+     */
     label = 'item.page.abstract';
 
 }

src/app/+item-page/simple/field-components/specific-field/author/item-page-author-field.component.ts

@@ -7,18 +7,35 @@ import { ItemPageFieldComponent } from '../item-page-field.component';
   selector: 'ds-item-page-author-field',
   templateUrl: '../item-page-field.component.html'
 })
+/**
+ * This component is used for displaying the author (dc.contributor.author, dc.creator and dc.contributor) metadata of an item
+ */
 export class ItemPageAuthorFieldComponent extends ItemPageFieldComponent {
 
+  /**
+   * The item to display metadata for
+   */
   @Input() item: Item;
 
+  /**
+   * Separator string between multiple values of the metadata fields defined
+   * @type {string}
+   */
   separator: string;
 
+  /**
+   * Fields (schema.element.qualifier) used to render their values.
+   * In this component, we want to display values for metadata 'dc.contributor.author', 'dc.creator' and 'dc.contributor'
+   */
   fields: string[] = [
     'dc.contributor.author',
     'dc.creator',
     'dc.contributor'
   ];
 
+  /**
+   * Label i18n key for the rendered metadata
+   */
   label = 'item.page.author';
 
 }

src/app/+item-page/simple/field-components/specific-field/date/item-page-date-field.component.ts

@@ -7,16 +7,33 @@ import { ItemPageFieldComponent } from '../item-page-field.component';
     selector: 'ds-item-page-date-field',
     templateUrl: '../item-page-field.component.html'
 })
+/**
+ * This component is used for displaying the issue date (dc.date.issued) metadata of an item
+ */
 export class ItemPageDateFieldComponent extends ItemPageFieldComponent {
 
+    /**
+     * The item to display metadata for
+     */
     @Input() item: Item;
 
+    /**
+     * Separator string between multiple values of the metadata fields defined
+     * @type {string}
+     */
     separator = ', ';
 
+    /**
+     * Fields (schema.element.qualifier) used to render their values.
+     * In this component, we want to display values for metadata 'dc.date.issued'
+     */
     fields: string[] = [
         'dc.date.issued'
     ];
 
+    /**
+     * Label i18n key for the rendered metadata
+     */
     label = 'item.page.date';
 
 }

src/app/+item-page/simple/field-components/specific-field/generic/generic-item-page-field.component.ts

@@ -7,14 +7,32 @@ import { ItemPageFieldComponent } from '../item-page-field.component';
   selector: 'ds-generic-item-page-field',
   templateUrl: '../item-page-field.component.html'
 })
+/**
+ * This component can be used to represent metadata on a simple item page.
+ * It is the most generic way of displaying metadata values
+ * It expects 4 parameters: The item, a seperator, the metadata keys and an i18n key
+ */
 export class GenericItemPageFieldComponent extends ItemPageFieldComponent {
 
+  /**
+   * The item to display metadata for
+   */
   @Input() item: Item;
 
+  /**
+   * Separator string between multiple values of the metadata fields defined
+   * @type {string}
+   */
   @Input() separator: string;
 
+  /**
+   * Fields (schema.element.qualifier) used to render their values.
+   */
   @Input() fields: string[];
 
+  /**
+   * Label i18n key for the rendered metadata
+   */
   @Input() label: string;
 
 }

src/app/+item-page/simple/field-components/specific-field/title/item-page-title-field.component.ts

@@ -7,12 +7,26 @@ import { ItemPageFieldComponent } from '../item-page-field.component';
     selector: 'ds-item-page-title-field',
     templateUrl: './item-page-title-field.component.html'
 })
+/**
+ * This component is used for displaying the title (dc.title) of an item
+ */
 export class ItemPageTitleFieldComponent extends ItemPageFieldComponent {
 
+    /**
+     * The item to display metadata for
+     */
     @Input() item: Item;
 
+    /**
+     * Separator string between multiple values of the metadata fields defined
+     * @type {string}
+     */
     separator: string;
 
+    /**
+     * Fields (schema.element.qualifier) used to render their values.
+     * In this component, we want to display values for metadata 'dc.title'
+     */
     fields: string[] = [
         'dc.title'
     ];

src/app/+item-page/simple/field-components/specific-field/uri/item-page-uri-field.component.ts

@@ -7,16 +7,33 @@ import { ItemPageFieldComponent } from '../item-page-field.component';
   selector: 'ds-item-page-uri-field',
   templateUrl: './item-page-uri-field.component.html'
 })
+/**
+ * This component is used for displaying the uri (dc.identifier.uri) metadata of an item
+ */
 export class ItemPageUriFieldComponent extends ItemPageFieldComponent {
 
+  /**
+   * The item to display metadata for
+   */
   @Input() item: Item;
 
+  /**
+   * Separator string between multiple values of the metadata fields defined
+   * @type {string}
+   */
   separator: string;
 
+  /**
+   * Fields (schema.element.qualifier) used to render their values.
+   * In this component, we want to display values for metadata 'dc.identifier.uri'
+   */
   fields: string[] = [
     'dc.identifier.uri'
   ];
 
+  /**
+   * Label i18n key for the rendered metadata
+   */
   label = 'item.page.uri';
 
 }

src/app/+item-page/simple/item-page.component.ts

@@ -30,14 +30,25 @@ import { Subscription } from 'rxjs/Subscription';
 })
 export class ItemPageComponent implements OnInit {
 
+  /**
+   * The item's id
+   */
   id: number;
 
-  private sub: any;
-
+  /**
+   * The item wrapped in a remote-data object
+   */
   itemRD$: Observable<RemoteData<Item>>;
 
+  /**
+   * The item's thumbnail
+   */
   thumbnail$: Observable<Bitstream>;
 
+  /**
+   * The view-mode we're currently on
+   * @type {ElementViewMode}
+   */
   ElementViewMode = viewMode.ElementViewMode;
 
   constructor(

src/app/+item-page/simple/related-entities/related-entities-component.ts

@@ -7,8 +7,24 @@ import * as viewMode from '../../../shared/view-mode';
   styleUrls: ['./related-entities.component.scss'],
   templateUrl: './related-entities.component.html'
 })
+/**
+ * This component is used for displaying relations between entities
+ * It expects a list of entities to display and a label to put on top
+ */
 export class RelatedEntitiesComponent {
+  /**
+   * A list of entities to display
+   */
   @Input() entities: Item[];
+
+  /**
+   * An i18n label to use as a title for the list (usually describes the relation)
+   */
   @Input() label: string;
+
+  /**
+   * The view-mode we're currently on
+   * @type {ElementViewMode}
+   */
   ElementViewMode = viewMode.ElementViewMode
 }

src/app/+search-page/filtered-search-page.component.ts

@@ -39,6 +39,12 @@ export class FilteredSearchPageComponent extends SearchPageComponent {
     super(service, sidebarService, windowService, filterService, searchConfigService, routeService);
   }
 
+  /**
+   * Get the current paginated search options after updating the fixed filter using the fixedFilterQuery input
+   * This is to make sure the fixed filter is included in the paginated search options, as it is not part of any
+   * query or route parameters
+   * @returns {Observable<PaginatedSearchOptions>}
+   */
   protected getSearchOptions(): Observable<PaginatedSearchOptions> {
     this.searchConfigService.updateFixedFilter(this.fixedFilterQuery);
     return this.searchConfigService.paginatedSearchOptions;

src/app/+search-page/search-filters/search-filter/search-filter.service.ts

@@ -57,14 +57,28 @@ export class SearchFilterService {
     return this.routeService.hasQueryParam(paramName);
   }
 
+  /**
+   * Fetch the current active scope from the query parameters
+   * @returns {Observable<string>}
+   */
   getCurrentScope() {
     return this.routeService.getQueryParameterValue('scope');
   }
 
+  /**
+   * Fetch the current query from the query parameters
+   * @returns {Observable<string>}
+   */
   getCurrentQuery() {
     return this.routeService.getQueryParameterValue('query');
   }
 
+  /**
+   * Fetch the current pagination from query parameters 'page' and 'pageSize'
+   * and combine them with a given pagination
+   * @param pagination      Pagination options to combine the query parameters with
+   * @returns {Observable<PaginationComponentOptions>}
+   */
   getCurrentPagination(pagination: any = {}): Observable<PaginationComponentOptions> {
     const page$ = this.routeService.getQueryParameterValue('page');
     const size$ = this.routeService.getQueryParameterValue('pageSize');
@@ -76,6 +90,12 @@ export class SearchFilterService {
     });
   }
 
+  /**
+   * Fetch the current sorting options from query parameters 'sortDirection' and 'sortField'
+   * and combine them with given sorting options
+   * @param {SortOptions} defaultSort       Sorting options to combine the query parameters with
+   * @returns {Observable<SortOptions>}
+   */
   getCurrentSort(defaultSort: SortOptions): Observable<SortOptions> {
     const sortDirection$ = this.routeService.getQueryParameterValue('sortDirection');
     const sortField$ = this.routeService.getQueryParameterValue('sortField');
@@ -87,19 +107,37 @@ export class SearchFilterService {
     );
   }
 
+  /**
+   * Fetch the current active filters from the query parameters
+   * @returns {Observable<Params>}
+   */
   getCurrentFilters() {
     return this.routeService.getQueryParamsWithPrefix('f.');
   }
 
+  /**
+   * Fetch the current active fixed filter from the route parameters and return the query by filter name
+   * @returns {Observable<string>}
+   */
   getCurrentFixedFilter(): Observable<string> {
     const filter: Observable<string> = this.routeService.getRouteParameterValue('filter');
     return filter.flatMap((f) => this.fixedFilterService.getQueryByFilterName(f));
   }
 
+  /**
+   * Fetch the current view from the query parameters
+   * @returns {Observable<string>}
+   */
   getCurrentView() {
     return this.routeService.getQueryParameterValue('view');
   }
 
+  /**
+   * Fetch the current paginated search options using the getters from above
+   * and combining them with given defaults
+   * @param defaults    Default paginated search options
+   * @returns {Observable<PaginatedSearchOptions>}
+   */
   getPaginatedSearchOptions(defaults: any = {}): Observable<PaginatedSearchOptions> {
     return Observable.combineLatest(
       this.getCurrentPagination(defaults.pagination),
@@ -125,6 +163,12 @@ export class SearchFilterService {
     )
   }
 
+  /**
+   * Fetch the current search options (not paginated) using the getters from above
+   * and combining them with given defaults
+   * @param defaults    Default search options
+   * @returns {Observable<SearchOptions>}
+   */
   getSearchOptions(defaults: any = {}): Observable<SearchOptions> {
     return Observable.combineLatest(
       this.getCurrentView(),

src/app/+search-page/search-filters/search-filter/search-fixed-filter.service.ts

@@ -14,6 +14,9 @@ import { hasValue } from '../../../shared/empty.util';
 import { configureRequest } from '../../../core/shared/operators';
 import { RouteService } from '../../../shared/services/route.service';
 
+/**
+ * Service for performing actions on the filtered-discovery-pages REST endpoint
+ */
 @Injectable()
 export class SearchFixedFilterService {
   private queryByFilterPath = 'filtered-discovery-pages';
@@ -25,6 +28,11 @@ export class SearchFixedFilterService {
 
   }
 
+  /**
+   * Get the filter query for a certain filter by name
+   * @param {string} filterName     Name of the filter
+   * @returns {Observable<string>}  Filter query
+   */
   getQueryByFilterName(filterName: string): Observable<string> {
     if (hasValue(filterName)) {
       const requestObs = this.halService.getEndpoint(this.queryByFilterPath).pipe(
@@ -56,6 +64,12 @@ export class SearchFixedFilterService {
     return Observable.of(undefined);
   }
 
+  /**
+   * Get the query for looking up items by relation type
+   * @param {string} relationType   Relation type
+   * @param {string} itemUUID       Item UUID
+   * @returns {string}              Query
+   */
   getQueryByRelations(relationType: string, itemUUID: string): string {
     return `query=relation.${relationType}:${itemUUID}`;
   }

src/app/+search-page/search-page.component.ts

@@ -111,6 +111,10 @@ export class SearchPageComponent implements OnInit {
     }
   }
 
+  /**
+   * Get the current paginated search options
+   * @returns {Observable<PaginatedSearchOptions>}
+   */
   protected getSearchOptions(): Observable<PaginatedSearchOptions> {
     return this.searchConfigService.paginatedSearchOptions;
   }

src/app/+search-page/search-results/search-results.component.ts

@@ -41,6 +41,11 @@ export class SearchResultsComponent {
   @Input() fixedFilter: string;
   @Input() disableHeader = false;
 
+  /**
+   * Get the i18n key for the title depending on the fixed filter
+   * Defaults to 'search.results.head' if there's no fixed filter found
+   * @returns {string}
+   */
   getTitleKey() {
     if (isNotEmpty(this.fixedFilter)) {
       return 'search.' + this.fixedFilter + '.results.head'

src/app/+search-page/search-service/search-configuration.service.ts

@@ -316,6 +316,10 @@ export class SearchConfigurationService implements OnDestroy {
     );
   }
 
+  /**
+   * Update the fixed filter in paginated and non-paginated search options with a given value
+   * @param {string} fixedFilter
+   */
   public updateFixedFilter(fixedFilter: string) {
     const currentPaginatedValue: PaginatedSearchOptions = this.paginatedSearchOptions.getValue();
     const updatedPaginatedValue: PaginatedSearchOptions = Object.assign(currentPaginatedValue, { fixedFilter: fixedFilter });