angular-slickgrid 8.14.0 → 9.0.0

package/docs/column-functionalities/cell-menu.md

@@ -0,0 +1,212 @@
+#### index
+- [Default Usage](#default-usage)
+- [Action Callback Methods](#action-callback-methods-preferred-approach)
+- [Override Callback Methods](#override-callback-methods)
+- [How to add Translations](#how-to-add-translations)
+- [How to Disable Cell Menu](#how-to-disable-the-cell-menu)
+- [UI Sample](#ui-sample)
+
+### Demo
+[Demo](https://ghiscoding.github.io/Angular-Slickgrid/#/context) / [Demo Component](https://github.com/ghiscoding/slickgrid-universal/blob/master/frameworks/angular-slickgrid/src/demos/examples/grid-contextmenu.component.ts)
+
+### Description
+A Cell Menu, most often used as an Action Menu and is more oriented on a row action (e.g. delete current row), it could be defined on 1 or more columns (defined in a column definition) and is triggered by a cell click or touch. The menu can show a list of Commands (to execute an action) and/or Options (to change the value of a field). Also note that the Commands list is following the same structure used in the [Context Menu](../grid-functionalities/Context-Menu.md), [Header Menu](../grid-functionalities/Header-Menu-&-Header-Buttons.md) & [Grid Menu](../grid-functionalities/Grid-Menu.md). The Cell Menu is very similar to the [Context Menu](../grid-functionalities/Context-Menu.md), both were create as SlickGrid plugins during the same period, their main difference is that they get triggered differently (cell click vs mouse right+click) and they serve different purposes. The Cell Menu is more oriented on a row action (e.g. delete current row) while the Context Menu is all about actions for the entire grid (e.g. export to Excel).
+
+This extensions is wrapped around the new SlickGrid Plugin **SlickCellMenu**
+
+### Default Usage
+To use the Cell Menu, you will need to enable it in the Grid Options and also define its structure in the chose column. You can customize the menu with 2 different lists, Commands and/or Options, they can be used separately or at the same time (same as [Context Menu](../grid-functionalities/Context-Menu.md)). However please note that you will also need to use a Custom Formatter to display the Action button/text, it's easy enough as you can see below. Also note that even though the code shown below makes a separation between the Commands and Options, you can mix them in the same Cell Menu.
+
+#### with Commands
+```ts
+this.columnDefinitions = [
+  { id: 'firstName', field: 'firstName', name: 'First Name' },
+  { id: 'lastName', field: 'lastName', name: 'Last Name' },
+  // ... more column defs
+  {
+    id: 'action', name: 'Action', field: 'action', width: 110, maxWidth: 200,
+    excludeFromExport: true,    // you typically don't want this column exported
+    formatter: actionFormatter, // your Custom Formatter
+    cellMenu: {
+      commandTitle: 'Commands', // optional title
+      commandItems: [
+        // array of command item objects, you can also use the "positionOrder" that will be used to sort the items in the list
+        {
+          command: 'command1', title: 'Command 1', positionOrder: 61,
+          // you can use the "action" callback and/or use "onCommand" callback from the grid options, they both have the same arguments
+          action: (e, args) => {
+            console.log(args.dataContext, args.column); // action callback.. do something
+          }
+        },
+        { command: 'help', title: 'HELP', iconCssClass: 'mdi mdi-help-circle', positionOrder: 62 },
+        // you can add sub-menus by adding nested `commandItems`
+        {
+         // we can also have multiple nested sub-menus
+         command: 'export', title: 'Exports', positionOrder: 99,
+         commandItems: [
+           { command: 'exports-txt', title: 'Text (tab delimited)' },
+           {
+              command: 'sub-menu', title: 'Excel', cssClass: 'green', subMenuTitle: 'available formats', subMenuTitleCssClass: 'text-italic orange',
+              commandItems: [
+                { command: 'exports-csv', title: 'Excel (csv)' },
+                { command: 'exports-xlsx', title: 'Excel (xlsx)' },
+             ]
+           }
+         ]
+        },
+      ],
+    }
+  }
+]
+```
+
+#### with Options
+That is when you want to define a list of Options (only 1 list) that the user can choose from and once an option is selected we would do something (for example change the value of a cell in the grid).
+```ts
+this.columnDefinitions = [
+  { id: 'firstName', field: 'firstName', name: 'First Name' },
+  { id: 'lastName', field: 'lastName', name: 'Last Name' },
+  // ... more column defs
+  {
+    id: 'action', name: 'Action', field: 'action', width: 110, maxWidth: 200,
+    excludeFromExport: true,    // you typically don't want this column exported
+    formatter: actionFormatter, // your Custom Formatter
+    cellMenu: {
+      optionTitle: 'Change Effort Driven Flag', // optional, add title
+      optionItems: [
+        { option: true, title: 'True', iconCssClass: 'mdi mdi-check-box-outline' },
+        { option: false, title: 'False', iconCssClass: 'mdi mdi-checkbox-blank-outline' },
+        { divider: true, command: '', positionOrder: 60 },
+      ],
+      // subscribe to Context Menu onOptionSelected event (or use the "action" callback on each option)
+      action: (e, args) => {
+        console.log(args.dataContext, args.column); // action callback.. do something
+      }
+    }
+  }
+};
+```
+
+### Action Callback Methods (preferred approach)
+There are 2 ways to execute an action after a Command is clicked (or an Option is selected), you could do it via the `action` callback or via the `onCommand` callback. You might be wondering why 2 and what's the difference? Well, the `action` would have to be defined on every single Command/Option while the `onCommand` (or `onOptionSelected`) is more of a global subscriber which gets triggered every time any of the Command/Option is clicked/selected, so for that, you would typically need to use `if/else` or a `switch/case`... hmm ok but I still don't understand when would I use the `onCommand`? Let say you combine the Cell Menu with the [Context Menu](../grid-functionalities/Context-Menu.md) and some of the commands are the same, well, in that case, it might be better to use the `onCommand` and centralize your commands in that callback, while in most other cases if you wish to do only 1 thing with a command, then using the `action` might be better. Also, note that they could also both be used if you wish.
+
+So if you decide to use the `action` callback, then your code would look like this
+##### with `action` callback
+```ts
+this.columnDefinitions = [
+  { id: 'action', field: 'action', name: 'Action',
+    cellMenu: {
+      commandItems: [
+        { command: 'command1', title: 'Command 1', action: (e, args) => console.log(args) },
+        { command: 'command2', title: 'Command 2', action: (e, args) => console.log(args) }
+        // ...
+      ]
+    }
+  }
+];
+```
+
+##### with `onCommand` callback
+The `onCommand` (or `onOptionSelected`) **must** be defined in the Grid Options
+
+```ts
+this.columnDefinitions = [
+  { id: 'action', field: 'action', name: 'Action',
+    cellMenu: {
+      commandItems: [
+        { command: 'command1', title: 'Command 1' },
+        { command: 'command2', title: 'Command 2' }
+        // ...
+      ]
+    }
+  }
+];
+
+this.gridOptions = {
+  enableCellMenu: true,
+  cellMenu: {
+    onCommand(e, args) => {
+      const columnDef = args.columnDef;
+      const command = args.command;
+      const dataContext = args.dataContext;
+
+      switch (command) {
+        case 'command1': alert('Command 1'); break;
+        case 'command2': alert('Command 2'); break;
+        default: break;
+      }
+    }
+  }
+};
+```
+
+### Override Callback Methods
+What if you want to dynamically disable or hide a Command/Option or even disable the entire menu in certain circumstances? For these cases, you would use the override callback methods, the method must return a `boolean`. The list of override available are the following
+- `menuUsabilityOverride` returning false would make the Cell Menu unavailable to the user
+- `itemVisibilityOverride` returning false would hide the item (command/option) from the list
+- `itemUsabilityOverride` return false would disabled the item (command/option) from the list
+  - **note** there is also a `disabled` property that you could use, however it is defined at the beginning while the override is meant to be used with certain logic dynamically.
+
+For example, say we want the Cell Menu to only be available on the first 20 rows of the grid, we could use the override this way
+```ts
+this.columnDefinitions = [
+  { id: 'action', field: 'action', name: 'Action',
+    cellMenu: {
+      menuUsabilityOverride: (args) => {
+        const dataContext = args && args.dataContext;
+        return (dataContext.id < 21); // say we want to display the menu only from Task 0 to 20
+      },
+    }
+  }
+];
+```
+
+To give another example, with Options this time, we could say that we enable the `n/a` option only when the row is Completed. So we could do it this way
+```ts
+this.columnDefinitions = [
+  { id: 'action', field: 'action', name: 'Action',
+    cellMenu: {
+      optionItems: [
+      {
+        option: 0, title: 'n/a', textCssClass: 'italic',
+        // only enable this option when the task is Not Completed
+        itemUsabilityOverride: (args) => {
+          const dataContext = args && args.dataContext;
+          return !dataContext.completed;
+        },
+        { option: 1, iconCssClass: 'mdi mdi-star-outline yellow', title: 'Low' },
+        { option: 2, iconCssClass: 'mdi mdi-star orange', title: 'Medium' },
+        { option: 3, iconCssClass: 'mdi mdi-star red', title: 'High' },
+      ]
+    }
+  }
+];
+```
+
+### How to add Translations?
+It works exactly like the rest of the library when `enableTranslate` is set, all we have to do is to provide translations with the `Key` suffix, so for example without translations, we would use `title` and that would become `titleKey` with translations, that;'s easy enough. So for example, a list of Options could be defined as follow:
+```ts
+this.columnDefinitions = [
+  { id: 'action', field: 'action', name: 'Action',
+    cellMenu: {
+      optionTitleKey: 'COMMANDS', // optionally pass a title to show over the Options
+      optionItems: [
+        { option: 1, titleKey: 'LOW', iconCssClass: 'mdi mdi-star-outline yellow' },
+        { option: 2, titleKey: 'MEDIUM', iconCssClass: 'mdi mdi-star orange' },
+        { option: 3, titleKey: 'HIGH', iconCssClass: 'mdi mdi-star red' },
+      ]
+    }
+  }
+];
+```
+
+### How to Disable the Cell Menu?
+You can disable the Cell Menu, by calling `enableCellMenu: false` from the Grid Options.
+```ts
+this.gridOptions = {
+   enableCellMenu: false
+};
+```
+
+### UI Sample
+![image](https://user-images.githubusercontent.com/643976/71301668-3aead800-2370-11ea-8ae5-acd124aff054.png)

package/docs/column-functionalities/editors/autocomplete-editor.md

@@ -0,0 +1,466 @@
+#### Index
+- [Using fixed `collection` or `collectionAsync`](#using-collection-or-collectionasync)
+- [Editor Options (`AutocompleterOption` interface)](#editor-options-autocompleteroption-interface)
+- [Using Remote API](#using-external-remote-api)
+  - [Basic Usage](#remote-api-basic)
+  - [Basic Usage with Object Result (**preferred way**)](#remote-api-basic-with-object-result)
+  - [with `renderItem` + custom Layout (`twoRows` or `fourCorners`)](#remote-api-renderitem-callback--custom-layout-tworows-or-fourcorners)
+  - [Custom Styling - SASS variables](https://github.com/ghiscoding/slickgrid-universal/blob/master/packages/common/src/styles/_variables.scss#L141)
+- [Force User Input](#autocomplete---force-user-input)
+- [How to change drop container dimensions?](#how-to-change-drop-container-dimensions)
+- [Animated Gif Demo](#animated-gif-demo)
+  - See the [Editors - Wiki](../Editors.md) for more general info about Editors (validators, event handlers, ...)
+
+### Demo
+[Demo Page](https://ghiscoding.github.io/Angular-Slickgrid/#/editor) | [Demo Component](https://github.com/ghiscoding/slickgrid-universal/blob/master/frameworks/angular-slickgrid/src/demos/examples/grid-editor.component.ts)
+
+### Introduction
+AutoComplete is a functionality that let the user start typing characters and the autocomplete will try to give suggestions according to the characters entered. The collection can be a fixed JSON files (collection of strings or objects) or can also be an external remote resource to an external API. For a demo of what that could look like, take a look at the [animated gif demo](#animated-gif-demo) below.
+
+We use an external lib named [Autocomplete](https://github.com/kraaden/autocomplete) (aka `autocompleter` on npm) by Kraaden.
+
+## Using `collection` or `collectionAsync`
+If you want to pass the entire list to the AutoComplete (like a JSON file or a Web API call), you can do so using the `collection` or the `collectionAsync` (the latter will load it asynchronously). You can also see that the Editor and Filter have almost the exact same configuration (apart from the `model` that is obviously different).
+
+##### Component
+```typescript
+export class GridBasicComponent {
+  columnDefinitions: Column[];
+  gridOptions: GridOption;
+  dataset: any[];
+
+  defineGrid(): void {
+      // your columns definition
+    this.columnDefinitions = [
+      {
+        id: 'countryOfOrigin', name: 'Country of Origin', field: 'countryOfOrigin',
+        formatter: Formatters.complexObject,
+        dataKey: 'code', // our list of objects has the structure { code: 'CA', name: 'Canada' }, since we want to use the code`, we will set the dataKey to "code"
+        labelKey: 'name', // while the displayed value is "name"
+        type: 'object',
+        sorter: Sorters.objectString, // since we have set dataKey to "code" our output type will be a string, and so we can use this objectString, this sorter always requires the dataKey
+        filterable: true,
+        sortable: true,
+        minWidth: 100,
+        editor: {
+          model: Editors.autocompleter,
+          customStructure: { label: 'name', value: 'code' },
+          collectionAsync: this.http.get('assets/data/countries.json'), // this demo will load the JSON file asynchronously
+        },
+        filter: {
+          model: Filters.autocompleter,
+          customStructure: { label: 'name', value: 'code' },
+          collectionAsync: this.http.get('assets/data/countries.json'),
+        }
+      }
+    ];
+
+    this.gridOptions = {
+      // your grid options config
+    }
+  }
+}
+```
+
+### Collection Label Render HTML
+By default HTML is not rendered and the `label` will simply show HTML as text. But in some cases you might want to render it, you can do so by enabling the `enableRenderHtml` flag.
+
+**NOTE:** this is currently only used by the Editors that have a `collection` which are the `MultipleSelect` & `SingleSelect` Editors.
+
+```typescript
+this.columnDefinitions = [
+  {
+    id: 'effort-driven', name: 'Effort Driven', field: 'effortDriven',
+    formatter: Formatters.checkmarkMaterial,
+    type: 'boolean',
+    editor: {
+      model: Editors.autocompleter,
+      placeholder: '🔍 search city',
+
+      // example with a fixed Collection (or collectionAsync)
+      // previously known as `editorOptions` for < 9.0
+      options: {
+        showOnFocus: true, // display the list on focus of the autocomplete (without the need to type anything)
+      } as AutocompleterOption,
+      enableRenderHtml: true, // this flag only works with a fixed Collection
+      // collectionAsync: this.http.get(URL_COUNTRIES_COLLECTION),
+      collection: [
+        { value: '', label: '' },
+        { value: true, label: 'True', labelPrefix: `<i class="mdi mdi-plus"></i> ` },
+        { value: false, label: 'False', labelPrefix: `<i class="mdi mdi-minus"></i> ` }
+      ],
+    }
+  }
+];
+```
+
+### Editor Options (`AutocompleterOption` interface)
+All the available options that can be provided as editor `options` to your column definitions can be found under this [AutocompleterOption interface](https://github.com/ghiscoding/slickgrid-universal/blob/master/packages/common/src/interfaces/autocompleterOption.interface.ts) and you should cast your editor `options` to that interface to make sure that you use only valid options of the autocomplete library.
+
+```ts
+editor: {
+  model: Editors.autocompleter,
+  // previously known as `editorOptions` for < 9.0
+  options: {
+    minLength: 3,
+  } as AutocompleterOption
+}
+```
+
+#### Grid Option `defaultEditorOptions
+You could also define certain options as a global level (for the entire grid or even all grids) by taking advantage of the `defaultEditorOptions` Grid Option. Note that they are set via the editor type as a key name (`autocompleter`, `date`, ...) and then the content is the same as editor `options` (also note that each key is already typed with the correct editor option interface), for example
+
+```ts
+this.gridOptions = {
+  defaultEditorOptions: {
+    autocompleter: { debounceWaitMs: 150 }, // typed as AutocompleterOption
+  }
+}
+```
+
+## Using External Remote API
+You could also use external 3rd party Web API (can be JSONP query or regular JSON). This will make a much shorter result since it will only return a small subset of what will be displayed in the AutoComplete Editor or Filter. For example, we could use GeoBytes which provide a JSONP Query API for the cities of the world, you can imagine the entire list of cities would be way too big to download locally, so this is why we use such API.
+
+### Remote API (basic)
+The basic functionality will use built-in 3rd party lib styling that is to display a label/value pair item result.
+
+##### Component
+```typescript
+export class GridBasicComponent {
+  columnDefinitions: Column[];
+  gridOptions: GridOption;
+  dataset: any[];
+
+  defineGrid() {
+    // your columns definition
+    this.columnDefinitions = [
+      {
+        id: 'product', name: 'Product', field: 'product',
+        filterable: true,
+        minWidth: 100,
+        editor: {
+          model: Editors.autocompleter,
+          alwaysSaveOnEnterKey: true,
+          // previously known as `editorOptions` for < 9.0
+          options: {
+            showOnFocus: true,
+            minLength: 1,
+            fetch: (searchText, updateCallback) => {
+              // assuming your API call returns a label/value pair
+              yourAsyncApiCall(searchText) // typically you'll want to return no more than 10 results
+                 .then(result => updateCallback((results.length > 0) ? results : [{ label: 'No match found.', value: '' }]))
+                 .catch(error => console.log('Error:', error));
+            },
+          }
+        } as AutocompleterOption,
+      },
+    ];
+
+    this.gridOptions = {
+      // your grid options config
+    }
+  }
+}
+```
+
+### Remote API (basic with object result)
+This is the preferred way of dealing with the AutoComplete, the main reason is because the AutoComplete uses an `<input/>` and that means we can only keep 1 value and if we do then we lose the text label and so using an Object Result makes more sense. Note however that you'll need a bit more code that is because we'll use the `'object'` and so we need to provide a custom `SortComparer` and also a custom `Formatters` and for them to work we also need to provide a `dataKey` (the value) and a `labelKey` (text label) as shown below.
+```ts
+this.columnDefinitions = [
+  {
+    id: 'product', name: 'Product', field: 'product',
+    dataKey: 'id',
+    labelKey: 'name', // (id/name) pair to override default (value/label) pair
+    editor: {
+      model: Editors.autocompleter,
+      alwaysSaveOnEnterKey: true,
+      type: 'object',
+      sortComparer: SortComparers.objectString,
+      options: {
+        showOnFocus: true,
+        minLength: 1,
+        fetch: (searchText, updateCallback) => {
+          // assuming your API call returns a label/value pair
+          yourAsyncApiCall(searchText) // typically you'll want to return no more than 10 results
+            .then(result => updateCallback((results.length > 0) ? results : [{ label: 'No match found.', value: '' }]))
+            .catch(error => console.log('Error:', error));
+        }
+      },
+    } as AutocompleterOption,
+  }
+];
+```
+
+### Remote API with `renderItem` + custom layout (`twoRows` or `fourCorners`)
+#### See animated gif ([twoRows](#with-tworows-custom-layout-without-optional-left-icon) or [fourCorners](#with-fourcorners-custom-layout-with-extra-optional-left-icon))
+The lib comes with 2 built-in custom layouts, these 2 layouts also have SASS variables if anyone wants to style it differently. When using the `renderItem`, it will require the user to provide a `layout` (2 possible options `twoRows` or `fourCorners`) and also a `templateCallback` that will be executed when rendering the AutoComplete Search List Item. For example:
+
+##### Component
+```typescript
+export class GridBasicComponent {
+  columnDefinitions: Column[];
+  gridOptions: GridOption;
+  dataset: any[];
+
+  defineGrid() {
+    // your columns definition
+    this.columnDefinitions = [
+      {
+        id: 'product', name: 'Product', field: 'product',
+        filterable: true,
+        minWidth: 100,
+        editor: {
+          model: Editors.autocompleter,
+          alwaysSaveOnEnterKey: true,
+          customStructure: {
+            label: 'itemName',
+            value: 'id'
+          },
+          // previously known as `editorOptions` for < 9.0
+          options: {
+            showOnFocus: true,
+            minLength: 1,
+            fetch: (searchText, updateCallback) => {
+              yourAsyncApiCall(searchText) // typically you'll want to return no more than 10 results
+                 .then(result => updateCallback((results.length > 0) ? results : [{ label: 'No match found.', value: '' }]))
+                 .catch(error => console.log('Error:', error));
+            }
+          },
+          renderItem: {
+            layout: 'twoRows',
+            templateCallback: (item: any) => `<div class="autocomplete-container-list">
+              <div class="autocomplete-left">
+                <span class="mdi ${item.icon} mdi-26px"></span>
+              </div>
+              <div>
+                <span class="autocomplete-top-left">
+                  <span class="mdi ${item.itemTypeName === 'I' ? 'mdi-information-outline' : 'mdi-content-copy'} mdi-14px"></span>
+                  ${item.itemName}
+                </span>
+              <div>
+            </div>
+            <div>
+              <div class="autocomplete-bottom-left">${item.itemNameTranslated}</div>
+            </div>`,
+          },
+        } as AutocompleterOption,
+      },
+    ];
+
+    this.gridOptions = {
+      // your grid options config
+    }
+  }
+}
+```
+
+### Remote API `renderItem` callback + custom layout (`twoRows` or `fourCorners`)
+#### See animated gif ([twoRows](#with-tworows-custom-layout-without-optional-left-icon) or [fourCorners](#with-fourcorners-custom-layout-with-extra-optional-left-icon))
+The previous example can also be written using the `renderItem` callback and adding `classes`, this is actually what Slickgrid-Universal does internally, you can do it yourself if you wish to have more control on the render callback result.
+
+##### Component
+```typescript
+export class GridBasicComponent {
+  columnDefinitions: Column[];
+  gridOptions: GridOption;
+  dataset: any[];
+
+  defineGrid() {
+      // your columns definition
+    this.columnDefinitions = [
+      {
+        id: 'product', name: 'Product', field: 'product',
+        filterable: true,
+        minWidth: 100,
+        editor: {
+          model: Editors.autocompleter,
+          alwaysSaveOnEnterKey: true,
+          customStructure: {
+            label: 'itemName',
+            value: 'id'
+          },
+          // previously known as `editorOptions` for < 9.0
+          options: {
+            showOnFocus: true,
+            minLength: 1,
+            classes: {
+              // choose a custom style layout
+              // 'ui-autocomplete': 'autocomplete-custom-two-rows',
+              'ui-autocomplete': 'autocomplete-custom-four-corners',
+            },
+            fetch: (searchText, updateCallback) => {
+              yourAsyncApiCall(searchText) // typically you'll want to return no more than 10 results
+                 .then(result => updateCallback((results.length > 0) ? results : [{ label: 'No match found.', value: '' }]))
+                 .catch(error => console.log('Error:', error);
+            },
+            renderItem: {
+              layout: 'twoRows',
+              templateCallback: (item: any) => `<div class="autocomplete-container-list">
+                <div class="autocomplete-left">
+                  <span class="mdi ${item.icon} mdi-26px"></span>
+                </div>
+                <div>
+                  <span class="autocomplete-top-left">
+                    <span class="mdi ${item.itemTypeName === 'I' ? 'mdi-information-outline' : 'mdi-content-copy'} mdi-14px"></span>
+                    ${item.itemName}
+                  </span>
+                <div>
+              </div>
+              <div>
+                <div class="autocomplete-bottom-left">${item.itemNameTranslated}</div>
+              </div>`,
+            },
+          } as AutocompleterOption,
+          callbacks: {
+             // callback on the AutoComplete on the instance
+             renderItem: {
+                templateCallback: (item: any) => {
+                  return `<div class="autocomplete-container-list">
+                    <div class="autocomplete-left">
+                      <!--<img src="http://i.stack.imgur.com/pC1Tv.jpg" width="50" />-->
+                      <span class="mdi ${item.icon} mdi-26px"></span>
+                    </div>
+                    <div>
+                      <span class="autocomplete-top-left">
+                        <span class="mdi ${item.itemTypeName === 'I' ? 'mdi-information-outline' : 'mdi-content-copy'} mdi-14px"></span>
+                        ${item.itemName}
+                      </span>
+                      <span class="autocomplete-top-right">${formatNumber(item.listPrice, 2, 2, false, '$')}</span>
+                    <div>
+                  </div>
+                  <div>
+                    <div class="autocomplete-bottom-left">${item.itemNameTranslated}</div>
+                    <span class="autocomplete-bottom-right">Type: <b>${item.itemTypeName === 'I' ? 'Item' : item.itemTypeName === 'C' ? 'PdCat' : 'Cat'}</b></span>
+                  </div>`;
+              }
+          },
+        },
+      }
+    ];
+
+    this.gridOptions = {
+      // your grid options config
+    }
+  }
+}
+```
+
+#### with JSONP
+Example from an external remote API (geobytes) returning a JSONP response.
+
+##### Component
+```typescript
+export class GridBasicComponent {
+  columnDefinitions: Column[];
+  gridOptions: GridOption;
+  dataset: any[];
+
+  defineGrid(): void {
+      // your columns definition
+    this.columnDefinitions = [
+      {
+        id: 'cityOfOrigin', name: 'City of Origin', field: 'cityOfOrigin',
+        filterable: true,
+        minWidth: 100,
+        editor: {
+          model: Editors.autocompleter,
+          placeholder: 'search city', //  you can provide an optional placeholder to help your users
+
+          // use your own autocomplete options, instead of $.ajax, use http
+          // here we use $.ajax just because I'm not sure how to configure http with JSONP and CORS
+          options: {
+            minLength: 3, // minimum count of character that the user needs to type before it queries to the remote
+            fetch: (searchText, updateCallback) => {
+              // assuming your API call returns a label/value pair
+              yourAsyncApiCall(searchText) // typically you'll want to return no more than 10 results
+                 .then(result => updateCallback((results.length > 0) ? results : [{ label: 'No match found.', value: '' }]))
+                 .catch(error => console.log('Error:', error));
+            }
+          },
+        },
+        filter: {
+          model: Editors.autocompleter,
+          // placeholder: '&#128269; search city', // &#128269; is a search icon, this provide an option placeholder
+
+          // use your own autocomplete options, instead of $.ajax, use http
+          // here we use $.ajax just because I'm not sure how to configure http with JSONP and CORS
+          options: {
+            minLength: 3, // minimum count of character that the user needs to type before it queries to the remote
+            fetch: (searchText, updateCallback) => {
+              // assuming your API call returns a label/value pair
+              yourAsyncApiCall(searchText) // typically you'll want to return no more than 10 results
+                 .then(result => updateCallback((results.length > 0) ? results : [{ label: 'No match found.', value: '' }]))
+                 .catch(error => console.log('Error:', error));
+            }
+          },
+        }
+      }
+    ];
+
+    this.gridOptions = {
+      // your grid options config
+    }
+  }
+}
+```
+
+## Autocomplete - force user input
+If you want to add the autocomplete functionality but want the user to be able to input a new option, then follow the example below:
+
+```ts
+this.columnDefinitions = [{
+  id: 'area',
+  name: 'Area',
+  field: 'area',
+  editor: {
+    model: Editors.autocompleter,
+    options: {
+      minLength: 0,
+      forceUserInput: true,
+      fetch: (searchText, updateCallback) => {
+        updateCallback(this.areas); // add here the array
+      },
+    }
+  }
+},
+];
+```
+You can also use the `minLength` to limit the autocomplete text to `0` characters or more, the default number is `3`.
+
+### How to change drop container dimensions?
+You might want to change the dimensions of the drop container, this 3rd party library has a `customize` method to deal with such a thing. Slickgrid-Universal itself is removing the width using this method, you can however override this method to change the drop container dimensions
+
+```ts
+this.columnDefinitions = [
+  {
+    id: 'product', name: 'Product', field: 'product', filterable: true,
+    editor: {
+      model: Editors.autocompleter,
+      alwaysSaveOnEnterKey: true,
+
+      // example with a Remote API call
+      options: {
+        minLength: 1,
+        fetch: (searchTerm, callback) => {
+          // ...
+        },
+        customize: (_input, _inputRect, container) => {
+          // change drop container dimensions
+          container.style.width = '250px';
+          container.style.height = '325px';
+        },
+      } as AutocompleterOption,
+    },
+  }
+];
+```
+
+## Animated Gif Demo
+### Basic (default layout)
+![](https://user-images.githubusercontent.com/643976/50624023-d5e16c80-0ee9-11e9-809c-f98967953ba4.gif)
+
+### with `twoRows` custom layout (without optional left icon)
+![](https://i.imgur.com/V9XzVXS.gif)
+
+### with `fourCorners` custom layout (with extra optional left icon)
+![](https://i.imgur.com/LirGZFm.gif)