Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

커스텀 시각화 API 2.0 참조

looker.plugins.visualizations.add 함수 호출은 시각화 API로 들어가는 진입점입니다. 이 함수는 커스텀 시각화를 완전히 정의하는 시각화 객체 를 허용합니다.

다음은 시각화의 예입니다.

looker.plugins.visualizations.add({
    create: function(element, config){
        element.innerHTML = "<h1>Ready to render!</h1>";
    },
    updateAsync: function(data, element, config, queryResponse, details, doneRendering){
        var html = "";
        for(var row of data) {
            var cell = row[queryResponse.fields.dimensions[0].name];
            html += LookerCharts.Utils.htmlForCell(cell);
        }
        element.innerHTML = html;
        doneRendering()
    }
});

환경

시각화 API는 일반 JavaScript이므로 JavaScript 라이브러리를 사용하여 데이터를 시각화할 수 있습니다.

JavaScript 코드는 Looker 인스턴스와 별도의 샌드박스 처리된 iframe에서 실행됩니다. 그럼에도 불구하고 커스텀 시각화 작성자는 작성하는 코드가 안전한지 확인할 책임이 있습니다.

모든 웹 개발과 마찬가지로 다양한 웹브라우저 (Chrome, Edge, Firefox)를 지원하는 것이 문제가 될 수 있습니다. 시각화 API는 Looker에서 지원하는 모든 브라우저에서 작동하지만 커스텀 코드의 브라우저 지원을 보장하는 것은 사용자에게 달려 있습니다. 예를 들어 let 또는 ()=>와 같은 ES6 사용은 대부분의 브라우저에서 작동하지만 IE11 또는 PhantomJS를 사용하여 PDF를 렌더링할 때 오류가 발생할 수 있습니다.

설치

관리자 > 플랫폼 > 시각화 양식으로 매니페스트를 정의하여 커스텀 시각화를 설치합니다. 매니페스트는 고유한 문자열 ID, 사람이 읽을 수 있는 라벨, 시각화의 URI, 필요한 종속 항목 (예: d3, jQuery, underscore)에 대한 링크로 구성됩니다.

커스텀 시각화는 Looker 외부에서 HTTPS 콘텐츠로 제공되어야 합니다. 커스텀 시각화 API의 첫 번째 버전에서 이전하는 경우 looker/plugins/visualizations 디렉터리에 파일이 있을 수 있습니다. 이 위치는 계속 액세스할 수 있으며 시각화의 상대 경로를 제공할 수 있지만 콘텐츠를 다른 위치로 이전하는 것이 좋습니다. /plugins 디렉터리는 공유 파일 시스템에 없으므로 클러스터링된 환경은 모든 노드에서 시각화 파일에 액세스할 수 없습니다.

시각화 객체

시각화 객체는 다음과 같은 필수, 선택적, 추가된 속성을 사용합니다.

필수 속성

create 함수

이 함수는 시각화가 페이지에 처음 그려질 때 한 번 호출됩니다. 시각화에서 항상 사용할 수 있도록 설정해야 합니다. 라이브러리를 로드하거나 나중에 사용할 요소 및 컨트롤 집합을 만들 수 있습니다.

create 함수에 대한 세부정보 보기 →
updateAsync / update 함수

이 함수는 시각화의 상태를 변경해야 할 때마다 호출됩니다. 항상 create 후에 호출되며 여러 번 호출될 수 있으므로 최대한 빨라야 합니다.

이 함수는 여러 가지 이유로 호출될 수 있지만 일반적으로 시각화할 쿼리가 변경되었거나 구성 옵션이 변경되었거나 시각화 크기가 조정된 경우입니다.

이 함수에는 동기 및 비동기 버전이 있습니다. 하나만 지정하면 됩니다. (둘 다 정의하면 오류가 발생합니다.) 비동기 메서드는 iframe의 특성으로 인해 PDF 렌더링에 더 안정적입니다.

이러한 update 함수에 대한 세부정보 보기 →

선택 속성

options 객체

사용자가 시각화에서 설정할 수 있는 옵션을 자세히 설명하는 객체입니다.

구성 UI 노출에 대한 세부정보 보기 →
destroy 함수 API V2에서 아직 구현되지 않음

시각화가 페이지에서 삭제되기 직전에 호출되는 함수입니다. 이 함수를 사용하여 이벤트 리스너 또는 기타 상태를 정리합니다. 예를 들어 사용자가 창을 닫으면 호출되지 않을 수 있습니다.

추가 속성

시각화가 looker.plugins.visualizations.add에 전달된 후 Looker는 객체에 다음 속성을 자동으로 추가합니다. create, update, updateAsync, destroy 함수의 컨텍스트 내에서 this를 사용하여 참조할 수 있습니다.

addError 함수

시각화 대신 오류 메시지를 표시하도록 UI에 지시하기 위해 시각화 코드에서 호출할 수 있는 함수입니다. error 객체를 가져옵니다.

오류가 추가되면 clearErrors가 호출될 때까지 계속 표시됩니다.

예:
```
this.addError({
    title: "Two Dimensions Required",
    message: "This really great visualization requires two dimensions."
});
```
clearErrors 함수

시각화 코드에서 addError를 사용하여 추가된 오류를 삭제하기 위해 호출할 수 있는 함수입니다.

예:
```
this.clearErrors();
```
trigger 함수

시각화 외부에서 이벤트를 트리거하기 위해 호출할 수 있는 함수입니다.

이벤트에 대한 세부정보 보기 →

예:
```
this.trigger("limit", [20]);
```

`create` 함수

create 함수에는 element 및 config라는 두 개의 매개변수가 전달됩니다.

create: function(element, config){
  // Your update code here.
},

매개변수

element DOMElement

시각화를 렌더링할 컨테이너를 나타내는 DOM 요소입니다.
config 객체

사용자가 이 차트에 대해 설정한 구성 옵션의 값을 나타내는 객체입니다.

예: {my_configuration_option: "User Value"}

`updateAsync` 및 `update` 함수

시각화를 업데이트하는 기본 방법은 updateAsync 메서드입니다. 이 메서드를 사용하면 시각화에서 파일 로드 또는 웹 요청 전송과 같은 비동기 작업을 실행할 수 있습니다.

이 버전의 함수에는 렌더링이 완료될 때 호출되는 콜백인 추가 매개변수가 있습니다.

updateAsync: function(data, element, config, queryResponse, details, done){
    // An example of an asynchronous update, fetching a file.
    d3.request("https://example.com/fun-file.docx").response(function(xhr) {
        // Your update code here that uses this file.
        done();
    });
}

시각화가 렌더링을 완료하면 Looker에 알리면 Looker에서 PDF 렌더링을 최적화하고 시각화 이미지가 올바르게 캡처되도록 할 수 있습니다.

일부 이전 시각화에서는 update 함수를 사용합니다. 이 함수는 계속 작동하지만 시각화가 완전히 렌더링될 때 Looker에 알리지 않으므로 기본 방법은 아닙니다. update 함수에는 5개의 매개변수가 전달됩니다.

update: function(data, element, config, queryResponse, details){
  // Your update code here.
}

매개변수

data 배열

쿼리의 현재 데이터를 나타내는 행 배열입니다. null일 수 있습니다.

각 행은 필드 이름을 나타내는 키와 '셀' 객체를 나타내는 값이 있는 객체입니다. 다음은 셀 객체 처리와 관련된 세부정보입니다.
element DOMElement

시각화를 렌더링할 컨테이너를 나타내는 DOM 요소입니다.
config 객체

사용자가 이 차트에 대해 설정한 구성 옵션의 값을 나타내는 객체입니다.

예: {my_configuration_option: "User Value"}
queryResponse 객체

필드에 대한 메타데이터와 같은 현재 쿼리에 대한 메타데이터를 나타내는 객체입니다. null일 수 있습니다.
details 객체

현재 렌더링 컨텍스트에 대한 세부정보입니다. 차트가 렌더링되는 이유와 변경된 사항에 대한 정보를 포함합니다. 일반적으로 이 정보는 고급 사례에서만 사용됩니다.

새 대시보드 환경을 사용하는 Looker 대시보드의 교차 필터와 관련하여 허용되는 속성에는 crossfilterEnabled 및 crossfilters가 포함됩니다.

print 속성은 done 함수와 함께 사용하여 커스텀 시각화, 특히 애니메이션이 포함된 시각화의 PDF 렌더링을 개선할 수 있습니다. 예를 들면 다음과 같습니다.
```
if (details.print) {
        done();
}
```
done 함수

시각화가 완전히 렌더링되었음을 나타내는 콜백입니다. 시각화에서 비동기 호출을 실행해야 하거나 PDF로 렌더링해야 하는 경우 이 함수를 호출하는 것이 특히 중요합니다.

데이터 렌더링

Looker에는 데이터 포인트의 모양과 동작을 맞춤설정하는 데 사용할 수 있는 LookML의 다양한 데이터 형식 지정 도구가 있습니다. 이러한 도구에는 커스텀 값 형식, HTML, 드릴 링크, 데이터 작업과 같은 필드 수준 LookML 설정이 포함됩니다.

셀에는 모든 경우에 존재하는 유일한 속성인 value 속성이 있습니다. 이 속성은 셀이 속한 필드의 유형과 일치하는 JavaScript 유형입니다. 그러나 HTML 이스케이프가 실행되지 않았고 일부 필드 값은 바람직하지 않거나 혼란스러운 방식으로 렌더링되는 복잡한 JavaScript 객체 또는 배열이므로 value 속성을 HTML 또는 SVG에 직접 삽입하는 것은 안전하지 않습니다.

모든 시각화에서 이러한 항목을 일관되고 안전하게 렌더링하도록 하기 위해 data에서 차트에 전달되는 셀 메타데이터를 다양한 용도로 다양한 표현으로 변환하는 여러 유틸리티 함수가 있습니다. 셀 메타데이터는 경우에 따라 특정 필드를 압축하거나 생략할 수 있으며 이러한 도우미 함수를 사용하면 일관된 환경을 제공할 수 있습니다.

이러한 도우미 함수는 모두 전역 LookerCharts.Utils 객체에서 사용할 수 있습니다.

LookerCharts.Utils.textForCell(cell)

이 함수는 셀을 허용하고 표시하기에 적합한 문자열 표현을 반환합니다. 항상 문자열입니다. 이 함수는 null 또는 다른 유형을 반환하지 않습니다.
LookerCharts.Utils.htmlForCell(cell)

이 함수는 셀을 허용하고 HTML이 포함된 문자열을 반환합니다. 항상 문자열입니다. 이 함수는 null 또는 다른 유형을 반환하지 않습니다.

이 함수의 출력은 올바르게 이스케이프 처리되며 요소의 HTML에 직접 삽입하는 데 적합합니다. 출력 HTML은 데이터에 적합한 경우 클릭 시 드릴 메뉴도 올바르게 표시합니다.
LookerCharts.Utils.filterableValueForCell(cell)

이 함수는 셀을 허용하고 이 셀의 값과 일치하는 Looker 고급 필터 구문 문자열을 반환합니다.

LookerCharts.Utils.toggleCrossfilter({row, pivot, event})

이 함수는 행, 피벗 또는 이벤트를 허용하며 시각화에 교차 필터링이 사용 설정되어 있는지 확인하는 데 사용됩니다. 다음 예는 이벤트가 발생할 때 교차 필터링이 사용 설정되어 있는지 확인하는 요소에 이벤트 리스너를 추가하는 방법을 보여줍니다.

d3.select("#myElement")
.on("click", function (d) {
    if (details.crossfilterEnabled) {
            LookerCharts.Utils.toggleCrossfilter({
                row: d.row,
                event: d3.event,
            });
    } else {
      // ... handle click when cross-filtering is not enabled
    }
});

LookerCharts.Utils.getCrossfilterSelection(row, pivot?)

이 함수는 행 또는 피벗을 허용하며 커스텀 시각화에서 해당 행 또는 피벗이 선택되어 있는지 확인하는 데 사용됩니다. 이 함수는 CrossfilterSelection {NONE, SELECTED, UNSELECTED}의 enum을 반환합니다. NONE인 경우 0, SELECTED인 경우 1, UNSELECTED인 경우 2입니다.

다음 예는 교차 필터링되는 경우 행에 채우기 색상을 조건부로 적용하고 해당 행에 교차 필터링이 사용 설정되지 않은 경우 기본 색상을 적용합니다.
```
d3.select("#myElement")
.attr("fill", function (d) {
    const crossfilter = LookerCharts.Utils.getCrossfilterSelection(d.row)
    if (details.crossfilterEnabled && crossfilter === 1) {
            return d.color
    } else {
            return "#DEE1E5" //Hex used for unselected elements in native visualizations
...
```
LookerCharts.Utils.openDrillMenu(options)

htmlForCell의 출력은 필요한 경우 드릴 메뉴를 자동으로 표시하지만 특정 유형의 렌더링에는 적합하지 않을 수 있습니다. (예를 들어 SVG는 HTML을 렌더링할 수 없지만 드릴을 시작하기 위해 클릭 이벤트를 캡처할 수 있습니다.)

options 객체에는 다음과 같은 매개변수가 있습니다.
- links 필수 배열
  
  셀의 links 속성에서 반환된 객체의 배열입니다. 여러 셀의 링크를 한 번에 표시하려면 먼저 이러한 배열을 연결하면 됩니다. 커스텀 링크의 경우 다음 형식으로 객체 배열을 제공합니다.
```
{ label: string, type: 'drill', type_label: string, url: url }
```
- event HTML DOM 이벤트
  
  드릴 이벤트를 발생시킨 클릭 (또는 기타) 이벤트입니다. Looker는 이를 사용하여 드릴 메뉴를 배치할 위치를 결정합니다. 없는 경우 pageX 및 pageY 좌표가 있는 객체를 전달해 보세요.
예:
```
for (var row of data) {
    var cell = row[queryResponse.fields.dimensions[0].name];
    var cellElement = myBuildElementFunction(cell);
    cellElement.onclick = function(event) {
        LookerCharts.Utils.openDrillMenu({
            links: cell.links,
            event: event
        });
    };
    // ... more visualization stuff...
}
```

구성 UI 표시

options 매개변수는 키가 옵션 이름의 임의 식별자이고 값이 옵션에 대한 정보를 설명하는 객체인 객체입니다.

예를 들면 다음과 같습니다.

options: {
    color_range: {
      type: "array",
      label: "Color Range",
      display: "colors"
    },
   top_label: {
      type: "string",
      label: "Label (for top)",
      placeholder: "My Great Chart"
    },
    transport_mode: {
      type: "string",
      label: "Mode of Transport",
      display: "select",
      values: [
         {"Airplane": "airplane"},
         {"Car": "car"},
         {"Unicycle": "unicycle"}
      ],
      default: "unicycle"
    }
}

옵션 객체 매개변수

option 객체에는 다음과 같은 기본 매개변수, 디스플레이별 속성, 구성 옵션이 있습니다.

기본 매개변수

type 문자열

옵션의 데이터 유형입니다.

허용되는 값: string (기본값), number, boolean, array
label 문자열

사용자에게 표시되는 옵션의 사람이 읽을 수 있는 라벨입니다.
default

옵션의 기본값입니다. 지정하지 않으면 옵션의 값은 null입니다. 이는 type과 동일한 유형의 값이어야 합니다.
display 문자열

특정 type 값은 UI에서 다양한 방식으로 표시될 수 있습니다.
- type이 string인 경우:
  
  허용되는 값: text (기본값), select, radio
- type이 number인 경우:
  
  허용되는 값: number (기본값), range
- type이 array인 경우:
  
  허용되는 값: text (기본값), color, colors
placeholder 문자열

지원하는 display 값의 경우 사용자에게 입력할 내용을 알려주는 예시 값 또는 설명입니다.

디스플레이별 속성

values 객체의 배열

display가 radio 또는 select인 경우 인터페이스에 나열될 라벨과 값이 포함된 배열입니다.

배열의 각 항목은 옵션의 라벨과 값을 나타내는 단일 키-값 쌍이 있는 객체여야 합니다. 라벨은 UI에만 표시됩니다. 렌더링 시에는 값만 수신됩니다.

예:
```
values: [
    {"Center": "c"},
    {"Left": "l"},
    {"Right": "r"}
]
```
display가 radio인 경우 각 옵션에 description을 추가로 지정할 수 있습니다.
```
values: [
    {"Cool": "c"},
    {"Uncool": {
            value: "unc",
            description: "Only choose this if the data is very uncool."
        }
    }
]
```
max number

display가 range인 경우 범위 슬라이더로 선택할 수 있는 최대 개수입니다.
min number

display가 range인 경우 범위 슬라이더로 선택할 수 있는 최소 개수입니다.
step number

display가 range인 경우 범위 슬라이더의 각 눈금이 나타내는 양입니다.

구성 옵션

section 문자열

옵션이 많은 차트의 경우 옵션이 표시되어야 하는 섹션의 라벨입니다. UI는 옵션을 section 값으로 그룹화합니다. 섹션이 하나만 있는 경우 섹션 UI가 표시되지 않습니다.

section을 사용하는 경우 모든 옵션에 설정해야 합니다.
order number

UI에 표시할 옵션의 순서를 나타내는 숫자입니다. 지정된 경우 옵션이 이 순서에 따라 정렬됩니다.
display_size 문자열

UI에서 옵션의 너비를 나타내는 크기 클래스입니다. 예를 들어 '최소' 및 '최대' 옵션을 나란히 표시하려면 각 옵션의 표시 크기를 half로 설정하면 됩니다.

허용되는 값: normal (기본값), half, third

이벤트

이벤트는 시각화 또는 쿼리의 속성을 업데이트할 수 있는 차트 (일반적으로 사용자 상호작용에 대한 응답)에 의해 트리거될 수 있습니다.

시각화 객체에서 trigger 함수를 호출하여 트리거할 수 있습니다. 첫 번째 매개변수는 항상 이벤트 이름 이고 두 번째 매개변수는 인수 배열입니다.

this.trigger("limit", [20]);

사용 가능한 이벤트

updateConfig

차트의 현재 구성 설정을 업데이트합니다.

인수: 업데이트할 구성 키가 포함된 객체입니다. 지정되지 않은 키는 변경되지 않습니다.

예:
```
var vis = this;
$(element).find(".axis").click(function(){
    vis.trigger("updateConfig", [{axis_hidden: true}]);
});
```
limit

기본 쿼리의 한도를 업데이트합니다.

인수: 쿼리의 새 한도를 나타내는 정수입니다.
```
var vis = this;
$(element).find(".show-all").click(function(){
    vis.trigger("limit", [500]);
});
```

filter

기본 쿼리의 필터 값을 업데이트합니다.

var vis = this;
$(element).find(".show-all-tommys").click(function(){
    vis.trigger("filter", [{
        field: "users.name", // the name of the field to filter
        value: "%tommy%", // the "advanced syntax" for the filter
        run: true, // whether to re-run the query with the new filter
    }]);
});

loadingStart

시각화를 로드 중으로 표시합니다. 대부분의 경우 필요하지 않지만 시각화에서 원격 위치에서 객체를 로드하거나 긴 계산을 실행하는 경우 이를 사용하여 로드 표시기를 계속 표시할 수 있습니다.

loadingEnd가 트리거될 때까지 로드 중으로 표시됩니다.
loadingEnd

시각화를 더 이상 로드 중이 아닌 것으로 표시합니다.
printSize (Looker 26.0 이상)

시각화에서 대시보드를 PDF로 렌더링할 때 '테이블을 펼쳐 모든 행 표시' 옵션을 활용할 수 있습니다. 이 이벤트를 사용하면 애플리케이션에서 렌더링된 콘텐츠의 높이를 알 수 있으며 모든 정보를 인쇄할 수 있도록 대시보드 타일을 적절하게 펼칠 수 있습니다.
```
  this.trigger('printSize', {
    heightExpanded: FULL_HEIGHT_IN_PIXELS
  });
```

registerOptions (Looker 5.24 이상)

시각화가 등록된 후 시각화에서 추가 옵션을 등록할 수 있습니다.

  update: function(data, element, config, queryResponse, details){
    options = {}
    // Create an option for each measure in your query
    queryResponse.fields.measure_like.forEach(function(field) {
      id = "color_" + field.name
      options[id] =
      {
    label: field.label_short + " Color",
    default: "#8B7DA8",
    section: "Style",
    type: "string",
    display: "color"
      }
    })
    this.trigger('registerOptions', options) // register options with parent page to update visConfig
    ...
  }
});

커스텀 시각화 API 2.0 참조 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

환경

설치

시각화 객체

필수 속성

선택 속성

추가 속성

create 함수

매개변수

updateAsync 및 update 함수

매개변수

데이터 렌더링

구성 UI 표시

옵션 객체 매개변수

기본 매개변수

디스플레이별 속성

구성 옵션

이벤트

사용 가능한 이벤트

커스텀 시각화 API 2.0 참조

`create` 함수

`updateAsync` 및 `update` 함수