차트 유형 만들기

이 페이지에서는 고유한 차트 유형을 개발하고 사용자에게 제공하는 방법을 설명합니다.

시청자층

이 페이지에서는 차트 사용 페이지를 읽었다고 가정합니다. 또한 자바스크립트 및 객체 지향 프로그래밍에 익숙하다고 가정합니다. 웹에서 다양한 자바스크립트 튜토리얼을 사용할 수 있습니다.

차트 만들기

차트는 개발자가 만든 자바스크립트 라이브러리를 통해 사용자에게 노출됩니다. 차트 라이브러리를 만드는 단계는 다음과 같습니다.

  1. 코드의 네임스페이스를 선택하세요. 다른 페이지에서 코드를 호스팅하므로 이름 충돌을 피해야 합니다.
  2. 차트 객체를 구현합니다. 다음을 노출하는 자바스크립트 객체를 구현합니다.
    • 생성자
    • 생성자에 전달된 DOM 요소 내에 객체를 그리는 draw() 메서드
    • 클라이언트가 사용할 기타 선택적 표준 메서드(예: getSelection())
    • 클라이언트에 노출할 커스텀 메서드입니다.
  3. [선택사항] 클라이언트에서 포착하도록 실행할 이벤트를 구현합니다.
  4. 차트에 대한 문서를 작성합니다. 문서화하지 않으면 다른 사용자가 문서를 삽입할 수 없습니다.
  5. 차트 갤러리에 차트를 게시합니다.

  • goog.visualization API 클래스 및 메서드 정의를 다운로드하여 IDE (코드 편집기)에서 자동 완성을 사용 설정할 수 있습니다. http://www.google.com/uds/modules/gviz/gviz-api.js에서 파일을 다운로드하여 프로젝트에 저장합니다. IDE는 다를 수 있지만 대부분의 IDE는 자동으로 색인을 생성하고 자동 완성을 사용 설정합니다. 파일이 항상 최신 상태가 아닐 수도 있다는 점에 유의하세요. 참조 페이지에서 최신 API 참조를 확인하세요.

네임스페이스 선택

차트는 다른 차트 또는 기타 관련 없는 자바스크립트를 호스팅하는 페이지에 삽입될 수 있습니다. 다른 코드 또는 CSS 클래스 이름과 이름 충돌을 피하려면 차트 코드에 고유한 네임스페이스를 선택해야 합니다. 네임스페이스 호스팅에 스크립트 호스팅에 사용할 URL (WWW 및 모든 확장 프로그램 제외)을 사용하는 것이 좋습니다. 예를 들어, 차트가 www.example.com에 게시될 경우 example를 고유한 네임스페이스로 사용합니다. 접미사를 . 차트를 더 그룹화합니다 (모든 Google 차트에는 네임스페이스 google.visualization가 있음). 네임스페이스 객체를 사용하여 차트 객체와 필요할 수 있는 전역 변수를 저장하세요.

다음은 MyTable이라는 차트 클래스와 필요한 전역 변수를 보유하기 위해 네임스페이스 객체를 만드는 예입니다.

// Namespace, implemented as a global variable.
var example = {};

// MyTable class constructor.
example.MyTable = function(container) {
  // ...
}

// MyTable.draw() method.
example.MyTable.prototype.draw = function(data, options) {
  // ...
}

CSS 충돌 방지

CSS를 사용하는 경우 페이지의 다른 차트에 영향을 미칠 수 있는 CSS 규칙을 작성하지 마세요. 예를 들어 td {color: blue;}와 같은 규칙은 차트 내에서뿐만 아니라 페이지의 다른 <td> 요소에도 영향을 미치므로 사용하지 않는 것이 좋습니다. 이 문제를 해결하는 방법은 전체 차트를 <div>에 클래스 이름으로 묶고 모든 CSS 규칙이 이 클래스 이름을 가진 요소의 하위 요소에만 적용되게 하는 것입니다. 예를 들어 다음 CSS 규칙은 클래스 이름이 'example'이 상위인 요소가 있는 <td> 요소에만 영향을 미칩니다.

td.example {color: blue;}

그러면 다음을 사용하여 <div>에 차트를 래핑할 수 있습니다.

<div class="example">
  ...
</div>

차트 구현

참조 섹션에 설명된 표준 메서드를 노출하는 자바스크립트 객체로 차트를 구현해야 합니다. 필수 메서드 두 가지는 생성자와 draw() 메서드입니다. 차트에 적합한 추가 메서드를 사용자에게 노출할 수도 있습니다. 사용은 간편할수록 좋습니다.

생성자

차트에는 차트를 그릴 단일 요소인 DOM 요소를 사용하는 단일 생성자가 노출되어야 합니다. 일반적으로 차트는 나중에 사용할 수 있도록 생성자에 이 요소의 로컬 사본을 저장합니다.

function example.MyTable(container) {
  this.container = container
}

draw() 메서드

차트 클래스에는 차트 클래스의 프로토타입에 정의된 draw() 메서드가 있어야 합니다. draw() 메서드는 다음 두 매개변수를 허용합니다.

  1. 표시할 데이터를 보유한 DataTable입니다.
  2. 차트의 이름/값 옵션에 관한 선택적 맵입니다. 옵션의 이름과 값 유형은 특정 차트에 맞게 정의됩니다. 예를 들어 아래 Hello 차트 예시에서 차트는 부울 유형 값이 'showLineNumber'라는 옵션을 지원합니다. 사용자가 특정 옵션의 값을 전달하지 않는 경우 각 옵션의 기본값을 지원해야 합니다. 이 매개변수는 선택사항이므로 사용자가 이 매개변수를 전달하지 않는 경우 모든 기본값을 사용할 준비를 해야 합니다(추가 정보).
example.MyTable.prototype.draw = function(data, options) {
  // Process data and options and render output into the container element.
  ...
}

안녕하세요. 차트입니다.

다음은 DataTable 데이터를 HTML 테이블로 표시하는 간단한 차트입니다.

구현 코드는 다음과 같습니다.

// Declare a unique namespace.
var example = {};

// Class constructor. Parameter container is a DOM elementon the client that
// that will contain the chart.
example.MyTable = function(container) {
  this.containerElement = container;
}

// Main drawing logic.
// Parameters:
//   data is data to display, type google.visualization.DataTable.
//   options is a name/value map of options. Our example takes one option.
example.MyTable.prototype.draw = function(data, options) {

  // Create an HTML table
  var showLineNumber = options.showLineNumber; // Boolean configuration option.

  var html = [];
  html.push('<table border="1">');

  // Header row
  html.push('<tr>');
  if (showLineNumber) {
    html.push('<th>Seq</th>');
  }
  for (var col = 0; col < data.getNumberOfColumns(); col++) {
    html.push('<th>' + this.escapeHtml(data.getColumnLabel(col)) + '</th>');
  }
  html.push('</tr>');

  for (var row = 0; row < data.getNumberOfRows(); row++) {
    html.push('<tr>');
    if (showLineNumber) {
      html.push('<td align="right">', (row + 1), '</td>');
    }

    for (var col = 0; col < data.getNumberOfColumns(); col++) {
      html.push(data.getColumnType(col) == 'number' ? '<td align="right">' : '<td>');
      html.push(this.escapeHtml(data.getFormattedValue(row, col)));
      html.push('</td>');
    }
    html.push('</tr>');
  }
  html.push('</table>');

  this.containerElement.innerHTML = html.join('');
}

// Utility function to escape HTML special characters
example.MyTable.prototype.escapeHtml = function(text) {
  if (text == null)
    return '';
  return text.replace(/&/g, '&').replace(/</g, '<')
      .replace(/>/g, '>').replace(/"/g, '"');
}

웹페이지에 차트 포함

이전 차트를 사용하려면 브라우저에서 액세스할 수 있는 .js 파일로 차트를 저장하세요. 다음 코드를 저장하고 자바스크립트 파일을 가리키도록 <script> 소스 매개변수를 변경합니다.

<html>
  <head>
    <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
    <script type="text/javascript" src="mytablevis.js"></script>
    <script type="text/javascript">
      google.charts.load("current");

      // Set callback to run when API is loaded
      google.charts.setOnLoadCallback(drawVisualization);

      // Called when the Chart API is loaded.
      function drawVisualization() {

        // Create and populate a data table.
        var data = new google.visualization.DataTable();
        data.addColumn('string', 'Task');
        data.addColumn('number', 'Daily Hours');
        data.addRows(5);
        data.setCell(0, 0, 'Work');
        data.setCell(0, 1, 11);
        // Add more data rows and cells here

        // Instantiate our table object.
        var vis = new example.MyTable(document.getElementById('mydiv'));

        // Draw our table with the data we created locally.
        vis.draw(data, {showLineNumber: true});
       }
   </script>
  <title>MyTable example page</title></head>
  <body>
    <div id="mydiv"></div>
    <p>This page demonstrates hosting a table visualization.</p>
  </body>
</html>

 

이벤트 구현하기

차트에서 유용한 이벤트 (예: 타이머 이벤트, 클릭과 같은 사용자 시작 이벤트)를 실행하려면 이벤트 세부정보 (이름, 전송할 속성 등)와 함께 google.visualization.events.trigger 함수를 호출해야 합니다. 자세한 내용은 이벤트 페이지를 참고하세요. 이벤트 객체에 속성을 추가하여 이벤트 세부정보를 클라이언트에 노출하거나 차트에서 일부 유형의 get...() 메서드를 노출할 수 있습니다. 그러면 클라이언트가 이 메서드를 호출하여 이벤트 세부정보를 가져올 수 있습니다. 두 경우 모두 메서드 또는 이벤트 속성을 잘 문서화하세요.

차트 문서화

차트를 제대로 문서화하지 않으면 사용자를 많이 확보하지 못할 수 있습니다. 다음 항목을 기록해야 합니다.

  • 지원하는 모든 방법을 설명합니다. draw() 메서드는 모든 차트에 공통되지만 각 차트는 자체 추가 메서드를 지원할 수 있습니다. (비표준 동작이 없는 한 생성자를 문서화할 필요가 없을 것입니다.) 예상 메서드 목록은 참조 페이지에서 확인하세요.
  • draw() 메서드가 지원하는 모든 옵션을 설명합니다. 여기에는 각 옵션의 이름, 예상 값 유형, 기본값이 포함됩니다.
  • 트리거하는 모든 이벤트를 설명합니다. 즉, 각 이벤트의 이름과 속성, 각 이벤트가 트리거되는 시점을 의미합니다.
  • 클라이언트의 <script> include 문에서 사용해야 하는 차트 라이브러리의 URL을 나열하고 문서의 URL을 제공합니다.
  • 차트의 정규화된 이름을 지정합니다.
  • 지원되는 옵션, 이벤트, 커스텀 메서드로 차트를 사용하는 방법을 보여주는 샘플 페이지를 만듭니다.
  • 차트의 데이터 정책을 명확히 설명합니다. 대부분의 차트는 브라우저 내에서 데이터를 처리하지만 차트나 지도 이미지를 만드는 등 데이터를 서버로 보낼 수도 있습니다. 데이터를 서버로 보내는 경우:
    • 전송되는 데이터를 명확하게 정의합니다.
    • 데이터가 서버에 저장되는 기간을 확인합니다.
    • 데이터에 액세스할 수 있는 항목을 문서화합니다. 예: 회사 XYZ 등
    • 데이터 로깅 여부와 기간을 지정합니다.

문서는 차트 코드와 동일한 위치에서 호스팅됩니다(아래의 차트를 갤러리에 제출 참조).

차트를 작성한 후 Google 갤러리의 '추가 차트' 섹션에 게시하기 위해 제출합니다. 차트를 제출하면 Google과 계약을 체결하여 악성 소프트웨어를 만들거나 사용자 데이터를 오용하지 않는 데 동의해야 합니다. 갤러리는 Google에서 만들었거나 검토한 차트를 가리키는 포인터의 목록일 뿐입니다. 갤러리는 실제 자바스크립트 라이브러리 및 문서를 자체 사이트에서 호스팅하거나 Google에서 라이브러리와 문서를 호스팅하도록 할 수 있습니다. 차트를 갤러리에 게시할 때 Google에서 차트를 호스팅할지 여부를 지정합니다.

문제 해결

코드가 작동하지 않는 것 같다면 다음과 같은 방법으로 문제를 해결할 수 있습니다.

  • 오타를 찾습니다. 자바스크립트는 대소문자를 구분하는 언어입니다.
  • Javascript 디버거를 사용합니다. Firefox에서는 자바스크립트 콘솔, Venkman Debugger 또는 Firebug 부가기능을 사용할 수 있습니다. IE에서는 Microsoft Script Debugger를 사용할 수 있습니다.
  • Google Chart API 토론 그룹을 검색합니다. 질문에 답변하는 게시물을 찾을 수 없는 경우 문제를 보여주는 웹페이지 링크와 함께 질문을 그룹에 게시합니다.

현지화

다양한 국가의 사용자가 차트를 사용할 것으로 예상되는 경우 다양한 언어 및 문화에 맞게 차트를 현지화할 수 있습니다. 가장 기본적인 현지화는 사용자의 브라우저 설정에 따라 UI의 표준 텍스트 문자열을 번역하는 것입니다. 더욱 발전된 형태의 현지화는 현지화에 따라 숫자 형식을 변경하거나 UI 디자인을 변경하는 것입니다. 차트를 현지화하기로 결정한 경우 차트에서 지원하는 언어를 문서에 나열하고 일반적으로 사용되는 언어의 기본 설정을 제공합니다. 또한 언어를 잘못 인식할 경우에 대비하여 차트의 UI에 '언어 변경' 버튼을 포함하는 것도 유용합니다. 브라우저 언어를 감지하는 일반적인 방법은 Accept-Language HTML 헤더를 확인하는 것입니다.