Skip to main content

함수 파라미터(Context)

LC5 내에서 함수를 작성하고자 할 때, 원하는 비즈니스 로직을 작성하기 위해서는 해당 페이지의 상태값, 외부 모듈, 트리거된 이벤트 등에 대한 접근이 필수적일 것입니다. LC5에서는 자유도 높은 로직 작성을 위해 생성 중인 페이지와 연결되는 풍부한 파라미터를 제공합니다.

현재 지원 중인 파라미터 리스트는 다음과 같습니다.

Image

다음은 각 파라미터에 대한 설명입니다.

state​

앞서 Meta, State 문서에서 설명했던 State 데이터가 바인딩됩니다. 이를 통해 함수 내 로직에서 현재 폼 및 테이블 등 컴포넌트들이 갖고 있는 값에 접근할 수 있습니다.

async ({ state }) => {
  console.log(state.forms.forms1.name);
};

getState​

함수가 호출되는 시점의 최신 State 값을 가져오는 함수입니다. state 파라미터는 함수가 정의될 당시의 값을 참조하는 반면, getState()를 호출하면 그 시점의 최신 State 값을 반환받을 수 있습니다. 비동기 로직 중간에 최신 값을 다시 확인해야 할 때 유용합니다.

async ({ getState }) => {
  setTimeout(() => {
    console.log(getState().forms.forms1.name);
  }, 3000);
};

setState​

함수 실행 도중에 State 값을 즉시 갱신하고 싶을 때 사용하는 함수입니다. 기존에는 async Function의 리턴값으로 State를 변경하는 updater 함수를 반환해야만 State가 갱신되었지만, setState를 사용하면 함수 실행 중간에도 필요한 시점에 자유롭게 State를 갱신할 수 있습니다.

Quick Start 예제와 마찬가지로, State draft 객체를 변경하는 콜백 함수를 인자로 전달하여 사용합니다.

async ({ setState }) => {
  // set new value by draft
  setState((draft) => {
    draft.forms.forms1.name = "";
  });
  // set new value by returning value
  setState({
    "forms.forms1": {
      name: ""
    }
  })
};

cache​

현재 페이지 단위로 데이터를 저장하고 꺼내올 수 있는 캐시 모듈입니다. cache.get([키]) 형식으로 저장된 값을 가져오고, cache.set([키], [값]) 형식으로 값을 저장할 수 있습니다. 키를 생략하면 현재 페이지의 id가 기본 키로 사용됩니다.

async ({ cache }) => {
  cache.set("recentKeyword", "홍길동");
  console.log(
    cache.get("recentKeyword")
  ); // "홍길동"
};

history​

Window.history를 복사하여 커스텀한 객체입니다. 이를 통해 history.push와 같은 페이지 이동 로직을 구현할 수 있습니다.

해당 history가 Window.history의 모든 프로퍼티를 담고 있지 않다는 것을 유의해야 합니다. 파라미터 안의 history는 push, replace, state 프로퍼티만 포함하고 있습니다. 이는 사용자의 브라우저 기록에 대한 직접적인 조작을 제한하고, 보안과 안정성을 유지하기 위함입니다.

async ({ history }) => {
  history.push("/g/lc5/list");
};

api​

API-Hub에 등록한 모듈을 가져오는 파라미터입니다. get, post, patch, put 네 가지 메서드를 지원하며, api.get([지정한 URL])와 같은 형식으로 사용합니다. 해당 파라미터를 통해 API Hub에서 작성한 서버 로직을 LC5와 연결할 수 있습니다.

async ({ api }) => {
  const result = await api.get("/g/lc5/sample")
    .then((res) => res.data.cbData.productionOrders || [])
    .catch(() => {
      return [];
    });
  if (result) {
    console.log(result);
  }
};

currentUser​

현재 서비스에 접속 중인 유저 정보를 가져옵니다.

async ({ currentUser }) => {
  console.log(currentUser.name);
};

mode​

Builder 페이지에서 지정할 수 있는 mode 데이터를 가져옵니다. mode란 같은 UI를 지녔지만 input의 readonly 속성만 다른 조회 페이지와 수정 페이지처럼, 일부 프로퍼티를 제외하면 UI가 완전히 똑같은 페이지를 별도의 Builder를 생성하는 수고로움 없이 하나의 Builder로 관리하기 위한 데이터입니다. mode 값으로는 CREATE, READ, UPDATE, DELETE가 올 수 있으며 설정하지 않으면 undefined 값을 갖습니다. Builder의 Paths 테이블에서 경로별로 설정할 수 있습니다.

async ({ mode }) => {
  if (mode === "READ") {
    console.log("조회 모드입니다.");
  }
};

params​

URL 파라미터를 {[이름] : [값]} 형태로 가져옵니다. 각 파라미터의 이름은 Builder의 Paths 테이블에서 설정할 수 있습니다. 만약 설정한 URL 파라미터가 없을 경우 빈 객체를 반환합니다.

async ({ params }) => {
  console.log(params.id);
};

s3​

AWS S3 Proxy 람다와 연결된 s3 객체를 리턴합니다. upload, download, getUrlForDownload, query, logEvents 다섯 가지 메서드를 지원합니다.

  • upload: 지정한 경로에 파일을 업로드합니다.
  • download: 지정한 경로의 파일을 다운로드합니다.
  • getUrlForDownload: 파일을 다운로드할 수 있는 signed URL을 취득합니다.
  • query: AWS Athena 서비스를 통하여 쿼리를 실행하여 S3에 저장된 데이터를 조회합니다.
  • logEvents: CloudWatch 로그 이벤트를 조회합니다.
async ({ s3 }) => {
  // 파일 업로드
  const uploaded = await s3.upload({
    configKey: "SAMPLE_CONFIG",                 // configuration 에 사전 설정 필요
    template: "sample/{fileName}",              // configuration 에 사전 설정 필요
    pathVariables: { fileName: "hello.txt" },   // configuration 에 사전 설정 필요
    data: "Hello World",
    contentType: "text/plain"
  });
  console.log(uploaded.key);

  // 파일 다운로드
  const downloaded = await s3.download({
    configKey: "SAMPLE_CONFIG",    // configuration 에 사전 설정 필요
    template: "sample/{fileName}", // configuration 에 사전 설정 필요
    pathVariables: { fileName: "hello.txt" }
  });
  console.log(downloaded.data);

  // 다운로드용 signed URL만 조회
  await s3.getUrlForDownload({
    configKey: "SAMPLE_CONFIG",
    template: "sample/{fileName}",
    pathVariables: { fileName: "hello.txt" }
  }).then((res) => res.data.cbData.url)
    .then((url) => console.log(url))
    .catch(() => {
      console.log("URL 조회에 실패했습니다.");
    });

  // 등록된 쿼리 실행
  const queried = await s3.query({
    configKey: "SAMPLE_CONFIG",
    template: "sample-select-query",
    variables: { id: "1" },
    db, // Athena Database Name
  });
  console.log(queried.data);

  // CloudWatch 로그 이벤트 조회
  const events = await s3.logEvents({
    logGroupName: "sample-log-group",
    logStreamName: "sample-log-stream",
    requestId: "req-1",
    startTime,
  });
  console.log(events.data);
};

file​

pdf, xlsx 작업과 연결된 file 모듈을 리턴합니다. xlsx, pdf 두 가지 메서드를 지원하며, 기본적으로 호출 시 변환된 파일이 자동으로 다운로드됩니다(download: false로 끌 수 있습니다). openPreview: true를 지정하면 미리보기 창이 열립니다.

  • xlsx({ templateID, body, outputName, download, openPreview }): 지정한 엑셀 템플릿에 body 데이터를 바인딩하여 엑셀 파일로 변환합니다.
  • pdf({ templateId, data, outputName, download, openPreview }): 지정한 PDF 템플릿에 data 데이터를 바인딩하여 PDF 파일로 변환합니다.

엑셀은 templateID(대문자 ID), PDF는 templateId(소문자 d)로 파라미터 이름이 다르므로 주의해야 합니다.

async ({ file }) => {
  // 엑셀 변환
  file.xlsx({
    templateID: "SAMPLE_XLSX_TEMPLATE",
    body: { title: "샘플 문서" },
    outputName: "sample.xlsx"
  });

  // PDF 변환
  file.pdf({
    templateId: "SAMPLE_PDF_TEMPLATE",
    data: { title: "샘플 문서" },
    outputName: "sample.pdf"
  });
};

fn​

Builder에서 설정한 Global Functions를 가져옵니다. Global Functions란 최초 함수, 컴포넌트 함수 등 여러 함수에서 재사용할 수 있는 함수 로직을 저장할 수 있는 공간으로 Builder에서 설정할 수 있습니다. 주로 반복되는 함수 코드를 줄이고자 할 때 사용하며, 호출 시 지정한 이름을 붙여 fn.funcName() 형식으로 활용하면 됩니다. 지정한 Global Functions가 없을 경우 빈 객체를 반환합니다.

async ({ fn }) => {
  fn.testFunction();
};

oEvent​

컴포넌트 이벤트 함수일 경우 이벤트 객체가 담깁니다. 이를 통해 이벤트로 들어온 value나 target 등에 접근할 수 있습니다. 최초 함수여서 이벤트가 들어오지 않을 경우 undefined를 반환합니다.

async ({ oEvent }) => {
  console.log(oEvent.value, oEvent.target);
};

env​

process.env 값을 그대로 가져오는 파라미터입니다. 빌드 시점에 주입된 환경 변수에 접근하고 싶을 때 사용합니다.

async ({ env }) => {
  console.log(env.NODE_ENV);
};

i18n​

현재 설정된 언어의 다국어 번역 객체입니다. i18n.getText([키]) 형식으로 호출하여 해당 키에 매칭되는 번역 문구를 가져올 수 있습니다.

async ({ i18n }) => {
  console.log(i18n.getText("common.save"));
};

messageBox​

사용자에게 확인 메시지를 노출하고 응답을 기다리는 함수입니다. messageBox([문구], [옵션]) 형식으로 호출하며, 사용자가 확인(OK)을 누르면 true를, 그 외에는 false를 반환하는 Promise를 리턴합니다.

async ({ messageBox }) => {
  const confirmed = await messageBox("저장하시겠습니까?");
  if (confirmed) {
    console.log("확인을 눌렀습니다.");
  }
};

require​

@bsgp/lib-api, @bsgp/lib-core 등 내부적으로 정의된 라이브러리를 호출할 수 있는 함수입니다. require("@bsgp/lib-core") 형식으로 사용합니다.

async ({ require }) => {
  const { isTruthy } = require("@bsgp/lib-core");
  console.log(isTruthy(""));
};