Dialog class

Description

Main class for handling entity selector dialog and its items.

Import to ES6

import { Dialog } from 'ui.entity-selector';

Use in ES5

var dialog = new BX.UI.EntitySelector.Dialog(options);

Events

Dialog class is descendant for class EventEmitter. Event handers can be set using either the events option, or using the standard method EventEmitter.subscribe.

const options = {
  events: {
      'onShow': (event: BaseEvent) => {
          const dialog: Dialog = event.getTarget();
      }
  }
}

const options = {
  events: {
      'onFirstShow': (event: BaseEvent) => {
          const dialog: Dialog = event.getTarget();
      }
  }
}

const options = {
  events: {
      'onHide': (event: BaseEvent) => {
          const dialog: Dialog = event.getTarget();
      }
  }
}

const options = {
  events: {
      'onDestroy': (event: BaseEvent) => {
          const dialog: Dialog = event.getTarget();
      }
  }
}

const options = {
  events: {
      'onSearch': (event: BaseEvent) => {
          const dialog: Dialog = event.getTarget();
          const { query } = event.getData();
      }
  }
}

const options = {
  events: {
      'onLoad': (event: BaseEvent) => {
          const dialog: Dialog = event.getTarget();
      }
  }
}

const options = {
  events: {
      'onLoadError': (event: BaseEvent) => {
          const dialog: Dialog = event.getTarget();
          const { error } = event.getData();
      }
  }
}

const options = {
  events: {
      'Item:onSelect': (event: BaseEvent) => {
          const { item: selectedItem } = event.getData();
          const dialog: Dialog = event.getTarget();
          const selectedItems: Item[] = dialog.getSelectedItems();
      }
  }
}

const options = {
  events: {
      'Item:onBeforeSelect': (event: BaseEvent) => {
          const { item } = event.getData();
          if (item.getId() === 1 && item.getEntityId() === 'user')
          {
              event.preventDefault();
          } 
      }
  }
}

const options = {
  events: {
      'Item:onDeselect': (event: BaseEvent) => {
          const { item: deselectedItem } = event.getData();
          const dialog: Dialog = event.getTarget();
          const selectedItems: Item[] = dialog.getSelectedItems();
      }
  }
}

const options = {
  events: {
      'Item:onBeforeDeselect': (event: BaseEvent) => {
          const { item } = event.getData();
          if (item.getId() === 1 && item.getEntityId() === 'user')
          {
              event.preventDefault();
          } 
      }
  }
}

const options = {
  events: {
      'Tab:onSelect': (event: BaseEvent) => {
          const { tab } = event.getData();
          const dialog: Dialog = event.getTarget(); 
      }
  }
}

const options = {
  events: {
      'Tab:onDeselect': (event: BaseEvent) => {
          const { tab } = event.getData();
          const dialog: Dialog = event.getTarget(); 
      }
  }
}

const options = {
    searchOptions: {
        allowCreateItem: true,
    },
    events: {
        'Search:onItemCreateAsync': (event) => {
            return new Promise((resolve) => {
                const { searchQuery } = event.getData();
                const dialog = event.getTarget();

                setTimeout(() => { // emulated asynchronous action
                    let tab = dialog.getTab('cities');
                    const item = dialog.addItem({
                        id: BX.Text.getRandom(),
                        entityId: 'city',
                        title: searchQuery.getQuery(),
                        tabs: 'cities',
                        sort: 1
                    });

                    if (item)
                    {
                        item.select();
                    }

                    dialog.selectTab(tab.getId());
                    resolve();

                }, 1000);
            });
        }
    }
}

Constructor

constructor(dialogOptions: DialogOptions): Dialog

Creates Dialog class object.

dialogOptions — dialog options, refined by the structure DialogOptions.

export type DialogOptions = {
	targetNode?: HTMLElement,
	id?: string,
	context?: string,
	items?: ItemOptions[],
	selectedItems?: ItemOptions[],
	preselectedItems?: ItemId[],
	undeselectedItems?: ItemId[],
	tabs?: TabOptions[],
	entities?: EntityOptions[],
	popupOptions?: PopupOptions,
	multiple?: boolean,
	preload?: boolean,
	dropdownMode?: boolean,
	enableSearch?: boolean,
	searchOptions?: SearchOptions,
	searchTabOptions?: TabOptions,
	recentTabOptions?: TabOptions,
	tagSelectorOptions?: TagSelectorOptions,
	events?: { [eventName: string]: (event: BaseEvent) => void },
	hideOnSelect?: boolean,
	hideOnDeselect?: boolean,
	clearSearchOnSelect?: boolean,
	width?: number,
	height?: number,
	autoHide?: boolean,
	hideByEsc?: boolean,
	offsetTop?: number,
	offsetLeft?: number,
	cacheable?: boolean,
	focusOnFirst?: boolean,
	footer?: FooterContent,
	footerOptions?: { [option: string]: any },
	showAvatars?: boolean,
	compactView?: boolean,
	clearUnavailableItems?: boolean,
}

• targetNode?: HTMLElement

  HTML item, with popup dialog near it.



• id?: string

  Dialog ID.
  Can be used for getting dialog object in the method Dialog.getById(id).



• context?: string

  Context ID.
  Can be used for saving selected items in the "Recent" tab. When context is not set, user selection is not saved, the "Recent" tab items are sorted based on their selection in other contexts.



• items?: ItemOptions[]

  Array with dialog items. Each item is defined by the structure ItemOptions.



• selectedItems?: ItemOptions[]

  Array with dialog items (similar to option items). All items are automatically defined as "selected".



• preselectedItems?: ItemId[]

  Array with selected item IDs, with data to be retrieved by dialog from entity providers. Each item is defined by the structure ItemId.

  type ItemId = [
    string,
    string | number
  ];
  

  ItemId — is an array with two items. First item provides item entity ID (entityId) and the second - the item ID itself (id).

  const options = {
    preselectedItems: [
        ['user', 1],
        ['department', 1],
        ['meta-user', 'all-users'],
        ['project', 2],
        ['department', '2:F'],
    ]
  }
  

  This option is usually used for completing the TagSelector widget with items, known to be selected beforehand. Dialog automatically completes dynamic loading of items (when creating the object new Dialog) with the set option preselectedItems.



• undeselectedItems?: ItemId[]

  Array with item IDs that cannot have the removed selection. Each item is defined by the structure ItemId.



• tabs?: TabOptions[]

  Array with dialog tabs. Each tab is defined by structure TabOptions.

  const options = {
    tabs: [
        { id: 'cities', title: 'Города', itemOrder: { title: 'asc' } },
        { id: 'countries', title: 'Страны', itemOrder: { id: 'desc' } },
    ],
  }
  



• entities?: EntityOptions[]

  Array with dialog entity settings. Each entity is defined by the structure EntityOptions.

  const options = {
    entities: [
        {
            id: 'meta-user',
            options: {
                'all-users': true
            }
        },
        {
            id: 'user',
            options: { emailUsers: true },
        },
        { id: 'project' },
        {
            id: 'department',
            options: {
                selectMode: 'usersAndDepartments'
            }
        },
    ],
  }
  

  Usually, you indicate only entity IDs in the entities option, with entity items to be dynamically loaded, as well as settings for data providers. Settings for the entities themselves (options for the structure EntityOptions) are usually defined globally. However, these global settings can be always re-defined:

  const options = {
    entities: [
        {
            id: 'user',
            dynamicLoad: false, // restrict dynamic loading
            dynamicSearch: false, // restrict dynamic search
            searchFields: [ // define other search fields
                { name: 'title', type: 'email', system: true, searchable: true },
                { name: 'subtitle', type: 'email', system: true, searchable: false },
                { name: 'position', type: 'string' },
                { name: 'email', type: 'email' }
            ],
        }
    ],
  }
  



• popupOptions?: PopupOptions

  Additional settings for popup-dialog. Entity selector dialog based in this dialog. Defined by structure PopupOptions. However, only the following values are permitted: overlay, bindOptions, targetContainer, zIndexOptions.



• multiple?: boolean

  By default, dialog operates in the multiple selection mode (true). False limits selection to a single item.



• preload?: boolean

  By default, item loading from the backend (if required) occurs at the moment of dialog opening. When set as true data loading occurs automatically when creating a dialog object.



• dropdownMode?: boolean

  True value enables the mode of a standard list. This mode hides "Recents" tab.



• enableSearch?: boolean

  Enables search form inside the dialog.



• searchOptions?: SearchOptions

  Sets search form settings. Defined by the structure SearchOptions.

  export type SearchOptions = {
    allowCreateItem?: boolean,
    footerOptions?: { [option: string]: any }
  } 
  

  • allowCreateItem?: boolean

    Enables the option to create new items using the search.

  
  
  • footerOptions?: { [option: string]: any }

    Additional settings for the footer at the "Search" tab. Option label defines the footer base title.

  const options = {
    searchOptions: {
        allowCreateItem: true,
        footerOptions: {
            label: 'Create city:'
        }
    },
  }
  



• searchTabOptions?: TabOptions

  Allows re-defining the configuration for the "Search" system tab. Settings are defined by the structure TabOptions.



• recentTabOptions?: TabOptions

  Allows re-defining настройки системной вкладки "Последние". Настройки определяются структурой TabOptions.



• tagSelectorOptions?: TagSelectorOptions

  Sets additional settings for inbuilt search form (TagSelector) with enabled setting enableSearch=true. Settings are defined by the structure TagSelectorOptions.



• events?: { [eventName: string]: (event: BaseEvent) => void }

  Sets dialog event handlers.



• hideOnSelect?: boolean

  Hides dialog after item selection. By default, dialog opens for single item selection (multiple=false), for multiple selection — not hidden.



• hideOnDeselect?: boolean

  Hide dialog after deselecting the item. Dialog doesn't hide by default.



• clearSearchOnSelect?: boolean

  Clear search form after selecting an item. Default value: true.



• width?: number

  Dialog width in pixels. Default value: 565.



• height?: number

  Dialog height in pixels. Default value: 420.



• autoHide?: boolean

  Automatically hide dialog by click at any page area. Default value: true.



• hideByEsc?: boolean

  Automatically hides dialog by clicking at Escape. Default value: true.



• offsetTop?: number

  Dialog offset relative to targetNode by X-axis. Default value: 5.



• offsetLeft?: number

  Dialog offset relative to targetNode by X-axis. Default value: 0.



• cacheable?: boolean

  When set as false, dialog will be automatically destroyed after being hidden. Default value: true (do not destroy).



• focusOnFirst?: boolean

  Set focus to the first list item. Default value: true.



• footer?: FooterContent

  Sets global (for all tabs) dialog footer. Defined by the structure FooterContent.

  export type FooterContent = string | HTMLElement | HTMLElement[] | Function;
  

  Footer can be set by several methods:

  • When passing the layout as a DOM-node, array with DOM-nodes or text string, creates the default footer (object of class DefaultFooter) with specified text content.
  
  
  • Creating an arbitrary footer requires passing either a link to class constructor (descendant for BaseFooter or DefaultFooter), or specify the full class name as a string.

  Link layout as a footer has the following available CSS-classes:

  • .ui-selector-footer-link — standard link.
  • .ui-selector-footer-link ui-selector-footer-link-add — link with "plus" icon.
  • .ui-selector-footer-conjunction — for defining linking words.


• footerOptions?: { [option: string]: any }

  Arbitrary footer options. Passed to footer class constructor.



• showAvatars?: boolean

  Show item avatars. True by default. This option defines behaviour for all default tabs, however, this option can be redefined for specific tab (similar option to showAvatars).



• compactView?: boolean

  Defines compact view for item display. False by default. Recommended for items without avatars (showAvatars=false).



• clearUnavailableItems?: boolean

  Delete item from "Recent" list when entity providers do not returns data from them. False by default.

Methods