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

Версия 15:53, 22 августа 2014

Шаблонизатор 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-код для выделения текста полужирным. Пример:
  • SELECT <@_bold>name</@_bold> FROM myTable -> (в MySQL) SELECT CONCAT( '<b>',name,'</b>' ) FROM myTable
• <@_italic>SQL</@_italic>: добавить SQL-код для выделения текста курсивом.Пример:
  • SELECT <@_bold><@_italic>name</@></@> FROM myTable -> (в MySQL) SELECT CONCAT( '<b>',CONCAT( '<i>',name,'</i>' ),'</b>' ) FROM myTable
• <@_align 'side'>SQL</@_align>: добавить SQL-код для выравнивания текста. Параметр '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.

Совет: если макрос допускает вложенные элементы (например, <@_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)

• <@_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' />
• <@_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</@>