Revealjs 플러그인

개요

Revealjs 플러그인은 Revealjs로 만든 HTML 프레젠테이션의 기능을 확장합니다. Reveal 플러그인 API는 매우 풍부하며, Quarto의 Revealjs 프레젠테이션에 내장된 기능 중 많은 부분이 플러그인으로 구현되어 있습니다. 예를 들어 메뉴, 칠판, PDF 내보내기 등이 있습니다.

다음은 Quarto 확장으로 패키징된 Revealjs 플러그인 예시입니다:

확장 설명
Pointer 발표 중 커서를 ‘포인터’ 스타일 요소로 전환하는 기능을 추가합니다.
Attribution 슬라이드 오른쪽 가장자리에 출처 텍스트를 표시합니다.

빠른 시작

여기서는 간단한 Revealjs 플러그인 확장을 만드는 방법을 설명합니다. 이를 위해 quarto create 명령을 사용합니다. VS Code, Positron, RStudio를 사용 중이라면 각 통합 터미널에서 quarto create를 실행하세요.

시작하려면 플러그인 확장을 만들 상위 디렉터리에서 quarto create extension revealjs-plugin을 실행합니다:

Terminal
$ quarto create extension revealjs-plugin
 ? Extension Name › shuffler

위와 같이 확장 이름을 묻게 됩니다. shuffler를 입력하고 Enter를 누르면 Revealjs 플러그인 확장이 생성됩니다:

Creating extension at /Users/jjallaire/quarto/dev/shuffler:
  - Created README.md
  - Created _extensions/shuffler/_extension.yml
  - Created _extensions/shuffler/shuffler.css
  - Created _extensions/shuffler/shuffler.js
  - Created .gitignore
  - Created example.qmd

VS Code, Positron, RStudio에서 실행 중이라면 새 창이 열리며 확장 프로젝트가 표시됩니다.

_extensions/shuffler/의 파일 내용은 다음과 같습니다:

_extensions/shuffler/_extension.yml
title: Shuffler
author: J.J. Allaire
version: 1.0.0
quarto-required: ">=1.2.222"
contributes:
  revealjs-plugins:
    - name: RevealShuffler
      script:
        - shuffler.js
      stylesheet:
        - shuffler.css
_extensions/shuffler/shuffler.js
window.RevealShuffler = function () {
  return {
    id: "RevealShuffler",
    init: function (deck) {
      // TODO: Implement your plugin functionality
      // Learn more at https://revealjs.com/creating-plugins/
      
      // This example shuffles the deck when the 'T' key is pressed
      deck.addKeyBinding({ keyCode: 84, key: "T" }, () => {
        deck.shuffle();
      });
    },
  };
};

플러그인에 필요한 스타일을 제공하는 shuffler.css 파일도 있습니다.

마지막으로 example.qmd에는 확장을 사용하는 코드가 포함됩니다. 예:

example.qmd
---
title: "Shuffler Example"
format:
  revealjs: default
revealjs-plugins:
  - shuffler
---

## Breakfast

- Eat eggs
- Drink coffee

## Dinner

- Eat spaghetti
- Drink wine

플러그인을 개발하려면 example.qmd를 렌더/미리보기한 다음 shuffler.js와 shuffler.css를 수정하세요(이 파일들이 바뀌면 미리보기가 자동으로 갱신됩니다).

설치 및 사용

확장 소스 코드가 GitHub 저장소에 있다면 GitHub 조직과 저장소 이름을 참조해 추가할 수 있습니다. 예를 들어 attribution 확장은 다음과 같이 설치합니다:

Terminal
quarto add quarto-ext/attribution

GitHub 저장소 대신 단순 gzip 아카이브로 확장을 묶어 배포하는 것도 가능합니다. 자세한 내용은 확장 배포 문서를 참고하세요.

확장을 추가한 뒤에는 reveal-plugins 키에 플러그인을 추가해 사용할 수 있습니다. 예:

---
title: "My Presentation"
format: revealjs
revealjs-plugins:
  - attribution
---

플러그인 패키징

위의 플러그인들은 처음부터 Quarto용으로 개발된 것이 아니라, Revealjs 기본 플러그인으로 개발된 뒤 Quarto 확장으로 패키징되었습니다.

예를 들어 attribution 플러그인의 원본 구현은 여기에서 확인할 수 있습니다: https://github.com/rschmehl/reveal-plugins/tree/main/attribution. 플러그인은 JavaScript 파일과 CSS 파일로 구현됩니다. Quarto 확장으로 제공하려면 _extension.yml 설정 파일과 함께 패키징하여 플러그인을 등록합니다. Quarto 확장에 포함된 파일은 다음과 같습니다:

LICENSE
README.md
example.qmd
_extensions/
   attribution/
     _extension.yml
     attribution.js
     attribution.css

LICENSE와 README.md는 표준 문서 파일이며 example.qmd는 확장 개발과 문서화를 위해 사용됩니다. 이 파일들은 최종 사용자에게 설치되지 않습니다(실제로 설치되는 것은 _extensions 디렉터리의 내용뿐입니다).

Quarto 버전의 전체 소스는 여기에서 확인할 수 있습니다: https://github.com/quarto-ext/attribution (아래에서 코드도 자세히 살펴봅니다).

플러그인 개발

Revealjs 플러그인을 처음부터 새로 만들 수도 있고, 위에서 설명한 방식으로 기존 Revealjs 확장을 패키징할 수도 있습니다.

Quarto 확장으로 패키징해볼 만한 3rd party Revealjs 플러그인 목록은 다음을 참고하세요: https://github.com/hakimel/reveal.js/wiki/Plugins,-Tools-and-Hardware.

새 플러그인을 개발하려면 위의 Quarto Reveal 확장과 다른 3rd party Reveal 플러그인 코드를 함께 참고하세요. Revealjs 웹사이트의 다음 문서도 중요한 기술 정보를 제공합니다:

플러그인 구성

일부 Revealjs 플러그인은 다양한 사용자 옵션을 제공합니다. 플러그인을 처음부터 개발하는 경우, 플러그인 전용 구성 키를 사용하는 것이 좋습니다. 사용자는 이 키를 다른 revealjs 옵션과 함께 사용할 수 있습니다. 예를 들어 pointer 확장은 다음처럼 설정할 수 있습니다:

---
title: "Example Presentation"
format:
  revealjs: 
    pointer:
      pointerSize: 18
      color: '#32cd32'
revealjs-plugins:
  - pointer
---

확장은 deck.getConfig() 함수로 옵션에 접근합니다:

return {
  id: "pointer",
  init: (deck) => {
    const config = deck.getConfig();
    const options = config.pointer || {};
    // etc
  }
}

기존 Revealjs 플러그인을 패키징하는 경우 _extension.yml의 config 키로 기본 설정을 덮어쓸 수 있습니다. 예를 들어 pointer 확장에서 제공하는 덮어쓰기 값은 다음과 같습니다:

title: Pointer
author: Charles Teague
contributes:
  revealjs-plugins:
    - name: RevealPointer
      script:
        - pointer.js
      stylesheet:
        - pointer.css
      config:
        pointer:
          key: "q"
          color: "red"
          pointerSize: 16
          alwaysVisible: false

예제: Attribution

여기서는 attribution 확장의 전체 소스 코드를 살펴봅니다. 이 확장은 Revealjs 슬라이드 오른쪽 가장자리에 출처 텍스트를 옆으로 표시할 수 있게 해줍니다.

확장 개발에 사용되는 소스 파일은 다음과 같습니다:

LICENSE
README.md
example.qmd
_extensions/
   attribution/
     _extension.yml
     attribution.js
     attribution.css

example.qmd와 문서 파일은 확장 개발용으로만 사용되며(최종 사용자에게 설치되지 않음), 나머지 파일은 확장 등록(_extension.yml)과 Revealjs 플러그인 구현(attribution.js, attribution.css)을 제공합니다.

example.qmd는 .attribution 클래스를 가진 div와 이미지를 포함하는 단일 슬라이드 프레젠테이션입니다:

example.qmd
---
title: "Attribution Extension"
format: revealjs
revealjs-plugins:
  - attribution
---

## Forest Image

![](ingtotheforest.jpg)
 
::: {.attribution)
Photo courtesy of [@ingtotheforest](https://unsplash.com/@ingtotheforest)
:::

revealjs-plugins 키는 _extensions/attribution 디렉터리에 구현된 attribution 확장을 참조합니다.

_extension.yml 파일에는 플러그인 이름, 스크립트, 스타일시트와 함께 Revealjs 플러그인을 제공한다는 내용이 포함되어 있습니다(플러그인 이름은 임의가 아니라 스크립트에서 사용하는 이름이며, 여기서는 RevealAttribution입니다):

_extensions/attribution/_extension.yml
title: Attribution
author:  Roland Schmehl
version: 0.1.0
quarto-required: ">=1.2.0"
contributes:
  revealjs-plugins:
    - name: RevealAttribution
      script:
        - attribution.js
      stylesheet:
        - attribution.css

attribution.js 파일은 Revealjs 플러그인 API를 사용해 플러그인을 구현합니다:

_extensions/attribution/attribution.js
window.RevealAttribution = window.RevealAttribution || {
  id: 'RevealAttribution',
  init: function(deck) {
      initAttribution(deck);
  }
};

const initAttribution = function(Reveal){

var ready = false;
var resize = false;
var scale = 1;

window.addEventListener( 'ready', function( event ) {

  var content;

  // Remove configured margin of the presentation
  var attribution = document.getElementsByClassName("attribution");
  var width = window.innerWidth;
  var configuredWidth = Reveal.getConfig().width;
  var configuredHeight = Reveal.getConfig().height;

  scale = 1/(1-Reveal.getConfig().margin);

  for (var i = 0; i < attribution.length; i++) {
    content = attribution[i].innerHTML;
    attribution[i].style.width = configuredWidth + "px";
    attribution[i].style.height = configuredHeight + "px";
    attribution[i].innerHTML = "<span class='content'>" + content + "</span>";
    attribution[i].style.transform = 'translate( -50%, -50% ) scale( ' + scale*100 + '% ) rotate(-180deg)';
  }

  // Scale with cover class to mimic backgroundSize cover
  resizeCover();

});

window.addEventListener( 'resize', resizeCover );

function resizeCover() {

  // Scale to mimic backgroundSize cover
  var attribution = document.getElementsByClassName("attribution");
  var xScale = window.innerWidth / Reveal.getConfig().width;
  var yScale = window.innerHeight / Reveal.getConfig().height;
  var s = 1;

  if (xScale > yScale) {
      // The div fits perfectly in x axis, stretched in y
      s = xScale/yScale;
  }
  for (var i = 0; i < attribution.length; i++) {
    attribution[i].style.transform = 'translate( -50%, -50% ) scale( ' + s*scale*100 + '% ) rotate(-180deg)';
  }
}

};

마지막으로 attribution.css는 슬라이드 오른쪽 가장자리에 .attribution 클래스를 가진 요소를 배치하고 회전시키는 CSS를 포함합니다:

_extensions/attribution/attribution.css
/* Attribution plugin: text along the right edge of the viewport */
.attribution{
  position: absolute;
  top: 50%;
  bottom: auto;
  left: 50%;
  right: auto;
  font-size: 0.4em;
  pointer-events: none;
  text-align: center;
  writing-mode: vertical-lr;
  transform: translate( -50%, -50% ) scale( 100% ) rotate(-180deg);
}

/* Attribution plugin: activate pointer events for attribution text only */
.attribution .content{
  pointer-events: auto;
}