사용자 정의 Listing

개요

기본 제공되는 3가지 listing 유형 외에도, 항목을 완전히 사용자 정의한 방식으로 표시할 수 있습니다. 사용자 정의 표시에서는 어떤 HTML이든 생성할 수 있으며, listing이 제공하는 정렬/필터링/페이지네이션도 선택적으로 사용할 수 있습니다.

Listing 템플릿

사용자 정의 listing 표시를 만들려면 EJS 템플릿을 만들어 템플릿에 전달되는 항목 집합의 HTML을 생성합니다. EJS 템플릿은 순수 JavaScript로 HTML을 생성할 수 있어 항목을 순회하며 값을 출력하기 쉽습니다.

사용자 정의 템플릿을 사용하려면 listing의 template 옵션으로 지정합니다:

listing:
  template: gallery.ejs

사용자 정의 템플릿이 있는 listing을 렌더링하면 listing 콘텐츠가 읽혀 항목 집합으로 처리되고, 템플릿에 전달되어 렌더링됩니다. 예를 들어 아래처럼 설정하면 posts 디렉터리의 모든 문서가 항목으로 읽혀 gallery.ejs 템플릿에 전달됩니다.

listing:
  contents: posts
  template: gallery.ejs

문서 목록을 출력하는 간단한 템플릿은 다음과 같습니다:

<ul>
<% for (const item of items) { %>
  <li><a href="<%- item.path %>"><%= item.title %></a></li>
<% } %>
</ul>

이 템플릿은 다음과 같은 간단한 HTML을 생성합니다:

렌더링 시 위 템플릿은 items라는 listing 항목 배열을 받습니다. listing 콘텐츠가 문서 목록에서 로드된 경우 각 항목은 Listing Fields에서 설명한 필드로 채워집니다. 또한 문서 메타데이터에 포함된 다른 필드도 항목의 속성으로 전달되므로, 사용자 정의 메타데이터를 문서와 listing 표시에서 사용할 수 있습니다.

Note

Quarto는 EJS 템플릿을 렌더링할 때 lodash를 사용합니다. lodash는 템플릿에서 HTML 이스케이프에 다른 구문을 사용합니다.

HTML escaped value:   <%- value %>
HTML unescaped value: <%= value %>

메타데이터 Listing

Listing의 contents 옵션에는 보통 경로 또는 글로브 목록이 들어가지만, 메타데이터도 포함할 수 있습니다. 이 경우 메타데이터가 항목으로 읽혀 템플릿에 전달됩니다. 예:

listing:
  template: custom.ejs
  contents:
    - name: First Item
      href: https://www.quarto.org
      custom-field: A custom value
    - name: Second Item
      href: https://www.rstudio.org
      custom-field: A second custom value

이를 다음과 같이 렌더링할 수 있습니다:

```{=html}
<ul>
<% for (const item of items) { %>
  <li>
    <a href="<%- item.href %>"><%= item.name %></a><br/>
    <%= item['custom-field'] %>
  </li>
<% } %>
</ul>
```

그러면 다음과 같은 간단한 HTML 표시가 생성됩니다:

메타데이터 파일 Listing

Listing의 contents 옵션은 하나 이상의 yaml 파일(메타데이터 포함)을 가리킬 수도 있습니다. 이 경우 메타데이터가 파일에서 읽혀 항목으로 템플릿에 전달됩니다. 예:

listing:
  template: custom.ejs
  contents:
    - items.yml

items.yml의 내용은 다음과 같습니다:

- name: First Item
  href: https://www.quarto.org
  custom-field: A custom value
- name: Second Item
  href: https://www.rstudio.org
  custom-field: A second custom value

템플릿 예시

이 웹사이트의 일부는 사용자 정의 listing으로 구성되어 있습니다. 가장 좋은 출발점은 사용자 정의 템플릿과 메타데이터 파일로 만든 갤러리입니다. 갤러리 페이지를 만드는 데 사용된 소스 코드는 Github 저장소에서 확인할 수 있습니다.

파일	설명
gallery.yml	갤러리 listing에 표시할 항목을 제어하는 메타데이터.
gallery.ejs	페이지에 항목을 표시하는 데 사용되는 템플릿.
index.qmd	`#gallery` div에 listing을 구성/배치하는 Quarto 문서.

정렬, 필터링, 페이지네이션

기본적으로 사용자 정의 listing 템플릿에서는 정렬/필터링/페이지네이션이 비활성화되어 있지만, 템플릿과 listing 옵션을 약간만 변경하면 이 기능을 추가할 수 있습니다. 이를 위해 사용자 정의 템플릿에 다음 세 가지를 포함해야 합니다:

항목 목록을 포함하는 HTML 태그에 list 클래스를 포함합니다.
각 항목을 포함하는 HTML 태그에 <%= metadataAttrs(item) %>를 포함합니다. 이를 통해 Quarto가 정렬/필터링에 사용하는 사용자 정의 속성을 기록할 수 있습니다.
각 항목 안에서, 항목 필드의 텍스트를 나타내는 태그에 클래스를 추가합니다. 클래스는 listing- 접두사와 필드 이름으로 구성해야 합니다. 예를 들어 item.name의 텍스트를 담는 태그에는 listing-name 클래스를 포함해야 합니다.

예를 들어 위의 custom.ejs 템플릿을 다음과 같이 수정할 수 있습니다:

<ul class="list">
<% for (const item of items) { %>
  <li <%= metadataAttrs(item) %>>
    <a href="<%- item.href %>" class="listing-name"><%= item.name %></a><br/>
    <span class="listing-custom-field"><%= item['custom-field'] %><span>
  </li>
<% } %>
</ul>

템플릿에 위 항목을 포함한 후 listing에서 옵션을 활성화합니다:

listing:
  sort-ui: true
  filter-ui: true
  page-size: 10

이제 UI 요소가 페이지에 나타나고 사용자 정의 listing과 정상적으로 상호작용합니다.

필드 표시 이름

필드 이름 대신 더 좋은 표시 이름을 제공하고 싶을 수 있습니다. 예를 들어 정렬 UI에 필드 이름이 표시됩니다. field-display-names로 필드 이름과 표시 이름의 매핑을 만들 수 있습니다. 예:

listing:
  template: custom.ejs
  contents:
    - items.yml
  sort-ui: true
  filter-ui: true
  page-size: 10
  field-display-names:
    name: "Name"
    custom-field: "Custom"

날짜 정렬 및 형식

날짜 값을 올바르게 형식화하고 정렬하려면 항목의 필드에 타입 정보를 지정할 수 있습니다. 필드를 날짜로 지정하면 지정된 날짜 형식(기본 또는 date-format으로 지정)으로 자동 포맷되며, 날짜 오름차순/내림차순 정렬을 지원합니다. 필드를 숫자로 지정하면 숫자 오름차순/내림차순 정렬을 지원합니다.

필드 타입은 다음과 같이 지정할 수 있습니다:

listing:
  template: custom.ejs
  contents:
    - items.yml
  field-types:
    custom-date: date
    custom-number: number

필수 필드

Listing은 다른 문서 또는 메타데이터에 지정된 필드로 생성되므로, 필수 필드가 존재하는지 확인하는 것이 도움이 됩니다. 필수 필드는 다음과 같이 지정할 수 있습니다:

listing:
  template: custom.ejs
  contents:
    - items.yml
  field-required: [name, custom-field]

Listing 페이지를 렌더링할 때 콘텐츠 중 필수 필드 값이 누락되면, 필요한 필드와 누락된 파일/메타데이터를 명시하는 오류가 발생합니다.

템플릿 파라미터

파라미터로 템플릿 동작을 제어해 사용자 정의 템플릿을 더 동적으로 만들 수 있습니다. template-params 옵션으로 파라미터를 제공합니다. 예:

listing:
  template: custom.ejs
  contents:
    - items.yml
  template-params:
    param1: "param-value"

템플릿에서는 <%= templateParams.param1 %>로 파라미터에 접근할 수 있습니다. 예를 들어 위 custom.ejs 템플릿을 다음과 같이 수정할 수 있습니다:

<h3><%= templateParams.param1 %></h3>
<ul class="pub-list list">
  <% for (const item of items) { %>
      <li <%= metadataAttrs(item) %>>
        <span class="listing-title"><%= item.title %>.</span>
      </li>
  <% } %>
</ul>