Создаём свой первый модуль для BAS или как оптимизировать повторяющий код в проектах

llimonix · 2 ноя 2023

Привет, гость
Это уже моя 3 статья, которая обучает вас правильно использовать программу для создание скриптов Browser Automation Studio.

Первые 2 авторские статьи:
https://zelenka.guru/threads/3240535/
https://zelenka.guru/threads/2853560/

В этом гайде, я научу вас создавать модули на примере самого простого модуля
Мои публичные модули:
https://zelenka.guru/threads/5426271/
https://zelenka.guru/threads/3721937/

Этап 1. Подготовка проекта

1. Запускаем программу BAS

2. Нажимаем на кнопку создать новый проект

3. Выбираем место куда сохранить наш будущий xml файл с структурой модуля. Я выбрал рабочий стол и дал название test

4. После успешного создания нового проекта, нажимаем кнопку запись

5. После запуска редактора скриптов, нажимаем на текст main, чтобы создать новую функцию в проекте

6. Нажимаем на плюсик, чтобы начать создавать новую функцию в проекте

7. Сразу же переходим в режим "Подробнее", чтобы получить дополнительные поля для создания нашей функции

8. Теперь давайте разберемся по каждому из пунктов в этом меню
1) Имя нашей функции
2) Описание нашей функции
3) Переключатель, который дает нам право вернуть какой либо итог выполнение нашей функции. В нашем случае это нужно включить. Так как мы с вами делаем генератор User-Agent.
4) Описание того, что вернётся после выполнения функции в данном модуле
5) Имя переменной по умолчанию. Это то к какой переменной будет присваиваться значение, чтобы потом его использовать в нашем проекте. В любой момент пользователь модуля, может указать свое название функции
6) Параметры. Это то что мы переделаем в нашу функцию из нашего проекта. Чтобы наша функция в модуле понимала с чем ей работать. В нашем случае мы будем передавать тип устройства User-Agent которого хотим получить
7) Имя параметра, который даст понять пользователю модуля, что от него требуется. Также описание, для более подробного объяснения. И тип передаваемого значения. Тип зависит от того какие данные вы хотите, чтобы пользователь передавал (имеются такие типы как Строка, Число, Булевый тип, Выражение, Строка или выражение, Число или выражение). Тут зависит от вашей надобности. В нашем случае хватит и простой строки.
8) Создать нашу функцию с указанными настройками

9. После нажатия кнопки "Сохранить изменения" нас сразу же забросит внутрь данной функции. Мы здесь увидим (1) В какую переменную будет сохраняться параметр, который мы передаем в эту функцию, (2) Что мы возвращаем при окончании работы модуля. То что мы туда укажем, автоматически попадет в переменную, который мы указали для сохранения результатов.

10. Сразу даю вам совет от себя, который мне дали при первом моем знакомстве с модулями. Называть переменные в функциях в модуле так, чтобы они не пересеклись с названиями переменных, которые может придумать потенциальный пользователь модуля. Лучшим вариантом можно добавлять приписку с названием модуля. В своих проектах я делал LOLZAPI_названиепеременной и тд.

11. Для примера я попросил ChatGPT создать скрипт на языке JS, для генерации рандомных User-Agent, на выходе получил не то что хотел, но для примера сойдет и этого. Давай пробежимся по тому, что тут происходит. Если вы тоже будете использовать "Выполнить код", то все ошибки в лог можете выводить через fail("Ваш текст") (1). Но если вы не будете этого делать, то можете воспользоваться стандартным вызовом FAIL в BAS.
(2) Вот сам вывод в лог. (3) Переменная, которой мы присвоили передаваемое значение в пункте 10. (4) Переменная, в которую сохраняем результат.
Для создания басовских переменных в "Выполнить код" можно использовать [[названием_переменной]] или же VAR_NAME - где NAME название переменной.

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

13. Проверить работу функции можно следующим способом:
1) Переходим в модуль "Логика скрипта"
2) Выбираем функцию в этом модуле под названием "Вызов функции"
3) У нас появляется вызванная функция в разделе main (обязательно сначала туда нужно перейти из внутренностей вашей функции)

14. Кликаем два раза на этот блок (но не на названием функции) и мы попадаем в нашу структуру (или же мы туда попадем при первом нажатии на "Вызов функции"). Здесь мы указываем все то, что мы сделали ранее. (1) Наша ранее созданная функция (2) Параметр, который мы передаем (3) Переменная, в которую сохраниться результат

15. После вызова функции и его настройки активируем её нажатием на стрелочку. И делаем так, пока не дойдем до return. По итогу выполнения нашей функции мы увидим, что в нашу переменную USER_AGENT упало сгенерированное значение из нашего скрипта (все лишние переменные отображаются только потому что, мы сейчас находим в структуре модуля, если вы будете его вызывать в других ваших проектах после компиляции модуля, лишних переменных из модуля не будет)

16. Начинаем компилировать наш модуль и проверяем
1) Нажимаем на завершить запись
2) Открываем менеджер модулей
3) Нажимаем "Создать новый модуль"
4) Выбираем функции, которые будет включать наш модуль

17. Настраиваем наш модуль
1) Придумываем ему названием, которые будет отображаться в списке модулей (ВНИМАНИЕ! Без пробелов и лишних символов)
2-3) Краткое описание на русском и английском. Этот пункт будет использоваться как название нашего модуля в режиме ЗАПИСЬ
4) Версия вашего модуля. Если вы будете обновлять ваш модуль и фиксить баги, то перед каждой новой компиляцией не забываем изменять версию, чтобы не войти в ступор и понять какая версия свежая, а какая нет
5) Подробное описание функции.
6) Прочая контактная информация создателя модуля, чтобы понять кто создатель и к кому обращаться из-за ху*евого написанного модуля

18. Теперь нужно выбрать иконку нашего модуля, чтобы дать визуальное понятие, что делает этот модуль или чтобы просто как то выделиться среди других модулей. Нажимаем на пазл и выбираем картинку, которую хотим использовать. В моем случае я скачал иконку из сайта flaticon.

19. Два главных пункта. (1) Чтобы названия функций не конфликтовали с функциями в самом будущем проекте с использованием вашего модуля, ставим, чтобы скрипт генерировал для них рандомное названием. (2) Ну и устанавливаем сразу модуль, чтобы проверить его работоспособность.

20. Сразу же после нажатия кнопки "Finish" нам откроется папка с zip архивом нашего модуля. Не выходим из неё. Нам она еще понадобится.
Так же мы сразу сможешь увидеть в менеджере модулей нас ранее созданный модуль

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

22. Ура мы создали свой первый модуль и можем уже его использовать, но а если мы выпускаем модуль не только для себя, а так же для других людей. Причем не только для русских, но и англоговорящих. То как нам быть? А вот сейчас мы с этим и разберемся!

Этап 2. Красота требует жертв!

1. Для того чтобы, у нас вышел красивый презентабельный модуль. У которого будут понятные названия функций да еще и переведены на два языка. А так же сделаем выпадающий список для параметров типа девайса.
2. Разархивируем архив модуля и видим следующие файлы
1) engine.js содержит все функции и их функциональность
2-4) Файлы с припиской _code.js, _interface.js, _select.js создаются для каждой, повторяю для каждой функции в модуле и редактируется отдельно.
5) manifest.json содержит в себе структуру нашего модуля. Названием кнопок, версию, локализацию и прочее. Подробнее можно изучить в так и не доделанном гайде по модулям: КЛИК

3. Давайте по порядку. Файл manifest.json
1) Эти строчки и строчки ниже под названиями interface, name. select содержат названия файлов, к которым нужно обращаться при нажатии кнопки для вызова нашей функции
2) description содержит текст нашей кнопки в модуле, для вызова функции. Вот здесь мы и переименовываем в более понятный вид.
3) description_small ранее созданное название нашего модуля в общем списке модулей в режиме ЗАПИСЬ. Пункты ниже указанные нами контактные данные
4) Наше более подробное описание
5) Версия нашего модуля
6) Наша локализация, куда мы и будем указывать английский и русский текст

4. Давайте приведем все в божеский вид и укажем более понятное название нашей кнопке. В поле description пишем русскую и английскую вариацию нашего действия

5. Чтобы проверить, что у нас получилось. Нам нужно ранее распакованный архив, запаковать заново в zip. Важно! Именно папку с файлами модуля, чтобы структура модуля не была нарушена. Если в архиве будут просто файлы, то BAS не считает модуль и посчитает его некорректным.
После чего заново переустанавливаем наш модуль (так как мы не изменили версию, то подтверждаем замену)

6. Открываем проект и смотрим какое теперь у нас названием нашей функции (кнопки)

7. С текстом кнопочек разобрались, а что там с описанием действий в самой функции. Они же только на русском. А нам нужно их локализировать. Вот в этом мы сейчас и разберемся. Открываем файл с припиской interface.js

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

И так. Что же тут такое. Без пива и пачки сухариков х*й разберешься. Ну давайте по порядку. Глубока нам лезть не надо. Разберем поверхность
1) Вот тут всегда будут параметры, которые мы должны указывать при запуске нашей функции в модуле. Их может быть неограниченное количество
2) Вот тут у нас поле для приписки нашей переменной, куда будет сохраняться наш результат (может быть и без нее, если ваша функция ничего не возвращает)
3) Ну тут все просто. Описание нашей функции
9. Локализация. Вся локализация каждого текста хранится в прошлом файле manifest.json и прописывает так (на скрине указано два параметра localize, я тут забыл удалить нижний. А вы не забывайте и параметр должен быть один, если не удалите, то нижняя локализация перезапишет верхнюю и ничего не поменяется в вашем модуле, также в конце у меня квадратная скобка, а должна быть фигурная, не ошибаемся друзья)
В моем модуле, где я перенес LolzAPI в BAS около 155 строк текста, который я перевёл. это заняло 1/3 времени создания модуля (в совокупности с редактирование интерфейса всех функций, а также дополнением описания каждого параметра, которого могло не быть в оригинальной документации)

10. Чтобы понять что наш текст переименуется нужно посмотреть если ли у нас класс tr в описании функции и описание функции должно быть на английском. А русский текст оно подтянет с manifest.json

11. Это классно мы перевели описание. Но как быть с описанием параметров и прочей ерунды в функции модуля. Тут все проще некуда. Там нужно заключить наш текст в скобки и перед скобкой написать tr. Также обязательно прописать текст на английском, а его перевод в файле manifest.json

12. Фух. С локализацией разобрались. Теперь разберемся с выпадающим списком для выбора типа девайса. На самом деле тут думать нечего. Создаем новый параметр с названием variants и в виде списка указываем наши типы девайсов. Вот так:

13. Теперь сохраняем наши файлы и запаковываем наш модуль снова в zip архив и устанавливаем. И смотрим что получилось

Этап 3. Немного важной информации

1. От себя добавлю моменты, с которыми придется вам столкнуться.
1) Если вы добавили функций в ваш модуль и сгенерировали его заново через BAS. То нужно заново настраивать описание и manifest.json или перенести существующий, если в вашем модуле не добавилось новых функций и параметров.
2) Чтобы поменять кнопки местами, в файла manifest.json нужно расположить данные каждой кнопки в нужном порядке, но не сломать структуру json
3) Так же из пункта 1. BAS генерирует случайные названия функций при каждой пересборке модуля, поэтому все что вы указали в параметрах. Будь то текст, число, переменную сбросится на дефолтное. И нужно будет все действия в вашем проекте, где используется этот модуль переделывать.
4) Советик дня: Собирайте весь модуль, проверяйте работу перед его компиляцией, а потом обновляйте только жизненно необходимые файлы со структурой кода в файле engine.js
5) Не используйте модули от сторонних разработчиков в вашем модуле. Так как по умолчанию при запуске скрипта в режиме ЗАПУСК, а не ЗАПИСЬ. BAS подгружает модули, которые используются в вашем проекте, поэтому ваш модуль может не найти те модули, которые вы указали внутри вашего модуля и ни разу не вызывали в вашем проекте. Так что, если вам нужна какая то функциональность, то лучше это все переделывать на чистый JS и выполнять в действии "Выполнить код"
6) Всегда можно создать модуль на чисто JS и не париться по поводу всего этого, но тут уже кто как умеет

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

Возникли вопросы? Обращайтесь: Telegram | llimonix

murphy · 2 ноя 2023

Годнота

ToSa · 2 ноя 2023

спасибо, полезная информация

vuchaev2015 · 2 ноя 2023

Лимоникс молодец, мне помогал с басом, челам помогает , еще и статью написал. Годно. Правда читать долго, но полезно максимально. Я в басе нубик , но хоть новое узнаю
Надеемся, что выиграешь в конкурсе статей.
Заказывайте софты у него :peka:.