В моем последнем посте я рассказал о надежных возможностях API-интерфейсов Qlik Sense (QS) для создания готовых визуальных метафор и способах их интеграции в экосистему Qlik. Естественным выбором для разработчиков при создании расширений QS на протяжении многих лет был Extension API , в  основном использующий ванильный JavaScript, jQuery и AngularJS.

API расширений состоит из методов и свойств, используемых для создания пользовательских расширений визуализации.

Введите… Решение Qlik Sense с открытым исходным кодом — Nebula.js ! 

Nebula.js — это набор библиотек и API-интерфейсов JavaScript, не зависящих от продукта и платформы, которые помогают разработчикам интегрировать визуализации и гибридные приложения поверх Qlik Associative Engine в QS Desktop, QS Enterprise для Windows и SaaS-редакции Qlik Sense. Это руководство специально относится к выпуску QS SaaS. Nebula.js предлагает разработчикам альтернативу API возможностей, которые исторически использовались для создания гибридных приложений. В этом руководстве основное внимание будет уделено разработке новой визуализации на основе пользовательского сценария с использованием Nebula.js и сторонней библиотеки визуализации D3.js. Наша цель — понять, как мы можем использовать Nebula.js для создания объекта расширения QS и реализации готовых возможностей визуализации в рамках SaaS .Платформа. В этом руководстве не делается акцент на части программирования D3.js, но обсуждается мотивация визуализации.

Сценарий пользователя. У организации, использующей Qlik Sense, есть новое требование по разработке визуального представления для понимания многомерного многомерного набора данных для своей организации. Их набор данных состоит из числовых значений, и они хотят сравнить несколько объектов вместе, чтобы проанализировать отношения между ними. Основываясь на этих требованиях, их инженер по визуализации данных представляет им «график с параллельными координатами». 

Итак, что такое график с параллельными координатами?

Графики с параллельными координатами (PCP) доказали свою эффективность при эффективной визуализации многомерных наборов данных высокой размерности. В параллельных координатах каждый объект представлен в виде вертикальных полос, а значения нанесены на график в виде серии линий, соединенных по каждой оси. Их преимущество в том, что вертикальные полосы (функции) могут иметь собственный масштаб, поскольку каждая функция работает с разными единицами измерения. PCP дает представление о конкретных скрытых закономерностях в данных, таких как сходства, кластеры и т. д., и позволяет проводить более простой сравнительный анализ.

Основываясь на требованиях, давайте начнем с создания расширения QS с помощью Nebula.js .

Предпосылки :

1. Node.js (версия 10 или новее)
2. Терминал (например, Git Bash в Windows или Terminal в Mac)
3. IDE на ваш выбор, например, VS Code.
4. Существующая веб-интеграция или возможность ее создания в вашем арендаторе (особенно это относится к выпуску QS SaaS).
5. Приложение Qlik Sense с данными.

Шаг 1: Используйте интерфейс командной строки nebula.js для импорта необходимых пакетов. Команда помещает проект в папку /hello со следующей структурой:

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

Команда:

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

Шаг 2: Запустите сервер разработки, выполнив:

cd hello
npm run start

Команда запускает локальный сервер разработки и открывает http://localhost:8080 в вашем браузере. Преимущество наличия сервера разработки с Nebula.js заключается в том, что он предоставляет интерактивный способ тестирования и редактирования вашего расширения без необходимости итеративного развертывания в QS каждый раз, когда вносится новое изменение.

Шаг 3: Настройте структуру данных.

Визуализации в QS основаны на определении гиперкуба (qHyperCubeDef). Следовательно, любой новый визуальный объект, который мы хотим добавить в экосистему QS, должен иметь определенную структуру данных. В Nebula.js у нас есть файл object-properties.js, который позволяет определить структуру нашего объекта.

const properties = {
  showTitles: true,
  qHyperCubeDef: {
    qInitialDataFetch: [{ qWidth: 30, qHeight: 200 }],
  }
}

Нам также необходимо установить цель данных в файле data.js, чтобы мы ссылались на правильное определение гиперкуба (важно отметить, если у вас есть несколько объектов qHyperCubeDef).

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

Шаг 4: Разработка расширения визуализации с использованием Nebula.js и D3.js.

Специальный код QS Nebula.js:

Теперь, когда у нас все готово, мы начинаем разработку нашего расширения с пользовательским объектом визуализации, используя файл index.js из нашего проекта.

Обратите внимание, что Nebula.js и его основной пакет @nebula.js/stardust построены на концепции настраиваемых хуков . Это может показаться знакомым людям, работающим с React.js . Хуки — это концепция, которая делает упор на повторно используемые составные функции, а не на классические объектно-ориентированные классы и наследование. Основные хуки, от которых мы зависим при разработке нашего объекта расширения, описаны ниже:

Метод, который помогает нам визуализировать наш объект визуализации, — это функция component(). Функция component() выполняется каждый раз, когда что-то, связанное с рендерингом объекта, изменяется, например, тема, модель данных, выборка данных, состояние компонента и т. д. Эту функцию можно сравнить с функцией paint() в Extension API.

Чтобы отобразить наши данные, нам сначала нужно получить доступ к макету через хук useLayout, а затем использовать его в сочетании с хуком useEffect. qDataPages [0].qMatrix гиперкуба содержит все данные (измерения и меры), используемые в среде QS, и нам нужно будет передать эти данные в нашу визуализацию на основе D3.js.

component() {
      const element = useElement();
      const layout = useLayout();
      useEffect(() => {
        var qMatrix = layout.qHyperCube.qDataPages[0].qMatrix;
      }
                }

Чтобы увидеть значения данных и понять структуру qHyperCube , всегда полезно выполнить console.log(layout) . Фрагмент показывает значения, характерные для нашего варианта использования. Каждый раз, когда к нашему объекту расширения добавляется новое измерение или мера, qDataPages[0].qMatrix обновляется этими значениями .

Затем необходимые значения измерения для нашей диаграммы извлекаются из гиперкуба с использованием свойства qText из qDataPages[0].qMatrix, как показано ниже.

var data = qMatrix.map(function (d) {
          return {
            PetalLength: d[0].qText,
            PetalWidth: d[1].qText,
            SepalLength: d[2].qText,
            SepalWidth: d[3].qText,
            Species: d[4].qText,
          };
        });

Наш следующий шаг — определить ширину и высоту объекта визуализации и зафиксировать его идентификатор . Мы будем использовать этот идентификатор для привязки его к нашему объекту элемента из хука useLayout, как показано ниже:

var width = 1000;
var height = 400;
var id = "container_" + layout.qInfo.qId;
const elem_new = `<div id=${id}></div>`;
element.innerHTML = elem_new;

Наконец, мы вызываем функцию D3.js из хука useEffect.

viz(data, width, height, id);

Специальный код D3.js:

Функция viz() содержит весь наш код D3.js, который позволяет нам рисовать график в параллельных координатах. Во-первых, нам нужно добавить SVG к <div> , содержащему идентификатор нашего объекта QS, как показано ниже.

var svg = d3
          .select("#" + id)
          .append("svg")
          .attr("width", width + margin.left + margin.right)
          .attr("height", height + margin.top + margin.bottom)
          .append("g")
          .attr(
            "transform",
            "translate(" + margin.left + "," + margin.top + ")"
          );

Затем мы получаем все измерения, кроме Species , для построения наших осей x и y.

var dimensions = Object.keys(data[0]).filter(function (d) {
          return d != "Species";
        });

        var y = {};
        for (var i in dimensions) {
          var name_new = dimensions[i];
          y[name_new] = d3.scaleLinear().domain([0, 8]).range([height, 0]);
        }

        var x = d3.scalePoint().range([0, width]).domain(dimensions);

Чтобы нарисовать линии для нашего графика с параллельными координатами, нам нужно построить функцию пути , которая будет брать строку из нашего qHyperCube и возвращать координаты x и y линии.

function path(d) {
          return d3.line()(
            dimensions.map(function (p) {
              return [x(p), y[p](d[p])];
            })
          );
        }

И, наконец, мы связываем все с нашим SVG, как показано ниже:

svg
  .selectAll("myPath")
  .data(data)
  .enter()
  .append("path")
  .attr("class", function (d) {
    return "line " + d.Species;
  })
  .attr("d", path)
  .style("fill", "none")
  .style("stroke", function (d) {
    return color(d.Species);
  })
  .style("opacity", 0.5);

Шаг 5: Развертывание расширения.

Чтобы создать наш проект, мы используем приведенную ниже команду, чтобы сгенерировать все файлы, доступные для чтения QS, и поместить их в папку /hello-ext. Затем эту папку можно сжать (.zip) и загрузить в раздел расширений консоли SaaS для использования в среде QS.

npm run sense

Dashboard:

Если вы только начинаете работать с Nebula.js, https://qlik.dev — отличное место для ознакомления с основами и подробного изучения связанных функций.

Исходный код этого проекта доступен по адресу: https://github.com/dipankarqlik/Nebula

Сообщение Создание Extension с помощью qlik nebula.js и D3.js – Tutorial появились сначала на Qlik Sense - Обучение, учебник, онлайн курс.

В этом уроке мы создадим расширение 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 он появится.

Сообщение Создание Extensions с помощью nebula.js – пример Hello World появились сначала на Qlik Sense - Обучение, учебник, онлайн курс.