Демо
Обучение
Блог
Главная

Использование SliderDataSDK – основной курс

СОДЕРЖАНИЕ

Введение
О курсе.
Целевая аудитория курса.
Разработчики корпоративных решений.
Системные администраторы и DevOps-инженеры..
Бизнес-аналитики с техническими навыками.
Технические писатели и документаторы..
Продвинутые пользователи офисных пакетов.
Предварительные требования.
Необходимые знания и навыки.
Желательные знания.
Техническое окружение.
Используемые библиотеки.
AlaSQL.js.
SheetJS.
ExcelJS.
jQuery.
Xmla.
Результаты обучения.
Глоссарий терминов.
Основные термины.
Термины SliderDataSDK.
Технические термины.
Форматы и стандарты.
Среда выполнения.
Операции с данными.

Модуль 1. Основы SliderDataSDK.
1. Цели модуля.
2. Описание модуля.
3. Архитектура решения, принципы работы.
4. Основная функциональность.
5. Основные составляющие решения.
6. Пример использования в макросах Р7.
7. Инструкция по развертыванию.
8. Системные требования.
9. Контрольные вопросы для Модуля 1.

Модуль 2. Компоненты SliderDataSDK. Класс XLDBProxy.js.
1. Цели модуля.
2. Описание модуля.
3. Назначение класса.
4. Зависимости.
5. Основные методы API, примеры их использования.
5.1 checkConnection(paramsName, options)
5.2 getTables(paramsName, options)
5.3 getViews(paramsName, options)
5.4 getFields(paramsName, options)
5.5 executeQuery(paramsName, options)
6. Полное описание методов XLDBProxy.js.
7. Пример использования XLDBProxy - запуск макроса «Комплексный тест».
8. Пример использования XLDBProxy - запуск макроса «Тест гетерогенных подключений».
9. Контрольные вопросы для Модуля 2.

Модуль 3. Компоненты SliderDataSDK. Работа с SQL запросами через AlaSQLProxy.
1. Цели модуля.
2. Описание модуля.
3. Назначение и область применения AlaSQLProxy.
4. Зависимости.
5. Ключевые преимущества, архитектура.
6. Основные методы API, примеры их использования.
6.1 executeQuery(query, params)
6.2 createLocalStorageDatabase(dbName)
6.3 readExcel(filePath, sheetName)
6.4 writeExcel(filePath, data, sheetName)
6.5 executeQueryOnExcel(filePath, coreQuery, params)
7. Полное описание методов AlaSQLProxy.
8. Пример использования AlaSQLProxy - запуск макроса «Тест AlaSQL».
9. Контрольные вопросы для модуля 3.
Модуль 4. Компоненты SliderDataSDK. Создание пользовательского интерфейса в макросах с UserGUIHelper
1. Цели модуля.
2. Описание модуля.
3. Назначение и область применения UserGUIHelper
4 Зависимости.
5 Основные методы API, примеры их использования.
5.1 initUI(commonUI)
5.2 alertWindow(title, message, onClose)
5.3 userInputWindow(titleWindow, labelForInputField, ...)
6. Полное описание методов UserGUIHelper
7. Пример использования UserGUIHelper - запуск макроса «Тест UserGUIHelper».
8. Контрольные вопросы для модуля 4.

Модуль 5. Компоненты SliderDataSDK. Работа с внешними Excel файлами через ExternalXLSXProxy.
1. Цели модуля:
2. Описание модуля:
3. Назначение и область применения.
4. Зависимости.
5. Основные методы API, примеры их использования.
5.1 init()
5.2 initWithExcelJS()
5.3 loadWorkbook(fileID, fileData)
5.4 readSheet(fileID, sheetIdentifier)
5.5 writeData(fileID, sheetIdentifier, startCellAddress, dataArray)
5.6 saveWorkbook(fileID)
6. Полное описание методов ExternalXLSXProxy.
7. Пример использования - запуск макроса «Тест ExternaXLSX (ExcelJS)».
8. Контрольные вопросы для модуля 5.

Модуль 6. Компоненты SliderDataSDK. Модуль OlapProxy - унифицированный API для работы с OLAP-данными.
1. Цели модуля.
2. Описание модуля.
3. Назначение и область применения.
4. Зависимости.
5. Основные методы API, примеры их использования.
5.1 init()
5.2 initWithXmla()
5.3 loadConnection(connectionID, connectionParams)
5.4 executeQuery(connectionID, mdxQuery)
5.5 writeToActiveSheet(connectionID, mdxQuery, startCellAddress)
5.6 saveQueryResult(connectionID, queryID)
6. Полное описание методов ExternalXLSXProxy.
7. Пример использования – запуск макроса «Тест OlapProxy».
8. Контрольные вопросы..


ВВЕДЕНИЕ
О курсе
Библиотека R7DataConsulting.SliderDataSDK предназначена для разработки и выполнения макросов в редакторе Р7-Офис в условиях ограниченной среды исполнения. Она предоставляет набор инструментов для безопасного и удобного доступа к данным из различных источников (внутренние базы XLDB, внешние XLSX-файлы, SQL и MDX -запросы) и для создания некоторых элементов взаимодействия с пользователем через pop-up (всплывающие) окна. Ключевыми преимуществами SliderDataSDK являются динамическая загрузка необходимых скриптов и подмодулей по требованию, управление зависимостями и изоляция глобальной области видимости, что предотвращает конфликты с другими скриптами. Архитектура библиотеки основана на прокси-модулях и вспомогательных классах, которые абстрагируют работу с конкретными форматами данных и UI-компонентами, обеспечивая надёжность, расширяемость и оптимальную производительность макросов.

Данный учебный курс посвящен практическому освоению библиотеки SliderDataSDK — специализированно раззработанного инструментария для для облегчения написания макросов в редакторах Р7-Офис и OnlyOffice. Курс разработан с учетом реальных потребностей специалистов, работающих с автоматизацией документооборота и интеграцией данных в корпоративной среде.

Курс состоит из нескольких модулей, каждый из которых посвящён отдельным аспектам работы с библиотекой — от базовой
инициализации и подключения подмодулей до построения сложных SQL-запросов, и создания интерактивных интерфейсов. По завершении курса вы будете уверенно использовать SliderDataSDK для интеграции данных и UI в макросах, эффективно работать с прокси-модулями, а также проектировать устойчивые и масштабируемые решения под ограничения среды редакторов.
Целевая аудитория курса
Разработчики корпоративных решений
  • Специалисты, создающие автоматизированные решения на базе Р7-Офис
  • Требуемый уровень: базовое владение JavaScript, понимание асинхронного программирования
  • Опыт работы с API REST-сервисов
Системные администраторы и DevOps-инженеры
  • Специалисты, отвечающие за автоматизацию рутинных операций с документами
  • Требуемый уровень: базовые навыки программирования, понимание клиент-серверной архитектуры
  • Опыт написания скриптов автоматизации
Бизнес-аналитики с техническими навыками
  • Аналитики, работающие с большими массивами данных в Excel и требующие их программной обработки
  • Требуемый уровень: базовое понимание JavaScript, опыт работы с SQL
  • Навыки работы с табличными данными
Технические писатели и документаторы
  • Специалисты, создающие автоматизированную техническую документацию
  • Требуемый уровень: понимание основ программирования
Продвинутые пользователи офисных пакетов
  • Пользователи, желающие расширить возможности стандартных инструментов
  • Требуемый уровень: готовность изучать программирование
Предварительные требования
Необходимые знания и навыки
  • JavaScript: переменные, функции, объекты, массивы, промисы
  • Базовое понимание DOM и событийной модели браузера
  • Опыт работы с Р7-Офис или OnlyOffice на уровне пользователя
  • Понимание JSON-формата данных
Желательные знания
  • SQL для работы с модулем AlaSQLProxy
  • Опыт работы с REST API
  • Знание основ работы с базами данных и OLAP
  • Понимание принципов асинхронного программирования в языке программирования javascript
Техническое окружение
  • Р7-Офис редактор (рекомендуется последняя стабильная версия)
  • Доступ к консоли разработчика (запуск редактора с флагом --ascdesktop-support-debug-info)
  • Текстовый редактор для работы с кодом
  • Браузер с поддержкой ES6 (для веб-версии)
Используемые библиотеки
Краткий список библиотек с версиями, лицензиями и разработчиками:

AlaSQL.js
  • Текущая версия: 4.6.6
  • Лицензия: MIT License
  • Разработчики: Andrey Gershun, Mathias Rangel Wulff, Aubert Grégoire
  • Описание: JavaScript SQL база данных для браузера и Node.js, поддерживает как реляционные таблицы, так и вложенные JSON данные (NoSQL)

SheetJS
  • Текущая версия: 0.20.3
  • Лицензия: Apache 2.0 License
  • Разработчики: SheetJS Community Edition (команда SheetJS)
  • Описание: Библиотека для парсинга и записи данных электронных таблиц, поддерживает множество форматов включая XLSX, XLS, CSV

ExcelJS
  • Текущая версия: 4.4.0
  • Лицензия: MIT License (Copyright (c) 2014-2019 Guyon Roche)
  • Разработчики: Guyon Roche и команда разработчиков
  • Описание: Менеджер Excel рабочих книг для чтения, записи и манипулирования данными XLSX и CSV

jQuery
  • Текущая версия: 3.7.1
  • Лицензия: MIT License
  • Разработчики: Создатель - John Resig (2006), поддерживается командой разработчиков под руководством Timmy Willison
  • Описание: Быстрая, легкая JavaScript библиотека для упрощения работы с DOM, обработки событий, анимации и Ajax

Xmla
  • Текущая версия: Последний коммит на GitHub (рекомендуется использовать версию с GitHub вместо npm 0.0.2)
  • Лицензия: Apache 2.0 License (ранее LGPL 3.0)
  • Разработчики: Создатель - Roland Bouman, активная разработка 2009-2018
  • Описание: Автономная JavaScript библиотека для базовых возможностей XML for Analysis (XML/A), позволяющая JavaScript разработчикам получать данные и метаданные от OLAP провайдеров для использования в веб-приложениях

Все перечисленные библиотеки имеют открытый исходный код и используют пермиссивные лицензии (MIT или Apache 2.0), которые позволяют свободное использование в коммерческих проектах при условии сохранения уведомлений об авторских правах.
Результаты обучения
По окончании курса слушатели будут уметь
  • Устанавливать и настраивать SliderDataSDK
  • Подключаться к различным источникам данных
  • Выполнять гетерогенные запросы
  • Работать с файлами и локальными данными
  • Создавать пользовательский интерфейс для работы с данными
  • Оптимизировать процессы обработки данных
  • Реализовывать комплексные решения на основе SliderDataSDK
Глоссарий терминов
Основные термины

  • API (Application Programming Interface) — программный интерфейс приложения, набор методов и функций для взаимодействия с программной системой.
  • Callback (обратный вызов) — функция, передаваемая в качестве аргумента другой функции и вызываемая после завершения определенной операции.
  • DOM (Document Object Model) — объектная модель документа, программный интерфейс для HTML и XML документов.
  • Promise (промис) — объект JavaScript, представляющий результат асинхронной операции, которая может завершиться успешно или с ошибкой.
  • Proxy (прокси) — промежуточный программный слой, выступающий посредником между клиентом и целевым объектом или сервисом.
  • HTG (Heterogeneous Query) — гетерогенный запрос, позволяющий объединять данные из разных источников.
Термины SliderDataSDK
  • SliderDataSDK — центральная библиотека для разработки макросов в Р7-Офис, обеспечивающая бесшовную автоматическую загрузку как исходных библиотек, так и прокси-классов для работы с ними, делая доступной работу с ними в макросах Р7.
  • XLDBProxy — прокси-модуль для взаимодействия с различными СУБД через унифицированный интерфейс.
  • AlaSQLProxy — модуль для выполнения SQL-запросов непосредственно в браузере без серверной части.
  • UserGUIHelper — вспомогательный модуль для создания всплывающих окон с элементами пользовательского интерфейса в макросах.
  • ExternalXLSXProxy — модуль для работы с внешними Excel-файлами через библиотеки SheetJS или ExcelJS.
  • OlapProxy – модуль для работы с OLAP-серверами через протокол XMLA без использования серверной части
Технические термины
  • Асинхронная операция — операция, выполняющаяся параллельно основному потоку программы без его блокировки.
  • Кеширование — сохранение данных в быстродоступной памяти для ускорения повторных обращений.
  • Ленивая загрузка (Lazy Loading) — техника отложенной загрузки ресурсов до момента их фактического использования.
  • Макрос — программный код, автоматизирующий выполнение повторяющихся задач в приложении.
  • Модальное окно — диалоговое окно, блокирующее взаимодействие с основным интерфейсом до его закрытия.
  • Всплывающее (pop-up) окно — небольшое диалоговое окно, выводимое обычно с целью информирования или подтверждения действий пользователя. В SDK используется так же для замены полноценного интерфейса с пользоваетелем, недоступного в рамках АПИ для макросво в Р7
  • Плагин — дополнительный программный модуль, расширяющий функциональность основного приложения.
Форматы и стандарты
  • A1 notation — формат адресации ячеек в Excel, использующий буквы для колонок и цифры для строк (например, B5).
  • R1C1 notation — альтернативный формат адресации ячеек, использующий номера строк (R) и колонок (C) (например, R5C2).
  • JSON (JavaScript Object Notation) — текстовый формат обмена данными, основанный на синтаксисе JavaScript.
  • localStorage — механизм веб-хранилища, позволяющий сохранять данные в браузере между сессиями.
  • XLSX — формат файлов Microsoft Excel, основанный на стандарте Office Open XML.
Среда выполнения
  • Common.UI — встроенный API Р7-Офис для создания пользовательского интерфейса.
  • Common.R7ConsultLibs — глобальный контейнер для размещения библиотеки SliderDataSDK.
  • Sandbox (песочница) — изолированная среда выполнения кода макроса с ограниченным доступом к системным ресурсам.
  • Системный плагин — плагин, загружающийся автоматически и недоступный в пользовательском интерфейсе.
Операции с данными
  • CRUD — Create, Read, Update, Delete — базовые операции с данными.
  • SQL (Structured Query Language) — язык структурированных запросов для работы с реляционными базами данных.
  • MDX -
  • Гетерогенные данные — данные из разных источников с различными форматами и структурами.
  • Двумерный массив — структура данных, представляющая таблицу с строками и столбцами.
Модуль 1. Основы SliderDataSDK
1. Цели модуля
  • Освоить архитектуру библиотеки SliderDataSDK и понять принципы работы с данными в ограниченной среде макросов
  • Изучить компоненты системы - центральный SDK и четыре прокси-класса для работы с различными источниками данных
  • Понять механизмы динамической загрузки, управления зависимостями и оптимизации производительности
  • Получить практические навыки развертывания и использования SDK в макросах Р7-Офис
2. Описание модуля
Модуль знакомит с библиотекой SliderDataSDK - комплексным решением для надежного управления данными и пользовательским интерфейсом в макросах редакторов Р7-Офис и OnlyOffice. Библиотека решает ключевые проблемы ограниченной среды выполнения макросов через динамическую загрузку скриптов, управление зависимостями и изоляцию глобальной области видимости. В основе архитектуры лежит центральный компонент SliderDataSDK, который управляет пятью специализированными прокси-классами для работы с базами данных, SQL-запросами, MDX-запросами, Excel-файлами и пользовательским интерфейсом. Модуль включает практическое изучение установки системного плагина-загрузчика и создания макросов с использованием SDK. Материал подкреплен примерами кода и контрольными вопросами для закрепления понимания архитектуры и принципов работы системы.
3. Архитектура решения, принципы работы
Библиотека SliderDataSDK – это решение для обеспечения надежного доступа и управления данными, а также простейший пользовательски интерфейс для макросов в ограниченных встроенным АПИ, средах выполнения макросов редакторов Р7-Офис и OnlyOffice. Применение SliderDataSDK решает ряд проблем:

  • Ограниченная среда выполнения макросов: Макросы выполняются в изолированной среде внутри редактора, которая имеет ограничения на прямой доступ к файловой системе или внешним ресурсам. SliderDataSDK и его прокси-модули предоставляют функции для работы с данными и пользовательский интерфейс в этой среде.
  • Управление зависимостями в браузере: Динамическая загрузка скриптов позволяет избежать проблем с порядком загрузки и зависимостями между различными частями библиотеки и внешними глобальными библиотеками и избавляет разработчика макросов от необходимости решать проблемы по способам доступа к разного рода js-библиотекам, разработанным для решения тех или иных задач.
  • Изоляция глобальной области видимости: Очистка глобальной области видимости после прикрепления библиотек к SliderDataSDK помогает предотвратить конфликты имен с другими скриптами, которые могут выполняться в той же среде.
  • Разнообразие источников данных и UI компонентов: Макросам может потребоваться доступ к данным из различных источников (внешняя база данных, внешние файлы XLSX, выполнение SQL и MDX запросов к данным) и возможность использовать специализированные компоненты пользовательского интерфейса в UserGUIHelper, обеспечивает платформу для интеграции специализированных прокси-объектов и вспомогательных модулей, каждый из которых предназначен для различных задачс определенным типом данных или UI функциональностью, уже разработанных и требующих от разработчика только правильного их применения, убирая необходимость писать такие модули и компоненты самостоятельно
  • Надежность и обработка ошибок: Механизмы обработки ошибок при загрузке скриптов повышают надежность работы макросов, позволяя корректно реагировать на ситуации, когда необходимые компоненты не могут быть загружены.
4. Основная функциональность
Библиотека классов SliderDataSDK выполняет следующие основные функции и обязанности:

  • Управление зависимостями: Отслеживает зависимости подмодулей от глобальных библиотек и обеспечивает их загрузку перед инициализацией соответствующего подмодуля.
  • Прикрепление объектов: После успешной загрузки прокси-модуля, он становится доступным как вложенный объект в основном модуле SliderDataSDK, делая его доступным для использования в макросах.
  • Отслеживание загруженных подмодулей: Ведет учет загруженных подмодулей и предоставляет функцию getLoadedSubModules() для доступа к списку подмодулей.
  • Очистка глобальной области видимости: После прикрепления объекта к SliderDataSDK, происходит очистка глобальную область видимости от ссылок на загруженные библиотеки/подмодули (за исключением XLSX в определенных случаях), чтобы избежать конфликтов и засорения глобального пространства имен.
  • Инициализация SDK: Предоставляет функцию для комплексной инициализации SDK, которая может загружать либо все доступные подмодули и их зависимости, либо только указанный набор модулей.
  • Обработка ошибок загрузки: Включает механизмы обработки ошибок при загрузке скриптов, уведомляя об этом через консоль и выбрасывая исключения.
5. Основные составляющие решения
  • Сервисный плагин-загрузчик - служит для загрузки модульной библиотеки SliderDataSDK для последующего использования в макросах
Библиотека SliderDataSDK состоит из следующих модулей:

  • SliderDataSDK - центральный компонент, который помещается в глобальный контейнер R7DataConsulting, и доступен для работы в макросах через вызов Common.R7DataConsulting.SliderDataSDK (Common.R7DataConsulting – глобальный контейнер механизма загрузки внешних модулей для работы внутри макросов, разработанный в ООО»ДатаКонс»). Он отвечает за загрузку и и дальнейшее предоставление доступа к рабочим прокси-модулям. Подмодули XLDBProxy,OlapProxy, AlaSQLProxy, ExternalXLSXProxy, UserGUIHelper предоставляют конкретную функциональность (работа с данными и пользовательским интерфейсом), их загрузка и доступность контролируются именно SliderDataSDK.
  • Набор прокси-классов
  • XLDBProxy.js - это клиентский API для взаимодействия с сервером Slider Data Proxy, обеспечивающим доступ к различным СУБД (PostgreSQL, ClickHouse, MySQL и др.).
  • AlaSQLProxy.js предоставляет асинхронный интерфейс для работы с SQL-библиотекой AlaSQL в JavaScript. Он упрощает выполнение запросов, работу с localStorage и обработку Excel-файлов.
  • UserGUIHelper.js - вспомогательные функции (создание окон) для работы с пользовательским интерфейсом в среде плагинов Р7/.
  • ExternalXLSXProxy.js - работа с внешними xlsx файлами в простом формате функций-запросов. Он является обёрткой над популярными библиотеками SheetJS и ExcelJS, позволяя переключаться между ними
  • OlapProxy.js - унифицированный API для работы с OLAP-серверами через протокол XMLA без использования серверной части. Он является обёрткой над библиотекой XMLA.js, упрощая операции подключения, выполнения MDX-запросов и интеграции многомерных данных в документ.

SliderDataSDK инициализируется при загрузке скрипта и затем предоставляет методы для динамической загрузки и доступа к XLDBProxy, AlaSQLProxy, OlapBProxy, ExternalXLSXProxy и UserGUIHelper по мере необходимости. Каждый из этих подмодулей включает собственную переменную _version и функцию getVersion() для идентификации своей версии.

Ниже представлена подробная модульная архитектура решения:

SliderDataSDK
├── _version
├── _scriptDirectory
├── _loadedSubmodules //массив загруженных подмодулей
├── getVersion()
├── getLoadedSubModules() //функция для получения списка загруженных подмодулей
├── loadSubObject()
├── loadSDKSubObjects()
├── initGlobalLibraries()
├── loadGlobalLib()
├── initSDK()
│  Прокси-классы
├── XLDBProxy (загружается динамически, имеет _version и getVersion())
├── OlapProxy (загружается динамически, имеет _version и getVersion())
├── AlaSQLProxy (загружается динамически, зависит от alasql, XLSX, имеет _version и getVersion())
├── ExternalXLSXProxy (загружается динамически, зависит от XLSX, ExcelJS, имеет _version и getVersion())
└── UserGUIHelper (загружается динамически, не зависит от внешних глобальных библиотек, имеет _version и getVersion())
6. Пример использования в макросах Р7
Работа внутри макросов осуществляется очень простым методом, позволяющим использовать серьезный сервисный функции модулей библиотек, без необходимости вникать в особенности устройства служебных библиотек, применяемых для выполнения того, или иного функционала. Например, макрос для ввода пользовательских данных:

(function(){
    if(Common.R7ConsultLibs){
        if(Common.R7ConsultLibs.SliderDataSDK&&Common.R7ConsultLibs.SliderDataSDK.UserGUIHelper){
            userHelper=Common.R7ConsultLibs.SliderDataSDK.UserGUIHelper;
            if(userHelper){
                userHelper.ui=Common.UI; //Инициализация использования библиотеки GUI от Р7
                userHelper.userInputWindow("Введите данные","Ваше имя (результат в консоли):",200,200,(val)=>{console.log(val);});                                      
            }
        }
        else{
            messageWindow("Внимание!",`Библиотека SliderDataSDK не загружена!`);
        }
    }else{
        messageWindow("Внимание!",`R7ConsultLibs не загружен!`);
    }  
})();
 
//Вывод окна сообщения пользователю
function messageWindow(title,textMessage){
    Common.UI.alert(
        {
            title: title,
            msg: textMessage,
            width: "auto",            
            closable: true            
        }
    );
}

После запуска данного макроса, перед пользователем появится окно в котором ему будет предложено осуществить ввод своего имени. Результат можно обработать в callback функции, которая передается как параметр в вызове создания данного типа окна, и вместо вывода в консоль, можно полученные от пользователя данные обработать любым другим доступным в API макросов способом.
7. Инструкция по развертыванию
Чтобы начать пользоваться решением, необходимо установить системный плагин загрузчик библиотек:
  • Для установки Загрузчика откройте редактор Р7-Офис, выберите «Плагины»-«Настройки», нажмите «Добавить плагин» и укажите файл Loader SliderDataSDK.plugin. Данный плагин является системным, недоступен из меню плагинов для выбора.
При установке плагин появляется в списке установленных плагинов, но при этом не имеет значка т на панели плагинов в меню редактора Р7.
8. Системные требования
Чтобы начать пользоваться решением, необходимо установить системный плагин загрузчик библиотек:

  • Аппаратные требования
  1. Процессор: двухъядерный 2 ГГц или выше
  2. Оперативная память: от 2 ГБ
  3. Дисковое пространство: от 2 ГБ
  • Программные требования
  1. Поддерживаемые ОС (Linux, Windows)
  2. Версии Р7-Офис (рекомендуется последняя)
  3. Отладка интегрирована в Р7-Офис (консоль разработчика)
9. Контрольные вопросы для Модуля 1

  • Вопрос 1 (понимание проблематики): Какие основные проблемы решает библиотека SliderDataSDK в среде выполнения макросов Р7-Офис и OnlyOffice? Объясните, почему динамическая загрузка скриптов критически важна для работы в браузерной среде.
  • Вопрос 2 (архитектура системы): Опишите роль центрального компонента SliderDataSDK в общей архитектуре системы. Через какой глобальный путь доступен SDK в макросах и какие основные функции он выполняет по управлению подмодулями?
  • Вопрос 3 (классификация компонентов): Сравните четыре прокси-класса XLDBProxy, AlaSQLProxy, ExternalXLSXProxy, UserGUIHelper по следующим критериям:
  1. Назначение и область применения
  2. Зависимости от внешних библиотек
  3. Способ загрузки
  • Вопрос 4 (практическое применение): Проанализируйте жизненный цикл работы с SDK: от установки системного плагина-загрузчика до выполнения макроса. Объясните, почему плагин-загрузчик является системным и недоступен в панели плагинов.
  • Вопрос 5 (управление зависимостями и производительность): Как SDK решает проблему управления зависимостями между подмодулями и глобальными библиотеками, и зачем необходима очистка глобальной области видимости?
Модуль 2. Компоненты SliderDataSDK. Класс XLDBProxy.js
1. Цели модуля

  • Освоить работу с XLDBProxy - клиентским API для унифицированного доступа к различным СУБД через прокси-сервер SliderDataProxy
  • Изучить основные методы API для управления подключениями, выполнения SQL-запросов и получения метаданных базы данных
  • Понять принципы работы с гетерогенными запросами (HTG) и их применение для обработки данных из разнородных источников
  • Получить практические навыки выполнения комплексных тестов и интеграции результатов SQL-запросов в документы Excel
2. Описание модуля

Модуль посвящен изучению класса XLDBProxy.js - ключевого компонента для работы с базами данных в рамках библиотеки SliderDataSDK. Класс обеспечивает унифицированный доступ к различным СУБД (PostgreSQL, ClickHouse, MySQL, MirandaDB,MS SQL, Oracle) через прокси-сервер, скрывая детали HTTP-взаимодействия и предоставляя набор асинхронных функций для выполнения различных операций по доступу к данным. Основной функционал включает методы для проверки подключений, получения метаданных (таблицы, представления, и их поля), выполнения SQL-запросов и работы с гетерогенными запросами. Модуль содержит практические примеры использования через готовые макросы "Комплексный тест" и "Тест гетерогенных подключений", демонстрирующие полный цикл работы с данными - от подключения к базе до вывода результатов в Excel-документ. Материал подкреплен детальным описанием API-методов и контрольными вопросами для проверки понимания принципов работы с базами данных через прокси-интерфейс.
3. Назначение класса

Класс XLDBProxy.js является клиентским API для взаимодействия с внешним прокси-сервером SliderDataProxy (разработка ООО «ДатаКонс»). Этот сервер обеспечивает унифицированный доступ к различным системам управления базами данных (СУБД), таким как PostgreSQL, ClickHouse, MySQL и ряда других.

Доступ к прокси-серверу осуществляется путем вызова API команд класса XLDBProxy.js, которые являются обертками для обращения к методам прокси-сервера.

Класс скрывает детали HTTP-взаимодействия, предоставляя разработчику набор асинхронных функций для:
  • Управления подключениями к базам данных
  • Выполнения SQL-запросов
  • Работы с гетерогенными запросами (HTG)
  • Получения метаданных (таблицы, поля, представления)
4. Зависимости

  • SliderDataProxy Server. Модуль требует для работы обязательного наличия запущенного и доступного экземпляра прокси-сервера.
  • Параметры подключения к прокси серверу . Для работы с удаленным источником данных, требуется описание параметров подключения, включающих логин\пароль в зашифрованном специальным образом виде, параметры удаленной СУБД. Данные подключения формируются плагином «Слайдер Данные» и требуемое подключение по его имени можно получить либо через localStorage, либо через чтение из внешнего файла, с заранее сохраненным списком подключений. 
5. Основные методы API, примеры их использования

Класс XLDBProxy предоставляет клиентский интерфейс для взаимодействия с прокси-сервером SliderDataProxy, обеспечивающим унифицированный доступ к различным СУБД. В данном разделе описаны основные методы API, необходимые для начала работы.
5.1 checkConnection(paramsName, options)

Назначение: Проверяет доступность и корректность подключения к базе данных. Использует кешированные параметры по paramsName.

Параметры:
Имя
Тип
Описания
Обязательный
options

object

Объект для переопределения или добавления параметров запроса

Нет
Возвращаемое значение: Promise<object> — промис, разрешающийся с JSON-ответом от сервера. В случае ошибки выбрасывает исключение.

Пример использования:

XLDBProxy.checkConnection("MyPostgresDB")
  .then(response => {
    console.log("Соединение успешно:", response);
  })
  .catch(error => {
    console.error("Ошибка соединения:", error);
  });
5.2 getTables(paramsName, options)

Назначение: Получает список таблиц из указанной схемы базы данных.

Параметры:
Имя
Тип
Описания
Обязательный
paramsName

string

Имя подключения из кеша

Да
options

object

Дополнительные параметры (например, { schema: 'public' })

Нет
Возвращаемое значение: Promise<object> — промис с ответом сервера, содержащим список таблиц в поле data.

Пример использования:

XLDBProxy.getTables("MyPostgresDB", { schema: 'public' })
  .then(response => {
    const tables = XLDBProxy.getData(response);
    console.log("Таблицы:", tables);
  });
5.3 getViews(paramsName, options)

Назначение: Получает список представлений (views) из указанной схемы.

Параметры:
Имя
Тип
Описания
Обязательный
paramsName

string

Имя подключения из кеша

Да
options

object

Дополнительные параметры (например, { schema: 'public' })

Нет
Возвращаемое значение: Promise<object> — промис с ответом сервера
5.4 getFields(paramsName, options)

Назначение: Получает список полей (столбцов) для указанной таблицы или представления.

Параметры:
Имя
Тип
Описания
Обязательный
paramsName

string

Имя подключения из кеша

Да
options

object

Обязательно должен содержать relation_name (имя таблицы) и relation_schema

Да
Возвращаемое значение: Promise<object> — промис с ответом сервера, содержащим список полей.

Пример использования:

XLDBProxy.getFields("MyPostgresDB", {
      relation_schema: 'public',
      relation_name: 'users'
    })
    .then(response => {
      const fields = XLDBProxy.getData(response);
      console.log("Поля таблицы 'users':", fields);
    });
5.5 executeQuery(paramsName, options)

Назначение: Выполняет произвольный SQL-запрос. – это основной метод для выполнения запросов к СУБД через прокси-сервер.

Параметры:
Имя
Тип
Описания
Обязательный
paramsName

string

Имя подключения из кеша

Да
options

object

Обязательно должен содержать поле query с текстом SQL-запроса

Да
Возвращаемое значение: Promise<object> — промис с результатом выполнения запроса

Пример использования:

const sql = "SELECT id, name FROM users WHERE age > 30";
XLDBProxy.executeQuery("MyPostgresDB", { query: sql })
  .then(response => {
    const { header, data } = XLDBProxy.getColumnsAndData(response);
    console.log("Заголовки:", header);
    console.log("Данные:", data);
  });
6. Полное описание методов XLDBProxy.js

Детальное описание всех методов класса XLDBProxy представлено в Приложении 6 (документ приложений к курсу), где информация структурирована по следующим разделам:
  • Управление параметрами и конфигурацией
  • Основные методы API
  • Работа с гетерогенными запросами (HTG)
  • Вспомогательные методы обработки данных
Обращайтесь к приложению для получения исчерпывающей информации о параметрах, возвращаемых значениях и примерах использования каждого метода.
7. Пример использования XLDBProxy - запуск макроса «Комплексный тест»

В состав курса входит XLSX файл «Макросы использования SliderDataSDK.xlsx» с тестовыми макросами для презентации работы библиотеки и ее модулей. Просмотреть и выполнить макросы после подключения SliderDataSDK можно в редакторе макросов – выберите «Плагины» -«Макросы» - «Комплексный тест».

Сценарий макроса: в данном макросе выполняется комплексное тестирование функциональности XLDBProxy в следующей последовательности:

  1. Инициализация и проверка загрузки - проверяет доступность библиотеки SliderDataSDK и настраивает параметры подключения к прокси-серверу
  2. Загрузка параметров подключения - загружает настройки соединения с базой данных из localStorage или использует тестовые параметры
  3. Тестирование API методов - последовательно проверяет работу основных функций: подключение к БД, получение списков таблиц и представлений, получение структуры полей
  4. Выполнение SQL-запроса - выполняет тестовый SELECT запрос к таблице person.address с ограничением в 10 записей
  5. Вывод результатов в Excel - заполняет активный лист данными из SQL-запроса (заголовки в первой строке, данные начиная со второй строки) и пересчитывает лист
Цель задания: убедиться, что прокси SliderDataSDK корректно подключается к заданной СУБД, возвращает структуру базы и данные по SQL-запросу, а результат отображается в документе. Ознакомьтесь с полным текстом макроса в файле «Макросы использования SliderDataSDK.xlsx» или в Приложении 1.

Запустите макрос:

  • Необходимо добавить корректное имя тестового подключения к БД в макросе в строчках
if(namesConnection.length && XLDBProxy.paramsCache["pg"])//Вместо "pg" вставить свое имя для соединения с postgresq
testParamsName='pg';

Перед запуском макроса необходимо настроить параметры подключения. Макрос поддерживает два способа: использование сохраненных соединений из плагина «Слайдер Данные» или прямое указание параметров в коде. Если у вас есть настроенные соединения в плагине «Слайдер Данные», замените значение 'pg' в строке 46 на имя вашего соединения. В противном случае заполните структуру testParams (строки 17-30) данными вашей базы: адрес сервера, логин, пароль и другие параметры подключения.
После запуска макроса выводится информационное окно о том, что результаты тестов можно просмотреть в консоли отладчика
Вызываем консоль (изначально Р7-Офис должен быть запущен с ключом --ascdesktop-support-debug-info для возможностей отладки) – щелкаем правой кнопкой мыши в окне редактора макросов и выбираем «Show Devtools». И выбираем вкладку «Console».
В консоли отображается лог успешно пройденных тестов, соответствующие тестовые данные отображены на листе редактора.
Можно убедиться, что все тесты пройдены успешно.
8. Пример использования XLDBProxy - запуск макроса «Тест гетерогенных подключений»

Цель: Убедиться, что на сервере зарегистрированы HTG-запросы, корректно загружаются их поля и успешно выполняется SQL-запрос с выборкой данных. Ознакомьтесь с полным текстом макроса в файле «Макросы использования SliderDataSDK.xlsx» или в Приложении 2.

Сценарий макроса:
Инициализация и проверка библиотеки
Скрипт проверяет наличие библиотеки SliderDataSDK и объекта XLDBProxy, выводит сообщение о версии и запускает тесты.
Загрузка гетерогенных запросов с сервера
Метод loadHTGConnectionsFromServer() загружает зарегистрированные гетерогенные запросы и выводит их список в консоль.
Проверка наличия конкретного HTG-запроса
Функция hasHTGRelations() проверяет, зарегистрирован ли запрос с именем test, и логирует результат.
Измените значение переменной с «test» на имя существующего гетерогенного запроса, чтобы он прошел проверку (строка let testHTGName="test";)
Получение полей HTG-запроса
Метод loadHTGFields() загружает структуру полей запроса test, если он существует, и выводит их в консоль.
Выполнение HTG-запроса и вывод результатов
Метод executeAndUpdateHtgQuery() выполняет SQL-запрос по гетерогенному источнику, а полученные данные записываются в активный лист Excel и логируются.

Запустите макрос:
  • Меняем значение «test» на реальное имя запроса «MSSQL_HTG» в строке
let testHTGName="test";

  • Запускаем макрос и смотрим вывод результатов в консоли DevTools. Также данные из запроса «MSSQL_HTG» выведены в лист редактора.
Можно убедиться, что необходимая информация о гетерогенных запросах, а также отладочная информация выведена успешно.
9. Контрольные вопросы для Модуля

  • Каково основное назначение класса XLDBProxy.js и какие основные задачи он решает при работе с базами данных?
  • Для чего используется метод copyOnlyNeedParametrs(objToCopy) и какую задачу он решает при интеграции с UI?
  • Чем отличаются методы getTables, getViews и getFields с точки зрения получаемых данных и обязательных параметров?
  • Что такое HTG-запросы, и какие шаги необходимо выполнить для их выполнения через XLDBProxy?
Модуль 3. Компоненты SliderDataSDK. Работа с SQL запросами через AlaSQLProxy
1. Цели модуля

  • Освоить работу с AlaSQLProxy - специализированным прокси-модулем для выполнения SQL-запросов непосредственно в браузере через библиотеку AlaSQL
  • Изучить методы работы с данными - выполнение SQL-запросов к массивам, локальным базам данных и Excel-файлам без использования сервера
  • Понять принципы создания локальных баз данных в localStorage браузера и выполнения операций CRUD над ними
  • Получить практические навыки создания SQL-анализаторов данных и интеграции результатов в макросы редакторов
2. Описание модуля

Модуль знакомит с AlaSQLProxy - мощным инструментом для выполнения SQL-операций на стороне клиента без необходимости подключения к серверу базы данных. Модуль обеспечивает работу с различными источниками данных: массивами в памяти, локальными базами данных в localStorage браузера и Excel-файлами с возможностью прямых SQL-запросов к их содержимому. Основной функционал включает создание и управление локальными базами данных, чтение и запись Excel-файлов, выполнение сложных SQL-запросов с фильтрацией и агрегацией данных. Модуль содержит практический пример "Тест AlaSQL" для проверки всех базовых операций, а также задание по созданию анализатора данных продаж с использованием SQL-запросов к массивам. Материал подкреплен детальным описанием API-методов и практическими заданиями для закрепления навыков работы с SQL в браузерной среде.
3. Назначение и область применения AlaSQLProxy

AlaSQLProxy — специализированный прокси-модуль SliderDataSDK, предоставляющий мощный интерфейс для выполнения SQL-запросов непосредственно в браузере (через взаимодействия с JavaScript SQL-библиотекой AlaSQL). Модуль расширяет возможности макросов редакторов Р7-Офис и OnlyOffice, упрощая выполнение SQL-запросов, работу с базами данных в localStorage, а также чтение и запись данных в файлы формата Excel.
4. Зависимости

  • AlaSQL: Основная библиотека для выполнения SQL-запросов. Предполагается, что AlaSQLProxy.alasql будет инициализирован экземпляром этой библиотеки.
  • XLDB: Неявная зависимость для некоторых функций, работающих с Excel. Предполагается, что AlaSQLProxy.XLDB будет инициализирован.
5. Ключевые преимущества, архитектура

  • SQL без сервера — все операции выполняются на клиенте
  • Работа с Excel файлами — прямые SQL-запросы к .xlsx файлам
  • Локальные базы данных — создание БД в localStorage браузера
  • Обработка массивов — SQL-запросы к данным в памяти
  • Макрос-ориентированный API — безопасная интеграция в редакторы

Базовые метода в AlaSQLProxy

6. Основные методы API, примеры их использования

В данном разделе описаны основные методы API, необходимые для начала работы.
6.1 executeQuery(query, params)

Назначение: Основная функция. Выполняет SQL-запрос с использованием AlaSQL.

Описание: Основная функция-обертка для выполнения любого SQL-запроса. Она принимает строку запроса и опциональные параметры, возвращая результат выполнения в виде промиса.

Параметры:
Имя
Тип
Описания
Обязательный
query

string

Строка SQL-запроса для выполнения

Да
params

Array<any>

Массив параметров для подстановки в SQL-запрос

Нет
Возвращаемое значение: Promise<any> - промис, который разрешается с результатом выполнения запроса.
В случае ошибки промис будет отклонен

Пример использования:

AlaSQLProxy.executeQuery("SELECT * FROM MyTable WHERE id = ?", [1])
  .then(result => {
    console.log("Найдена запись:", result);
  })
  .catch(error => {
    console.error("Ошибка выполнения запроса:", error);
  });
6.2 createLocalStorageDatabase(dbName)

Создает новую или подключается к существующей базе данных в localStorage.

Описание: Использует синтаксис CREATE localStorage DATABASE для создания постоянной базы данных в хранилище браузера.

Параметры:
Имя
Тип
Описания
Обязательный
dbName

string

Имя создаваемой базы данных

Да
Возвращаемое значение: Promise<void> — промис, который разрешается после успешного создания базы данных.

Пример использования:

AlaSQLProxy.createLocalStorageDatabase("MyLocalDB")
  .then(() => {
    console.log("База данных 'MyLocalDB' успешно создана.");
  });
6.3 readExcel(filePath, sheetName)

Читает данные изфайла Excel.

Описание: Использует функциональность AlaSQL для прямого чтения данных из .xlsx файла.

Параметры:
Имя
Тип
Описания
Обязательный
filePath

string

Путь к файлу Excel.

Да
sheetName

string

Имя листа для чтения. Если не указано, читается первый лист.

Нет
Возвращаемое значение: Promise<Array<Array<any>>> — промис, который разрешается с массивом данных из листа.

Пример использования:

AlaSQLProxy.readExcel("data.xlsx", "Sheet1")
  .then(data => {
    console.log("Данные из Excel:", data);
  });
6.4 writeExcel(filePath, data, sheetName)

Описание: Записывает данные в файл Excel. Использует синтаксис SELECT * INTO XLSX(...) для сохранения массива данных в .xlsx файл.

Параметры:
Имя
Тип
Описания
Обязательный
filePath

string

Путь к файлу для записи

Да
data

Array<Array<any>>

Двумерный массив данных для записи.

Да
sheetName

string

Имя листа, в который будут записаны данные.

Нет
Возвращаемое значение: Promise<void> — промис, который разрешается после успешной записи файла.

Пример использования:

const dataToWrite = [
    ["ID", "Name"],
    [1, "Product A"],
    [2, "Product B"]
  ];
  AlaSQLProxy.writeExcel("output.xlsx", dataToWrite, "Products")
    .then(() => {
      console.log("Данные успешно записаны в output.xlsx");
    });

6.5 executeQueryOnExcel(filePath, coreQuery, params)

Описание: Выполняет SQL-запрос непосредственно к данным в файле Excel. Позволяет выполнять сложные SQL-запросы (фильтрация, агрегация) к данным Excel-файла, не загружая их предварительно в базу данных.

Параметры:
Имя
Тип
Описания
Обязательный
filePath

string

Путь к файлу Excel

Да
coreQuery

string

Основная часть SQL-запроса (например, "WHERE Category = 'Books'").

Да
params

Array<any>

Параметры для запроса.

Нет
Возвращаемое значение: Promise<any> — промис, который разрешается с результатом запроса.

Пример использования:

AlaSQLProxy.executeQueryOnExcel("sales.xlsx", "WHERE Amount > ?", [1000])
  .then(results => {
    console.log("Продажи с суммой > 1000:", results);
  });
7. Полное описание методов AlaSQLProxy

Детальное описание всех методов класса AlaSQLProxy представлено в Приложении 7 (документ приложений к курсу):
  • Управление базами данных localStorage
  • Операции с таблицами
  • Работа с Excel файлами
  • Работа с массивами в памяти
Обращайтесь к приложению для получения исчерпывающей информации о параметрах, возвращаемых значениях и примерах использования каждого метода.
8. Пример использования AlaSQLProxy - запуск макроса «Тест AlaSQL»

В состав курса входит XLSX файл «Макросы использования SliderDataSDK.xlsx» с тестовыми макросами для проверки работы библиотеки и ее модулей. Просмотреть и выполнить макросы после подключения SliderDataSDK можно в редакторе макросов – выберите «Плагины» -«Макросы» - «Тест AlaSQL».

Цель: Подтвердить корректность базовых операций (создание, вставка, выборка, удаление) в локальной базе, реализованной средствами AlaSQL. Убедиться в правильности чтения/записи Excel, получения листов и выполнения SQL к файлам и структурам данных в памяти с помощью AlaSQL.

Ознакомьтесь с полным текстом макроса в файле «Макросы использования SliderDataSDK.xlsx» или в Приложении 4.

Сценарий макроса:
Инициализация и проверка библиотеки
  • Скрипт проверяет наличие библиотеки AlaSQLProxy, выводит сообщение с версией и запускает тесты.
Проверка базовых SQL-операций
  • Функции библиотеки проверяются на выполнение простого запроса, создание, подключение, использование и удаление базы данных, а также создание таблицы и вставку данных.
Тестирование массивов как источника данных
  • Метод selectFromArray() используется для выполнения SQL-запроса к двумерному массиву и фильтрации данных по условию.
Работа с Excel-файлами
  • Проверяются функции чтения Excel-файлов с указанием и без указания имени листа, запись данных в Excel и получение списка листов.
Выполнение запросов к Excel-файлу
  • Метод executeQueryOnExcel() тестируется на корректность выполнения SQL-запроса к содержимому Excel-файла.
Запуск макроса:
  • Запускаем макрос
  • Также можем изменить в коде макроса название тестового файла (по умолчанию test.xlsx) и путь к нему – используем для сценария проверки чтения файла
  • Выводится диалоговое окно для сохранения результата в виде xlsx файла. По умолчанию output.xlsx (можем поменять его в макросе). Сохраняем файл.
9. Контрольные вопросы для модуля 3

  • Как AlaSQLProxy взаимодействует с движком AlaSQL и почему он используется вместо прямого обращения к базе?
  • Каким образом метод executeSQL обрабатывает входные параметры и как это влияет на безопасность и производительность?
  • В чём разница между методами getTables и getColumns в AlaSQLProxy, и в каких сценариях каждый из них используется?
  • Как реализована вставка и обновление данных в AlaSQLProxy, и какие механизмы предусмотрены для проверки успешности этих операций?
  • Каким образом AlaSQLProxy управляет подключением к базе данных и что происходит в случае ошибок при инициализации или выполнении запроса?
Практическое задание - задача: «Анализатор данных продаж»
  • Условие: Вам дан массив данных о продажах товаров. Необходимо создать функцию анализа, которая использует AlaSQLProxy для получения различной статистики (топ продаваемый товар, средние цены на продукцию)

  • Данные: const salesData = [ [1, 'Телефоны', 'Январь', 15, 25000], [2, 'Ноутбуки', 'Январь', 8, 45000], [3, 'Планшеты', 'Январь', 12, 15000], [4, 'Телефоны', 'Февраль', 18, 24000], [5, 'Ноутбуки', 'Февраль', 10, 44000], [6, 'Планшеты', 'Февраль', 9, 16000], [7, 'Телефоны', 'Март', 22, 23000], [8, 'Ноутбуки', 'Март', 12, 46000], [9, 'Планшеты', 'Март', 15, 15500] ];
Модуль 4. Компоненты SliderDataSDK.
Создание пользовательского интерфейса в макросах с UserGUIHelper
1. Цели модуля

  1. Освоить создание пользовательского интерфейса в макросах через прокси-класс UserGUIHelper для взаимодействия с пользователем
  2. Изучить типы диалоговых окон - информационные, предупреждения, ошибки, подтверждения и окна ввода данных с различными элементами управления
  3. Понять систему callback-функций для обработки пользовательских действий и организации навигации между окнами
  4. Получить практические навыки создания интерактивных приложений с валидацией данных и обработкой ошибок
2. Описание модуля

Модуль посвящен изучению UserGUIHelper - специализированного прокси-модуля для создания пользовательского интерфейса в макросах редакторов Р7-Офис и OnlyOffice. Класс предоставляет удобные обёртки для работы с встроенными UI-компонентами редакторов, включая модальные окна различных типов, диалоги ввода данных с текстовыми полями и выпадающими списками, а также специализированные окна для отображения табличных данных. Основной функционал строится на интеграции с Common.UI API редактора и использует гибкую систему callback-функций для обработки пользовательских действий. Модуль включает практический пример "Тест UserGUIHelper" с демонстрацией всех типов диалогов, от простых информационных окон до сложных форм ввода и таблиц сравнения данных. Материал завершается практическим заданием по созданию интерактивного калькулятора с валидацией и обработкой ошибок.
3. Назначение и область применения UserGUIHelper

Прокси-класс UserGUIHelper - специализированный прокси-модуль SliderDataSDK, предоставляющий удобный интерфейс для создания диалоговых окон и элементов пользовательского интерфейса в макросах редакторов Р7-Офис и OnlyOffice. Модуль упрощает взаимодействие с пользователем через встроенные UI-компоненты редакторов. Он предоставляет обёртки для создания стандартных модальных окон (ошибки, предупреждения, информационные сообщения) и более сложных диалогов с элементами ввода, таких как текстовые поля и выпадающие списки.

Ключевые преимущества:
  • Простота создания UI — готовые методы для типовых диалогов
  • Интеграция с Common.UI — использование встроенных компонентов редакторов
  • Обратные вызовы — гибкая система callback-функций
  • Типизированные окна — специализированные методы для разных задач
  • Безопасность макросов — контролируемое взаимодействие с пользователем

Архитектура взаимодействия

4. Зависимости

Common UI API: Прокси-класс полностью зависит от объекта Common.UI (или аналогичного), предоставляемого средой редактора Р7. Этот объект должен быть передан в класс через функцию initUI перед использованием любых других методов.\
5. Основные методы API, примеры их использования

В данном разделе описаны основные методы API, необходимые для начала работы.
5.1 initUI(commonUI)

Описание: Инициализирует класс, сохраняя ссылку на объект UI. Этот метод обязателен к вызову перед использованием любых функций, создающих окна. Он позволяет модулю взаимодействовать с API пользовательского интерфейса редактора.

Параметры:
Имя
Тип
Описание
Обязательный
commonUI

object

Объект Common.UI из API редактора.

Да
Возвращаемое значение: void

Пример использования:

// Предполагается, что parent.Common.UI доступен
UserGUIHelper.initUI(parent.Common.UI);
5.2 alertWindow(title, message, onClose)

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

Параметры:
Имя
Тип
Описание
Обязательный
title

string

Заголовок окна.

Да
message

string

Текст сообщения.

Да
onClose

function

Callback-функция, вызываемая при закрытии окна.

Нет
Возвращаемое значение: object | null — объект окна или null, если UI не инициализирован.

Пример использования:

UserGUIHelper.alertWindow("Внимание", "Операция может занять несколько минут.");
5.3 userInputWindow(titleWindow, labelForInputField, ...)

Описание: Создаёт модальное окно с полем для ввода текста. Удобно для запроса у пользователя короткой текстовой информации, например, имени или значения.

Параметры:
Имя
Тип
Описание
Обязательный
titleWindow

string

Заголовок окна.

Да
labelForInputField

string

Текст метки над полем ввода.

Да
wWindow

number

Ширина окна. По умолчанию 200.

Нет
hWindow

number

Высота окна. По умолчанию 130.

Нет
onChange

function

Callback, вызываемый при нажатии "ОК". Принимает введенное значение.

Нет
onClose

function

Callback, вызываемый при закрытии окна (любым способом).

Нет
Возвращаемое значение: object | null — объект окна или null, если UI не инициализирован.

Пример использования:

UserGUIHelper.userInputWindow("Новая категория", "Введите название:", 300, 150, (value) => {
    if (value) {
      console.log("Пользователь ввел:", value);
    }
  });
6. Полное описание методов UserGUIHelper

Детальное описание всех методов класса UserGUIHelper представлено в Приложении 8 (документ приложений к курсу):
  • Инициализация и служебные
  • Информационные окна
  • Диалоги взаимодействия
  • Окна ввода данных
  • Специализированные диалоги
Обращайтесь к приложению для получения исчерпывающей информации о параметрах, возвращаемых значениях и примерах использования каждого метода.
7. Пример использования UserGUIHelper - запуск макроса «Тест UserGUIHelper»

Цель: Показать и проверить работу типовых окон (инфо, ошибка, подтверждение, ввод) для взаимодействия с пользователем в UI-сценариях. Ознакомьтесь с полным текстом макроса в файле «Макросы использования SliderDataSDK.xlsx» или в Приложении 5.

Сценарий макроса:
  • Инициализация и загрузка библиотеки - Проверка наличия R7ConsultLibs и SliderDataSDK.UserGUIHelper, инициализация userHelper, запуск главного меню или вывод ошибки.
  • Главное меню с тремя категориями - Отображение окна выбора тестов: "Простые окна", "Ввод данных", "Вывод данных".
  • Меню простых окон - Тестирование 6 типов диалогов: alert, confirm, warning, error, info и кастомное окно с настраиваемыми параметрами.
  • Меню ввода данных - Тестирование 4 форм ввода: текстовое поле, выбор диапазона ячеек, выпадающий список, диалог выбора файла.
  • Меню вывода данных - Тестирование табличного отображения: простая таблица 100×150 и режим сравнения таблиц с подсветкой различий.
  • Генерация тестовых данных - Функция generateTestData() создает таблицы заданного размера с опциональными заголовками и данными для сравнения.
  • Навигация и возврат - Каждое подменю имеет кнопку "Назад", callback-функции обеспечивают возврат в соответствующее меню после закрытия окна.
Запуск макроса:
  • После запуска макроса выбираем вариант тестирования - «Простые окна» или «Ввод данных»
  • Если выбираем простые окна, то появляется еще одно окно с выбором
  • Затем при выборе отображается соответствующее модальное окно. Например, «Подтверждение»
  • Если выбрать ввод данных, то появится опция для выбора окна ввода, где можно ввести текст
Вывод данных отображает 2 окна: Вывод таблицы и Вывод сравнения таблиц
  • При нажатии на «Вывод таблицы» отображается модальное окно с большой таблицей с данными (150 столбцов на 100 строк)
  • При нажатии на «Вывод сравнения таблиц» отобразится пример раскрашивания строк при сравнении данных двух таблиц (15 столбцов на 10 строк)
8. Контрольные вопросы для модуля 4

Вопрос 1: Инициализация и зависимости
Опишите, как и зачем выполняется инициализация UserGUIHelper. Что произойдёт, если вызвать методы до initUI()?

Вопрос 2: Callback-функции
Как работает механизм обратных вызовов (callback) в UserGUIHelper? Приведите пример, как можно реализовать возврат к предыдущему меню после закрытия окна.

Вопрос 3: Валидация пользовательского ввода
Как организовать проверку введённых пользователем данных в окне userInputWindow? Приведите пример проверки email или числового значения.

Вопрос 4: Выбор элементов UI
Чем отличается окно userInputWindow от userComboBoxWindow, и в каких случаях стоит использовать каждое из них?
Модуль 5. Компоненты SliderDataSDK. Работа с внешними Excel файлами через ExternalXLSXProxy
1. Цели модуля:

  • Освоить работу с внешними Excel-файлами через унифицированный API ExternalXLSXProxy без использования серверной части
  • Изучить двойную библиотечную архитектуру с возможностью переключения между SheetJS и ExcelJS для различных задач обработки данных
  • Понять систему кэширования рабочих книг и потокового чтения для эффективной обработки больших файлов
  • Получить практические навыки создания конвертеров данных с интерактивным выбором файлов и трансформацией содержимого
2. Описание модуля:

Модуль посвящен изучению ExternalXLSXProxy - унифицированного прокси-класса для работы с внешними Excel-файлами в браузерной среде. Класс является обёрткой над популярными библиотеками SheetJS и ExcelJS, предоставляя гибкость выбора инструмента в зависимости от задач обработки данных. Основной функционал включает загрузку и кэширование рабочих книг, чтение и запись данных с листов, потоковое чтение больших файлов без блокировки UI и прямую интеграцию данных в активный лист документа. Модуль содержит практический пример "Тест ExternalXLSX" для демонстрации полного цикла работы с Excel-файлами - от загрузки по URL до записи данных в документ и управления жизненным циклом книг в памяти. Материал завершается практическим заданием по созданию интерактивного конвертера Excel-данных с возможностями предварительного просмотра, трансформации и валидации данных перед интеграцией в документ.
3. Назначение и область применения

Прокси-класс  ExternalXLSXProxy - унифицированный API для работы с внешними Excel файлами без использования серверной части. Он является обёрткой над популярными библиотеками SheetJS.js и ExcelJS.js, позволяя переключаться между ними. Он упрощает такие операции, как чтение, запись и модификация данных в .xlsx файлах, кеширует загруженные книги для повышения производительности и предоставляет утилиты для конвертации форматов адресов ячеек.

Ключевые преимущества:
  • Полная поддержка Excel форматов — работа с .xlsx файлами через ExcelJS
  • Кэширование рабочих книг — эффективная система управления памятью
  • Потоковое чтение — обработка больших файлов без блокировки UI
  • Интеграция с документом — прямая загрузка данных в активный лист
  • Клиентская обработка — все операции выполняются в браузере

Архитектура взаимодействия

4. Зависимости

  • SheetJS (XLSX): Одна из возможных библиотек для работы с Excel-файлами. Должна быть доступна через ExternalXLSX.XLSX.
  • ExcelJS: Альтернативная библиотека для работы с Excel-файлами. Должна быть доступна через ExternalXLSX.ExcelJS.
  • jQuery: Требуется для метода loadWorkbookFromUrl для выполнения AJAX-запросов.
5. Основные методы API, примеры их использования

5.1 init()

  • Описание: Инициализирует API с использованием библиотеки по умолчанию (ExcelJS). Этот метод необходимо вызвать перед использованием любых других функций модуля. Он создаёт внутренний менеджер для работы с данными.
  • Параметры: Нет.
  • Возвращаемое значение: void.

Пример использования:
ExternalXLSX.init();
5.2 initWithExcelJS()

  • Описание: Инициализирует API с использованием библиотеки ExcelJS. Явно указывает модулю использовать ExcelJS для всех последующих операций.
  • Параметры: Нет.
  • Возвращаемое значение: void.
Пример использования:
ExternalXLSX.initWithExcelJS();
5.3 loadWorkbook(fileID, fileData)

Описание: Загружает рабочую книгу из данных файла и кеширует её. Если книга с указанным fileID уже была загружена, возвращает её из кеша. В противном случае, читает данные и сохраняет книгу в памяти.

Параметры:
Имя
Тип
Описание
Обязательный
fileID

string

Уникальный идентификатор для кеширования книги.

Да
fileData

ArrayBuffer | string

Данные файла. ArrayBuffer является предпочтительным форматом.

Да
Возвращаемое значение: Promise<any> | any — промис, который разрешается с объектом рабочей книги (для ExcelJS), или сам объект книги (для SheetJS).

Пример использования:

// fileData - это ArrayBuffer, полученный, например, из <input type="file">
const fileID = "myReport.xlsx";
ExternalXLSX.loadWorkbook(fileID, fileData)
  .then(workbook => {
    console.log("Книга успешно загружена:", workbook);
  });
5.4 readSheet(fileID, sheetIdentifier)

Описание: Читает все данные с указанного листа. Возвращает содержимое всего листа в виде двумерного массива.

Параметры:
Имя
Тип
Описание
Обязательный
fileID

string

Идентификатор ранее загруженной книги.

Да
sheetIdentifier

string | number

Имя листа или его индекс (для SheetJS индекс с 0, для ExcelJS — с 1).

Да
Возвращаемое значение: Array<Array<any>> — двумерный массив, представляющий данные листа.

Пример использования:
const sheetData = ExternalXLSX.readSheet("myReport.xlsx", "Итоги");
console.log(sheetData);
5.5 writeData(fileID, sheetIdentifier, startCellAddress, dataArray)

Описание: Записывает двумерный массив данных на лист, начиная с указанной ячейки. Этот метод изменяет только внутреннее представление книги в памяти. Для сохранения изменений в файл необходимо вызвать saveWorkbook.

Параметры:
Имя
Тип
Описание
Обязательный
fileID

string

Идентификатор ранее загруженной книги.

Да
sheetIdentifier

string | number

Имя или индекс листа. Если лист не существует, он будет создан.

Да
startCellAddress

string

Адрес левой верхней ячейки для начала записи (например, "A1").

Да
dataArray

Array<Array<any>>

Двумерный массив данных для записи.

Да
Возвращаемое значение: void.

Пример использования:
const newData = [
    ["Заголовок 1", "Заголовок 2"],
    [100, 200],
    [150, 250]
  ];
  ExternalXLSX.writeData("myReport.xlsx", "Новый лист", "B2", newData);
5.6 saveWorkbook(fileID)

Сохраняет все изменения в рабочей книге и возвращает её данные.

Описание: Генерирует бинарные данные .xlsx файла из текущего состояния книги в памяти.

Параметры:
Имя
Тип
Описание
Обязательный
fileID

string

Идентификатор книги для сохранения.

Да
Возвращаемое значение: Promise<ArrayBuffer> | ArrayBuffer — промис, разрешающийся с ArrayBuffer (для ExcelJS), или сам ArrayBuffer (для SheetJS).

Пример использования:
// После вызова writeData
Promise.resolve(ExternalXLSX.saveWorkbook("myReport.xlsx"))
  .then(fileData => {
    // fileData - это ArrayBuffer, который можно сохранить в файл
    // (например, с помощью FileSaver.js)
    const blob = new Blob([fileData], { type: "application/octet-stream" });
    // saveAs(blob, "myReport_updated.xlsx");
    console.log("Книга готова к сохранению.");
  });
6. Полное описание методов ExternalXLSXProxy

Детальное описание всех методов класса ExternalXLSXProxy представлено в Приложении 9 (документ приложений к курсу):
  • Инициализация и служебные
  • Управление рабочими книгами
  • Информация о структуре
  • Чтение/запись данных
  • Манипуляции с адресами ячеек
Обращайтесь к приложению для получения исчерпывающей информации о параметрах, возвращаемых значениях и примерах использования каждого метода.
7. Пример использования - запуск макроса «Тест ExternaXLSX (ExcelJS)»

Цель: Протестировать работу loadWorkbookFromUrl(), чтение листа и отдельных ячеек, а также вывод результата в интерфейс документа.  Ознакомьтесь с полным текстом макроса в файле «Макросы использования SliderDataSDK.xlsx» или в Приложении 3.

Сценарий макроса:
  • Проверка наличия библиотеки и инициализация
  •  Скрипт проверяет наличие SliderDataSDK.ExternalXLSXProxy, выводит сообщение в консоль и инициализирует прокси-объект extApi.
  • Задание параметров и запуск загрузки файла
  •  Указывается путь к файлу Excel test.xlsx, и вызывается асинхронная функция loadAndProcessFile() для его загрузки.
  • Загрузка книги и чтение листа
  •  Метод loadWorkbookFromUrl()загружает книгу по локальному пути, после чего данные с листа 'Лист1'считываются функцией readSheet().
  • Запись данных в активный лист документа
  •  Прочитанные строки и ячейки из Excel-файла последовательно записываются в текущий лист документа через Api.GetActiveSheet().
  • Чтение отдельной ячейки и завершение работы
  •  Значение ячейки A1 считывается методом readCell()и отображается через messageWindow(), после чего вызывается перерасчёт и выгрузка книги из кэша.
Запуск макроса:
  • Подготовить тестовый файл, из которого будут считываться данные.
  • Указать в макросе путь и название файла. По умолчанию в макросе путь – «file:\\\\C:\Projects\\test.xlsx» и название «test.xlsx»
  • После запуска макроса выдастся информационное окно, а также считается тестовый файл и данные из него перенесутся на текущий лист
8. Контрольные вопросы для модуля 5

  • Вопрос 1: Управление жизненным циклом- объясните важность правильного управления жизненным циклом рабочих книг в ExternalXLSXProxy. Что произойдет, если не вызывать unloadWorkbook()?
  • Вопрос 2: Система кэширования. Как работает система кэширования в ExternalXLSXProxy? Предложите стратегию управления памятью для обработки большого количества файлов.
  • Вопрос 3: Интеграция с документом. Опишите процесс интеграции данных Excel в активный лист редактора. Какие проблемы могут возникнуть и как их решить?
  • Вопрос 4: Различие между стандартными и кастомными окнами. В чём отличие методов errorWindow, alertWindow, confirmWindow от метода withOneButtonWindow? В каких случаях стоит использовать каждый из них?
Модуль 6. Компоненты SliderDataSDK. Модуль OlapProxy - унифицированный API для работы
с OLAP-данными
1. Цели модуля

  1. Освоить работу с OLAP-данными через унифицированный API OlapProxy для выполнения MDX-запросов к многомерным базам данных
  2. Понять систему кеширования соединений и асинхронное выполнение MDX-запросов для оптимизации производительности
  3. Получить практические навыки создания OLAP-дашбордов с преобразованием многомерных данных в табличный формат
2. Описание модуля

Модуль знакомит с OlapProxy - специализированным прокси-классом для работы с OLAP-серверами через стандартный протокол XMLA. Класс является обёрткой над библиотекой XMLA.js и обеспечивает полную поддержку многомерных баз данных с возможностью выполнения сложных MDX-запросов непосредственно в браузере. Основной функционал включает управление соединениями с кешированием для повышения производительности, асинхронное выполнение аналитических запросов и автоматическое преобразование многомерных данных в плоский табличный формат для интеграции в документы. Модуль содержит практический пример "Тест OlapProxy" для работы с кубом данных FoodMart, демонстрирующий полный цикл от подключения к OLAP-серверу до записи результатов в активный лист. Материал завершается практическим заданием по созданию интерактивного построителя дашбордов с визуальным конструктором MDX-запросов и множественными представлениями данных.
3. Назначение и область применения

Прокси-класс OlapProxy - унифицированный API для работы с OLAP-серверами через протокол XMLA без использования серверной части. Он является обёрткой над библиотекой XMLA.js, упрощая операции подключения, выполнения MDX-запросов и интеграции многомерных данных в документ. Класс кеширует соединения для повышения производительности и предоставляет утилиты для преобразования OLAP-данных в табличный формат.

Ключевые преимущества:
  • Полная поддержка XMLA протокола — работа с любыми OLAP-серверами через стандартный протокол
  • Кэширование соединений — эффективная система управления подключениями
  • Асинхронное выполнение запросов — обработка MDX-запросов без блокировки UI
  • Интеграция с документом — прямая загрузка данных в активный лист
  • Клиентская обработка — все операции выполняются в браузере
4. Зависимости

  • XMLA.js: Основная библиотека для работы с XMLA протоколом. Должна быть доступна через OlapProxy.Xmla
  • jQuery: Требуется для выполнения AJAX-запросов к серверу конфигураций
  • SliderDataSDK.UserGUIHelper: Для отображения сообщений пользователю (опционально)
5. Основные методы API, примеры их использования

5.1 init()

  • Описание: Инициализирует API с использованием библиотеки XMLA по умолчанию. Этот метод необходимо вызвать перед использованием любых других функций модуля. Он создаёт внутренний менеджер для работы с соединениями и устанавливает обработчики ошибок.
  • Параметры: Нет.
  • Возвращаемое значение: void.
Пример использования:
  • SliderDataSDK.OlapProxy.init();
5.2 initWithXmla()

  • Описание: Инициализирует API с использованием библиотеки XMLA. Явно указывает модулю использовать XMLA для всех последующих операций и устанавливает специфичные настройки.
  • Параметры: Нет.
  • Возвращаемое значение: void.
Пример использования:
  • SliderDataSDK.OlapProxy.initWithXmla();
5.3 loadConnection(connectionID, connectionParams)

Описание: Загружает соединение с OLAP-сервером и кеширует его. Если соединение с указанным connectionID уже было загружено, возвращает его из кеша. В противном случае, создает новое подключение и сохраняет его в памяти.

Параметры:
Имя
Тип
Описание
Обязательный
connectionID

string

Уникальный идентификатор для кеширования соединения

Да
connectionParams

object

Параметры подключения (url, catalog, source, user, password)

Да
Возвращаемое значение: Promise<Connection> — промис, который разрешается с объектом соединения.

const connectionParams = {
    name: "Adventure Works",
    url: "http://localhost:8080/xmla",
    catalog: "Adventure Works DW 2019",
    source: "Adventure Works DW 2019",
    user: "admin",
    password: "admin"
};
SliderDataSDK.OlapProxy.loadConnection("main", connectionParams)
    .then(connection => {
        console.log("Соединение успешно загружено:", connection);
    });
5.4 executeQuery(connectionID, mdxQuery)

Описание: Выполняет MDX-запрос к OLAP-серверу используя указанное соединение. Возвращает результат в структурированном виде с осями, ячейками и метаданными.

Параметры:
Имя
Тип
Описание
Обязательный
connectionID

string

Идентификатор ранее загруженного соединения

Да
mdxQuery

string

MDX-запрос для выполнения

Да
Возвращаемое значение: Promise<QueryResult> — промис с результатом запроса.

Пример использования:
const mdxQuery = `
    SELECT
        [Date].[Calendar Year].Members ON 0,
        [Product].[Category].Members ON 1
    FROM [Adventure Works]
    WHERE [Measures].[Sales Amount]
`;
SliderDataSDK.OlapProxy.executeQuery("main", mdxQuery)
    .then(result => {
        console.log("Результат запроса:", result);
        console.log("Данные в табличном виде:", result.flatData);
    });
5.5 writeToActiveSheet(connectionID, mdxQuery, startCellAddress)

Описание: Выполняет MDX-запрос и записывает результат прямо в активный лист документа, начиная с указанной ячейки. Этот метод автоматически преобразует многомерные данные OLAP в плоскую табличную структуру.

Параметры:
Имя
Тип
Описание
Обязательный
connectionID

string

Идентификатор ранее загруженного соединения

Да
mdxQuery

string

MDX-запрос для выполнения

Да
startCellAddress

string

Адрес левой верхней ячейки для начала записи (например, "A1")

Да
Возвращаемое значение: Promise<void>.

Пример использования:
const mdxQuery = `
    SELECT
        [Date].[Calendar Year].[Calendar Year].ALLMEMBERS ON 0,
        [Product].[Category].[Category].ALLMEMBERS ON 1
    FROM [Adventure Works]
    WHERE [Measures].[Sales Amount]
`;
SliderDataSDK.OlapProxy.writeToActiveSheet("main", mdxQuery, "B2")
    .then(() => {
        console.log("Данные успешно записаны в лист");
    });
5.6 saveQueryResult(connectionID, queryID)

Описание: Сохраняет результат выполненного запроса и возвращает его данные в различных форматах для экспорта или дальнейшей обработки.

Параметры:
Имя
Тип
Описание
Обязательный
connectionID

string

Идентификатор соединения

Да
queryID

string

Идентификатор запроса для сохранения

Да
Возвращаемое значение: Promise<QueryExport> — промис, разрешающийся с данными для экспорта.

Пример использования:
SliderDataSDK.OlapProxy.saveQueryResult("main", "query_001")
    .then(exportData => {
        console.log("Результат готов к сохранению:", exportData);
        // exportData содержит данные в различных форматах
    });
6. Полное описание методов ExternalXLSXProxy

Детальное описание всех методов класса ExternalXLSXProxy представлено в Приложении 10 (документ приложений к курсу):
  • Управление параметрами и конфигурацией
  • Основные методы API для выполнения запросов
  • Обработка и преобразование данных
  • Вспомогательные и служебные методы
Обращайтесь к приложению для получения исчерпывающей информации о параметрах, возвращаемых значениях и примерах использования каждого метода.
7. Пример использования – запуск макроса «Тест OlapProxy»

Этот JavaScript макрос представляет собой тестовую утилиту для работы с OLAP-данными.
Вот краткий сценарий его работы:
Краткий сценарий макроса
Цель: Тестирование библиотеки SliderDataSDK для выполнения MDA запросов к OLAP серверу
Основной поток выполнения:
  • Инициализация и проверки
  1. Проверяет наличие библиотеки Common.R7ConsultLibs.SliderDataSDK.OlapProxy
  2. При отсутствии библиотеки показывает предупреждение и останавливается
  3. При успешной загрузке показывает информационное окно с версией SDK
  • Подготовка к тестированию
  1. Загружает параметры подключения из localStorage (созданные плагином «Слайдер Данные»)
  2. Ищет подключение с именем "FoodMart"
  3. При отсутствии подключения показывает ошибку и прерывает выполнение
  • Выполнение OLAP запроса
  1. Настраивает функцию обработки полученных данных
  2. Выполняет MDA запрос к кубу "Warehouse" для получения:
Городов магазинов по колонкам
Кварталов по строкам
Значений "Store Invoice" как мер

  • Обработка результатов
  1. Полученные данные записывает в активный лист Excel/Calc
  2. Устанавливает жирный шрифт для заголовков
  3. Выполняет пересчет активного листа
  4. Логирует результаты в консоль

Запуск макроса – после запуска результат можно просмотреть в консоли DevTools
8. Контрольные вопросы

  • Управление соединениями: Объясните преимущества кеширования OLAP-соединений. Что произойдет при превышении лимита одновременных соединений?
  • Обработка MDX-запросов: Как обеспечить валидацию MDX-запросов перед отправкой на сервер? Предложите стратегию обработки синтаксических ошибок.
  • Интеграция с документом: Опишите процесс преобразования многомерных OLAP-данных в плоскую табличную структуру для отображения в листе.
  • Безопасность: Какие меры безопасности необходимо предусмотреть при работе с учетными данными OLAP-соединений?