Параметры для статического встраивания¶

Примечание

Также известно как: параметры для подписанного встраивания или автономного встраивания.

С помощью параметров вы можете передавать данные между Glarus BI и вашим веб‑сайтом через URL встраивания: задавать, как элементы Glarus BI должны выглядеть и вести себя внутри iframe.

Типы параметров¶

Параметры могут быть подписанными и неподписанными.

Подписанные параметры¶

Подписанные параметры (например, названия и значения фильтров) нужно добавлять в серверный код.

Редактируемые параметры
Заблокированные параметры

Неподписанные параметры¶

Неподписанные параметры (например, настройки внешнего вида) нужно добавлять прямо в атрибут src вашего iframe.

Значения по умолчанию для редактируемых параметров
Настройки видимости для редактируемых параметров
Настройки внешнего вида

Добавление виджета фильтра в статическое встраивание¶

Вы можете использовать редактируемые параметры, чтобы добавить виджеты фильтров во встроенные дашборды или запросы SQL.

Откройте дашборд или SQL‑запрос. Убедитесь, что вы настроили фильтр дашборда или переменную SQL.
Нажмите на значок общего доступа > Встроить в приложение.
В разделе Параметры вы увидите названия фильтров дашборда или SQL‑переменных.
Для каждого параметра, который должен получить виджет‑фильтр во встраивании, выберите Редактируемо.
Нажмите Опубликовать, чтобы сохранить изменения.
Добавьте или обновите код на вашем сервере так, чтобы он соответствовал коду, сгенерированному Glarus BI.

Редактируемые параметры отвечают за передачу значений из встроенного виджета фильтра (который отображается в iframe) в фильтры вашего исходного дашборда или SQL‑запроса (в вашем Glarus BI).

Нельзя отключить параметр, если исходный запрос или дашборд требует значение¶

Если фильтр на дашборде или в запросе настроен как "Всегда требовать заполнения", вы не сможете отключить параметр при встраивании.

Заполнение виджета фильтра значением по умолчанию¶

Если вы хотите задать значение по умолчанию для редактируемого виджета фильтра, добавьте это значение в атрибут src вашего iframe как значение соответствующего параметра:

your_embedding_url?parameter_name=value

Например, если во встроенном дашборде есть фильтр, связанный с редактируемым параметром Breakfast, и вы хотите, чтобы значение по умолчанию было Scrambled_eggs, добавьте:

your_embedding_url?breakfast=Scrambled_eggs

Чтобы задать значения по умолчанию для нескольких фильтров, разделяйте их амперсандом (&):

your_embedding_url?breakfast=Scrambled_eggs&lunch=Grilled_cheese

Вы можете задать несколько значений по умолчанию для одного фильтра, повторяя параметр и разделяя значения амперсандом (&):

your_embedding_url?breakfast=Scrambled_eggs&breakfast=Bacon

Скрытие виджетов фильтров в статическом встраивании¶

Если у вас несколько редактируемых параметров (и, соответственно, несколько виджетов‑фильтров), вы можете скрывать отдельные виджеты, добавляя #hide_parameters в конец URL в атрибуте src вашего iframe:

your_embedding_url#hide_parameters=parameter_name

Например, чтобы скрыть фильтр Breakfast во встроенном дашборде:

your_embedding_url#hide_parameters=breakfast

Чтобы скрыть несколько виджетов фильтров, перечислите параметры через запятую:

your_embedding_url#hide_parameters=breakfast,lunch

Можно одновременно задать значение параметра по умолчанию и скрыть его виджет фильтра:

your_embedding_url?breakfast=Scrambled_eggs#hide_parameters=breakfast

Синтаксис неподписанных параметров¶

Когда вы добавляете параметр в URL встраивания в атрибуте src вашего iframe, учитывайте:

названия параметров — в нижнем регистре;
значения параметров чувствительны к регистру (значения должны совпадать с вашими данными).
пробелы нужно заменять подчёркиваниями.

Ограничение данных в статическом встраивании с помощью заблокированных параметров¶

Если вы хотите ограничить данные, которые показываются во встроенном дашборде или SQL‑запросе, настройте заблокированный параметр. Заблокированный параметр фильтрует данные в дашборде или SQL‑запросе до того, как результат будет показан пользователям в статическом встраивании.

Откройте дашборд или SQL‑запрос. Убедитесь, что вы настроили фильтр дашборда или SQL‑переменную.
Нажмите на значок общего доступа > Встраивание элемента в приложение.
В разделе Параметры вы увидите названия фильтров дашборда или переменных SQL.
Для каждого параметра, через который вы хотите ограничивать данные, выберите Заблокирован.
Опционально: выберите значение в Предварительный просмотр заблокированных параметров, чтобы увидеть, как будут выглядеть данные при ограничении.
Нажмите Опубликовать, чтобы сохранить изменения.
Добавьте или обновите код на вашем сервере так, чтобы он соответствовал коду, который сгенерирован Glarus BI.

Заблокированные параметры можно использовать, чтобы показывать отфильтрованные данные на основе атрибутов, которые использует ваш сервер (например, username или tenant ID). Больше примеров — в reference apps repo (ссылка на github.com).

Заблокированные параметры применяют выбранные значения фильтров к вашему исходному дашборду или SQL‑запросу, но не показываются как виджеты фильтров во встраивании. Заблокированные параметры также могут ограничивать значения, которые будут доступны в ваших редактируемых виджетах фильтров.

Если вам нужно лишь сделать значение обязательным, можно оставить параметр редактируемым и настроить исходный запрос или дашборд так, чтобы он всегда требовал значение.

Обновление заблокированного параметра¶

Что важно учитывать, если вам нужно менять заблокированные параметры.

В серверном коде должны быть указаны все заблокированные параметры¶

После публикации графика или дашборда с заблокированным параметром требуется передавать название этого параметра в серверном коде. Если вы опустите название параметра, в журналах появится сообщение вроде этого: You must specify a value for :parameter in the JWT.

Чтобы отключить заблокированный параметр, передайте пустой массив в JWT¶

Если вы не хотите, чтобы заблокированный фильтр применялся, передайте пустой массив [] как значение параметра в JWT.

Убедитесь, что название фильтра совпадает с названием заблокированного параметра¶

Если вы меняете название фильтра из конструктора запросов, который используется как заблокированный параметр, обязательно обновите название параметра и значение(я) в серверном коде. Если заблокированный параметр связан с переменной SQL, менять название и значения не нужно.

Несколько заблокированных параметров или несколько значений¶

Значения для заблокированного параметра в серверном коде должны точно совпадать со значениями фильтра. Самый надёжный способ правильно задать несколько заблокированных параметров или передать несколько значений в заблокированный параметр — выбрать значение в Предварительный просмотр заблокированных параметров и посмотреть серверный код, который сгенерировал Glarus BI.

Если использовать несколько заблокированных параметров одновременно, фильтрация будет работать через AND, а не через OR. Если нужно применить только часть заблокированных параметров, вам нужно явно сказать Glarus BI игнорировать остальные заблокированные параметры.

Заблокированные параметры ограничивают значения, доступные в других редактируемых параметрах¶

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

Например, вы встраиваете дашборд с двумя фильтрами: State и City. Если вы заблокируете параметр State со значением Vermont, Glarus BI покажет в дашборде только виджет‑фильтр City, а выпадающий список для City будет содержать только города из Vermont. Хотя вы явно не связываете два фильтра, они будут вести себя как связанные фильтры.

Заблокированные параметры на дашбордах с SQL‑запросами¶

Если ваш заблокированный параметр связан с фильтром дашборда, который, в свою очередь, связан с SQL‑запросом, вы сможете выбрать только одно значение для заблокированного параметра.

Например, у вас есть фильтр дашборда Breakfast со значениями Hash browns, Muffin и Waffles. Если фильтр Breakfast связан хотя бы с одним SQL‑запросом на дашборде, вы сможете выбрать только один вариант для заблокированного параметра, связанного с фильтром Breakfast.

Использование заблокированных параметров для пользовательских виджетов в вашем приложении¶

Поскольку Glarus BI не показывает заблокированные параметры как виджеты‑фильтры, вы можете использовать заблокированные параметры как основу для собственных виджетов фильтров в вашем приложении. Это может быть полезно, если вы хотите:

сделать виджеты визуально более согласованными с дизайном вашего приложения;
добавить собственную логику (например, чтобы виджет сохранял последние значения);
использовать один и тот же дашборд по‑разному в разных частях приложения. Например, у вас может быть дашборд с несколькими заблокированными параметрами: в одном месте вы блокируете его по region, а в другом — по team.

Настройка внешнего вида статического встраивания¶

Настройки внешнего вида статического встраивания

Вы можете изменить внешний вид встроенного элемента, добавив hash‑параметры (например, #theme=night) в конец URL в атрибуте src вашего iframe.

Например, следующий URL встраивания покажет элемент в тёмном режиме, без рамки и с исходным заголовком:

your_embedding_url#theme=night&bordered=false&titled=true

Вы можете предварительно просмотреть настройки внешнего вида в настройках встраивания вашего запроса или дашборда.

Название параметра	Возможные значения
`background`	`true` (по умолчанию), `false`. Только для дашбордов.
`bordered`	`true` (по умолчанию), `false`.
`titled`	`true` (по умолчанию), `false`.
`theme`	`null` (по умолчанию), `night`. `theme=transparent` должно работать, но помечено как deprecated (см. прозрачные фоны).
`refresh` (только дашборд)	целое число (секунды, например, `refresh=60`).

Для глобальных настроек внешнего вида (например, цветов и шрифтов, используемых во всём экземпляре) см. настройку внешнего вида.

Прозрачные фоны для встраиваний¶

Как сделать фон прозрачным, зависит от типа встраивания:

Дашборды: задайте background=false. Параметр background можно комбинировать с theme (например, background=false&theme=night).
Запросы: задайте theme=transparent (deprecated, но всё ещё поддерживается).

Максимальный размер запроса¶

Максимальная длина URL статического встраивания (включая все параметры) задаётся значением вашей переменной окружения MB_JETTY_REQUEST_HEADER_SIZE. По умолчанию 8 192 байта.

Если URL статического встраивания превышает максимальный размер заголовка, вы увидите в логах сообщение вроде URI too long. Вы можете увеличить значение переменной окружения, чтобы принимать более длинные заголовки. Если вы используете прокси‑сервер, возможно, потребуется настроить соответствующий параметр и на нём.