HTL 언어 정리 (2. 표현식 옵션)

이전 글 : https://thinking-it.tistory.com/29

HTL 언어 정리 (1. 표현 언어, 구문 및 의미론)

 

해당 글은 아래 출처에서 가져온 것으로 자세한 것은 출처로 이동하여 봐주시길 바랍니다.

자료 출처 : https://github.com/adobe/htl-spec/blob/master/SPECIFICATION.md#121-display-context

해당 자료의 길이가 길어 분할하여 업로드하려고 합니다.

 

1.2 사용 가능한 표현식 옵션

1.2.1 디스플레이 컨텍스트

XSS(교차 사이트 스크립팅) 취약성으로부터 보호하기 위해 HTL은 출력 문자열이 최종 HTML 출력 내에 표시되는 컨텍스트를 자동으로 인식하고 해당 문자열을 적절하게 이스케이프합니다.

옵션 을 사용하여 자동 디스플레이 컨텍스트 처리를 재정의할 수도 있습니다 context.

${properties.jcr:title @ context='text'}

다음 표에는 사용 가능한 컨텍스트가 나열되어 있습니다.

 

문맥

사용시기

기능

attribute	속성 값의 기본값	모든 HTML 특수 문자를 인코딩합니다.
attributeName	속성 이름을 설정할 때 data-sly-attribute의 기본값	속성 이름의 유효성을 검사하고 유효성 검사에 실패하면 아무 것도 출력하지 않습니다.
elementName	data-sly-element의 기본값	요소 이름의 유효성을 검사하고 유효성 검사에 실패하면 아무 것도 출력하지 않습니다.
html	마크업을 안전하게 출력하려면	위험한 태그를 제거하기 위해 HTML을 필터링합니다.
number	숫자를 표시하려면	전달된 값이 숫자인지 확인하고, 확인에 실패하면 아무 것도 출력하지 않습니다.
scriptComment	JavaScript 주석 내	JavaScript 주석의 유효성을 검사하고 유효성 검사에 실패하면 아무 것도 출력하지 않습니다.
scriptString	JavsScript 문자열 내에서	문자열에서 벗어나는 문자를 인코딩합니다.
scriptToken	JavaScript 식별자, 리터럴 숫자 또는 리터럴 문자열의 경우	JavaScript 토큰의 유효성을 검사하고 유효성 검사에 실패하면 아무 것도 출력하지 않습니다.
styleComment	CSS 주석 내	CSS 주석의 유효성을 검사하고 유효성 검사에 실패하면 아무 것도 출력하지 않습니다.
styleString	CSS 문자열 내	문자열에서 벗어나는 문자를 인코딩합니다.
styleToken	CSS 식별자의 경우 숫자, 크기, 문자열, 16진수 색상 또는 기능.	CSS 토큰의 유효성을 검사하고 유효성 검사에 실패하면 아무 것도 출력하지 않습니다.
text	HTML 텍스트 노드 내부 콘텐츠의 기본값	모든 HTML 특수 문자를 인코딩합니다.
unsafe	다른 모든 컨텍스트가 너무 제한적일 때	이스케이프 및 XSS 보호를 완전히 비활성화합니다.
uri	링크 및 경로 표시 action, cite, data, formaction, href, 및 속성 값 manifest에 대한 기본값postersrc	URI의 유효성을 검사하고 유효성 검사에 실패하면 아무 것도 출력하지 않습니다.

 

context='elementName'다음 요소 이름만 허용됩니다 .

section, nav, article, aside, h1, h2, h3, h4, h5, h6, header, footer, address, main, p, pre, blockquote, ol, li, dl, dt, dd, figure, figcaption, div, a, em, strong, small, s, cite, q, dfn, abbr, data, time, code, var, samp, kbd, sub, sup, i, b, u, mark, ruby, rt, rp, bdi, bdo, span, br, wbr, ins, del, table, caption, colgroup, col, tbody, thead, tfoot, tr, td, th

HTML 주석 내에서 HTL 표현식을 사용하려면 출력하려는 ​​내용에 따라 컨텍스트를 조정해야 할 수 있습니다. 자동으로 암시되는 컨텍스트는 다음 comment과 같습니다.

<!--[if IE]><link rel="shortcut icon" href="${site.root @ context='uri'}/images/favicon/favicon.ico?v2"><![endif]-->

 

1.2.2 체재

Strings이 옵션 은 Dates및 를 포맷하는 데 사용할 수 있습니다 Numbers. 서식 패턴 문자열은 식에 제공되어야 하며 format옵션에는 사용할 값이 포함됩니다. 서식 유형은 다음에 따라 결정됩니다.

1. 옵션( 있는 type경우)(허용되는 값은 string, date및 number)
2. 패턴의 자리 표시자(예: {0}), 문자열 형식화 트리거
3. 유형 이 a 또는 a format인 경우 옵션 개체의 유형DateNumber
4. 기본값, 문자열 형식으로 대체

1.2.2.1 문자열

문자열 형식화는 i18n문자열이 사전을 통해 실행된 후 자리 표시자가 대체되도록 옵션과 결합할 수 있습니다.

<!--/* Numbered parameters for injecting variables: */-->
${'Asset {0}' @ format=properties.assetName}   <!--/* Basically a shortcut of the array notation, useful when it has only one element */-->
${'Asset {0}' @ format=[properties.assetName]}
${'Asset {0} out of {1}' @ format=[properties.current, properties.total]}
${'Asset {0} out of {1}' @ format=[properties.current, properties.total], i18n, locale='de'}

다음 출력을 생성합니다

Asset Night Sky
Asset Night Sky
Asset 3 out of 5
Bild 3 von 5

가정

properties.assetName = 'Night Sky'
properties.current   = 3
properties.total     = 5
formatter 'Asset {0} out of {1}' will be translated to 'Bild {0} von {1}' for the 'de' locale by i18n

 

1.2.2.2 날짜

날짜 형식은 시간대 및 현지화를 지원합니다. 국제화도 지정된 경우( i18n) 서식 패턴에 적용되고 서식 지정에 로케일이 전달됩니다.

<!--/* Formatting pattern: */-->
${'yyyy-MM-dd' @ format=myDate}
${'yyyy-MM-dd' @ format=myDate, type='date'}                <!--/* Forced formatting type */-->
${'yyyy-MM-dd HH:mm' @ format=myDate, timezone='GMT+00:30'} <!--/* Timezone */-->
${'EEEE, dd MMMM yyyy' @ format=obj.date, locale='de'}      <!--/* Locale */-->

서식 패턴은 최소한 다음 문자를 지원합니다.

• y- 년도. 변형: yy,yyyy
• M- 년 월. 변형: MM, MMM,MMMM
• w- 연중 주. 변형:ww
• D- 일 년 중 일. 변형: DD,DDD
• d- 월의 일. 변형:dd
• E- 요일 이름. 변형:EEEE
• a- 오전/오후 마커
• H- 시간(0-23). 변형:HH
• h- 오전/오후 시간. 변형:hh
• m- 분. 변형:mm
• s- 초 단위로. 변형:ss
• S- 밀리초. 변형:SSS
• z- 일반 시간대
• Z- RFC 822 시간대
• X- ISO 8601 시간대. 변형: XX,XXX

'A'에서 'Z'까지 그리고 'a'에서 'z'까지의 다른 모든 문자는 나중에 사용할 수 있도록 예약되어 있습니다. 필요한 경우 작은따옴표를 사용하여 이스케이프할 수 있습니다. 작은따옴표는 연속으로 두 개로 이스케이프됩니다. 다른 문자는 해석되지 않습니다.

${'yyyy-MM-dd HH:mm:ss.SSSXXX' @ format=obj.date, timezone='UTC'}
${'yyyy-MM-dd HH:mm:ss.SSSXXX' @ format=obj.date, timezone='GMT+02:00'}
${'yyyy-MM-dd HH:mm:ss.SSS(z)' @ format=obj.date, timezone='GMT+02:00'}
${'yyyy-MM-dd HH:mm:ss.SSSZ' @ format=obj.date, timezone='GMT+02:00'}
${'dd MMMM \'\'yy hh:mm a; \'day in year\': D; \'week in year\': w' @ format=obj.date, timezone='UTC'}
${'EEEE, d MMM y' @ format=obj.date, timezone='UTC', locale='de'}
${'EEEE, d MMM y' @ format=obj.date, timezone='UTC', locale='en_US', i18n}

날짜에 대해 다음 출력을 생성합니다.1918-12-01 00:00:00Z

1918-12-01 00:00:00.000Z
1918-12-01 02:00:00.000+02:00
1918-12-01 02:00:00.000(GMT+02:00)
1918-12-01 02:00:00.000+0200
01 December '18 12:00 AM; day in year: 335; week in year: 49
Sonntag, 1 Dez 1918
Sunday, Dec 1, 1918  <!--/* assuming the formatter 'EEEE, d MMM y' will be translated to 'EEEE, MMM d, y' for the 'en_US' locale by i18n */-->

 

1.2.2.3 숫자

숫자 서식은 현지화를 지원합니다. 국제화도 지정된 경우( i18n) 서식 패턴에 적용되고 서식 지정에 로케일이 전달됩니다.

<!--/* Formatting pattern: */-->
${'#.00' @ format=42}
${'#.00' @ format=myNumber, type='number'} <!--/* Forced formatting type */-->
${'#.00' @ format=myNumber, locale='de'}   <!--/* Locale */-->

서식 패턴은 세미콜론으로 구분된 양수 패턴과 음수 패턴을 모두 지원합니다. 각 하위 패턴은 접두사, 숫자 부분 및 접미사를 가질 수 있습니다. 부정 하위 패턴은 접두사 또는/및 접미사만 변경할 수 있습니다. 최소한 다음 문자가 지원됩니다.

• 0- 숫자, 없으면 0으로 표시
• #- 숫자, 부재시 표시되지 않음
• .- 소수 구분 기호
• -- 빼기 기호
• ,- 그룹화 구분 기호
• E- 가수와 지수 사이의 구분 기호
• ;- 하위 패턴 경계
• %- 100을 곱하고 백분율로 표시

작은따옴표를 사용하여 접두사 또는 접미사에서 문자를 이스케이프 처리할 수 있습니다. 작은따옴표는 연속으로 두 개로 이스케이프됩니다.

${'#,###.00' @ format=1000}
${'#.###;-#.###' @ format=obj.number}
${'#.00;(#.00)' @ format=obj.number}
${'#.000E00' @ format=obj.number}
${'#%' @ format=obj.number}
${ 'curr #,###.##' @ format=1000.14, locale='de_CH', i18n}

obj.number로 평가되는 경우 다음 출력을 생성합니다 -3.14.

1,000.00
-3.14
(3.14)
-.314E01
-314%
CHF 1'000.14 <!--/* assuming the formatter 'curr #,###.##' will be translated to 'CHF #,###.##' for the 'de_CH' locale by i18n */-->

 

1.2.3 i18n

이 옵션은 문자열을 국제화합니다.

${'Assets' @ i18n} <!--/* Translates the string to the resource language */-->

이 옵션을 사용하면 두 가지 추가 옵션이 특별한 의미를 갖습니다.

• locale: 설정하면 소스의 언어를 재정의합니다. 예: en_US또는fr_CH
• hint: 번역자를 위한 컨텍스트에 대한 일부 정보를 제공할 수 있습니다.

${'Assets' @ i18n, locale='en-US', hint='Translation Hint'}

 

1.2.4 어레이 조인

이 join옵션을 사용하면 구분 문자열을 지정하여 배열 개체의 출력을 제어할 수 있습니다.

${['one', 'two'] @ join='; '} <!--/* outputs: one; two */-->
 
<!--/* This can for e.g. be useful for setting class-names */-->
<span class="${myListOfClassNames @ join=' '}"></span>

간단한 문자열에 옵션을 적용하면 join문자열만 출력됩니다.

${'test' @ join=', '} <!--/*  outputs: test */-->

 

1.2.5 URI 조작

표현식에 다음 옵션을 추가하여 URI 조작을 수행할 수 있습니다.

• scheme- URI에 대한 체계 부분을 추가하거나 제거할 수 있습니다.

${'//example.com/path/page.html' @ scheme='http'}
<!-- outputs: http://example.com/path/page.html -->

${'http://example.com/path/page.html' @ scheme='https'}
<!-- outputs: https://example.com/path/page.html -->

${'http://example.com/path/page.html' @ scheme=''}
<!-- outputs: http://example.com/path/page.html -->

${'http://example.com/path/page.html' @ scheme}
<!-- outputs: http://example.com/path/page.html -->

• domain- URI에 대한 호스트 및 포트(도메인) 부분을 추가하거나 교체할 수 있습니다.

${'///path/page.html' @ domain='example.org'}
<!-- outputs: //example.org/path/page.html -->

${'http:///path/page.html' @ domain='example.org'}
<!-- outputs: http://example.org/path/page.html -->

${'http://www.example.com/path/page.html' @ domain='www.example.org'}
<!-- outputs: http://www.example.org/path/page.html -->

• path- 리소스를 식별하는 경로를 수정합니다.
• prependPath- 리소스를 식별하는 경로에 콘텐츠를 추가합니다.
• appendPath- 리소스를 식별하는 경로에 콘텐츠를 추가합니다.

${'one' @ appendPath='two'}
<!-- outputs: one/two -->

${'/one/' @ appendPath='/two/'}
<!-- outputs: /one/two/ -->

${'path' @ prependPath='..'}
<!-- outputs: ../path -->

${'path' @ prependPath='/', appendPath='/'}
<!-- outputs: /path/ -->

${'http://example.com/path/page.html' @ prependPath='foo'}
<!-- outputs: http://example.com/foo/path/page.html -->

${'path/page.selector.html/suffix?key=value#fragment' @ appendPath='appended'}
<!-- outputs: path/page/appended.selector.html/suffix?key=value#fragment -->

${'http://example.com/this/one.selector.html/suffix?key=value#fragment' @ path='that/two'}
<!-- outputs: http://example.com/that/two.selector.html/suffix?key=value#fragment -->

${'http://example.com/this/one.selector.html/suffix?key=value#fragment' @ path=''}
<!-- outputs: http://example.com/this/one.selector.html/suffix?key=value#fragment -->

${'http://example.com/this/one.selector.html/suffix?key=value#fragment' @ path}
<!-- outputs: http://example.com/this/one.selector.html/suffix?key=value#fragment -->

• selectors- URI에서 선택자를 수정하거나 제거합니다. 선택자는 리소스를 식별하는 부분(리소스의 경로)과 리소스를 나타내는 데 사용되는 확장자 사이의 URI 세그먼트입니다.
• addSelectors- 제공된 선택자(선택자 문자열 또는 선택자 배열)를 URI에 추가합니다.
• removeSelectors- URI에서 제공된 선택기(선택기 문자열 또는 선택기 배열)를 제거합니다.

${'path/page.woo.foo.html' @ selectors='foo.bar'}
<!-- outputs: path/page.foo.bar.html -->

${'path/page.woo.foo.html' @ selectors=['foo', 'bar']}
<!-- outputs: path/page.foo.bar.html -->

${'path/page.woo.foo.html' @ addSelectors='foo.bar'}
<!-- outputs: path/page.woo.foo.foo.bar.html -->

${'path/page.woo.foo.html' @ addSelectors=['foo', 'bar']}
<!-- outputs: path/page.woo.foo.foo.bar.html -->

${'path/page.woo.foo.html' @ removeSelectors='foo.bar'}
<!-- outputs: path/page.woo.html -->

${'path/page.woo.foo.html' @ removeSelectors=['foo', 'bar']}
<!-- outputs: path/page.woo.html -->

${'path/page.woo.foo.html' @ selectors}
<!-- outputs: path/page.html -->

${'path/page.woo.foo.html' @ selectors=''}
<!-- outputs: path/page.html -->

• extension- URI에서 확장자를 추가, 수정 또는 제거합니다.

${'path/page' @ extension='html'}
<!-- outputs: path/page.html -->

${'path/page.json' @ extension='html'}
<!-- outputs: path/page.html -->

${'path/page.selector.json' @ extension='html'}
<!-- outputs: path/page.selector.html -->

${'path/page.json/suffix' @ extension='html'}
<!-- outputs: path/page.html/suffix -->

${'path/page.json?key=value' @ extension='html'}
<!-- outputs: path/page.html?key=value -->

${'path/page.json#fragment' @ extension='html'}
<!-- outputs: path/page.html#fragment -->

${'path/page.json' @ extension}
<!-- outputs: path/page -->

• suffix- URI에서 접미사 부분을 추가, 수정 또는 제거합니다. 접미사는 확장과 쿼리 세그먼트 사이의 URI 세그먼트입니다.
• prependSuffix- 기존 접미사에 콘텐츠를 추가합니다.
• appendSuffix- 기존 접미사에 내용을 추가합니다.

${'path/page.html' @ suffix='my/suffix'}
<!-- outputs: path/page.html/my/suffix -->

${'path/page.html/some/suffix' @ suffix='my/suffix'}
<!-- outputs: path/page.html/my/suffix -->

${'path/page.html?key=value' @ suffix='my/suffix'}
<!-- outputs: path/page.html/my/suffix?key=value -->

${'path/page.html#fragment' @ suffix='my/suffix'}
<!-- outputs: path/page.html/my/suffix#fragment -->

${'path/page.html/suffix' @ prependSuffix='prepended'}
<!-- outputs: path/page.html/prepended/suffix -->

${'path/page.html/suffix' @ appendSuffix='appended'}
<!-- outputs: path/page.html/suffix/appended -->

${'path/page.html/suffix' @ suffix}
<!-- outputs: path/page.html -->

• query- 맵 값의 내용에 따라 URI의 쿼리 세그먼트를 추가, 교체 또는 제거합니다.
• addQuery- 맵 값의 내용으로 URI의 쿼리 세그먼트를 추가하거나 확장합니다.
• removeQuery- URI의 기존 쿼리 세그먼트에서 식별된 매개변수를 제거합니다. 해당 값은 문자열 또는 문자열 배열일 수 있습니다.

<!--
    assuming that jsuse.query evaluates to:
    
    {
      "query": {
        "q" : "htl",
        "array" : [1, 2, 3]
      }
    }
-->

${'http://www.example.org/search' @ query=jsuse.query, context='uri'}
<!-- outputs: http://www.example.org/search?q=htl&array=1&array=2&array=3 -->

${'http://www.example.org/search?s=1' @ addQuery=jsuse.query, context='uri'}
<!-- outputs: http://www.example.org/search?s=1&q=htl&array=1&array=2&array=3 -->

${'http://www.example.org/search?s=1&q=htl' @ removeQuery='q', context='uri'}
<!-- outputs: http://www.example.org/search?s=1 -->

${'http://www.example.org/search?s=1&q=htl' @ removeQuery=['s', 'q'], context='uri'}
<!-- outputs: http://www.example.org/search -->

${'http://www.example.org/search?s=1&q=htl' @ query, context='uri'}
<!-- outputs: http://www.example.org/search -->

• fragment- URI의 조각 세그먼트를 추가, 수정 또는 대체합니다.

${'path/page' @ fragment='fragment'}
<!-- outputs: path/page#fragment -->

${'path/page#one' @ fragment='two'}
<!-- outputs: path/page#two -->

${'path/page#one' @ fragment}
<!-- outputs: path/page -->