1. Введение (эта статья)

2. Расширяем структуру файлов надстройки и удалённая отладка

Поскольку это первая моя публикация на Хабре, хотя как читатель я присутствую здесь уже довольно много лет, я скажу пару слов о себе. Вообще мой стаж как программиста, если учитывать и студенческие годы, когда я под руководством моего руководителя практики начал изучать С и С++ еще в 1992 году (откидываем программирование на калькуляторах, это всё таки баловство), уже более 30 лет. Много чем занимался в этой сфере, и что перепробовал по работе и чисто из интереса. Несколько более «известным»  я стал с 2016 года в кругу тех, кто активно использует станки ЧПУ, как разработчик средств автоматизации (макросов) под CorelDraw. Тем не менее,  сегодня речь пойдет о другой автоматизации – офисной. В силу своей работы на гос службе, мне приходилось заниматься внедрением и поддержкой документооборота, а также автоматизацией разных рутинных задач. Поэтому тема не сказать что для меня незнакомая.

Итак, что на текущий момент есть в плане автоматизации в пакете «МойОфис». На самом деле, если сравнивать с возможностями даже почти 20 летней давности автоматизации на VBA в «MS Office», то не много.  Языком для автоматизации выбран неплохой, в общем-то, хотя и мало для этого полезный, скриптовый язык Lua. Есть два типа поддерживаемых скриптов (поддержка есть только для текстового и табличного редакторов):

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

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

Имеется простой редактор для написания и отладки  скрипта макроса с расстановкой точек отладки и просмотра локальных переменных, но при этом нет даже автодополнения кода для API «МойОфис». То есть писать макросы в нем приходится, особенно по началу, с открытым справочником и поиском по нему требуемых данных об используемых в API функциях, что как по мне,  в 2023 году, как-то не особо правильно! Ещё недавно добавили "импорт" в виде закомментированного исходного кода VBA макросов, при открытии документов Word или Excel. Ну, в общем, для простых переносов простых же макросов, пусть «со скрипом», но терпимо!

А вот для надстроек, которые в общем то и являются более менее адекватной заменой макросам, даже и этого «не завезли»!

Итак, что я предлагаю для решения проблем с отсутствием встроенной среды разработки, и создания более комфортной среды для тех коллег, кому придётся всё-таки заниматься внедрением надстроек под «МойОфис»?

1. Для разработки надстройки использовать стороннюю среду разработки(IDE) предназначенная для программирования под Lua.

2. Удалённая отладка надстроек средствами того же IDE.

3. Создание в IDE простого визуального редактора для проектирования форм для новых надстроек (пока не пробовал, но шанс есть!)

4. Создания аддона для встроенного в Microsoft Office IDE VBA, который бы позволил существенно упростить перенос уже разработанных макросов из «MS Office» под «МойОфис», за счёт хотя бы частичной трансляции дизайна форм и бизнес-логики

Таков мой план на текущий момент, хотя пункт 4 из него, всё таки это более дальняя перспектива, так как задача сама по себе, мягко говоря – нетривиальная! И сразу оговорюсь – решение найденное мной на текущий момент рассматривается под Windows. Собственно, если речь именно о переносе, то в любом случае актуально сперва всё сделать в винде, и потом перенести под Linux готовые надстройки. Поэтому, может быть,этим вопросом я займусь позже. И если всё пройдет успешно, опишу особенности, если таковые возникнут, уже отдельной статьёй.

Выбор IDE для написания надстроек

Мой выбор  для проведения экспериментов пал на LuaRT версии 1.4.  Данная среда разработки является форком другой, наверное самого известной среди Lua программистов всего мира ZeroBrane Studio (автор  Paul Kulchenko). При этом LuaRT является, наверное самый развивающийся в мире Lua IDE, в которой реализовано много новых своих интересных «фич», таких как компиляция в exe файл, работа со  своими модулями, в том числе и GUI. К тому же под она лицензией MIT, а значит позволяет безбоязненно использовать её возможности под выбранные цели.

Очень удобным плюсом такого  выбора оказалось и то, что  в LuaRT внедрёна возможность удаленной отладки, через модуль «mobdebug», который используется и для отладки Lua скриптов и в самом «МойОфис». Ещё из выявившихся в ходе исследований плюсов является возможность самостоятельно создать систему автодополнений для API «МойОфис», а значит существенно упростить себе жизнь при написании кода! О том, как это сделать я обязательно так же расскажу в следующей части.

Пишем простейшую надстройку

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

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

Сразу опишу папку META-INF, так как она второстепенная, но обязательная. В ней должен быть всего лишь файл LICENSE с лицензионным соглашением, демонстрируемым при инсталляции надстройки. Содержимое лицензии на ваш вкус.

В корневой папке должен присутствовать файл регистрации с обязательным именем Package.lua, содержащий пары ключ-значение для конфигурации надстройки в приложении редакторов «МойОфис». Какие именно ключи и для чего можно узнать в соответствующем разделе руководства. Пока же приведу листинг из пробного файла с пояснением самых важных на текущий момент пунктов:

• extensionName - Название надстройки. Отображается в меню Надстройки командного меню приложения в том случае, если надстройка установлена и включена

• applicationId - Идентификатор приложения, с которым может работать надстройка

• commandsProvider - Наименование файла сценария надстройки. Допустимо указание пути относительно домашнего каталога надстройки. Файл сценария под названием entryform.lua расположен в каталоге cmd домашней папки надстройки.

Полное содержимое файла Package.lua

local Package = {
vendor = "МойОфис",
description = "Это пример расширения для МойОфис",
extensionID = "ru.starfair.test",
extensionName = "Тестовое Расширение 1",
extensionVersion = {
 major = 1,
 minor = 1,
 patch = 0,
 build = "" },
applicationId = "MyOffice Text",
apiVersion = {
 major = 1,
 minor = 0 },
commandsProvider = "cmd/entryform.lua",
fallbackLanguage = 'en',
onLoad = "cmd/entryform-prep.lua",
onUnload = "cmd/entryform-prep.lua"
}
return Package

Остальные пункты не столь критичны на текущий момент. Далее, в каталоге cmd следует создать новый файл, с именем entryform.lua соответствующим имени указанном в commandsProvider файла Package.lua. Поскольку я хочу немного сэкономить место для этой статьи, содержимое я выберу сразу с созданием простой формы и пока не буду углубляться в сам код. Его я поясню в следующих статьях, или же можно понять, немного полистав руководство:

Actions = {}
--[[Обязательная команда, по которой устанавливается 
набор доступных для данной надстроки команд в меню--]]
function Actions.getCommands()
	return {
			{
				id = "DlgForm.ShowDlg",
				menuItem = "Показать форму",
				command = Actions.ShowControls
			}
	}   
end
--Создадим набор из двух кнопок Ок и Cancel
Actions.dialogButtons = ui:DialogButtons{}
Actions.dialogButtons:addButton("OK", Forms.DialogButtonRole_Accept)
Actions.dialogButtons:addButton("Cancel", Forms.DialogButtonRole_Reject)

--Создадим метку в середине формы
Actions.lblMenu = ui:Label{
  Text="Поздравляю с первой надстройкой!", 
  Color=Forms.Color(255,0,0),  
}
Actions.lblMenu:setColor(Forms.Color(255,0,0))
Actions.lblMenu:setAlignment(Forms.Alignment_MiddleCenter)

--Создадим форму используя созданные ранее контролы
Actions.dlgBegin = ui:Dialog {
	Title = "Демонстрация мультиформенного расширения",
	Size = Forms.Size(600,300),
	Buttons = Actions.dialogButtons,
	--Позиционирование метки строго по центру формы
  ui:Column {		
		ui:Row {Actions.lblMenu},   
	}
} 
--Функция выводящая созданую форму
function Actions.ShowControls(context)	    
  context.showDialog(Actions.dlgBegin) 
end
return Actions

На этой стадии, нужно быть очень внимательным, и поскольку отладка надстроек ещё не внедрена (этому я посвящу следующую статью), то любые ошибки придётся исправлять "вслепую", опираясь на скупые сообщения об ошибке (причем по одной за раз!), при попытке запустить инсталлированное расширение!

Итак, вводим данный листинг, сохраняем файл под названием entryform.lua в подпапку cmd (не обязательно именно такую, можно вообще в корне записать, но лучше не сваливать всё в одну кучу!). Дальше из под Проводника Windows выделяем всё содержимое корневой папки (помним что в папке META-INF, обязательно надо разместить файл с лицензией, иначе надстройка не инсталируется) и сохраняем в zip файл (правая кнопка мышки, в контекстном меню выбрать: Отправить/Сжатая ZIP папка). Далее надо просто сменить расширение получившегося .zip архива на расширение .mox. Как инсталлировать расширение, так же проще прочесть в руководстве по созданию надстроек от разработчиков. Если все прошло удачно, то в меню Надстройки программы «МойОфис Текст» появится созданная нами надстройка:

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

В общем-то, пока я ничего особо нового не сказал, чего-бы не было в руководстве по созданию надстроек. Но как обычно принято, для самых упорных дочитавших до этого момента, теперь я начинаю делиться более ценной информацией!

Итак, допустим собрали надстройку, инсталлировали и запустили.Первый же вопрос любого нормального программиста: "Каким образом теперь вносить изменения, и желательно без необходимости каждый раз создавать архив, инсталлировать по новой надстройку и т.д.?" Так вот, чтобы продолжить более комфортно заниматься расширением функционала, нужно найти место на жестком диске, где располагается инсталлированное расширение.И расположение не такое и очевидное! А именно вот по такому пути:

C:\Users\Your_User_Name\AppData\Local\New Cloud Technologies Ltd\MyOffice\MyOffice Text\Extensions 

Это для  «МойОфис Текст». Для редактора таблиц, MyOffice Text сменится на MyOffice Spreadsheet. Далее, после Extensions, следует специфичный Код_Надстройки, который генерируется для каждой надстройки отдельно. Если их много, то чему что соответствует, можно найти в реестре по следующим путям:
Для текстового редактора:

HKEY_CURRENT_USER\Software\MyOffice Standard\MyOffice Text\Plugins\Код_Надстройки

Для табличного:

HKEY_CURRENT_USER\Software\MyOffice Standard\MyOffice
Spreadsheet\Plugins\ Код_Надстройки

Теперь, закрываем в LuaRT всё что мы уже написали ранее, и вот таким образом указываем путь для проекта по выясненному как показано выше, абсолютному пути к инсталлированной надстройке:

Вот таким образом, мы теперь будем продолжать работу с исходным кодом, но уже инсталлированного расширения в достаточно удобной для работы IDE! А значит - без необходимости заново каждый раз при изменениях упаковывать в архив и инсталлировать надстройку!

Но не забывайте периодически делать самостоятельно вручную обратные копии файлов, так как если вы каким то образом по новой инсталлируете надстройку, прежняя папка будет удалена со всем содержимым, и "новое" содержимое будет распаковано в папку под новым кодом, хотя формально и для той же самой надстройки. И даже если вы сделаете обновление (такая возможность в диспетчере надстроек так же имеется), то всё равно, содержимое будет перезаписано, а значит в следующий раз у вас получится откат на более раннюю версию.

На сегодня всё! В следующей части я расскажу о подключении удалённой отладки и создании файла для автодополнения для API «МойОфис» в LuaRT.