본문으로 건너뛰기

syn.$p

개요​

syn.$p는 HandStack 화면에서 Reportify 기반 문서 출력과 Excel 템플릿 기반 PDF 생성을 지원하는 인쇄/문서 유틸리티입니다. 현재 syn.js의 syn.$p는 브라우저의 임의 HTML을 직접 PDF로 변환하는 범용 API가 아니라, Reportify API와 Excel 템플릿 작업 항목을 조합해 문서를 생성하는 흐름에 맞춰 설계되어 있습니다.

개발자가 알아야 할 구조​

항목설명
reportifyPathReportify brief API 기본 경로입니다.
reportifyTemplateUrl템플릿 다운로드 API 기본 경로입니다.
pageExportScheme출력 스키마 생성 action 이름입니다.
pageExcelToPdfExcel 템플릿을 PDF로 변환하는 action 이름입니다.
workItem템플릿의 특정 셀, 목록, 항목에 값을 주입하는 작업 단위입니다.
workData여러 작업 항목을 묶어 Reportify API에 전달하는 데이터입니다.

syn.Config.IsReportifyModule이 true이면 필요한 보조 스크립트를 로드하고, ProxyPathName이 설정된 환경에서는 syn.$w.proxyBasePath를 기준으로 Reportify URL을 구성합니다.

주요 기능​

템플릿 URL 확인​

const templateUrl = syn.$p.getDocumentTemplateUrl(syn.$w.pageScript.substring(1));

화면 스크립트 이름을 기준으로 Reportify 템플릿 다운로드 URL을 생성합니다. 화면별 문서 템플릿을 규칙적으로 배치할 때 사용합니다.

출력 스키마 확인​

const schemeText = await syn.$p.getSchemeText(templateUrl, true);

템플릿 또는 Reportify 서버에서 출력 스키마를 가져옵니다. 개발 중에는 이 값을 확인해 어떤 datafield, bind, row, col 조합으로 데이터를 주입해야 하는지 파악합니다.

작업 항목 추가​

const workItems = [];

syn.$p.addWorkItem(workItems, 0, 0, 'cell', 'CustomerName', 'B', 'string', '홍길동');
syn.$p.addWorkItem(workItems, 0, 0, 'cell', 'CreatedAt', 'D', 'date', new Date());
syn.$p.addWorkItem(workItems, 0, 0, 'list:OrderList', 'Orders', ['A', 'B', 'C'], ['string', 'number', 'number'], [
    ['A001', 3, 12000],
    ['A002', 1, 8000]
]);

addWorkItem은 템플릿 어느 위치에 어떤 타입의 데이터를 넣을지 정의합니다. 인자를 객체로 전달하는 형태도 지원하므로, 작업 항목이 복잡하면 객체 형식을 사용하는 편이 안전합니다.

syn.$p.addWorkItem(workItems, {
    document: 0,
    worksheet: 0,
    bind: 'cell',
    datafield: 'CustomerName',
    row: 3,
    col: 'B',
    type: 'string',
    data: '홍길동'
});

PDF 렌더링​

await syn.$p.renderPrint(syn.$w.pageScript.substring(1), {
    excelUrl: syn.$p.getDocumentTemplateUrl(syn.$w.pageScript.substring(1)),
    workData: {
        FormData0: {
            CustomerName: '홍길동'
        }
    }
});

renderPrint는 템플릿 URL과 workData를 Reportify API로 전달해 PDF를 생성하거나 표시하는 흐름에서 사용합니다.

Reportify API 직접 호출​

const payload = {
    excelUrl: syn.$p.getDocumentTemplateUrl('OrderReport'),
    workData: {
        FormData0: {
            OrderID: 'ORD-001'
        }
    }
};

const result = await syn.$r.httpRequest(
    'POST',
    syn.$p.getReportifyUrl(syn.$p.pageExcelToPdf),
    payload,
    null,
    { responseType: 'blob' }
);

const pdfUrl = syn.$r.createBlobUrl(result.response);
window.open(pdfUrl);

서버 응답을 blob으로 받아 브라우저에서 미리보기하거나 다운로드할 때는 syn.$r.createBlobUrl과 syn.$r.revokeBlobUrl을 함께 사용합니다.

출력 작업 설계 기준​

  • cell은 단일 셀 값 주입에 사용합니다.
  • list 또는 item:* 형태는 반복 데이터 주입에 사용합니다.
  • type은 string, number, date, image, url, html처럼 Reportify가 해석할 수 있는 값으로 지정합니다.
  • 대량 데이터를 넣을 때는 화면에서 모든 데이터를 조립하기보다 transact 거래로 필요한 데이터를 조회한 뒤 workData로 전달합니다.

주의사항​

  • syn.$p.printPage, syn.$p.printHtml, syn.$p.previewPdf, syn.$p.generateFromTemplate 같은 범용 PDF API는 현재 syn.js의 공개 API가 아닙니다.
  • 템플릿 파일 경로, Reportify URL, proxy base path는 배포 환경에 따라 달라질 수 있으므로 syn.Config와 syn.$w.proxyBasePath를 기준으로 구성합니다.
  • 이미지, URL, HTML 작업 항목은 외부 리소스를 참조할 수 있으므로 접근 권한과 네트워크 허용 범위를 확인합니다.
  • blob URL은 사용 후 syn.$r.revokeBlobUrl(url)로 정리합니다.

데모​

Javascript 예제​

'use strict';

let $printSample = {
    prop: {
        reportID: 'OrderReport'
    },

    async method_createPdf() {
        const excelUrl = syn.$p.getDocumentTemplateUrl(this.prop.reportID);
        const workData = {
            FormData0: {
                OrderID: 'ORD-001',
                CustomerName: '홍길동',
                CreatedAt: $date.toString(new Date(), 'a')
            }
        };

        await syn.$p.renderPrint(this.prop.reportID, {
            excelUrl,
            workData
        });
    },

    async method_previewBlob() {
        const payload = {
            excelUrl: syn.$p.getDocumentTemplateUrl(this.prop.reportID),
            workData: {
                FormData0: {
                    OrderID: 'ORD-001'
                }
            }
        };

        const result = await syn.$r.httpRequest(
            'POST',
            syn.$p.getReportifyUrl(syn.$p.pageExcelToPdf),
            payload,
            null,
            { responseType: 'blob' }
        );

        const pdfUrl = syn.$r.createBlobUrl(result.response);
        window.open(pdfUrl);
    }
};

소스) syn.$p Javascript 예제