⟵ сюдатуда ⟶
  • Установка
  • Установка на NetAngels.ru
  • Установка на Ubuntu
  • Установка с Docker
  • Обновления
  • Бэкапы
  • Multi/no-multi
  • Консольная утилита bin/totum
  • Основы для пользователей
  • Интерфейс и компоновка
  • Таблицы и их параметры
  • Префильтр
  • Поля и их параметры
  • Синтаксис
  • Общие положения
  • Места применения кода
  • Возврат результата работы кода
  • Обращения
  • Варианты обращения к значениям
  • Обращение к значениям строк внутри кода
  • Обращение к значениям полей
  • Обращение к предыдущему значению
  • Обращение к отображению для Селектов
  • Получение значений зафиксированных полей
  • Определить кодом name поля
  • Уровень вложенности для Селект-дерева
  • Сокращенное обращение
  • Обращение к элементу списка
  • Обращение к секции (колонке) списка
  • Функции
  • Вызов функции в коде
  • Автозаполнение функций
  • Хоткеи
  • Переменные
  • Переменные внутри кода
  • Глобальные и процессные переменные
  • Глобальные переменные
  • Процессные переменные
  • Передача переменных в строку кода
  • Порядок вычисления
  • Порядок вычисления строк кода
  • Порядок математических операций в строке
  • MATH — математический порядок
  • Типы
  • Типы данных
  • Типы хранения данных
  • Операторы
  • Операторы сравнения
  • Математические операторы
  • Разное
  • Логическая конструкция cond
  • Конкатенация строк
  • Текстовое включение в код
  • Код, действия, форматирование
  • Реляционные взаимосвязи
  • Порядок расчета и единицы пересчета
  • Сравнения
  • Функции
  • Отладка
  • Автозаполнение расчетных и временных
  • Дублирование строк и циклов
  • Деревья
  • Печать и CSV
  • API
  • Роли и пользователи
  • Нотификации
  • Действия по расписанию
  • Анонимные таблицы
  • Внешние формы
  • Экспорт и импорт таблиц
  • Системные таблицы
  • Подключение функций
  • Дополнительные интерфейсы
  • Структура файлов
  • Структура базы
  • Синтаксис

    Общие положения

    Места применения кода

    Код применяется для вычисления значений полей, для выполнения действий и для определения форматирования полей, строк и таблицы.

    Также коды используются при дублировании строк и вызове панелей в селектах.

    Код может храниться как текст в поле и быть вызван при исполнении другого кода с передачей ему необходимых параметров функцией exec.

    Возврат результата работы кода

    Код обрабатывается построчно, значение возвращается из строки начинающейся с = : независимо от ее расположения.

    = : 10 + 10
    
    // Результат: 20
    

    Обращения

    Варианты обращения к значениям

    • $ — строка кода.

    • # — значение ячейки.

    • $# — переменная внутри кода.

    • #$ — значение ячейки, определенной кодом.

    • $$ — вызывает строку кода, которую определил другой код. Изящный способ ветвления!

    • @ — обращение к нестрочным полям в других таблицах.

    Обращение к значениям строк внутри кода

    Обращение к значению строки кода осуществляется через $codename.

    Именование строки осуществляется как codename:. Имена строк регистрозависимы и могут состоять из латинских букв, цифр и нижнего подчеркивания.

    Для визуального обозначения порядка вызова строк кода или иерархичности можно использовать табуляции. Так же поддерживаются однострочные комментарии начинающиеся с //.

    = : $code1 + $code2
        // Комментарий
        code1: 10
        code2: 10
    
    // Результат: 20
    

    Обращение к значениям полей

    Обращение к значению поля текущей таблицы осуществляется через #fieldname. Значение полей берется в момент начала выполнения кода.

    Обращение к полям в другой таблице осуществляется через функции вида select.

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

    Обращение к предыдущему значению

    При выполнении изменений в поле возможно обращение к предыдущему значению через #old.fieldname. Это работает в кодах и кодах действия.

    • В момент создания строки или таблицы #old.fieldname равен пустоте.

    Предыдущее значение — это то значение, с которым поле вошло в текущий цикл пересчета в соответствии с единицей пересчета.

    Обращение к отображению для Селектов

    Обращение к отображаемому значению, а не к основанию поля для селекта и селект-дерева осуществляется через #s.fieldname.

    Получение значений зафиксированных полей

    Возможно получить признак фиксирования значения для полей с кодамиtrue или false используя #h.fieldname.

    Для зафиксированных полей можно получить расчетное значение через #c.fieldname.

    Определить кодом name поля

    Возможно обращение к полю, определенному строкой кода при помощи #$whatfield. Таким образом значение в строке whatfield: будет определять name поля из которого брать данные.

    Уровень вложенности для Селект-дерева

    Обращение #l.name_field может быть использовано для любого поля селект-дерево — возвращает уровень вложенности значения в поле.

    Подробнее про tree-view ⟶

    id fieldname1 fieldname2
    1 10 (C=5) [HAND] 15
    example1: #fieldname1 + #fieldname2
    
    // Результат: 25
    
    example2: #h.fieldname1
    
    // Результат: true
    
    example3: #c.fieldname1
    
    // Результат: 5
    
    example4: #$whatfield
    
        whatfield: "fieldname2"
    
    // Результат: 10
    

    Сокращенное обращение

    Для обращения к нестрочным полям в другой таблице используется сокращенное обращение @tablename.header_or_footer_fieldname.

    @ — это короткое написание селекта. @ не будет взята при начале выполнения кода как #field_name, а будет взята в порядке своей очереди.

    Если обращение идет к строчной части таблицы, то используется такие записи:

    • @table.field[#value] аналогично:

      =: select(table: 'table'; field: 'field'; where: 'id' = #value)
      
      
    • @table.field[[#value]] аналогично:

      =: selectList(table: 'table'; field: 'field'; where: 'id' = #value)
      
      
    • @table.field.where[#value] аналогично:

      =: select(table: 'table'; field: 'field'; where: 'where' = #value)
      
      
    • @table.field.where[[#value]] аналогично:

      =: selectList(table: 'table'; field: 'field'; where: 'where' = #value)
      
      

    Такие обращения могут быть использованы внутри функций:


    =:
    select(table: 'table'; cycle: @cycles.id.status[#status]; field: 'field')

    Обращение к элементу списка

    Обращение $list[1], #listfieldname[1], $list[$#iterator] или $list[$codename] вернет значение элемента списка аналогично функции listitem.

    Номер или ключ элемента списка внутри квадратных скобок могут быть обозначены всеми возможными способами.

    Если элемента с запрошенным ключом не окажется - выражение вернет null.

    Если структура, к которой вы обращаетесь содержит технические символы или символы вне латинского алфавита, то путь внутри скобок должен быть заключен в кавычки!

    $list["Представление"], #listfieldname["Ссылка"], $list["date.settings"] или $list["so$iska"]

    // Через функцию:
    example1: listitem(list: $list1; item: 1)
    
    list1: listcreate(item: "A"; item: "B"; item: "C") 
    
    // Результат: "B"
    
    // Через быстрый вызов:
    example2: $list2[1]
    
    list2: listcreate(item: "A"; item: "B"; item: "C") 
    
    //Результат: "B"
    

    Подобным образом можно обратиться к вложенным элементам на произвольной глубине:

    id fieldname3
    1 ["b", "c"]
    example3: strAdd(str: $code3_1[0]; str: #fieldname3[1]; str: $code3_2[test])
    
     code3_1: listCreate(item: "a"; item: "b")
     code3_2: rowCreate(field: "test" = "z")
    
    // Результат: "acz"
    
    example4: $code4[0][test]
    
     code4: listCreate(item: $row4)
        row4: rowCreate(field: "test" = "abc")
    
    //Результат: "abc"
    

    Обращение к секции (колонке) списка

    Похожим образом работает обращение к секции. Если вам необходимо получить список по ключу из списка ассоциированных массивов, то помимо функции listSection можно использовать синтаксическую запись $row[[key]], #rowfieldname[[key]], $row[[$#key]] или $row[[$key]].

    example5: $listList[[1]]
        listList: listCreate(item: $l1; item: $l2)
            l1: listCreate(item: 1; item: 2; item: 3)
            l2: listCreate(item: 4; item: 5; item: 6)
    
    // Результат: [2,5]
    

    Функции

    Вызов функции в коде

    Скобки являются признаком функции.

    Параметры функций могут определяться в любом порядке. В ряде случаев порядок параметров внутри функции определяет возвращаемый ей результат.

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

    ВСЕ ПАРАМЕТРЫ ФУНКЦИИ ДОЛЖНЫ БЫТЬ ЗАПОЛНЕНЫ. ЕСЛИ ПАРАМЕТР НЕ ИСПОЛЬЗОВАН — ОН ДОЛЖЕН БЫТЬ УДАЛЕН!

    tablename

    id fieldname1 fieldname2
    1 10 10

    example1: select(table: 'tablename'; field: 'fieldname1'; where: 'id' = 1)
    
    // Результат: 10
    
    • Желтым — обозначены name-параметры в которые передаются name полей или таблиц (в зависимости от параметра). Name может быть передан любым способом. Если он указывается вручную, то при наборе в одинарных кавычках '' будет срабатывать механизм поиска name в текущей схеме базы данных.

    • Жирным — обозначены обязательные параметры функции.

    • Подчеркнутым — обозначены множественные параметры, которые могут быть указаны в вызове функции несколько раз. Порядок вызова важен, так-как выборки и сортировки будут применены именно в том порядке, в котором они будут указаны в вызове функции.

    ФУНКЦИЯ НЕ МОЖЕТ БЫТЬ ВЫЗВАНА ВНУТРИ ДРУГОЙ ФУНКЦИИ — ЭТО ДЕЛАЕТСЯ ЧЕРЕЗ ОТДЕЛЬНУЮ СТРОКУ!

    example2: select(table: 'tablename'; field: 'fieldname1'; where: 'price' = $what_id)
    
        what_id: round(num: #price; type: "up"; step: 1; dectimal: 0)
    
    // Результат: 10
    

    Автозаполнение функций

    • При наборе функции осуществляется ее поиск в базе функций.

    • При постановке скобки ( или ) после названия функции она автоматически заполняется.

    • При постановке ; и начале ввода следующего параметра осуществляется поиск доступных параметров.

    • При наборе названий в одинарных кавычках '' осуществляется поиск поля в таблице источнике.

    • При постановке вместо открывающей скобки / или ; осуществляется поиск параметра. Последующий параметр также ищется через / или ;. В конце набора при постановке скобки ( или ) синтаксис автоматически заменяется на валидный.

    Хоткеи

    • TAB — переводит на следующий парамет функции.

    • SHIFT + TAB — если курсор стоит перед закрывающей ; то будет выделен следующий параметр до закрывающей ;.

    • SHIFT + TAB — если курсор стоит в любом другом месте параметра, то будет выделен текущий параметр включая ;.

    • Для mac аналогичным хоткеем является OPT+TAB.

    Переменные

    Переменные внутри кода

    Такие переменные существуют только при выполнении конкретного кода внутри одной итерации вычисления.

    Эти переменные могут определятся некоторыми функциями, например var или while.

    Для обращения к ним используется $#paramname.

    Существует список зарезервированных переменных, возвращающих определенные значения:

    • $#ntn — возвращает name текущей таблицы.

    • $#nci — возвращает номер текущего цикла.

    • $#nth — возвращает hash текущей таблицы. (только для временных таблиц).

    • $#lc — возвращает пустой список.

    • $#nd — возвращает текущую дату в Y-m-d.

      example2: dateAdd(date: $#nd; days: 10; format: "Y-m-d")
      
      // Результат: "2019-08-10"
      
    • $#ndt — возвращает текущую дату в Y-m-d H:i.

    • $#ndts — возвращает текущее время с секундами Y-m-d H:i:s.

    • $#nu - возвращает id текущего пользователя.

    • $#nr — возвращает список id ролей текущего пользователя.

    • $#nfv — возвращает значение текущего поля (неприменимо в секции код).

    • $#onfv — возвращает предыдущее значение текущего поля.

    • $#ids — возвращает список id строк, выбранных галочками (доступна только в коде-действия Кнопок).

    • $#nh — возвращает текущий хост.

    • $#nf — возвращает name текущего поля.

    • $#nti — возвращает id текущей таблицы.

    • $#nl — возвращает специальный символ переноса строки.

    • $#duplicatedId — возвращает id строки, с которой было осуществлено дублирование (только для секции КОД при добавлении во вставляемой строке при дублировании). В противном случае возвращает 0.

    • $#ih — доступна только в строке добавлния. Позволяет передать хэш строки добавления во временную таблицу и потом из нее вернуть данные в поле строки добавления используя параметр hash функции set. Или выполнить set в поле строки добавления без вызова временной таблицы. Используется в строке добавления совместно с параметром поля buttonActiveOnInsert.

    • $#rows — доступна только в коде форматирования и в коде графиков — возвращает rowlist с содержимым строк, отображаемых на странице.

    • $#changes — переменная доступная только в коде-действия таблицы. Информация об изменившихся полях в таблице в виде row:

      • deletedid удаленных строк.
      • restoredid восстановленных строк.
      • addedid добавленных строк.
      • changedrow ключами которого являются id измененных строк, а значениями список из name полей измененных в строке.
      • reorderedIdsid строк с измененным порядком по n.

      Пример получения списка id строк, в которых произошло изменение в поле field_1:

      =: rowKeys(row: $listf)
              listf: listFilter(list: $#changes[changed]; key: "value" = "field_1")
      
    • $#kanban — доступна только в panel-view в режиме канбан при выполнении h_kanban_html_code.

    • Переменные в коде могут создаваться функциями:

    example1: while(action: $set; limit: 10)
        set: var(name: "count"; value: $plus; default: 0)
            plus: $#count + 1
    
    // Результат: 10
    

    Глобальные и процессные переменные

    Глобальные переменные

    Глобальная переменная может быть записана функцией globVar.

    Доступна из любого кода.

    Вызывается — @$name_glob_var

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

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

    Что бы этого избежать при запросе значения устанавливается блокировка, которая снимается по истечении указанного времени, либо при записи переменной или запросе ее значения с передачей block: false.

    Блокировка на чтение работает только для запросов, устанавливающих или снимающих блокировку чрез параметр block. При получении переменной @$name_glob_var ее значение будет возвращено сразу.

    Переменная записывается сразу вне транзакционной модели!

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

    Рекомендуется использовать вместе с tryCatch — в этом случае в catch записывается обнуление переменной или установку ее в стартовое значение, которое произойдет если транзакция будет отменена.

    Процессные переменные

    Процессная переменная может быть записана функцией procVar.

    Доступна из любого кода.

    Вызывается — $@name_proc_var.

    Существует только в рамках одного процесса php.

    Передача переменных в строку кода

    Используя конструкцию $codename{var: "varname" = value} можно передать значение value переменной varname в строку codename и дальше.

    varname тоже может быть задан кодом.

    example1: strAdd(str: $code1{var: "fruit" = "apple"}; str: " and "; str: $code1{var: "fruit" = "banana"})
        code1: strAdd(str: "green "; str: $#fruit)
    
    // Результат: "green apple and green banana"
    

    Таким образом можно обрабатывать элементы массива:

    example2: $split{var: "fruits" = $code2}
    
     split: if(condition: $#fruits != $#lc; then: $str1; else: "")
        str1: strAdd(str: $#fruits[0]; str: ", "; str: $split{var: "fruits" = $fruitsCut})
            fruitsCut: listCut(list: $#fruits; cut: "first"; num: 1)
    
    code2: listCreate(item: "apple"; item: "banana"; item: "lemon")
    
    // Результат: "apple, banana, lemon, "
    // Данный пример приведен здесь как пример, эта конкретная операция выполняется функцией listJoin().
    

    Порядок вычисления

    Порядок вычисления строк кода

    Вычисление осуществляется от секции = : в порядке каскадного обращения к значениям других строк слева направо.

    Если к одной строке идет несколько обращений она будет рассчитана столько раз, сколько к ней обратились.

    1.| = : $code1 + $code2 + $code2
    
    2.| code1: 10 / 2
    3.| code2: 10 * 2
    
    // Результат: 45
    // Количество раз вычислений:
    // Строка 1 — 1 раз
    // Строка 2 — 1 раз
    // Строка 3 — 2 раза
    

    При стандартном обращении к значению строки кода codename: оно рассчитывается при каждом обращении.

    Для того, что бы рассчитать значение один раз и сократить требуемые на расчет ресурсы процессора необходимо использовать ~codename:.

    tablename h_fieldname = 1

    example2: while(action: $set2; limit: 10)
    set2: var(name: "count"; value: $plus2; default: 0)
    plus2: $#count + $step2
    ~step2: select(table: 'tablename'; field: 'h_fieldname')
    
    // Результат 10
    // Строка step2: будет вычислена только один раз при первом обращении.
    // При отсутствии ~ перед step2: select() будет выполнен 10 раз.
    

    На обращениях к значениям полей #fieldname можно не экономить, они самые быстрые.

    Будьте внимательны при использовании ~ в циклических вычислениях так-как можно по ошибке зафиксировать результат вычисления первого цикла.

    Порядок математических операций в строке

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

    ВНИМАНИЕ: по умолчанию порядок выполнения отличается от принятой математической записи! Скобки для математических операций не используются, так как являются признаком функций.

    example1: 10 + 10 / 2
    
    // Результат: 10
    
    // Код для реализации математической записи (32 + 10) / 2 = 21 будет выглядеть так:
    
    example2: $sum / 2
        sum: 32 + 10
    
    // Результат: 21
    

    MATH — математический порядок

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


    example3:
    math`$A3 + $B3 / 2` A3: 10 B3: 10 // Результат: 15

    math можно использовать и внутри функций:


    example4:
    if(condition: math`$A4 + $B4 / 2` = 15; then: true; else: false) A4: 10 B4: 10 // Результат: true

    MATH обрабатывает скобки как часть математической формулы:

    example5: math`2 / ($A5 + $B5)`
    
    A5: 10
    B5: 10
    
    // Результат: 0.1
    

    Типы

    Типы данных

    • 5 — целое число или десятичная дробь. Знаком десятичного деления в кодах является . (точка). При вводе, в поле можно использовать , — при сохранении запятая будет преобразована в точку.

    • "str" — utf-8 строковое значение, желательно не рассчитывать на большие значения, так-как полностью передается в веб-интерфейс. При заполнении через интерфейс не содержит переводов строки.

    • true, false — булевы значения.

    • 'name' — name-параметр. Аналогичен строке, используется в коде с одинарными кавычками, на которые срабатывают подсказки автоматического заполнения.

    • "" — пустая строка или пустота.

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

    • [] — пустой список. Является результатом работы функций, некоторых полей и быстрой переменной $#lc.

    Типы хранения данных

    • Одно значение — самый простой тип хранения.

      • Например:

        "mouse" или 5 или true или false
        
    • Список значений — упорядоченный список значений с числовыми ключами.

      • Таблица в одну колонку и несколько строк, у каждой строки номер.
      • Ключи идут от 0 с шагом в 1.
      • Например

        [1,2,3,4,5]
        
    • Ассоциированный массив — объект вида ключи-значения.

      • Одна строка из таблицы с несколькими колонками.
      • Например:

        {"data":"Строковые интервалы","type":"Тип","version":"Версия 1"}
        
    • Список ассоциированных списков — список объектов вида ключ-значение.

      • Таблица с несколькими строками и несколькими колонками.
      • Строки нумеруются от 0 с шагом в 1.
      • Колонки обозначаются буквенно-числовыми ключами.
      • Например:

        [{"data":null,"type":"Расчетная в дереве"},{"data": null,"type": "Расчетная в цикле"}]
        

    Операторы

    Операторы сравнения

    По результатам сравнений есть отдельный раздел документации!

    Математические операторы

    • + — сложение.

    • - — вычитание.

    • * — умножение.

    • / — деление.

    • ^ — степень.

    Разное

    Логическая конструкция cond

    cond: cond`($A=1 && $B=1) || ($A=2 && $B=2)`
    A: "..."
    B: "..."
    

    Возвращает true или false.

    • && — и.

    • || — или.

    Скобки — группировка. Пример выше читается как: «Если A=1 и B=1 или A=2 и B=2 тогда true».

    Может быть использована внутри функций:

    cond_2: if(condition: cond`$line_1 != 0 || $line_2 != 0`; then: 100; else: 0)
    
    line_1: 10
    line_2: 0
    
    // Результат = 100.
    

    Конкатенация строк

    Конкатенация выполняется функцией strAdd или сахаром str:

    str: str`"#" + $#nfv ++ "—" ++ #field`
    
    // Результат: #34 — закрыт
    
    
    • + — склеивает без пробела.
    • ++ — склеивает добавляя пробел.

    Текстовое включение в код

    Если вам нужно включить в код часть текста с переносами строк, то это можно сделать таким образом:

    =: $text_in_code
    
    ```text_in_code:text
    Some text in this section.
    
    With automatic lines separators.
    ```
    
    

    Если вы хотите, что бы эта секция была подсвечена как totum-код то надо указать так:

    =: $code
    
    ```code:totum
    =: set(table: 'table_name'; field: 'field_name' = $some_value)
    
    some_value: 10
    ```
    
    

    Переменные внутри этого блока кода и названия строк не будут пересекаться с переменными и строками в хостовом коде.