이 문서에서는 다음과 같은 주제를 다룹니다.

• 소개
• 기본서식 작성의 기본 사항
• 주석
• 블록 주석
• 리터럴
• 특성
• 조건부
• 조건을 평가하는 방법
• 공백 잘라내기
• 도우미
• 범위 변경하기
• 루트 컨텍스트를 도우미에 전달하기
• 배열에 있는 항목에 액세스하기
• Length

소개

각 헬프 센터 테마는 헬프 센터에서 다양한 유형의 페이지 레이아웃을 정의하는 편집 가능한 페이지 기본서식 모음으로 구성되어 있습니다. 예를 들어 지식창고 문서의 기본서식, 요청 목록의 기본서식 등이 있습니다.

각 기본서식은 HTML 마크업과 Handlebars와 같은 표현식이 혼합되어 구성되어 있으며, 기본서식에서 이중 중괄호로 식별됩니다. Handlebars는 디자인할 때가 아니라 렌더링할 때 페이지에서 콘텐츠를 삽입하거나 수정할 수 있는 간편한 기본서식 작성 엔진입니다.

헬프 센터에서 기본서식 작성 언어를 Curlybars라고 하며 대규모 Handlebars 언어 하위 집합을 구현합니다. 이 가이드에서는 이 언어를 사용해서 헬프 센터의 페이지를 사용자 지정하는 방법에 대해 설명합니다.

헬프 센터는 콘텐츠를 사용자 지정할 수 있는 도우미 및 명명된 특성을 제공합니다. 이들 중 일부는 모든 헬프 센터 페이지에서 공유하여 사용할 수 있습니다. 나머지는 특정 페이지에서만 사용할 수 있습니다.

예

{{#each comments}}
  

    

      
    

    

      

        
          {{author.name}}
        
      
    
  
{{/each}}

이 예에서는 페이지에 댓글을 남긴 사용자의 목록을 만듭니다. each 도우미는 페이지에 있는 각 comments 특성의 값에서 반복됩니다. 각 댓글에서 author.avatar_url 및 author.name 특성의 값이 HTML에 삽입됩니다.

기본서식 작성의 기본 사항

이 섹션에서는 기본서식을 작성해야 하는 구성 단위에 대해 설명합니다. 자세한 내용은 developer.zendesk.com에서 헬프 센터 기본서식을 참조하세요.

Curlybars 기본서식은 글자 그대로 렌더링되는 축자(verbatim) 텍스트와 Curlybars 표현식 두 가지로 구성되어 있습니다. 즉, 비어 있는 기본서식도 유효하며 텍스트만 포함되어 있는 기본서식도 유효하다는 의미입니다. 예를 들어 다음 기본서식은 유효한 기본서식입니다.

Article

Some details on the article

헬프 센터 기본서식에는 축자(verbatim) 텍스트만 지원되지만 렌더링할 때 이러한 텍스트를 실제로 사용자 지정할 수 없습니다. 기본서식 작성 논리를 추가하려면 Curlybars 표현식이 필요하며 이중 중괄호로 묶어야 합니다({{ and }}).

앞서 설명한 예에서 기본서식 작성 논리를 추가하려면 다음과 같이 기본서식을 수정해야 합니다.

Article

Some details on the article

{{article.author.name}}

아래 섹션에서는 기본서식에서 중요한 내용을 변경하기 위해 유효한 표현식을 작성하는 방법에 대해 설명합니다.

한 쌍의 중괄호 내에 다른 중괄호 쌍을 사용할 수 없습니다. 예를 들어 다음과 같은 구문은 유효하지 않습니다.

Article

Some details on the article

{{ {{ ... }} }}

주석

렌더링 페이지에는 반영되지 않는 메모를 기본서식에 사용하면 도움이 되는 경우도 있습니다. Curlybars에서는 {{! ... }}). 이 예에서 이 구문을 사용하여 코드 주석을 추가할 수 있습니다.

{{!
  This template aims to
  show details of an article
}}

Article

Some details on the article

다음은 페이지가 렌더링된 후에 브라우저에 표시되는 내용입니다.

Article

Some details on the article

이렇게 주석 내에 있는 모든 내용을 버리는 기능은 실제로 기본서식을 만들 때 편리할 수 있습니다. 확인, 디버깅 등을 수행하려면 일부 코드에 주석을 달아야 할 수도 있습니다.

블록 주석

지금까지 설명한 주석 구문은 Curlybars 코드에 주석을 다는 데는 적합하지 않습니다. Curlybars 코드에 주석을 달려면 {{!-- ... ---}}). 이러한 종류의 주석은 여러 줄에 걸쳐 사용할 수 있으므로 코드에 효과적으로 댓글을 달 수 있습니다. 예:

{{!
  This template aims to
  show details of an article
}}

Article

Some details on the article

{{!--
  I want to commend out the following code:

  {{ ... some Curlybars expressions }}

--}}

위의 기본서식은 다음과 같이 렌더링됩니다.

Article

Some details on the article

리터럴

Curlybars에서는 리터럴 개념이 지원되므로 글자 그대로 해석되는 값을 포함할 수 있습니다. 리터럴은 문자열, 부울 또는 숫자 3가지 유형의 값으로 나눌 수 있습니다.

문자열을 나타낼 때는 작은따옴표 또는 큰따옴표 둘 중 하나만 사용할 수 있습니다. 예를 들어 'this is a valid string', "this is valid as well"과 같이 사용할 수 있지만 "this is not valid'와 같이 큰따옴표와 작은따옴표를 혼용할 수는 없습니다.

숫자에는 양의 정수 또는 음의 정수를 사용할 수 있습니다. 123은 유효한 양수이고 +123은 이와 동일한 값을 나타내며, 00123도 유효하고 -123도 유효합니다.

부울은 true 및 false로 나타냅니다. 다른 변형은 사용할 수 없습니다. 예를 들어 TRUE 및 FALSE는 Curlybars에서 부울로 해석되지 않습니다.

리터럴을 렌더링할 수 있습니다. 예:

A string: {{ 'hello world' }}
A boolean: {{ true }}
A number: {{ 42 }}

페이지가 다음과 같이 렌더링됩니다.

A string: 'hello world'
A boolean: true
A number: 42

특성

헬프 센터의 모든 기본서식에서는 헬프 센터에 대한 데이터를 나타내는 컨텍스트에 액세스할 수 있습니다. 예를 들어 문서 페이지 기본서식에는 사용자가 요청한 문서의 구조를 보여주는 article이라는 개체가 있습니다. 기본서식에 사용할 수 있는 모든 특성을 확인하려면 developer.zendesk.com에서 헬프 센터 기본서식을 참조하세요.

이러한 개체에서 특정 정보를 추출하려면 article.title과 같이 점 표기법을 사용하세요.

특성의 정규화된 이름을 경로라고 하기도 합니다. 예를 들어 name은 author 개체의 특성이지만 article.author.name은 경로입니다.

특성 값을 이중 중괄호로 묶어서 표시할 수 있습니다. 이 예에서는 다음과 같이 별도의 단락에 작성자 이름을 표시할 수 있습니다.

Article

Author: {{article.author.name}}

사용자가 John Venturini라는 상담원이 작성한 문서를 보려고 한다고 가정해 보죠. 이 경우 기본서식은 다음과 같이 렌더링됩니다.

Article

Author: John Venturini

문서 자체를 렌더링할 수도 있습니다. article 개체에는 문서 콘텐츠가 포함된 body 특성이 있습니다. 기본서식을 다음과 같이 수정하여 문서 본문을 렌더링합니다.

Article

Author: {{article.author.name}}

{{article.body}}

조건부

기본서식 언어를 사용하면 특성 값을 렌더링할 수 있을 뿐만 아니라 기본서식에 조건부 렌더링 논리를 추가할 수 있습니다.

예를 들어 요청된 문서가 내부용일 때 HTML 스니펫을 렌더링해야 하는 경우가 있습니다. 문서 페이지 컨텍스트에는 article.internal 특성이 있어, 문서가 내부용이면 true를 리턴하고 그렇지 않으면 false를 리턴합니다.

이 정보를 사용해서 if 블록을 만들 수 있습니다. if 표현식은 조건이 true 또는 false인지 지정해야 합니다. 이 결과에 따라 블록 콘텐츠가 렌더링될지 여부가 결정됩니다. 기본 구문은 다음과 같습니다.

{{#if condition}}
  This is rendered if the condition is true.
{{/if}}

이 예에서 기본서식을 아래와 같이 수정할 수 있습니다.

Article

{{#if article.internal}}
  
This article is internal.
{{/if}}

Author: {{article.author.name}}

{{article.body}}

조건이 false일 때 블록을 렌더링해야 하는 경우에는 unless 블록을 사용합니다. 구문은 if 블록과 비슷합니다.

{{#unless condition}}
  This is rendered if the condition is false.
{{/unless}}

이 예에서 문서가 내부용이 아니어도 메시지를 렌더링해야 하는 경우에는 아래와 같이 기본서식을 수정할 수 있습니다.

Article

{{#if article.internal}}
  
This article is internal.
{{/if}}

{{#unless article.internal}}
  
This is a publicly visible article!
{{/unless}}

Author: {{article.author.name}}

{{article.body}}

이러한 종류의 조건부 논리(값이 true일 때와 false일 때 수행되는 작업이 각각 다르게 지정됨)는 일반적으로 if-else 블록에서 처리됩니다. 구문은 다음과 같습니다.

{{#if condition}}
  This is rendered if the condition is true.
{{else}}
  This is rendered if the condition is false.
{{/if}}

이 예를 아래와 같이 수정할 수 있습니다.

Article

{{#if article.internal}}
  
This article is internal.
{{else}}
  
This is a publicly visible article!
{{/if}}

Author: {{article.author.name}}

{{article.body}}

unless 블록에는 unless-else 변형도 포함되어 있습니다. 이 변형을 사용하면 if-else 블록과 동일한 결과를 얻을 수 있습니다.

Article

{{#unless article.internal}}
  
This is a publicly visible article!
{{else}}
  
This article is internal.
{{/unless}}

Author: {{article.author.name}}

{{article.body}}

조건을 평가하는 방법

일반적으로 조건은 article.internal과 같은 헬프 센터의 특성이며, true 또는 false 부울 값이 있습니다. 일부 특성에는 부울 값이 없으며 이러한 특성은 다음과 같이 평가됩니다.

• 값이 숫자이면 0은 false이고 그밖의 숫자는 true입니다.

• 값이 문자열이면 빈 문자열은 false이고 그밖의 문자열은 true입니다.

• 값이 개체 모음이면 빈 모음은 false이고 그밖의 모음은 true입니다.

• 값이 null이면 표현식은 false입니다.

숫자를 확인하는 몇 가지 조건부 논리를 설정한다고 가정해 보죠. 문서 페이지에 있는 문서의 총 댓글 수가 포함된 article.comment_count 특성이 있습니다. if 조건을 사용해서 총 댓글 수가 0이 아닌지 확인하고 응원 메시지를 표시할 수 있습니다. 예:

Article

Author: {{article.author.name}}

{{article.body}}

{{#if article.comment_count}}
  
Yahoo! This article has got some comments!
{{/if}}

공백 잘라내기

Curlybars에서 기본서식을 처리할 때 모든 축자(verbatim) 텍스트를 있는 그대로 표시합니다. 이 방식은 대부분의 경우 유용하게 활용됩니다. 하지만 표현식 옆의 공백 문자를 보다 정교하게 제어해야 하는 경우가 있습니다. 다음 코드를 예로 들겠습니다.

Click me!

highlighted가 true이면 다음 HTML이 렌더링됩니다.

Click me!

highlight 단어 앞뒤에는 공백이 있습니다. 물론 이렇게 두어도 괜찮지만, 공백을 렌더링하지 않고 기본서식에 유지해야 하는 경우에는 물결 문자(~)를 사용할 수 있습니다.

여는 중괄호 또는 닫는 중괄호에 물결 문자를 추가하면 괄호로 묶인 텍스트에서 공백이 잘립니다. 예:

Click me!

물결 문자가 highlight 단어 앞뒤에 있는 공백을 잘라냅니다.

Click me!

물결 문자는 시각적 표현이 없는 모든 공백 문자를 잘라내지만 새 줄, 탭, 캐리지 리턴, 줄 바꿈 또는 단순 공백 등과 같이 줄 간격을 조절하거나 줄을 분할할 때 영향을 줍니다. 이 예는 이해를 돕기 위한 것이므로 참고용으로만 사용하고, 실제 작업에서는 앞에서 설명한 if 블록을 여러 줄에 사용하면 보다 이해하기 쉽게 표현할 수 있습니다. 예:

Click me!

이렇게 수정해도 다음과 같이 렌더링됩니다.

Click me!

이러한 예가 실제 작업에 크게 도움이 되지는 않지만, 물결 문자의 효과는 실제 사례마다 따라 다를 수 있습니다.

도우미

일부 기본서식에서는 데이터에 액세스하고, 데이터를 표시하며, 몇 가지 조건부 논리를 추가하기만 해도 됩니다. 하지만 부가적인 기능이 필요할 수 있습니다. 예를 들어 페이지 요청자의 로캘에 따라 변경되는 현지화된 문자열을 표시하거나 길이가 긴 텍스트 구절을 잘라야 하는 경우가 있습니다.

도우미를 사용하면 이러한 종류의 기능을 기본서식에서 활용할 수 있습니다. 기본서식에 사용할 수 있는 모든 도우미를 확인하려면 developer.zendesk.com에서 헬프 센터 기본서식을 참조하세요.

예를 들어 문서 페이지 기본서식에 excerpt라고 하는 도우미를 사용해서 문자열을 자를 수 있습니다. 이 예에서 문서 제목이 잘린 버전을 표시해야 하는 경우에는 다음과 같이 기본서식을 수정하면 됩니다.

{{excerpt article.title characters=50}}

Author: {{article.author.name}}

{{article.body}}

위 예에서는 도우미를 호출하는 데 중괄호를 사용했습니다. excerpt 도우미에는 문자열로 인식되는 표현식으로 구성되는 매개변수를 사용할 수 있습니다. 이 도우미에는 유지할 문자 수를 지정할 수 있는 characters 옵션이 있습니다. characters 옵션은 필수가 아니며 이 옵션을 지정하지 않으면 기본값이 사용됩니다. 자세한 내용은 헬프 센터 기본서식의 excerpt를 참조하세요.

도우미를 호출하는 구문은 {{ [ ...] [ ...]}}입니다. 여기에서 필수 요소는 도우미 이름뿐이며 매개변수와 옵션은 도우미에 따라 다릅니다.

이제 작성자 이름이 John Venturini일 때 응원 메시지가 표시되도록 기본서식을 업데이트한다고 가정해 보죠. 안타깝게도 if 조건을 사용해서 article.author.name이 "John Venturini"인지 확인할 수 없습니다. if는 하나의 표현식에서만 작동하기 때문입니다. == 등과 같은 비교 연산자를 사용할 수 없습니다.

그렇다면 어떻게 논리를 추가할 수 있을까요? is 도우미를 사용하면 됩니다. 이 도우미는 두 개의 매개변수를 비교하여 서로 같은지 확인합니다. 예:

{{excerpt article.title characters=50}}

{{#is article.author.name 'John Venturini'}}
  
Cool! John Venturini is the author of this article!
{{/is}}

{{article.body}}

위의 스니펫은 작성자가 John Venturini일 때 응원 메시지를 렌더링합니다. 하지만 작성자가 다른 사람일 때 다른 메시지를 렌더링해야 하는 경우는 어떨까요? 다행히도 is에는 else 블록(if-else 문과 같은 역할)도 포함되어 있습니다. 작성자가 John Venturini가 아닐 때 이전의 메시지를 복원하려면 다음과 같이 else 블록을 추가하면 됩니다.

{{excerpt article.title characters=50}}

{{#is article.author.name 'John Venturini'}}
  
Cool! John Venturini is the author of this article!
{{else}}
  
Author: {{article.author.name}}
{{/is}}

{{article.body}}

범위 변경하기

필요한 정보를 찾아 갈 수 있는 경로가 너무 길지 않으면 점 표기법을 사용해서 간편하게 데이터에 액세스할 수 있습니다 예: article.title). 하지만 경로가 긴 특성에 액세스해야 하는 경우도 있습니다 예: article.author.name). 원할 경우 기본서식에 길이가 더 긴 경로를 사용할 수 있습니다. 예를 들어 이 예에서 다음과 같이 작성자 이름과 아바타를 추가할 수 있습니다.

{{excerpt article.title characters=50}}


{{#is article.author.name 'John Venturini'}}
  
Cool! John Venturini is the author of this article!
{{else}}
  
Author: {{article.author.name}}
{{/is}}

{{article.body}}

위의 스니펫에 문제는 없지만, 특성의 경로가 길면 코드가 산만해질 수 있습니다. 이 문제를 해결할 수 있는 한 가지 방법은 with라고 하는 특수 문을 사용하는 것입니다. with 문에는 연관된 코드 블록에 사용할 기본 컨텍스트를 나타내는 매개변수 하나를 사용할 수 있습니다. 구문은 다음과 같습니다.

{{#with }}
   ...
{{/with}}

이 예를 아래와 같이 수정하여 개선할 수 있습니다.

{{excerpt article.title characters=50}}

{{#with article.author}}
  
  {{#is name 'John Venturini'}}
    
Cool! John Venturini is the author of this article!
  {{else}}
    
Author: {{name}}
  {{/is}}
{{/with}}

{{article.body}}

article.author 매개변수를 사용하면 블록에 있는 모든 경로에 article.author를 포함할 필요가 없습니다. 따라서 블록 내부에 있는 {{name}}은 블록 외부에 있는 article.author.name과 동일합니다.

article.author.name은 article.author.article.author.name과 동일하므로 블록에 사용할 수 없습니다. 이와 마찬가지로 article.title을 사용해서 블록 내부에 있는 문서 제목에 액세스할 수 없습니다. 문서 개체는 블록 외부에 있는 루트 컨텍스트에서만 액세스할 수 있기 때문입니다.

with를 사용해서 설정된 컨텍스트에서 나가고 외부 컨텍스트에 액세스하려면 경로에 ../ 표기법을 사용하세요. 다음과 같이 with 블록 내부에 문서 제목을 렌더링할 수 있습니다.

{{excerpt article.title characters=50}}

{{#with article.author}}
  {{../article.title}}

  
  {{#is name 'John Venturini'}}
    
Cool! John Venturini is the author of this article!
  {{else}}
    
Author: {{name}}
  {{/is}}
{{/with}}

{{article.body}}

같은 경로에 ../ 표기법을 반복해서 사용할 수 있습니다. 컨텍스트 수는 동일하게 됩니다. 예를 들어 다음과 같이 코드를 작성해도 됩니다.

{{excerpt article.title characters=50}}

{{#with article}}
  {{#with author}}
    {{../../article.title}}

    ...

{{/with}}

{{article.body}}

좀 더 신중한 방법으로서, 작성자가 지정되어 있지 않을 때마다 특정 메시지를 렌더링하려면 다음과 같이 if 블록을 사용하면 됩니다.

{{excerpt article.title characters=50}}

{{#if article.author}}
  {{#with article.author}}
    ...
  {{/with}}
{{else}}
  No author is present for this article!
{{/if}}

{{article.body}}

헬프 센터에서 article.author는 null이 아니며 여기에 제시된 예에서는 이해를 돕기 위해 가정한 것뿐입니다.

위의 스니펫에 문제는 없지만 else 블록을 with 문에 사용해서 동일한 결과를 얻을 수 있습니다. 매개변수가 falsy이면 else 블록이 실행됩니다. 이 예를 아래와 같이 수정할 수 있습니다.

{{excerpt article.title characters=50}}

{{#with article.author}}
  ...
{{else}}
  No author is present for this article!
{{/with}}

{{article.body}}

else 블록을 사용하면 코드의 가독성을 높일 수 있습니다.

루트 컨텍스트를 도우미에 전달하기

this 키워드를 사용해서 현재 루트 컨텍스트를 도우미에 전달할 수 있습니다. render_author 도우미에서 작성자에 대한 세부 정보를 표시하기 위해 article 개체를 매개변수로 사용할 수 있는 경우, 다음과 같이 this 키워드를 사용할 수 있습니다.

{{excerpt article.title characters=50}}

{{#with article}}
  {{render_author this}}
{{/with}}

{{article.body}}

this 는 article로 인식됩니다.

배열에 있는 항목에 액세스하기

일부 헬프 센터 특성은 개체 배열로 구성되어 있습니다. 예를 들어 attachments 특성은 첨부 파일의 배열로 구성됩니다.

배열에 있는 항목에 액세스하려면 각 항목을 반복해야 합니다. each 도우미를 사용하면 쉽게 반복할 수 있습니다. 예:

{{excerpt article.title characters=50}}

{{#with article.author}}
  ...
{{/with}}

{{article.body}}

{{#each attachments}}
  {{name}}
  ({{size}})
{{/each}}

위의 스니펫은 모든 첨부 파일을 나열합니다. 나열되는 각 항목에는 url, name 및 size 등과 같이 첨부 파일 하나와 관련된 데이터가 표시됩니다.

with와 마찬가지로 each는 블록에서 컨텍스트를 변경합니다. 즉, 외부 컨텍스트에 액세스하기 위해 ../ 표기법을 사용할 수 있습니다.

배열이 비어 있을 때 메시지를 렌더링하려는 경우에는 다음과 같이 if 블록을 사용하면 쉽게 렌더링할 수 있습니다.

...

{{#if attachments}}
  {{#each attachments}}
    {{name}}
    ({{size}})
  {{/each}}
{{else}}
  Sorry, no attachments available!
{{/if}}

이렇게 코드를 작성해도 되지만 else 블록을 사용하면 코드의 가독성을 높일 수 있습니다.

...

{{#each attachments}}
  {{name}}
  ({{size}})
{{else}}
  Sorry, no attachments available!
{{/each}}

Length

각 배열에는 해당 배열에 포함되는 요소 수를 지정하는 암시적인 length 특성이 있습니다. 예를 들어 첨부 파일 수를 표시하려면 다음과 같이 length 특성을 사용하면 됩니다.

...

There are {{attachments.length}}.

{{#each attachments}}
  {{name}}
  ({{size}})
{{/each}}