Макросы — различия между версиями

Текущая версия на 17:23, 19 ноября 2015

Шаблонизатор Freemarker поддерживает макросы или пользовательские директивы. Вы можете создавать свои макросы как непосредственно в месте использования (custom step или в коде представления), так и в отдельном файле macro.ftl (тогда они будут видны во всём проекте).

Имеется также набор предопределённых макросов, которые позволяют выполнить стандартный функционал, полезный в разных проектах. Все эти макросы определены в файле be4/src/com/beanexplorer/enterprise/metadata/freemarker/macro/common.ftl. Все предопределённые макросы начинаются с подчерка. Просьба не создавать макросы с подчерка в своих проектах.

Макросы для использования в запросах:

• <@_copyQuery name/>: скопировать текст другого запроса из текущего entity.
• <@_copySelectionQuery/>: скопировать текст запроса *** Selection view *** из текущего entity.
• <@_copyAllRecordsQuery/>: скопировать текст запроса All records из текущего entity.
• <@_str>text</@_str>: превратить текст в SQL-строку (альтернатива суффиксу ?str), удобно использовать для запросов второго уровня.
• <@_bold>SQL</@_bold>: добавить SQL-код для выделения текста полужирным( НО правильнее это делать через CSS! ). Пример:

• SELECT <@_bold>name</@_bold> FROM myTable -> (в MySQL) SELECT CONCAT( '<b>',name,'</b>' ) FROM myTable

• <@_italic>SQL</@_italic>: добавить SQL-код для выделения текста курсивом( НО правильнее это делать через CSS! ).Пример:

• SELECT <@_bold><@_italic>name</@></@> FROM myTable -> (в MySQL) SELECT CONCAT( '<b>',CONCAT( '<i>',name,'</i>' ),'</b>' ) FROM myTable

• <@_align 'side'>SQL</@_align>: добавить SQL-код для выравнивания текста( НО правильнее это делать через CSS! ). Параметр 'side' принимает значения 'left', 'center', 'right', 'justify'
• <@_localize>SQL</@_localize>: добавить SQL-код для локализации текста. Полезно при сочетании с другими макросами, например:

• SELECT <@_bold><@_localize>name</@></@> FROM myTable (в этом случае внутри _localize должен быть самым внутренним макросом)

• <@_substring from [to]>SQL</@>: аналог функции substring. Полезен, если в качестве входной строки подаётся сложное выражение: здесь входная строка задаётся вложенным элементом.
• <@_isInRole 'roles'/>: добавляет условие для проверки обладает ли текущий пользователь хотя бы одной из указанных ролей. Параметры могут включать конкретные роли и группы ролей через запятую, например <@_isInRole '@AllRolesExceptGuest'/>
• <@_contains list column/>: создаёт IN-предложение для списка элементов list и заданной колонки (column IN ('val1', 'val2', ...)).
• <@_selectRow>SQL</@>: добавляет начало и конец SQL-запроса для выбора только одной строки (либо SELECT TOP 1 ..., либо SELECT ... LIMIT 1). Пример:

• <@_selectRow> * FROM myTable</@>

• <@_staticList 'element1' 'element2' ... />: создаёт SQL-предложение, выдающее одну колонку с заданными элементами. Удобно использовать для quick filter. Пример:

• <@_staticList 'waiting' 'running' 'complete'/> -> (в Postgres):

SELECT 'waiting'
UNION
SELECT 'running'
UNION
SELECT 'complete'

• <@_enumList 'columnName'/>: создаёт SQL-предложение, выдающее одну колонку со списком вариантов типа ENUM для колонки columnName, определённой в текущей таблице. Удобно использовать для quick filter.
• <@_sql>SQL</@>: форматирует данный SELECT-запрос с помощью движка BE-SQL в соответствии с текущим движком базы данных. В теле макроса должен присутствовать целый SQL-запрос. Пример: можно написать с помощью FTL-конструкций так:

SELECT c.ID AS "Code",
  ${concat('c.alphabeticCode', ' - '?str, 'CASE WHEN '+length('c.name')+' > 30 THEN '+concat(substring('c.name', 1, 30), '...'?str)+' ELSE c.name END')} AS "Name"
  FROM currencies c

А можно воспользоваться <@_sql>:

<@_sql>SELECT c.ID AS "Code",
  c.alphabeticCode || ' - ' || CASE WHEN LENGTH(c.name) > 30 THEN SUBSTRING(c.name, 1, 30) || '...' ELSE c.name END AS "Name"
  FROM currencies c</@>

Совет: если макрос допускает вложенные элементы (например, <@_bold>), завершать его можно либо </@_bold>, либо просто </@>.

Макросы для использования в кастомизациях

• <@_onLoad 'functionName'/>: .js-кастомизация, добавляющая вызов указанной JS-функции при загрузке страницы.
• <@_loadScript 'fileName.js'>code</@>: загрузить на клиенте указанный js-файл и выполнить указанный код по завершении.

Макросы для использования в ftl-скриптах:

• <@_systemSetting category key value/>: добавить системную настройку. Пример:

• <@_systemSetting 'system' 'FORCED_LOCALE' 'ru' />
• <@_systemSetting category='system' key='FORCED_LOCALE' value='ru' /> — то же самое

• <@_jsHandler code name>JavaScript code</@>: добавить в базу JavaScript-handler. Code — код (машинночитаемое имя), name — человекочитаемое имя, JavaScript code — исходник хэндлера
• <@_isInRole 'roles' 'column'/>: добавляет условие для проверки,

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

• DELETE FROM queries_per_role WHERE <@_isInRole '@DisabledRoles,DbAdmin' 'role_name'/> -> DELETE FROM queries_per_role WHERE ( role_name IN ( 'DbAdmin', 'Dispatcher', 'Guest' )) (группа DisabledRoles содержала роли Dispatcher и Guest)

• <@_insertInto table [idCol]>columns</@>: добавить начало предложения INSERT INTO для таблицы с автоинкрементной колонкой idCol (по умолчанию 'ID'). Columns — список колонок через запятую. Далее должно следовать <@_insertValues> или <@_insertSelect>
• <@_insertValues>values</@>: продолжение INSERT INTO. Values — список значений через запятую (должно быть столько же, сколько колонок в _insertInto. Пример:

• <@_insertInto myTable>col1, col2</@> <@_insertValues>'val1', 'val2'</@> — сгенерирует

INSERT INTO myTable(col1, col2) VALUES ('val1', 'val2'); (в Oracle будет сложнее)

• <@_insertSelect>statement</@>: продолжение INSERT INTO. Statement — SQL-предложение SELECT (без самого слова SELECT). Пример:

• <@_insertInto 'categories'>entity, name, parentID</@>
• <@_insertSelect>'utilitySuppliers', 'Жилищные услуги', ID FROM tmp_cat_table</@>

• <@_noAutoIncrement>insert statements...</@>: выполнить вставку записей в таблицу с явным заданием значения auto-increment. В некоторых СУБД может требоваться включить специальный режим для такой вставки, для чего и служит данный макрос.

Устаревшие макросы

Эти макросы использовались для массового назначения ролей. После появления MassChange их использовать нельзя и они могут исчезнуть.

• <@_operationRoles 'roles' [entities] [names]/>: создаёт SQL для задания ролей операциям. Каждый параметр необязательный,

если отсутствует, означает, любое. Использовать только в Pre-meta для некастомизированных операций! Примеры:

• <@_operationRoles entities=['documents','addresses','socialEvents2documents'] names='Filter'/>
• <@_operationRoles entities='CSPcalls' names=['Insert','Edit'] roles='Passport,ClearingHouse,Reception'/>

• <@_removeOperationRoles 'roles' [entities] [names]/>: создаёт SQL для удаления заданных ролей из заданных операций. Каждый параметр необязательный, если отсутствует, означает, любое. Использовать только в Pre-meta для некастомизированных операций! Примеры:

• <@_removeOperationRoles names=['Explain Plan', 'Parent Record']/>
• <@_removeOperationRoles roles='Accountant' entities='utilityRates' names=['Insert', 'Edit']/>

• <@_queryRoles 'roles' [entities] [names]/>: создаёт SQL для задания ролей представлениям. Каждый параметр необязательный,

если отсутствует, означает, любое. Использовать только в Pre-meta для некастомизированных представлений! Примеры:

• <@_queryRoles entities=['documents','addresses','socialEvents2documents'] names='All records'/>

• <@_removeQueryRoles 'roles' [entities] [names]/>: создаёт SQL для удаления заданных ролей из заданных представлений. Каждый параметр необязательный, если отсутствует, означает, любое. Использовать только в Pre-meta для некастомизированных представлений! Примеры:

• <@_removeQueryRoles entities='messages'/>
• <@_removeQueryRoles entities='_system_' names=['MySQL Variables','MySQL Tables','MySQL Processes'] />
• <@_removeQueryRoles entities=['votes','problems','sharedDocuments'] roles='Manager,Property Manager' />