В этом уроке мы создадим расширение HelloWorld, используя nebula.js и Qlik Sense Desktop

Видео

Hello World Extension – What is Nebula.js?

Making Sense of Qlik APIs – Nebula CLI

Создайем расширение HelloWorld, используя nebula.js

В этом руководстве вы узнаете, как создать простое расширение, отображающее таблицу с использованием nebula.js.

В статье будут пройдены следующие шаги:

1. Создание проекта
2. Настройка структуры данных
3. Данные рендеринга
4. Выбор данных
5. Создание и загрузка расширения

Примечание. Чтобы загрузить расширение в Qlik Sense SaaS, вам необходим доступ к тенанту Qlik Sense SaaS и либо права администратора тенанта, либо средства для получения ключа API, сгенерированного для вас. Вы можете подписаться на бесплатную пробную версию , если у вас нет существующего клиента.

Требования

Этот учебник требует, чтобы у вас было следующее:

• Node.js (версия 10 или новее)
• Терминал (например , Git Bash для Windows или Terminal.app для Mac)
• Современный веб-браузер, например Google Chrome
• Текстовый редактор или IDE по вашему выбору, например Visual Studio Code.
• Существующая веб-интеграция или возможность ее создания. Или клиент Qlik Sense Desktop.

Создание проекта

Самый быстрый способ начать работу — использовать nebula.js интерфейс командной строки:

npx @nebula.js/cli create hello --picasso none

Параметр --picasso none указывает команде не создавать шаблон визуализации Пикассо, другие параметры – minimalи barchart.

Команда формирует проект в папке /hello со следующей структурой:

• /src
  • index.js – Основная точка входа этой визуализации
  • object-properties.js – Свойства объекта, хранящиеся в приложении
  • data.js – Конфигурация данных
• /test – Интеграционные тесты
• package.json

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

Запуск сервера разработки

Запустите сервер разработки с помощью команды:

cd hello
npm run start

Команда запускает локальный сервер разработки и открывает http://localhost:8080 в вашем браузере.

Сервер разработки должен подключаться к ассоциативному движку Qlik, работающему в любом развертывании Qlik. Введите URL-адрес WebSocket, соответствующий используемому вами продукту Qlik.

Чтобы открыть WebSocket для движка, используйте один из следующих URI:

• Qlik Sense Enterprise: wss://server.domain.com:4747/ или wss://server.domain.com[/virtual proxy]/
• Qlik Sense Desktop: ws://localhost:4848/

Затем выберите приложение для подключения.

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

Любые обновления /src/index.js, влияющие на вывод, автоматически вызывают обновление визуализации, и вы сразу же видите изменения.

Настроить структуру данных

Простое Helloсообщение на самом деле не так уж полезно, пора добавить некоторые данные.

Добавьте qHyperCubeDef определение в object-properties.js:

const properties = {
  qHyperCubeDef: {
    qInitialDataFetch: [{ qWidth: 2, qHeight: 10 }],
  },
  // ...
};

Затем добавьте /qHyperCubeDef в качестве цели данных в data.js:

export default {
  targets: [
    {
      path: '/qHyperCubeDef',
    },
  ],
};

После этих изменений у вас должна появиться возможность добавлять данные на панели свойств справа:

Добавьте измерение, нажав Add dimension и выбрав значение в появившемся меню. Затем проделайте то же самое с мерой – Add measures.

Данные рендеринга

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

import { useLayout, useElement, useEffect } from '@nebula.js/stardust';

// ...
component() {
  console.log(useLayout());
}

Затем вы можете useLayout в сочетании с useEffect отображать заголовки и строки данных в qHyperCube:

component() {
  const element = useElement();
  const layout = useLayout();

  useEffect(() => {
    if (layout.qSelectionInfo.qInSelections) {
      // skip rendering when in selection mode
      return;
    }
    const hc = layout.qHyperCube;

    // headers
    const columns = [...hc.qDimensionInfo, ...hc.qMeasureInfo].map((f) => f.qFallbackTitle);
    const header = `<thead><tr>${columns.map((c) => `<th>${c}</th>`).join('')}</tr></thead>`;

    // rows
    const rows = hc.qDataPages[0].qMatrix
      .map((row) => `<tr>${row.map((cell) => `<td>${cell.qText}</td>`).join('')}</tr>`)
      .join('');

    // table
    const table = `<table>${header}<tbody>${rows}</tbody></table>`;

    // output
    element.innerHTML = table;

  }, [element, layout])
}

Выберите данные

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

// rows
const rows = hc.qDataPages[0].qMatrix
  .map(
    (row, rowIdx) =>
      `<tr data-row="${rowIdx}">
        ${row.map((cell) => `<td>${cell.qText}</td>`).join('')}
      </tr>`
  )
  .join('');

Затем добавьте 'click'обработчик событий, elementкоторый выполняет следующие действия:

• Проверяет, что выбранный элемент является td
• Начинает выбор /qHyperCubeDef, если он еще не активирован
• Извлекает data-row индекс из tr
• Обновления selectedRows по клику data-row

const element = useElement();
const selections = useSelections();
const [selectedRows, setSelectedRows] = useState([]);

useEffect(() => {
  const listener = (e) => {
    if (e.target.tagName === 'TD') {
      if (!selections.isActive()) {
        selections.begin('/qHyperCubeDef');
      }
      const row = +e.target.parentElement.getAttribute('data-row');
      setSelectedRows((prev) => {
        if (prev.includes(row)) {
          return prev.filter((v) => v !== row);
        }
        return [...prev, row];
      });
    }
  };

  element.addEventListener('click', listener);

  return () => {
    element.removeEventListener('click', listener);
  };
}, [element]);

Затем обновите стиль выбранных строк в таблице всякий раз, когда они изменяются:

useEffect(() => {
  if (!layout.qSelectionInfo.qInSelections) {
    // no need to update when not in selection mode
    return;
  }
  element.querySelectorAll('tbody tr').forEach((tr) => {
    const idx = +tr.getAttribute('data-row');
    tr.style.backgroundColor = selectedRows.includes(idx) ? '#eee' : '';
  });
}, [element, selectedRows, layout]);

Наконец, примените выбранные значения через selections API:

useEffect(() => {
  if (selections.isActive()) {
    if (selectedRows.length) {
      selections.select({
        method: 'selectHyperCubeCells',
        params: ['/qHyperCubeDef', selectedRows, []],
      });
    } else {
      selections.select({
        method: 'resetMadeSelections',
        params: [],
      });
    }
  } else if (selectedRows.length) {
    setSelectedRows([]);
  }
}, [selections.isActive(), selectedRows]);

Создайте и загрузите расширение

До сих пор вы работали в локальной изолированной среде над диаграммой, которая не зависела от какого-либо конкретного продукта Qlik.

Команда:

npm run build

генерирует пакет в /dist папку, и это все, что вам нужно для распространения диаграммы в виде пакета npm.

Однако Qlik Sense требует некоторых дополнительных файлов и немного другого формата для интерпретации диаграммы как расширения. Чтобы сгенерировать эти файлы, вы можете запустить команду:

npm run sense

Команда создает все файлы в папку /hello-ext, которую затем можно использовать в качестве расширения в Qlik Sense по вашему выбору.

Чтобы загрузить расширение в клиент Qlik Sense SaaS, следуйте инструкциям по управлению расширениями.

Важная и неочевидный шаг для использования собранного расширения из директории hello-ext: Обязательно нужно удалить “-ext” из директории, иначе экстеншен не будет работать и появится приписка, что экстеншен не найден на сервере. Хотя в списке визуализаций в Qlik Sense он появится.