Workshop 모듈 인터페이스

모듈 인터페이스는 외부에서 값을 전달할 수 있도록 공개한 변수 집합입니다. 부모 모듈에 삽입할 때 변수를 매핑하거나 URL로 초기값을 지정하는 모듈의 입출력 계약입니다. 여러 객체 유형의 공통 속성과 링크를 정의하는 온톨로지 인터페이스와는 다릅니다.

변수 공개

변수의 Settings에서 external ID를 지정하고 Module interface를 켭니다. 표시 이름과 설명은 선택 사항이며 모듈을 삽입하거나 Open Workshop module 이벤트로 사용할 때 보여 줍니다.

삽입 모듈의 공유 상태

부모가 자식 모듈을 삽입하면 자식의 interface 변수에 부모의 변수를 매핑할 수 있습니다. 매핑한 변수에는 부모 변수의 정의를 사용하고 자식에 작성한 해당 interface 변수의 정의는 사용하지 않습니다.

선택 객체, 선택 탭이나 overlay의 표시 상태를 공유할 수 있습니다. 자식 모듈의 이벤트로 interface 변수값을 바꾸면 같은 값을 참조하는 부모 또는 형제 모듈도 그 변경에 반응할 수 있습니다. 공유 값을 레이아웃 상태에 연결하는 방식도 사용할 수 있습니다.

Open Workshop module 이벤트

Open Workshop module 이벤트를 사용하면 URL을 직접 조립하지 않고 대상 모듈의 interface에 현재 변수값을 전달합니다. 이벤트 설정에 대상 interface가 나타나며 실행 순간의 값으로 새 모듈을 엽니다.

편집 모드에서 모듈 참조를 통해 자식 모듈을 별도 편집기로 열 때도 참조한 곳에서 전달하던 interface 변수의 현재 값을 함께 사용합니다. 부모 안에서 보던 상태를 유지하여 자식 구성을 살펴볼 수 있습니다.

새 창으로 열 때 전달하는 초기값과, 삽입한 모듈에서 매핑하여 공유하는 변수 상태는 구분합니다.

URL로 String 초기값 지정

1. Workshop 앱의 보기 모드에서 브라우저 URL을 복사합니다. 편집 모드 URL을 사용하지 않습니다.
2. 편집 모드의 Variables에서 New variable, String, Static을 선택합니다.
3. Settings에서 external ID를 정하고 Module interface를 켭니다.
4. 복사한 URL의 query parameter 이름으로 external ID를, 값으로 초기화할 문자열을 넣습니다.

예를 들어 외부 ID가 interfaceVariable이고 문자열 값이 123이면 쿼리 부분은 ?interfaceVariable=123입니다. 이미 쿼리 매개변수가 있으면 &로 추가합니다. 실제 값에 공백, + 또는 &가 있으면 URL에 맞게 인코딩합니다.

다음 함수의 viewUrl에는 실제 보기 모드의 절대 URL을, values에는 공개한 String 변수의 외부 ID와 원래 문자열을 전달합니다. 기존의 다른 매개변수와 fragment를 유지하며 같은 이름의 매개변수는 새 값으로 교체합니다.

export function withWorkshopStringParameters(
  viewUrl: string,
  values: Readonly<Record<string, string>>,
): string {
  const url = new URL(viewUrl);
  for (const [externalId, value] of Object.entries(values)) {
    url.searchParams.set(externalId, value);
  }
  return url.toString();
}

이 함수는 주소를 만들며 모듈을 열거나 값을 실행 중인 앱에 전달하지 않습니다. 일반적인 문자열 조합이 필요한 경우 변수 변환으로 동적 링크를 구성할 수도 있습니다. 링크를 받은 사용자는 대상 모듈과 데이터에 필요한 권한을 갖춰야 합니다.

초기화 시점과 버전

URL의 interface 매개변수는 모듈을 처음 로드할 때 사용합니다. 로드 후 주소만 바꾸어도 현재 변수값이 동적으로 갱신되지는 않습니다. 실행 중 값을 바꾸려면 Set variable value 같은 이벤트를 사용하고 초기 로드 처리는 On module load에서 구성합니다.

Routing으로 페이지를 선택하는 변수는 기본값을 비워 두는 조건을 함께 적용합니다.

시험할 때 보기 URL 경로의 /latest/ 구간을 /dev/로 바꾸면 마지막 게시 버전 대신 마지막 저장 버전을 엽니다. 그 경로가 가리키는 버전과 사용자의 접근 범위를 확인합니다.

Carbon에서 전달

Workshop에 직접 전달하는 query parameter와 Carbon의 매개변수 이름은 다릅니다.

Carbon을 통해 Workshop 모듈 탭 사이를 이동할 때 객체 집합 필터 변수도 전달할 수 있습니다. 다만 다음 interface 값과 유형은 Carbon navigation에서 지원하지 않습니다.

• 빈 객체 집합을 값으로 가진 Object set 변수
• NaN 값을 가진 Number 변수
• Time series set 변수
• GeoShape와 GeoPoint 변수
• Struct 변수
• Scenario 변수

Carbon의 전달 제약은 Workshop 내부에서 그 변수 유형을 사용할 수 있는지와는 별개입니다.