[Handlebars] View Engine 으로서의 Handlebars 기본 사용법

들어가기 전

저는 Handlebars 모듈을 사용하는 웹 소스코드를 분석하고자 간단한 사용법을 익히기 위해서 포스팅에 정리하고자 합니다. Handlebars 와 다른 View Engine 간의 장단점 및 차이점에 대해서는 다루지 않습니다.

Handlebars 란 무엇인가?

Handlebars 는 간단한 템플릿 언어입니다. Client Side 에서 HTML 태그 또는 다른 문자열들 사이에 템플릿 기호와 입력값을 함께 사용하여 표현에 사용됩니다.

<p>{{firstname}} {{lastname}}</p>

표현식은 {{ 로 시작해서 내용이 들어가고 }} 기호로 끝나는 형태입니다. 템플릿이 실행되면 이와 같은 표현식은 특정 값으로 대체됩니다.

 

Handlebars 설치법

가장 빨리 Handlebars 을 테스트해볼 수 있는 방법은 script 태그에서 CDN 을 불러와서 HTML 파일에 넣어서 사용해보는 것입니다.

<!-- CDN에 Handlebars 넣어서 사용함 -->
<script src="https://cdn.jsdelivr.net/npm/handlebars@latest/dist/handlebars.js"></script>
<script>
  // 템플릿을 컴파일함
  var template = Handlebars.compile("Handlebars <b>{{doesWhat}}</b>");
  // 컴파일된 템플릿을 실행하고, 콘솔로그로 출력해서 결과를 확인함
  console.log(template({ doesWhat: "rocks!" }));
</script>

그리고 이외에도 설치법은 다양하게 있는데, 만약 Node.js 서버에서 사용한다고 하면 npm(node package manager)이나 yarn 명령어로 설치해서 사용할 수도 있습니다.

npm install handlbars
# or
yarn add handlebars

그리고 require 함수를 이용해서 불러와서 사용할 수 있겠습니다.

const Handlebars = require("handlebars");
const template = Handlebars.compile("Name: {{name}}");
console.log(template({ name: "Nils" }));

 

공식문서에 의하면 node.js 외에도 RubyGems 환경에서도 사용할 수 있게 배포되어 있다고 합니다.

 

기본 사용법

기본 표현식(simple expression)

기본 사용법은 위에서도 언급했듯이 아래와 같이 {{ + 내용 + }} 형태입니다.

<p>{{firstname}} {{lastname}}</p>

그리고 여기에서 사용자가 만약 아래와 같은 입력을 줬다면,

{
    firstname: "Domdomi",
    lastname: "Kim"
}

표현식은 아래와 같이 입력 값들로 대체(replace)될 것입니다.

<p>Domdomi Kim</p>

Nested Input Objects 사용 예시

가끔 사용자 입력 객체로써 여러 객체나 배열 형태로 들어오는 경우가 있습니다. 예를 들어 아래와 같이요.

{
  person: {
    firstname: "Domdomi",
    lastname: "Kim",
  },
}

이런 경우에는 dot-notation 을 통해 객체에 내장되어 있는 속성들을 가져와 사용할 수 있습니다.

{{person.firstname}} {{person.lastname}}

그리고 이전에는 사용되어왔고, 지금은 deprecated 되었다고 알려지는 / 문법(path expression) 도 사용할 수 있다고 합니다.

{{person/fistname}} {{person/lastname}}

HTML-escaping

Handlebars에서는 기본적으로 {{표현식}} 형태를 사용하면 자동으로 HTML-escaped 된 형태가 된다고 합니다. 즉, 만약 표현식에 & 연산자가 포함되었다고 하면 & 형태로 변환되서 출력되게 되는 것입니다.

만약 Handlebars 표현식에서 이와 같이 HTML-escaped 되지 않게 하려면 {{{ 표현식 }}} 형태로 사용해야 합니다. 중괄호를 3개를 써야하는 것입니다.

raw: {{{specialChars}}}
html-escaped: {{specialChars}}

예시를 들어보면 아래와 같습니다. 만약 아래와 같은 형태로 입력값을 넘겼다고 가정하면,

{ specialChars: "& < > \" ' ` =" }

바로 위에서 언급한 템플릿 문법을 적용하여 아래와 같은 결과가 나오게 됩니다.

raw: & < > " ' ` =
html-escaped: &amp; &lt; &gt; &quot; &#x27; &#x60; &#x3D;

 

Helpers

조건문(if, unless), 반복문(each), lookup, log 와 같은 Built-in Helper도 있고, 직접 사용자가 Helper 를 정의해서 사용할 수도 있습니다. 간단하게 Helper 의 개념을 알아보기 위해서 아래의 예시를 보도록 하겠습니다.

#if

if문 helper 는 특정 조건 하에 block 을 렌더링 할 수 있게 해주는 helper 입니다. 만약 인자값으로 false, undefined, null, "", 0, 또는 [] 와 같은 값이 반환되어졌다면, Handlebars 는 렌더링하지 않고 그 외의 경우의 값이 들어오면 block을 렌더링하는 예시를 보도록하겠습니다.

<div class="entry">
{{#if author}}
<h1>{{firstName}} {{lastName}}</h1>
{{/if}}
</div>

그리고 사용자가 입력값으로 아래와 같이 줬다고 했을 때,

{
  author: true,
  firstName: "Domdomi",
  lastName: "Kim",
}

위 템플릿을 적용하게 되면 아래와 같은 결과가 나오게 됩니다.

<div class="entry">
<h1>Domdomi Kim</h1>
</div>

그리고 만약에 사용자 입력값이 공백(JSON 객체로 표현하면 { })이라면, author 변수는 undefined 가 될 것이고, if 문에서 author 값은 참이 아닌 거짓이 될 것입니다. 그리고 그 결과로 템플릿이 렌더링되면 아래와 같은 결과가 나오게 되겠습니다.

<div class="entry"></div>

입력값을 대문자로 변환하는 Helper 만들기

Built-in 즉 이미 Handlebars 측에서 미리 만들어둔 빌트인 Helper 외에도 사용자가 직접 만들어서 사용할 수 있다고 했습니다. 이번에는 사용자가 입력한 값을 대문자로 변환해주는 Helper 를 만들어보겠습니다.

Handlebars.registerHelper('toUpper', function(aString) {
    return aString.toUpperCase();
});

위와 같이 Handlebars.registerHelper 라는 함수를 활용해서 런타임에 helper를 등록할 수 있습니다. 그리고 toUpper 라는 이름의 Helper를 만들었고, 해당 콜백함수에서는 인자로 받은 aString 파라미터 값의 내용을 String.toUpperCase() 함수를 호출한 결과를 반환하도록 했습니다. 이로써 사용자가 입력한 값을 대문자로 변환해주는 Helper 를 완성한 것입니다.

이제 실제로 템플릿에서 사용해보겠습니다.

{{firstname}} {{toUpper lastname}}

그럼 toUpper 라는 이름의 Helper 로 인해 lastname 변수의 값인 문자열은 아래와 같이 문자열로 바뀔 겁니다.

Domdomi KIM

 

Helper 는 함수로 구현되는 만큼 파라미터를 줄 수 있게끔도 할 수 있습니다. 자세한 이외의 다양한 활용법은 공식문서를 참고해보시면 쉽게 사용법을 알 수 있습니다.

https://handlebarsjs.com/guide/expressions.html#helpers

Expressions | Handlebars

Partials

Handlebars 에서는 템플릿 재사용을 가능하게 해주는데요, 바로 partials 가 그 역할을 해줍니다. Partials 사용법도 다양한데요, 우선 저는 간단하게 기본 사용법에 대한 설명만 해보겠습니다.

우선 partial 을 사용하기 위해서는 등록절차가 필요합니다. 이는 javascript 기준으로 말하는 것이고, Handlebars 모듈 사용 환경에 따라 등록철차나 코드가 달라질 수 있습니다.

Handlebars.registerPartial('myPartial', '{{prefix}}');

Handlebars.registerPartial 함수를 통해서 myPartial 이란 이름으로 partial 을 등록했습니다.

그리고 partial 을 호출해서 사용할 때는 특수하게 사용되는 문법이 있는데, 아래와 같습니다.

{{> myPartial }}

그리고 사실 이것만 봐서는 사용처에 대한 이해가 잘 안되기 때문에 웹서버에서 일반적으로 view engine 으로 사용될 때의 partials 사용법을 익혀보면 이해가 쉽습니다.

 

Node.js 웹서버에서 아래와 같이 partials 등록을 했다고 하면,

Handlebars.registerPartials('./views/partials');

이제 views 디렉토리 하위에 있는 partials 디렉토리 하위 파일들 중 hbs 확장자 파일들을 모두 partials 로 등록하겠다는 의미가 되겠습니다.

 

그리고 만약에 ./views/partials/footer.hbs 파일이 있다고 하고 그 내용으로는 아래와 같다면,

<footer>
    <p>Created by {{name}}</p>
</footer>

그리고 ./views/index.hbs 파일에서 위의 footer.hbs 파일을 partials 로 불러온다는 코드를 작성하면 아래와 같습니다.

<!DOCTYPE html>

<html>
    <head>
        <title>test</title>
    </head>
    <body>
        <h1>hello</h1>
        {{>footer}}
    </body>
</html>

그리고 위 템플릿을 렌더링할 때 입력 값으로 name 에 Domdomi 라고 주어진다면 아래와 같은 결과가 나오게 됩니다.

<!DOCTYPE html>

<html>
    <head>
        <title>test</title>
    </head>
    <body>
        <h1>hello</h1>
        <footer>
            <p>Created by Domdomi</p>
        </footer>
    </body>
</html>

직접 실습해보기

Handlebars 에서는 직접 각종 표현식을 테스트하고 그 결과를 바로 알아볼 수 있게 실습환경(Playground)을 제공해줍니다. 아래 링크에 접속해보면 테스트해볼 수 있습니다.

https://handlebarsjs.com/playground.html#format=1&currentExample=%7B%22template%22%3A%22%7B%7Bfirstname%7D%7D%20%7B%7Blastname%7D%7D%22%2C%22partials%22%3A%5B%5D%2C%22input%22%3A%22%7B%5Cn%20%20firstname%3A%20%5C%22Domdomi%5C%22%2C%5Cn%20%20lastname%3A%20%5C%22Kim%5C%22%5Cn%7D%22%2C%22output%22%3A%22Domdomi%20Kim%22%2C%22preparationScript%22%3A%22%22%2C%22handlebarsVersion%22%3A%224.7.7%22%7D

Handlebars

 

마무리

Handlebars 에는 기본 표현식(Expression) 외에도 아까도 말한 Helpers 그리고 Hooks 나 Partials 개념도 있습니다.

더 자세한 정보는 handlebarsjs 공식문서를 참고하시면 되겠습니다.