Класс Dialog

Описание

Основной класс для работы с диалогом выбора сущностей и его элементами.

Импорт в ES6

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

Использование в ES5

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

События

Класс Dialog является наследником класса EventEmitter. Обработчики события можно установить либо с помощью опции events, либо через стандартный метод 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(() => { // эмуляция асинхронного действия
					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(dialogOptions: DialogOptions): Dialog

Создает объект класса Dialog.

dialogOptions — опции диалога, которые определяются структурой 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-элемент, около которого отобразится всплывающий диалог.



• id?: string

  Идентификатор диалога.
  Может использоваться для получения объекта диалога в методе Dialog.getById(id).



• context?: string

  Идентификатор контекста.
  Используется для сохранения выбранных элементов на вкладке "Последние". Если контекст не задан, выбор пользователя не сохраняется, элементы на вкладке "Последние" сортируются с учетом их выбора в других контекстах.



• items?: ItemOptions[]

  Массив элементов диалога. Каждый элемент определяется структурой ItemOptions.



• selectedItems?: ItemOptions[]

  Массив элементов диалога (аналогично опции items), все элементы которого автоматически определяются как "выбранные".



• preselectedItems?: ItemId[]

  Массив идентификаторов выбранных элементов, данные по которым должен получить диалог от провайдеров сущностей. Каждый элемент определяется структурой ItemId.

  type ItemId = [
  	string,
  	string | number
  ];
  

  ItemId — это массив из двух элементов. Первый элемент представляет идентификатор сущности элемента (entityId), а второй — идентификатор самого элемента (id).

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

  Данная опция обычно используется для заполнения виджета TagSelector элементами, о которых заранее известно, что они выбраны. Диалог автоматически выполнит динамическую загрузку элементов (в момент создания объекта new Dialog), если установлена опция preselectedItems.



• undeselectedItems?: ItemId[]

  Массив идентификаторов элементов, у которых нельзя снять выбор. Каждый элемент определяется структурой ItemId.



• tabs?: TabOptions[]

  Массив вкладок диалога. Каждая вкладка определяется структурой TabOptions.

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



• entities?: EntityOptions[]

  Массив с настройками сущностей диалога. Каждая сущность определяется структурой EntityOptions.

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

  Как правило, в опции entities указывают только идентификаторы сущностей, элементы которых необходимо динамически загрузить, а также настройки для провайдеров данных. Настройки же самих сущностей (опции структуры EntityOptions) обычно определяют глобально. Однако эти глобальные настройки можно всегда переопределить:

  const options = {
  	entities: [
  		{
  			id: 'user',
  			dynamicLoad: false, // запрещаем динамическую загрузку
  			dynamicSearch: false, // запрещаем динамический поиск
  			searchFields: [ // определяем другие поля поиска
  				{ 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

  Дополнительные настройки для Popup-диалога, на котором основан диалог выбора сущностей. Определяются структурой PopupOptions, однако разрешены только следующие значения: overlay, bindOptions, targetContainer, zIndexOptions.



• multiple?: boolean

  По умолчанию диалог работает в режиме множественного выбора (значение true). Значение false ограничивает выбор только одним элементом.



• preload?: boolean

  По умолчанию загрузка элементов с бэкенда (если требуется) происходит в момент открытия диалога. Если установлено значение true, загрузка данных произойдет автоматически при создании объекта диалога.



• dropdownMode?: boolean

  Значение true включает режим простого списка. В этом режиме скрывается ярлык вкладки "Последние".



• enableSearch?: boolean

  Включает форму поиска внутри диалога.



• searchOptions?: SearchOptions

  Устанавливает настройки формы поиска. Определяется структурой SearchOptions.

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

  • allowCreateItem?: boolean

    Включает возможность создавать новые элементы через поиск.

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

    Дополнительные настройки для футера на вкладке "Поиск". Опция label определяет базовый заголовок для футера.

  const options = {
  	searchOptions: {
  		allowCreateItem: true,
  		footerOptions: {
  			label: 'Создать город:'
  		}
  	},
  }
  



• searchTabOptions?: TabOptions

  Позволяет переопределить настройки системной вкладки "Поиск". Настройки определяются структурой TabOptions.



• recentTabOptions?: TabOptions

  Позволяет переопределить настройки системной вкладки "Последние". Настройки определяются структурой TabOptions.



• tagSelectorOptions?: TagSelectorOptions

  Задает дополнительные настройки встроенной форме поиска (TagSelector) при включенной настройке enableSearch=true. Настройки определяются структурой TagSelectorOptions.



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

  Задает обработчики событий диалога.



• hideOnSelect?: boolean

  Скрывать диалог после выбора элемента. По умолчанию диалог скрывается для одиночного выбора элемента (multiple=false), для множественного выбора — не скрывается.



• hideOnDeselect?: boolean

  Скрывать диалог после снятия выбора элемента. По умолчанию диалог не скрывается.



• clearSearchOnSelect?: boolean

  Очищать форму поиска после выбора элемента. По умолчанию true.



• width?: number

  Ширина диалога в пикселях. По умолчанию 565.



• height?: number

  Высота диалога в пикселях. По умолчанию 420.



• autoHide?: boolean

  Автоматически скрывать диалог по клику в любую область страницы. По умолчанию true.



• hideByEsc?: boolean

  Автоматически скрывать диалог по нажатию клавиши Escape. По умолчанию true.



• offsetTop?: number

  Смещение диалога относительно targetNode по оси ординат. По умолчанию 5.



• offsetLeft?: number

  Смещение диалога относительно targetNode по оси абсцисс. По умолчанию 0.



• cacheable?: boolean

  Если установлено значение false, диалог будет автоматически уничтожен после скрытия. По умолчанию true (не уничтожать).



• focusOnFirst?: boolean

  Устанавливать фокус на первый элемент списка. По умолчанию true.



• footer?: FooterContent

  Задает глобальный (на все вкладки) футер диалога. Определяется структурой FooterContent.

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

  Футер можно задать несколькими способами:

  • Если передана верстка в виде DOM-узла, массива DOM-узлов или текстовой строки, будет создан футер по умолчанию (объект класса DefaultFooter) с указанным текстовым контентом.
  
  
  • Для создания произвольного футера необходимо передать либо ссылку на конструктор класса (наследник BaseFooter или DefaultFooter), либо указать полное имя класса в виде строки.

  Для верстки ссылок в футере доступны следующие CSS-классы:

  • .ui-selector-footer-link — обычная ссылка.
  • .ui-selector-footer-link ui-selector-footer-link-add — ссылка с иконкой "плюс".
  • .ui-selector-footer-conjunction — для оформления связующих слов между ссылками.


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

  Произвольные опции футера. Передаются в конструктор класса футера.



• showAvatars?: boolean

  Отображать аватары элементов. По умолчанию true. Данная опция определяет поведение для всех вкладок по умолчанию, однако, эту настройку можно переопределить для конкретной вкладки (аналогичная опция showAvatars).



• compactView?: boolean

  Определяет компактный вид отображения элементов. По умолчанию false. Рекомендуется использовать для элементов без аватаров (showAvatars=false).



• clearUnavailableItems?: boolean

  Удалять элемента из списка "Последних", если провайдеры сущностей не возвращают для них данные. По умолчанию false.

Методы