Переменные
Данное руководство расскажет о том что такое переменные, какие принципы и механики заложенные в их основу, а также опишет все возможные способы работы с ними в @MenuBuilderBot.
❖ Переменные - что это такое?
Переменная - (в @MenuBuilderBot) это некий контейнер для хранения данных (текстовых или числовых). Более детальное описание концепции переменных.
Как добавить переменные в бот
Функционал раздела «🧩Расширения»: чтобы дополнительные переменные появились в вашем боте они должны быть активированы в вашем боте.
Дополнительные переменные.
Для подключения перейдите в вашем боте:☞ 🔐Админ | 🧩Расширения | 📂Переменные
После активации необходимого количества дополнительных переменных перейдите:☞ 🔐Админ |🗄Переменные
и выбрав нужный Вид переменной добавьте её, указав желаемое Имя. Только после этого новая переменная может считаться полностью созданной.
Для редактирования переменной перейдите внутрь кнопки с ее именем. Переменной (в зависимости от выбранного Вида) можно:
● Изменить имя (соответственно ее макрос)
● Изменить отображаемое имя (используется в системных сообщениях которые нельзя редактировать).
● Включить уведомление юзера об изменении данных в переменной (доступно кастомное сообщение, см.ниже).
● Включить "Топ по переменной" (если данная функция активирована в боте).
● Добавить комментарий (бывает полезно при большом количестве переменных в боте).
● Задать значение по умолчанию
Кастомное уведомление переменной
Кастомное сообщение об изменении значения переменной.
Функционал раздела «🧩Расширения»: Позволяет задать своё собственное сообщение для юзера об изменении значения Переменной.
Кастомное уведомление переменной.
Для подключения перейдите в вашем боте:☞ 🔐Админ | 🧩Расширения | 📂Кастомизация
После активации опции в Расширениях, вы можете задать Кастомное Сообщение для Уведомления Переменной:
☞ 🔐Админ | 🗄 Переменные
• Выберите Вид Переменной
• Укажите переменную
• Нажмите «Задать Сообщ. Уведомления».
Типизация переменных
В общем случае данные хранящиеся в Переменных могут быть текстовыми и/или числовыми.
ВАЖНО: в Условиях и Выражениях, для корректной работы с текстовыми данными их нужно брать в "" (кавычки).
Тип данных в переменной - определяется Видом переменной (см ниже).
Виды переменных
На сегодня в @MenuBuilderBot есть 6 видов переменных:
Текстовая переменная
Это контейнер для текста. Она может содержать как Буквы, Эмодзи, так и Цифры (как текст). Эта переменная может содержать индивидуальные данные юзера (например адрес его кошелька). При работе с Текстовыми Переменными в Выражениях нужно использовать кавычки.
● Значение по умолчанию: Отсутствует.
● Размер: 200 символов.
● Тип данных: текстовые
Цифровая переменная
Может содержать только числа. Благодаря этому содержимым этой переменной можно манипулировать как обычным числом (принимая значение такая переменная проверяет - является ли значение цифровым). Баланс - является примером цифровой переменной.
● Значение по умолчанию: 0 (ноль).
● Тип данных: числовые
Глобальная переменная
Главная особенность в том что у неё одинаковое значение для всех юзеров. Таким образом изменив её значение один раз, значение сменится одновременно у всех юзеров бота. Сами по себе Глобальные переменные - это Текстовые Переменные (см выше), однако они могут содержать Медиа контент (Картинки, Аудио, Видео) так же как и Медиа Переменная (см. ниже), кроме того, если задать им числовое значение - могут выступать в роли Цифровых (см. выше).
Глобальной переменной, в отличие от всех остальных, можно задавать значение в её настройках - для этого нажмите кнопку «Задать Значение».
● Значение по умолчанию: Отсутствует.
● Размер: 1000 символов (текст поместится под картинкой).
● Тип данных: текстовые или числовые (в зависимости от заданного значения)
Переменная (Даты) Времени
Содержит данные о дате-времени записанные в определённом (текстовом) формате.
● Формат записи: "17.05.2020 19:45:05".
● Значение по умолчанию: Системное время "Сейчас" (то же что и в функции dt_now()).
● Тип данных: текстовые
Чисто технически, Время в таком формате можно сохранять и в Текстовых Переменных, но полноценно работать с такими переменными у вас не получится. В Текстовой переменной Время можно только хранить, но не выполнять с ним каких-либо действий.
Как узнать что переменная Даты и Времени - не инициализирована? Например вам нужно чтобы Action сработал только если переменная Даты и Времени ещё не инициализирована.
• В условии можно указать такое выражение:{dt_diff(dt_now(), "%varname%", "s") < 1} - Верно, если разница между "Сейчас" и значением меньше секунды.
Где varname - имя переменной Даты и Времени.
• Action Инициализации - может сам отличать инициализированную переменную Даты и Времени от неинициализированной.
Медиа переменная
Может содержать любой вид медиа - картинки, видео, стикеры, аудио и прочее. Медиа переменная является Текстовой Переменной - по этой причине особенности работы с ней такие же как и у Текстовых Переменных (см руководство по Выражениям касательно Текстовых Переменных).
● Значение по умолчанию: Отсутствует.
● Тип данных: текстовые
На данный момент задать первоначальное значение Медиа Переменной - можно только при помощи Формы в режиме «Ввод Переменной». Любые Action-ы работающие с текстом, могут работать с уже существующими значениями Медиа переменных.
Вывод значения Медиа переменной в сообщении.
1. Перейдите в «Редактор Постов» и создайте сообщение (так же как обычно) или используйте для этого уже готовое сообщение.
2. Зайдите в «Настройки сообщения» нажав на кнопку со звёздочкой ("*")
3. Выберите опцию «Переменная Media»
• Выберите Переменную из списка ИЛИ используйте Выражение (типа bool_symb(), num_symb(), vget()) которое сформирует нужное значение.
• Укажите, показывать ли Медиа из самого Сообщения (если есть), если переменная пуста?
ВАЖНО: При использовании переменных содержащих медиаконтент, имейте в виду что в Telegram "сообщение с картинкой" по сути является картинкой с подписью... При этом не каждый медиаконтент (например стикер) может содержать подпись - таким образом, если у вас есть сообщение с текстом и картинка для него берётся из переменной, то данный текст, может отсутствовать в зависимости от того какой медиаконтент содержится в этой переменной.
ВАЖНО: имейте в виду что если ваша переменная пуста, а в сообщении отсутствует текст, то бот покажет --Error--. Бот должен показать сообщение но какие-либо данные для него отсутствуют - поэтому конструктор подставит текст ошибки.
Переменная Формул
Переменная Формул - содержит формулы или части других Выражений. Используется в Выражениях в виде Макроса. Содержимое Переменной Формул подставляется в Конечное Выражение как текст и окончательно вычисляется уже в Конечном Выражении. Основная задача Переменной Формул - это сократить длину и упростить понимание Конечного Выражения, а также упростить изменение единообразных формул используемых в разных местах бота.
● Значение по умолчанию: Отсутствует.
● Тип данных: текстовые
Переменная Формул, технически - это Глобальная Переменная.
Записывать в неё можно:
• Текст
• Числа
• Знаки математических операций
• Макросы
ОСНОВНОЙ ОСОБЕННОСТЬЮ этой переменной является то, что все необходимые значения (например значения Макросов) в ней подготавливаются заранее - формируя готовую Формулу, ДО того как текст самой Переменной будет подставлен в Конечное Выражение.
Технически, в Конечное Выражение, обработанное значение Переменной Формул подставляется ПЕРВЫМ - ДО всех остальных подстановок и обработок. Поэтому оно может содержать в себе разные Макросы и нужные вам части Конечного Выражения, которые (ПОСЛЕ подстановки в формуле) будут размещены и окончательно обработаны в Конечном Выражении. Это позволяет убедиться в том что все необходимые значения будут подставлены и обработаны - тогда как при использовании обычной Глобальной Переменной возможны ошибки.
ВАЖНО: Переменная формул - НЕ является Выражением в полном смысле, а скорее является его частью - {Фигурные Скобки} в ней ЗАПРЕЩЕНЫ. Использовать ее кроме как часть другого Выражения - не имеет смысла.
НАПРИМЕР:
Переменная: var со значением %rate% * 1.2
Переменная invest со значением 5
Выражение: {%invest% * %var%}
Если переменная var - это Переменная Формул, то Выражение ПЕРЕД разбором примет вид: {%invest% * %rate% * 1.2} - то есть её значение будет подставлено заранее - до подстановки значений основных Макросов самого выражения. В случае Обычной Глобальной мы бы получили {5 * %rate% * 1.2} и ошибку разбора выражения.
Особенности переменных
Ниже приведён общий для всех переменных список возможностей. У каждого вида переменных есть свои особенности - по этой причине какие-либо из возможности могут отсутствовать, в том или ином случае...
● Данные в переменных могут быть индивидуальными для каждого юзера, а так же глобальными - общими для всех.
● Данные в переменной могут изменяться: Только Админом, Админом и Юзером вместе, Кнопками по нажатию или прямым вводом данных через Формы.
● Каждая переменная имеет Имя для обращения к её данным.
● Каждая переменная имеет макрос для вывода ее значения (юзеру или админу, использования в Выражениях и Условиях), основанный на ее имени.
● Каждая переменная может находится в двух состояниях: Инициализирована и НЕ инициализирована.
● Каждая новая переменная является НЕ инициализированной - не содержит и не содержала значения - показывает свое значение по умолчанию.
● Переменная инициализируется присвоением значения или Action-ом инициализации.
● Вернуть инициализированную переменную в её изначальное (НЕ инициализированное) состояние можно только тремя способами: 1. Удалить через редактор переменных или командой /vardel. 2. Очистить командой /varclearall. 3. Использовать Action Очистки. Если инициализированной переменной присвоить значение по умолчанию - это НЕ сделает её снова НЕ инициализированной.
● В функциях где требуется указать какую-либо переменную, в списке будут присутствовать только переменные с которыми данная функция может работать (то есть возможно не все имеющиеся).
● В списках переменные отсортированы по алфавиту (по этому задавая одинаковые префиксы отдельные переменные можно "держать" в нужных частях списка).
● В списках сначала идут отсортированные Индивидуальные переменные, а потом отсортированные Глобальные.
❖ Управление переменными
Для управления переменными существует несколько способов.
1. Команды Админа
2. Ввод пользователем
3. Редактор Переменных
4. Кнопки и Action-ы
Использование Команд для работы с переменными
К переменным подключён модуль ручного управления значениями, принимающий составные команды.
В общем случае, команда имеет такой вид:/command var_name user_id value
Для ЦИФРОВЫХ переменных, в команде после значения можно добавить комментарий. Юзер получит текст комментария вместе с сообщением об изменении переменной - в независимости от настроек самого оповещения.
В общем случае, команда с комментарием имеет такой вид:/command var_name user_id value comment
Комментарий должен обязательно начинаться в той же строке что и сама команда - внутри комментария допустим перенос строк.
Где:/ (Slash, Слеш) - любая команда начинается со знака "/". command - это сама команда.var_name - имя переменной.user_id - Telegram ID или UserCode пользователя бота.value или delta - это значение которое нужно использовать.comment - текст комментария.
Все аргументы составной команды, должны идти через ПРОБЕЛ (а не с новой строки).
Пример 1 (без переноса строк):/varadd balance 888888 1 текст
Пример 2 (с переносом строк):/varset balance 888888 0 текст1текст2
Комментарий можно добавлять и в редакторе переменных. Подробнее смотри в руководстве по балансу и редактору переменных.
Команды работают без подтверждения и их действие необратимо.
Пакет команд для индивидуальной обработки переменных
ЗАПРОСИТЬ значение переменной. Бот просто пришлёт значение переменной. Никаких изменений внесено не будет.
УСТАНОВИТЬ значение переменной. Бот перезапишет старое значение в переменной в не зависимости от состояния.
ДОБАВИТЬ значение к переменной (чтобы вычесть - используйте отрицательное число). Бот прибавит указанное в команде значение к существующему в переменной.
Работает только с Числовыми переменными.
УДАЛИТЬ значение переменной указанному юзеру. Удалит любое имеющееся значение в переменной приведя ее в исходное состояние для одного юзера.
Данная команда делает переменную снова НЕинициализированной. Подробнее об инициализации в руководстве по "Action-у инициализации".
ОБЩАЯ СУММА данных переменной у всех юзеров бота.
Работает только с Числовыми переменными.
Пакет команд для массовой обработки переменных:
ОЧИСТИТЬ ДАННЫЕ этой переменной у ВСЕХ юзеров.
Данная команда делает переменную снова НЕинициализированной. Подробнее об инициализации в руководстве по "Action-у инициализации".
ВАЖНО: Будьте внимательны действие не обратимо и срабатывает без подтверждения.
СКОЛЬКО ВСЕГО ЗНАЧЕНИЙ в данной переменной (у скольких юзеров переменная инициализирована).
ПРИБАВЛЯЕТ "value" КО ВСЕМ ЗНАЧЕНИЯМ ВСЕХ юзеров, у кого эта переменная инициализирована (для вычитания используйте отрицательное значение в качестве value).
Команда /varaddall потребляет "Токены Функций". Количество потребляемых токенов равно количеству значений, которые будут изменены. Для того, чтобы количество списанных токенов не стало сюрпризом - количество значений перед этим можно (и нужно) узнать командой /varcountall. Она, в первую очередь, для этого и нужна.
УМНОЖАЕТ ВСЕ ЗНАЧЕНИЯ ВСЕХ юзеров, у кого эта переменная инициализирована, на "value".
Команда /varmultall потребляет "Токены Функций". Количество потребляемых токенов равно количеству значений, которые будут изменены. Для того, чтобы количество списанных токенов не стало сюрпризом - количество значений перед этим можно (и нужно) узнать командой /varcountall. Она, в первую очередь, для этого и нужна.
Массовые изменения НЕ фиксируются в логах изменения переменных.
Для тех, кто не в математику: для прибавления процента используйте /varmultall, а value считайте так:
1 + процент/100.
Например, добавить 10% к балансу:/varmultall balance 1.1
ЕЩЁ РАЗ: ВСЕ команды пакета работают ТОЛЬКО С ТЕМИ ЮЗЕРАМИ, У КОГО ЭТА ПЕРЕМЕННАЯ ИНИЦИАЛИЗИРОВАНА. Если у вас тысяча юзеров, а баланс инициализирован у трех из них - сработает для этих трех.
ЕЩЁ РАЗ: НЕТ, с помощью этих коман НЕЛЬЗЯ присвоить ВСЕМ юзерам какое-то значение. До тех пор, пока переменная у них не будет инициализирована.
Пример команды:
• Имя текстовой переменной - rank
• ID (UserCode) юзера - 111222333
• Данные переменной - "Любой текст"
Команда /varsetбудет выглядеть так:/varset rank 111222333 Любой текст
Каждый параметр в команде должен идти через ПРОБЕЛ, в ОДНУ СТРОКУ, а не с новой строки.
Пользователь задаёт значение
Можно позволить юзеру самому задавать значение отдельной переменной. Другими словами: принимать данные от пользователя и сохранять их в переменной. Например для ввода адреса своего крипто-кошелька, адреса eMail или других личных данных.
Работает это как и Вопрос в QnA чат, только ответ юзера поступает сразу в переменную, а не админу.
Создание ввода переменной осуществляется через:☞ 📝 Редактор Постов > Добавить Ввод Переменной
Кнопка добавления появится только при наличии хотя бы одной переменной, кроме "balance".
Подробнее в руководстве по "Формам Обратной Связи".
Изменение значения цифровой переменной при помощи Редактора.
Значение любой ЦИФРОВОЙ переменной можно менять при помощи редактора идентичного редактору Баланса. Данный редактор можно назначить любой кнопке в любом месте меню.
Подробнее о создании редактора переменных.
Изменение значений при помощи Кнопок и Action-ов
Кнопки Бонус и Обнен.
Для подключения перейдите в вашем боте:☞ 🔐Админ | 🧩Расширения | 📂Кнопки
Action-ы.
Для подключения перейдите в вашем боте:☞ 🔐Админ | 🧩Расширения | 📂Action-ы
Кнопка Бонус
Позволяет начислять юзерам бонус (указанное админом количество условных единиц) на выбранную переменную (например Баланс). Особенностью данной кнопки является то что Админ может задавать Период для получения бонуса юзером (время между бонусами если желаете). То есть ту частоту с которой Юзер может получать Бонус нажимая на кнопку. Переменная для начисления, Сумма и Частота (в часах - целыми или дробными числами) указывается админом при создании самой кнопки. Все параметры могут задаваться Макросами.
Кнопка Бонус может изменить ОДНУ переменную за одно нажатие.
Кнопка Фикс. Обмен 1
Позволяет юзерам осуществлять обмен фиксированной суммы в условных единицах внутри бота, переводя заранее заданную админом сумму с одной переменной на другую. Кнопка ОТНИМАЕТ заданную сумму от одной переменной и ДОБАВЛЯЕТ в другую - тем самым осуществляя обмен средств. Все параметры могут задаваться Макросами.
Кнопка "Фикс. Обмен 1" изменяет ДВЕ переменные за одно нажатие.
Данная кнопка может использоваться и не по прямому значению. Например, не смотря на то что одно из чисел всегда отниматься, можно добавить два числа в разные переменные. Если отнять отрицательное число, то фактически оно будет прибавлено. На этом можно строить разные механики.
Кнопка Курс Обмен 2
Позволяют юзерам осуществлять обмен суммы по курсу в условных единицах внутри бота, переводя сумму с одной переменной на другую с учетом курса обмена указанного Админом. Кнопка ОТНИМАЕТ заданную сумму от одной переменной и после вычисления ДОБАВЛЯЕТ в другую - тем самым осуществляя обмен средств. Для вычислений используется указанный курс обмена который тоже может браться из переменной (курс обмена может обновляться автоматически (при помощи авто обновляемых курсов валют - смотри ниже) и модифицироваться при помощи Выражений). Все параметры могут задаваться Макросами.
Кнопка "Курс Обмен 2" изменяет ДВЕ переменные за одно нажатие.
Курсы валют.
Для подключения перейдите в вашем боте:
☞ 🔐Админ | 🧩Расширения | 📂Логи и Данные
Action-ы и переменные
Action (Действие — англ.) в @MenuBuilderBot — это способ выполнить одно действие. Один Action – одно действие. Действия могут быть разными — изменить значение переменной, проверить условие, отправить процент рефералу и т.п. Action-ы в кнопках можно комбинировать создавая уникальные алгоритмы и последовательности действий, получая тем самым нужный функционал. Руководство по Action-ам объёмно, но оно того стоит.
Кнопка с Action-ам не имеет ограничений в применении и за одно нажатие может изменять столько переменных сколько нужно.
❖ Переменные в выражениях и условиях
Значения переменных при помощи макросов можно использовать в вычислениях подставляя их в выражения, а так же в условиях кнопок и Action-ов. Подробные описания каждого из случаев по ссылкам в тексте. Выражения могут использоваться как в сообщениях бота, так и в функциях кнопок.
Напоминаем что имена переменных являются регистрозависимыми. То есть переменные с именами "Var" и "var" - это две разные переменные.
❖ Работа со значениями переменных
Вывод значений юзеру
Для того чтобы показать юзеру значение его переменной достаточно в нужном сообщении вставить макрос с именем переменной. Макрос это имя переменной окруженное знаками "%".
Например макрос %wallet%
Покажет значение переменной «wallet».
В тексте одной переменной можно использовать макросы других переменных.
Экспорт значений переменных
Данные переменных можно экспортировать в .csv файл. Для экспорта нужно чтобы у юзера были рефералы, баланс либо ещё что-нибудь - бонусы например.
Подробнее об условиях и работе с функцией в руководстве по экспорту.
ВАЖНО: Данные тех кто просто зашёл посмотреть и понажимать кнопки меню - экспортироваться не будут.
ВНИМАНИЕ: один экспортированный файл будет содержать ВСЕ доступные данные ВСЕХ доступных пользователей.
ЗА ИСКЛЮЧЕНИЕМ ТЕХ ЧТО УКАЗАНЫ ВЫШЕ!!!!!!!!!!!!!
Экспорт данных юзеров.
Для подключения перейдите в вашем боте:
☞ 🔐Админ | 🧩Расширения | 📂Логи и ДанныеЭкспорт подключается на 1 бот.
Пример файла экспорта в нашем новостном канале:
https://t.me/MenuBuilderNews/294
Лог транзакций Баланса
В целях повышения безопасности и устойчивости данных в системе начислений и для решения спорных вопросов по балансам переменных в боте, существует возможность логировать каждую транзакцию, в файл, последовательно записывая все транзакции для переменной balance в таблицу.
Подробности и условия подключения смотрите в своем боте
Лог баланса.
Для подключения перейдите в вашем боте:
☞ 🔐Админ | 🧩Расширения | 📂Логи и ДанныеЛогирование подключается на 1 бот.
Пример файла экспорта Лога в нашем новостном канале:
https://t.me/MenuBuilderNews/295
Данные Реф. Родителя для Медиа переменной
Медиа переменная может брать данные Реф. Родителя для показа рефералу. Например если вам нужно показать рефералу фотографию его реферального родителя добавленную им самим свой профиль. Данная возможность требует активации расширения.
Данные Реф. Родителя
Для подключения перейдите в вашем боте:
☞ 🔐Админ | 🧩Расширения | 📂Логи и Данные
ТОП по переменной
Существует возможность создавать ТОП по данным в переменных. Например ТОП по сумме на Балансе юзера. Размер ТОПа и частота его обновления может задаваться при помощи плагинов.
39. Базовый ТОП по Переменной
Для подключения перейдите в вашем боте:☞ 🔐Админ | 🧩Расширения | 📂Переменные