이 문서에서는 다음과 같은 주제를 다룹니다.
- 소개
- 기본서식 작성의 기본 사항
- 주석
- 블록 주석
- 리터럴
- 특성
- 조건부
- 조건을 평가하는 방법
- 공백 잘라내기
- 도우미
- 범위 변경하기
- 루트 컨텍스트를 도우미에 전달하기
- 배열에 있는 항목에 액세스하기
- Length
소개
각 헬프 센터 테마는 헬프 센터에서 다양한 유형의 페이지 레이아웃을 정의하는 편집 가능한 페이지 기본서식 모음으로 구성되어 있습니다. 예를 들어 지식창고 문서의 기본서식, 요청 목록의 기본서식 등이 있습니다.
각 기본서식은 HTML 마크업과 Handlebars와 같은 표현식이 혼합되어 구성되어 있으며, 기본서식에서 이중 중괄호로 식별됩니다. Handlebars는 디자인할 때가 아니라 렌더링할 때 페이지에서 콘텐츠를 삽입하거나 수정할 수 있는 간편한 기본서식 작성 엔진입니다.
헬프 센터에서 기본서식 작성 언어를 Curlybars라고 하며 대규모 Handlebars 언어 하위 집합을 구현합니다. 이 가이드에서는 이 언어를 사용해서 헬프 센터의 페이지를 사용자 지정하는 방법에 대해 설명합니다.
헬프 센터는 콘텐츠를 사용자 지정할 수 있는 도우미 및 명명된 특성을 제공합니다. 이들 중 일부는 모든 헬프 센터 페이지에서 공유하여 사용할 수 있습니다. 나머지는 특정 페이지에서만 사용할 수 있습니다.
예
{{#each comments}}
<li class="comment" id="{{comment_id}}">
<div class="comment-avatar {{#if author.agent}} comment-avatar-agent {{/if}}">
<img src="{{author.avatar_url}}" alt="Avatar" />
</div>
<div class="comment-container">
<header class="comment-header">
<strong class="comment-author">
{{author.name}}
</strong>
</header>
</div>
</li>
{{/each}}
이 예에서는 페이지에 댓글을 남긴 사용자의 목록을 만듭니다. each
도우미는 페이지에 있는 각 comments
특성의 값에서 반복됩니다. 각 댓글에서 author.avatar_url
및 author.name
특성의 값이 HTML에 삽입됩니다.
기본서식 작성의 기본 사항
이 섹션에서는 기본서식을 작성해야 하는 구성 단위에 대해 설명합니다. 자세한 내용은 developer.zendesk.com에서 헬프 센터 기본서식을 참조하세요.
Curlybars 기본서식은 글자 그대로 렌더링되는 축자(verbatim) 텍스트와 Curlybars 표현식 두 가지로 구성되어 있습니다. 즉, 비어 있는 기본서식도 유효하며 텍스트만 포함되어 있는 기본서식도 유효하다는 의미입니다. 예를 들어 다음 기본서식은 유효한 기본서식입니다.
<h1>Article</h1>
<p>Some details on the article</p>
헬프 센터 기본서식에는 축자(verbatim) 텍스트만 지원되지만 렌더링할 때 이러한 텍스트를 실제로 사용자 지정할 수 없습니다. 기본서식 작성 논리를 추가하려면 Curlybars 표현식이 필요하며 이중 중괄호로 묶어야 합니다({{
and }}
).
앞서 설명한 예에서 기본서식 작성 논리를 추가하려면 다음과 같이 기본서식을 수정해야 합니다.
<h1>Article</h1>
<p>Some details on the article</p>
{{article.author.name}}
아래 섹션에서는 기본서식에서 중요한 내용을 변경하기 위해 유효한 표현식을 작성하는 방법에 대해 설명합니다.
한 쌍의 중괄호 내에 다른 중괄호 쌍을 사용할 수 없습니다. 예를 들어 다음과 같은 구문은 유효하지 않습니다.
<h1>Article</h1>
<p>Some details on the article</p>
{{ {{ ... }} }}
주석
렌더링 페이지에는 반영되지 않는 메모를 기본서식에 사용하면 도움이 되는 경우도 있습니다. Curlybars에서는 {{! ... }}
). 이 예에서 이 구문을 사용하여 코드 주석을 추가할 수 있습니다.
{{!
This template aims to
show details of an article
}}
<h1>Article</h1>
<p>Some details on the article</p>
다음은 페이지가 렌더링된 후에 브라우저에 표시되는 내용입니다.
<h1>Article</h1>
<p>Some details on the article</p>
이렇게 주석 내에 있는 모든 내용을 버리는 기능은 실제로 기본서식을 만들 때 편리할 수 있습니다. 확인, 디버깅 등을 수행하려면 일부 코드에 주석을 달아야 할 수도 있습니다.
블록 주석
지금까지 설명한 주석 구문은 Curlybars 코드에 주석을 다는 데는 적합하지 않습니다. Curlybars 코드에 주석을 달려면 {{!-- ... ---}}
). 이러한 종류의 주석은 여러 줄에 걸쳐 사용할 수 있으므로 코드에 효과적으로 댓글을 달 수 있습니다. 예:
{{!
This template aims to
show details of an article
}}
<h1>Article</h1>
<p>Some details on the article</p>
{{!--
I want to commend out the following code:
{{ ... some Curlybars expressions }}
--}}
위의 기본서식은 다음과 같이 렌더링됩니다.
<h1>Article</h1>
<p>Some details on the article</p>
리터럴
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
은 경로입니다.
특성 값을 이중 중괄호로 묶어서 표시할 수 있습니다. 이 예에서는 다음과 같이 별도의 단락에 작성자 이름을 표시할 수 있습니다.
<h1>Article</h1>
<p>Author: {{article.author.name}}</p>
사용자가 John Venturini라는 상담원이 작성한 문서를 보려고 한다고 가정해 보죠. 이 경우 기본서식은 다음과 같이 렌더링됩니다.
<h1>Article</h1>
<p>Author: John Venturini</p>
문서 자체를 렌더링할 수도 있습니다. article
개체에는 문서 콘텐츠가 포함된 body
특성이 있습니다. 기본서식을 다음과 같이 수정하여 문서 본문을 렌더링합니다.
<h1>Article</h1>
<p>Author: {{article.author.name}}</p>
<article>{{article.body}}</article>
조건부
기본서식 언어를 사용하면 특성 값을 렌더링할 수 있을 뿐만 아니라 기본서식에 조건부 렌더링 논리를 추가할 수 있습니다.
예를 들어 요청된 문서가 내부용일 때 HTML 스니펫을 렌더링해야 하는 경우가 있습니다. 문서 페이지 컨텍스트에는 article.internal
특성이 있어, 문서가 내부용이면 true
를 리턴하고 그렇지 않으면 false
를 리턴합니다.
이 정보를 사용해서 if
블록을 만들 수 있습니다. if
표현식은 조건이 true 또는 false인지 지정해야 합니다. 이 결과에 따라 블록 콘텐츠가 렌더링될지 여부가 결정됩니다. 기본 구문은 다음과 같습니다.
{{#if condition}}
This is rendered if the condition is true.
{{/if}}
이 예에서 기본서식을 아래와 같이 수정할 수 있습니다.
<h1>Article</h1>
{{#if article.internal}}
<p>This article is internal.</p>
{{/if}}
<p>Author: {{article.author.name}}</p>
<article>{{article.body}}</article>
조건이 false일 때 블록을 렌더링해야 하는 경우에는 unless
블록을 사용합니다. 구문은 if
블록과 비슷합니다.
{{#unless condition}}
This is rendered if the condition is false.
{{/unless}}
이 예에서 문서가 내부용이 아니어도 메시지를 렌더링해야 하는 경우에는 아래와 같이 기본서식을 수정할 수 있습니다.
<h1>Article</h1>
{{#if article.internal}}
<p>This article is internal.</p>
{{/if}}
{{#unless article.internal}}
<p>This is a publicly visible article!</p>
{{/unless}}
<p>Author: {{article.author.name}}</p>
<article>{{article.body}}</article>
이러한 종류의 조건부 논리(값이 true일 때와 false일 때 수행되는 작업이 각각 다르게 지정됨)는 일반적으로 if-else
블록에서 처리됩니다. 구문은 다음과 같습니다.
{{#if condition}}
This is rendered if the condition is true.
{{else}}
This is rendered if the condition is false.
{{/if}}
이 예를 아래와 같이 수정할 수 있습니다.
<h1>Article</h1>
{{#if article.internal}}
<p>This article is internal.</p>
{{else}}
<p>This is a publicly visible article!</p>
{{/if}}
<p>Author: {{article.author.name}}</p>
<article>{{article.body}}</article>
unless
블록에는 unless-else
변형도 포함되어 있습니다. 이 변형을 사용하면 if-else
블록과 동일한 결과를 얻을 수 있습니다.
<h1>Article</h1>
{{#unless article.internal}}
<p>This is a publicly visible article!</p>
{{else}}
<p>This article is internal.</p>
{{/unless}}
<p>Author: {{article.author.name}}</p>
<article>{{article.body}}</article>
조건을 평가하는 방법
일반적으로 조건은 article.internal
과 같은 헬프 센터의 특성이며, true 또는 false 부울 값이 있습니다. 일부 특성에는 부울 값이 없으며 이러한 특성은 다음과 같이 평가됩니다.
-
값이 숫자이면 0은 false이고 그밖의 숫자는 true입니다.
-
값이 문자열이면 빈 문자열은 false이고 그밖의 문자열은 true입니다.
-
값이 개체 모음이면 빈 모음은 false이고 그밖의 모음은 true입니다.
-
값이 null이면 표현식은 false입니다.
숫자를 확인하는 몇 가지 조건부 논리를 설정한다고 가정해 보죠. 문서 페이지에 있는 문서의 총 댓글 수가 포함된 article.comment_count
특성이 있습니다. if
조건을 사용해서 총 댓글 수가 0
이 아닌지 확인하고 응원 메시지를 표시할 수 있습니다. 예:
<h1>Article</h1>
<p>Author: {{article.author.name}}</p>
<article>{{article.body}}</article>
{{#if article.comment_count}}
<p>Yahoo! This article has got some comments!</p>
{{/if}}
공백 잘라내기
Curlybars에서 기본서식을 처리할 때 모든 축자(verbatim) 텍스트를 있는 그대로 표시합니다. 이 방식은 대부분의 경우 유용하게 활용됩니다. 하지만 표현식 옆의 공백 문자를 보다 정교하게 제어해야 하는 경우가 있습니다. 다음 코드를 예로 들겠습니다.
<a href="..." class="{{#if highlighted}} highlight {{/if}}">Click me!</a>
highlighted
가 true이면 다음 HTML이 렌더링됩니다.
<a href="..." class=" highlight ">Click me!</a>
highlight 단어 앞뒤에는 공백이 있습니다. 물론 이렇게 두어도 괜찮지만, 공백을 렌더링하지 않고 기본서식에 유지해야 하는 경우에는 물결 문자(~)를 사용할 수 있습니다.
여는 중괄호 또는 닫는 중괄호에 물결 문자를 추가하면 괄호로 묶인 텍스트에서 공백이 잘립니다. 예:
<a href="..." class="{{#if highlighted~}} highlight {{~/if}}">Click me!</a>
물결 문자가 highlight 단어 앞뒤에 있는 공백을 잘라냅니다.
<a href="..." class="highlight">Click me!</a>
물결 문자는 시각적 표현이 없는 모든 공백 문자를 잘라내지만 새 줄, 탭, 캐리지 리턴, 줄 바꿈 또는 단순 공백 등과 같이 줄 간격을 조절하거나 줄을 분할할 때 영향을 줍니다. 이 예는 이해를 돕기 위한 것이므로 참고용으로만 사용하고, 실제 작업에서는 앞에서 설명한 if
블록을 여러 줄에 사용하면 보다 이해하기 쉽게 표현할 수 있습니다. 예:
<a href="..." class="
{{~#if highlighted~}}
highlight
{{~/if~}}
">Click me!</a>
이렇게 수정해도 다음과 같이 렌더링됩니다.
<a href="..." class="highlight">Click me!</a>
이러한 예가 실제 작업에 크게 도움이 되지는 않지만, 물결 문자의 효과는 실제 사례마다 따라 다를 수 있습니다.
도우미
일부 기본서식에서는 데이터에 액세스하고, 데이터를 표시하며, 몇 가지 조건부 논리를 추가하기만 해도 됩니다. 하지만 부가적인 기능이 필요할 수 있습니다. 예를 들어 페이지 요청자의 로캘에 따라 변경되는 현지화된 문자열을 표시하거나 길이가 긴 텍스트 구절을 잘라야 하는 경우가 있습니다.
도우미를 사용하면 이러한 종류의 기능을 기본서식에서 활용할 수 있습니다. 기본서식에 사용할 수 있는 모든 도우미를 확인하려면 developer.zendesk.com에서 헬프 센터 기본서식을 참조하세요.
예를 들어 문서 페이지 기본서식에 excerpt
라고 하는 도우미를 사용해서 문자열을 자를 수 있습니다. 이 예에서 문서 제목이 잘린 버전을 표시해야 하는 경우에는 다음과 같이 기본서식을 수정하면 됩니다.
<h1>{{excerpt article.title characters=50}}</h1>
<p>Author: {{article.author.name}}</p>
<article>{{article.body}}</article>
위 예에서는 도우미를 호출하는 데 중괄호를 사용했습니다. excerpt
도우미에는 문자열로 인식되는 표현식으로 구성되는 매개변수를 사용할 수 있습니다. 이 도우미에는 유지할 문자 수를 지정할 수 있는 characters
옵션이 있습니다. characters
옵션은 필수가 아니며 이 옵션을 지정하지 않으면 기본값이 사용됩니다. 자세한 내용은 헬프 센터 기본서식의 excerpt를 참조하세요.
도우미를 호출하는 구문은 {{<helper> [<param> ...] [<key=value> ...]}}
입니다. 여기에서 필수 요소는 도우미 이름뿐이며 매개변수와 옵션은 도우미에 따라 다릅니다.
이제 작성자 이름이 John Venturini일 때 응원 메시지가 표시되도록 기본서식을 업데이트한다고 가정해 보죠. 안타깝게도 if
조건을 사용해서 article.author.name
이 "John Venturini"
인지 확인할 수 없습니다. if
는 하나의 표현식에서만 작동하기 때문입니다. ==
등과 같은 비교 연산자를 사용할 수 없습니다.
그렇다면 어떻게 논리를 추가할 수 있을까요? is
도우미를 사용하면 됩니다. 이 도우미는 두 개의 매개변수를 비교하여 서로 같은지 확인합니다. 예:
<h1>{{excerpt article.title characters=50}}</h1>
{{#is article.author.name 'John Venturini'}}
<p>Cool! John Venturini is the author of this article!</p>
{{/is}}
<article>{{article.body}}</article>
위의 스니펫은 작성자가 John Venturini일 때 응원 메시지를 렌더링합니다. 하지만 작성자가 다른 사람일 때 다른 메시지를 렌더링해야 하는 경우는 어떨까요? 다행히도 is
에는 else
블록(if-else
문과 같은 역할)도 포함되어 있습니다. 작성자가 John Venturini가 아닐 때 이전의 메시지를 복원하려면 다음과 같이 else
블록을 추가하면 됩니다.
<h1>{{excerpt article.title characters=50}}</h1>
{{#is article.author.name 'John Venturini'}}
<p>Cool! John Venturini is the author of this article!</p>
{{else}}
<p>Author: {{article.author.name}}</p>
{{/is}}
<article>{{article.body}}</article>
범위 변경하기
필요한 정보를 찾아 갈 수 있는 경로가 너무 길지 않으면 점 표기법을 사용해서 간편하게 데이터에 액세스할 수 있습니다 예: article.title
). 하지만 경로가 긴 특성에 액세스해야 하는 경우도 있습니다 예: article.author.name
). 원할 경우 기본서식에 길이가 더 긴 경로를 사용할 수 있습니다. 예를 들어 이 예에서 다음과 같이 작성자 이름과 아바타를 추가할 수 있습니다.
<h1>{{excerpt article.title characters=50}}</h1>
<img src="{{article.author.avatar_url}}" alt="Author's avatar" height="42" width="42">
{{#is article.author.name 'John Venturini'}}
<p>Cool! John Venturini is the author of this article!</p>
{{else}}
<p>Author: {{article.author.name}}</p>
{{/is}}
<article>{{article.body}}</article>
위의 스니펫에 문제는 없지만, 특성의 경로가 길면 코드가 산만해질 수 있습니다. 이 문제를 해결할 수 있는 한 가지 방법은 with
라고 하는 특수 문을 사용하는 것입니다. with
문에는 연관된 코드 블록에 사용할 기본 컨텍스트를 나타내는 매개변수 하나를 사용할 수 있습니다. 구문은 다음과 같습니다.
{{#with <context>}}
...
{{/with}}
이 예를 아래와 같이 수정하여 개선할 수 있습니다.
<h1>{{excerpt article.title characters=50}}</h1>
{{#with article.author}}
<img src="{{avatar_url}}" alt="Author's avatar" height="42" width="42">
{{#is name 'John Venturini'}}
<p>Cool! John Venturini is the author of this article!</p>
{{else}}
<p>Author: {{name}}</p>
{{/is}}
{{/with}}
<article>{{article.body}}</article>
article.author
매개변수를 사용하면 블록에 있는 모든 경로에 article.author
를 포함할 필요가 없습니다. 따라서 블록 내부에 있는 {{name}}
은 블록 외부에 있는 article.author.name
과 동일합니다.
article.author.name
은 article.author.article.author.name
과 동일하므로 블록에 사용할 수 없습니다. 이와 마찬가지로 article.title
을 사용해서 블록 내부에 있는 문서 제목에 액세스할 수 없습니다. 문서 개체는 블록 외부에 있는 루트 컨텍스트에서만 액세스할 수 있기 때문입니다.
with
를 사용해서 설정된 컨텍스트에서 나가고 외부 컨텍스트에 액세스하려면 경로에 ../
표기법을 사용하세요. 다음과 같이 with
블록 내부에 문서 제목을 렌더링할 수 있습니다.
<h1>{{excerpt article.title characters=50}}</h1>
{{#with article.author}}
{{../article.title}}
<img src="{{avatar_url}}" alt="Author's avatar" height="42" width="42">
{{#is name 'John Venturini'}}
<p>Cool! John Venturini is the author of this article!</p>
{{else}}
<p>Author: {{name}}</p>
{{/is}}
{{/with}}
<article>{{article.body}}</article>
같은 경로에 ../
표기법을 반복해서 사용할 수 있습니다. 컨텍스트 수는 동일하게 됩니다. 예를 들어 다음과 같이 코드를 작성해도 됩니다.
<h1>{{excerpt article.title characters=50}}</h1>
{{#with article}}
{{#with author}}
{{../../article.title}}
...
{{/with}}
<article>{{article.body}}</article>
좀 더 신중한 방법으로서, 작성자가 지정되어 있지 않을 때마다 특정 메시지를 렌더링하려면 다음과 같이 if
블록을 사용하면 됩니다.
<h1>{{excerpt article.title characters=50}}</h1>
{{#if article.author}}
{{#with article.author}}
...
{{/with}}
{{else}}
No author is present for this article!
{{/if}}
<article>{{article.body}}</article>
헬프 센터에서 article.author
는 null이 아니며 여기에 제시된 예에서는 이해를 돕기 위해 가정한 것뿐입니다.
위의 스니펫에 문제는 없지만 else
블록을 with
문에 사용해서 동일한 결과를 얻을 수 있습니다. 매개변수가 falsy이면 else 블록이 실행됩니다. 이 예를 아래와 같이 수정할 수 있습니다.
<h1>{{excerpt article.title characters=50}}</h1>
{{#with article.author}}
...
{{else}}
No author is present for this article!
{{/with}}
<article>{{article.body}}</article>
else
블록을 사용하면 코드의 가독성을 높일 수 있습니다.
루트 컨텍스트를 도우미에 전달하기
this
키워드를 사용해서 현재 루트 컨텍스트를 도우미에 전달할 수 있습니다. render_author
도우미에서 작성자에 대한 세부 정보를 표시하기 위해 article
개체를 매개변수로 사용할 수 있는 경우, 다음과 같이 this
키워드를 사용할 수 있습니다.
<h1>{{excerpt article.title characters=50}}</h1>
{{#with article}}
{{render_author this}}
{{/with}}
<article>{{article.body}}</article>
this
는 article
로 인식됩니다.
배열에 있는 항목에 액세스하기
일부 헬프 센터 특성은 개체 배열로 구성되어 있습니다. 예를 들어 attachments
특성은 첨부 파일의 배열로 구성됩니다.
배열에 있는 항목에 액세스하려면 각 항목을 반복해야 합니다. each
도우미를 사용하면 쉽게 반복할 수 있습니다. 예:
<h1>{{excerpt article.title characters=50}}</h1>
{{#with article.author}}
...
{{/with}}
<article>{{article.body}}</article>
{{#each attachments}}
<a href="{{url}}" target="_blank">{{name}}</a>
<span>({{size}})</span>
{{/each}}
위의 스니펫은 모든 첨부 파일을 나열합니다. 나열되는 각 항목에는 url
, name
및 size
등과 같이 첨부 파일 하나와 관련된 데이터가 표시됩니다.
with
와 마찬가지로 each
는 블록에서 컨텍스트를 변경합니다. 즉, 외부 컨텍스트에 액세스하기 위해 ../
표기법을 사용할 수 있습니다.
배열이 비어 있을 때 메시지를 렌더링하려는 경우에는 다음과 같이 if
블록을 사용하면 쉽게 렌더링할 수 있습니다.
...
{{#if attachments}}
{{#each attachments}}
<a href="{{url}}" target="_blank">{{name}}</a>
<span>({{size}})</span>
{{/each}}
{{else}}
Sorry, no attachments available!
{{/if}}
이렇게 코드를 작성해도 되지만 else
블록을 사용하면 코드의 가독성을 높일 수 있습니다.
...
{{#each attachments}}
<a href="{{url}}" target="_blank">{{name}}</a>
<span>({{size}})</span>
{{else}}
Sorry, no attachments available!
{{/each}}
Length
각 배열에는 해당 배열에 포함되는 요소 수를 지정하는 암시적인 length
특성이 있습니다. 예를 들어 첨부 파일 수를 표시하려면 다음과 같이 length
특성을 사용하면 됩니다.
...
There are {{attachments.length}}.
{{#each attachments}}
<a href="{{url}}" target="_blank">{{name}}</a>
<span>({{size}})</span>
{{/each}}