Skip to content

Platform: ComboBox Component Technical Design

Jump to bottom
manjunathanagaraj edited this page Jun 23, 2020 · 13 revisions

Combobox

Summary

The combobox is a selection input for selecting a value from a very large set of options. It is often connected to some backend service. It has a "typeahead" feature which enables to user to pair down the set of options based on keyword input.

Autocomplete-like component that provides Typeahead functionality needs to support variety of input types such as Array, Observable or DataSource.

As this is an input control it needs to implement the FormFieldControl as described in the FormGroup Layout or extend existing BaseInputComponent.

Arrays

Array is pretty much clear as core component already works with [] but what we want to support is a new type which represent readonly array ReadonlyArray. When working with array and this component can work with larger dataserver we need to use differ to make sure we are not re-rendering list of suggestion if nothing is changed.

Observable

Reactive stream that can emits data array every time the array changes. This is usually output type from a HTTP requests.

DataSource

A need for the DataSource I have already described in this document Enterprise Data where I tried to stress how important is to be able to connect directly to your data especially if we are working with thousands or millions of records. On this level we will create a new interface similar to the one used by cdk datatable, to define several abstract methods that a specific component implementation needs to extend in order to unify a way how we work with a data.

Example

The signature will be similar to core combobox with a few adjustments to align inputs naming with similar components (select).

<fdp-combobox [(ngModel)]="searchTermOne"
    [dataSource]="addresses"
    [placeholder]="'Type some text...'"
    [maxHeight]="'250px'">
</fdp-combobox>

<fdp-combobox [dataSource]="addresses"
    [placeholder]="'Type some text...'"
    [maxHeight]="'250px'"
    (select)="onSelect($event)">
</fdp-combobox>

We need also support several ng-template to be able to modify rendered items

<fdp-combobox [(ngModel)]="searchTermOne"
    [dataSource]="addresses"
    [placeholder]="'Type some text...'"
    [maxHeight]="'250px'">
   <ng-template #sugessionItem let-item let-index="index">
        <div class="fd-template-container-div">
            <fd-icon [glyph]="item.icon" size="l" class="fd-template-icon"></fd-icon>
            <span>{{item.name}}</span>
       </div>
   </ng-template>
</fdp-combobox>

Based on the document DataSource we should be able to also bootstrap combox with just passing entityClass.

<fdp-combobox [(ngModel)]="searchTermOne" [entityClass]="'Addresses'"
    >
   <ng-template #sugessionItem let-item let-index="index">
        <div class="fd-template-container-div">
            <fd-icon [glyph]="item.icon" size="l" class="fd-template-icon"></fd-icon>
            <span>{{item.name}}</span>
       </div>
   </ng-template>
</fdp-combobox>

Based on the entity it lookup the best DataSource available registered on Application level and initialize DataSource internally.

Since its form components then it needs to also provide id.

Design

Property Bindings

dataSource: AutoCompleteDataSource | [string] | Observable<[string]>

Can be a datasource, string array, or observable which returns a string array.

placeholder: string

Placeholder text for input field.

maxHeight: string

The CSS dimension string which sets the maxHeight of the dropdown component of the typeahead option list.

Two-Way Bindings

ngModel

The combobox component should be able to be bound to an Angular form control element via the ngModel directive.

Event Bindings

select

Event triggered on selection of item.

Projected Content

The component should allow for an ng-template to be inserted for customization of typeahead item display.

i18n

Link to general support for i18n: Supporting internationalization in ngx/platform

Special Usecase: No

  • fdp-combobox's placeholder attribute can be supported with string binding
  • The individual items themselves can be marked in the <span> using the ng-template approach:
<fdp-combobox [(ngModel)]="searchTermOne"
    [dataSource]="addresses"
    i18n-placeholder="@@placeholder"
    placeholder="Type some text..."
    [maxHeight]="'250px'">
   <ng-template #sugessionItem let-item let-index="index">
        <div class="fd-template-container-div">
            <fd-icon [glyph]="item.icon" size="l" class="fd-template-icon"></fd-icon>
            <span i18n="@@itemName">{{item.name}}</span>
       </div>
   </ng-template>
</fdp-combobox>

Redesign Required: No Since the ng-template declarative approach allows to modify the item elements, i18n markers can be placed here.

#Note: Manju: This may need update. Refer the link below for the signature. https://github.com/SAP/fundamental-ngx/blob/master/libs/platform/src/lib/components/form/combo-box/combo-box.component.html. maxheight,communicate by object, inshellbar - why are they required? displayfn,_suggestions - why two functions? Are these taken care of?:Grouping, Sorting. Event bindings: selection change, oneselect, onOpen, onClose. Mobile behaviour - to be addressed later?

https://wiki.ariba.com/pages/viewpage.action?pageId=111320076

Clone this wiki locally