사용자 정의 코드
개요
ActiveReportsJS는 다양한 표현식 모음을 제공하며, 이를 계산, 숫자 및 날짜 서식 지정, 조건부 서식 적용 등 다양한 작업에 활용할 수 있습니다. 그러나 보고서에 이러한 기본 제공 표현식의 기능을 넘어서는 기능이 필요한 경우가 있을 수 있습니다. 복잡한 수학 연산을 수행하거나, 정교한 조건부 서식을 구현하거나, 보고서 전반에서 동일한 코드를 재사용함으로써 DRY(Don't-Repeat-Yourself) 원칙을 유지해야 할 수 있습니다.
그런 경우 ActiveReportsJS의 사용자 정의 코드 기능을 활용할 수 있습니다.
사용자 정의 코드 만들기
사용자 정의 코드를 보고서에 포함하려면 우선 코드를 작성해야 합니다. 다음 원칙을 준수하는 것이 중요합니다.
코드를 JavaScript 함수로 분해합니다.
각 함수마다 하나의 목적이나 역할을 갖게 합니다.
비동기 함수는 지원되지 않으므로 각 함수는 동기적이어야 합니다.
모든 함수는 순수해야야 합니다. 즉 함수가 출력으로 부작용을 일으키는 일 없이 그 자체의 입력에만 의존해야 합니다.
다음은 그러한 함수의 예시입니다. 숫자 값을 크기에 상대적인 통화 서식으로 변환합니다. 이는 단일 작업을 수행하는 동시적인 퓨어 함수를 나타냅니다.
function formatCurrencyValue(value) {
let currencySymbol = '$';
if (value >= 1000000000) {
return currencySymbol + (value / 1000000000).toFixed(1) + 'B';
} else if (value >= 1000000) {
return currencySymbol + (value / 1000000).toFixed(1) + 'M';
} else if (value >= 1000) {
return currencySymbol + (value / 1000).toFixed(1) + 'K';
} else {
return currencySymbol + value.toFixed(1);
}
}사용자 정의 코드 통합하기
코어 객체의 registerFunctions 메서드를 사용하여 사용자 정의 코드를 응용 프로그램 수준에 등록합니다. 이 메서드는 다양한 사용자 정의 함수 정의를 받아들이며, 각각의 구조는 다음과 같습니다,
{
name: <name to call the function>,
body: <function definition>,
info: {
description: <function description for the expression editor>,
example: <sample function invocation for the expression editor>,
syntax: <function syntax for the expression editor>
}
}정보 객체는 선택 사항이며 보고서 디자이너 컴포넌트 사용자에게 사용자 정의 함수를 공개하고 싶을 때만 사용되어야 합니다. 등록된 함수는 표현식 편집기의 함수 노드에 있는 사용자 정의 코드 섹션에 표시됩니다.
아래는 앞서 다뤘던 formatCurrencyValue 함수에 대한 사용자 정의 함수 정의입니다.
var customCode = [
{
name: 'FormatCurrencyValue',
body: formatCurrencyValue,
info: {
description: 'Format a number to currency in relation to their magnitude',
example: 'Code.numberToWords(Sum(SalesAmount))',
syntax: 'Code.numberToWords(<number>)'
}
}
]함수를 퓨어 JavaScript 응용 프로그램에 등록하는 방법의 전체 예시는 다음과 같습니다.
<script src="https://cdn.mescius.com/activereportsjs/5.latest/dist/ar-js-core.js"></script>
<script>
MESCIUS.ActiveReportsJS.Core.CustomCode.registerFunctions(customCode);
</script> 코드 모듈을 사용하여 빌드된 응용 프로그램의 경우 코드는 다음과 같습니다.
import { Core } from "@mescius/activereportsjs";
Core.CustomCode.registerFunctions(customCode); 독립 실행형 디자이너 응용 프로그램에 사용자 정의 코드 통합하기
독립 실행형 보고서 디자이너 응용 프로그램에서 사용자 정의 코드를 사용하려면 다음의 해당하는 디렉터리에 customCode.json 파일을 생성합니다.
Windows:
%AppData%\ActiveReportsJS Designer\MacOS:
~/Library/Application Support/ActiveReportsJS Designer/Linux Desktop:
~/.config/ActiveReportsJS Designer/
앞서 다뤘던 사용자 정의 코드 정의를 JSON 형식으로 직렬화하고 아래와 같은 함수 객체 내에서 이 customCode.json 파일에 저장합니다.
{
"functions": [
{
"name": "FormatCurrencyValue",
"body": "function(value) {let currencySymbol = '$'; if (value >= 1000000000) {return currencySymbol + (value / 1000000000).toFixed(1) + 'B';} else if (value >= 1000000) {return currencySymbol + (value / 1000000).toFixed(1) + 'M';} else if (value >= 1000) {return currencySymbol + (value / 1000).toFixed(1) + 'K';} else {return currencySymbol + value.toFixed(1);}}",
"info": {
"description": "Format a number to currency in relation to their magnitude",
"example": "Code.numberToWords(Sum(SalesAmount))",
"syntax": "Code.numberToWords(<number>)"
}
}
]
}독립 실행형 디자이너 응용 프로그램에서는 타사 라이브러리가 지원되지 않으므로 그러한 라이브러리를 사용하는 사용자 정의 코드가 작동하지 않습니다.