Loading...
Spring Framework Reference Documentation 7.0.2의 FreeMarker의 한국어 번역본입니다.
아래의 경우에 피드백에서 신고해주신다면 반영하겠습니다.
감사합니다 :)
See equivalent in the Reactive stack
Apache FreeMarker는 HTML에서 email 및 기타 모든 종류의 text output을 생성하기 위한 텍스트 출력 템플릿 엔진입니다. Spring Framework는 FreeMarker 템플릿과 함께 Spring MVC를 사용하기 위한 내장 통합을 제공합니다.
See equivalent in the Reactive stack
다음 예제는 FreeMarker를 뷰 기술로 설정하는 방법을 보여줍니다:
1@Configuration 2@EnableWebMvc 3public class WebConfig implements WebMvcConfigurer { 4 5 @Override 6 public void configureViewResolvers(ViewResolverRegistry registry) { 7 registry.freeMarker(); 8 } 9 10 // Configure FreeMarker... 11 12 @Bean 13 public FreeMarkerConfigurer freeMarkerConfigurer() { 14 FreeMarkerConfigurer configurer = new FreeMarkerConfigurer(); 15 configurer.setTemplateLoaderPath("/WEB-INF/freemarker"); 16 configurer.setDefaultCharset(StandardCharsets.UTF_8); 17 return configurer; 18 } 19}
1@Configuration 2@EnableWebMvc 3class WebConfig : WebMvcConfigurer { 4 5 override fun configureViewResolvers(registry: ViewResolverRegistry) { 6 registry.freeMarker() 7 } 8 9 // Configure FreeMarker... 10 11 @Bean 12 fun freeMarkerConfigurer() = FreeMarkerConfigurer().apply { 13 setTemplateLoaderPath("/WEB-INF/freemarker") 14 setDefaultCharset(StandardCharsets.UTF_8) 15 } 16}
다음 예제는 XML에서 동일한 설정을 구성하는 방법을 보여줍니다:
1<mvc:annotation-driven/> 2 3<mvc:view-resolvers> 4 <mvc:freemarker/> 5</mvc:view-resolvers> 6 7<!-- Configure FreeMarker... --> 8<mvc:freemarker-configurer> 9 <mvc:template-loader-path location="/WEB-INF/freemarker"/> 10</mvc:freemarker-configurer>
또한 다음 예제에서 보듯이, 모든 프로퍼티에 대한 완전한 제어를 위해 FreeMarkerConfigurer 빈을 선언할 수도 있습니다:
1<bean id="freemarkerConfig" class="org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer"> 2 <property name="templateLoaderPath" value="/WEB-INF/freemarker/"/> 3 <property name="defaultEncoding" value="UTF-8"/> 4</bean>
템플릿은 앞의 예제에 표시된 FreeMarkerConfigurer에 의해 지정된 디렉터리에 저장되어야 합니다. 앞의 설정에 따라, 컨트롤러가 welcome이라는 뷰 이름을 반환하면, 리졸버는 /WEB-INF/freemarker/welcome.ftl 템플릿을 찾습니다.
See equivalent in the Reactive stack
적절한 빈 프로퍼티를 FreeMarkerConfigurer 빈에 설정함으로써 FreeMarker Configuration 객체(이는 Spring에 의해 관리됨)에 FreeMarker 'Settings'와 'SharedVariables'를 직접 전달할 수 있습니다. freemarkerSettings 프로퍼티는 java.util.Properties 객체를 필요로 하고, freemarkerVariables 프로퍼티는 java.util.Map을 필요로 합니다.
다음 예제는 FreeMarkerConfigurer를 사용하는 방법을 보여줍니다:
1<bean id="freemarkerConfig" class="org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer"> 2 <property name="templateLoaderPath" value="/WEB-INF/freemarker/"/> 3 <property name="freemarkerVariables"> 4 <map> 5 <entry key="xml_escape" value-ref="fmXmlEscape"/> 6 </map> 7 </property> 8</bean> 9 10<bean id="fmXmlEscape" class="freemarker.template.utility.XmlEscape"/>
Configuration 객체에 적용되는 설정과 변수에 대한 자세한 내용은 FreeMarker 문서를 참조하십시오.
See equivalent in the Reactive stack
Spring은 JSP에서 사용할 태그 라이브러리를 제공하며, 그 중에는 <spring:bind/> 요소도 포함됩니다. 이 요소는 주로 폼-백킹 객체의 값을 폼에 표시하고 웹 또는 비즈니스 계층에서 Validator에 의해 실패한 검증 결과를 보여줄 수 있게 해줍니다.
Spring은 FreeMarker에서도 동일한 기능을 지원하며, 폼 입력 요소 자체를 생성하기 위한 추가적인 편의 매크로도 제공합니다.
See equivalent in the Reactive stack
표준 매크로 집합이 FreeMarker용으로 spring-webmvc.jar 파일 내에 유지되므로, 적절히 설정된 애플리케이션에서는 항상 사용할 수 있습니다.
Spring 템플릿 라이브러리에 정의된 매크로 중 일부는 내부(private)로 간주되지만, 매크로 정의에는 그러한 스코핑이 존재하지 않으므로 모든 매크로가 호출 코드와 사용자 템플릿에 보이게 됩니다. 다음 섹션에서는 템플릿 내에서 직접 호출해야 하는 매크로에만 초점을 맞춥니다. 매크로 코드를 직접 보고 싶다면, 파일 이름은 spring.ftl이며 org.springframework.web.servlet.view.freemarker 패키지에 있습니다.
Spring MVC 컨트롤러에 대한 폼 뷰 역할을 하는 FreeMarker 템플릿 기반의 HTML 폼에서, 다음 예제와 유사한 코드를 사용하여 필드 값에 바인딩하고 각 입력 필드에 대해 JSP와 유사한 방식으로 오류 메시지를 표시할 수 있습니다.
다음 예제는 personForm 뷰를 보여줍니다:
1<!-- FreeMarker macros have to be imported into a namespace. 2 We strongly recommend sticking to 'spring'. --> 3<#import "/spring.ftl" as spring/> 4<html> 5 ... 6 <form action="" method="POST"> 7 Name: 8 <@spring.bind "personForm.name"/> 9 <input type="text" 10 name="${spring.status.expression}" 11 value="${spring.status.value?html}"/><br /> 12 <#list spring.status.errorMessages as error> <b>${error}</b> <br /> </#list> 13 <br /> 14 ... 15 <input type="submit" value="submit"/> 16 </form> 17 ... 18</html>
<@spring.bind>는 'path' 인수가 필요하며, 이는 커맨드 객체의 이름(컨트롤러 설정에서 변경하지 않았다면 'command')과 바인딩하려는 커맨드 객체의 필드 이름을 마침표로 구분하여 구성됩니다. command.address.street와 같은 중첩 필드도 사용할 수 있습니다.
bind 매크로는 web.xml의 ServletContext 파라미터 defaultHtmlEscape에 의해 지정된 기본 HTML 이스케이프 동작을 가정합니다.
<@spring.bindEscaped>라고 하는 매크로의 대체 형태는 상태 오류 메시지나 값에 HTML 이스케이프를 사용할지 여부를 명시적으로 지정하는 두 번째 인수를 받습니다. 필요에 따라 true 또는 false로 설정할 수 있습니다.
추가적인 폼 처리 매크로는 HTML 이스케이프 사용을 단순화하며, 가능한 한 이러한 매크로를 사용해야 합니다. 이들은 다음 섹션에서 설명합니다.
FreeMarker용 추가 편의 매크로는 바인딩과 폼 생성(검증 오류 표시 포함)을 모두 단순화합니다. 이러한 매크로를 사용하여 폼 입력 필드를 생성할 필요는 전혀 없으며, 이전에 강조한 Spring 바인드 매크로에 대한 직접 호출이나 단순 HTML과 섞어서 사용할 수 있습니다.
다음 사용 가능한 매크로 표는 FreeMarker 템플릿(FTL) 정의와 각 매크로가 받는 파라미터 목록을 보여줍니다:
| macro | FTL definition |
|---|---|
message (code 파라미터를 기반으로 리소스 번들에서 문자열을 출력) | <@spring.message code/> |
messageText (code 파라미터를 기반으로 리소스 번들에서 문자열을 출력하고,<br>default 파라미터의 값으로 폴백) | <@spring.messageText code, text/> |
url (relative URL 앞에 애플리케이션의 컨텍스트 루트를 접두) | <@spring.url relativeUrl/> |
formInput (사용자 입력을 수집하기 위한 표준 입력 필드) | <@spring.formInput path, attributes, fieldType/> |
formHiddenInput (사용자 입력이 아닌 값을 제출하기 위한 hidden 입력 필드) | <@spring.formHiddenInput path, attributes/> |
formPasswordInput (password를 수집하기 위한 표준 입력 필드. 이 타입의 필드에는<br>어떠한 값도 채워지지 않는다는 점에 유의하십시오.) | <@spring.formPasswordInput path, attributes/> |
formTextarea (길고 자유 형식의 텍스트 입력을 수집하기 위한 large 텍스트 필드) | <@spring.formTextarea path, attributes/> |
formSingleSelect (단일 필수 값을 선택할 수 있는 option의 드롭다운 박스) | <@spring.formSingleSelect path, options, attributes/> |
formMultiSelect (사용자가 0개 이상의 값을 선택할 수 있는 option의 리스트 박스) | <@spring.formMultiSelect path, options, attributes/> |
formRadioButtons (사용 가능한 선택지에서 하나만 선택할 수 있는 라디오 버튼 집합) | <@spring.formRadioButtons path, options separator, attributes/> |
formCheckboxes (0개 이상의 값을 선택할 수 있는 체크박스 집합) | <@spring.formCheckboxes path, options, separator, attributes/> |
formCheckbox (단일 체크박스) | <@spring.formCheckbox path, attributes/> |
showErrors (바인딩된 필드에 대한 검증 오류 표시를 단순화) | <@spring.showErrors separator, classOrStyle/> |
Table 1. Table of macro definitions
FreeMarker 템플릿에서는
formHiddenInput과formPasswordInput이 실제로는 필요하지 않습니다.<br>일반formInput매크로를 사용하여fieldType파라미터의 값으로hidden또는password를<br>지정하면 되기 때문입니다.
위 매크로에 대한 파라미터는 모두 일관된 의미를 가집니다:
path: 바인딩할 필드의 이름(예: "command.name")options: 입력 필드에서 선택할 수 있는 모든 사용 가능한 값을 담은 Map. 맵의 key는 폼에서 POST되어 커맨드 객체에 바인딩되는 값입니다. key에 저장된 Map 객체는 폼에 사용자에게 표시되는 label이며, 폼이 다시 post하는 해당 값과는 다를 수 있습니다. 일반적으로 이러한 맵은 컨트롤러에서 참조 데이터로 제공됩니다. 요구되는 동작에 따라 임의의 Map 구현을 사용할 수 있습니다. 엄격하게 정렬된 맵의 경우, 적절한 Comparator를 가진 SortedMap(예: TreeMap)을 사용할 수 있고, 삽입 순서대로 값을 반환해야 하는 임의의 Map의 경우, LinkedHashMap 또는 commons-collections의 LinkedMap을 사용할 수 있습니다.separator: 여러 option이 개별 요소(라디오 버튼 또는 체크박스)로 제공되는 경우, 목록에서 각 요소를 구분하는 데 사용되는 문자 시퀀스(예: <br>).attributes: HTML 태그 자체 내에 포함될 임의의 태그나 텍스트의 추가 문자열. 이 문자열은 매크로에 의해 그대로 에코됩니다. 예를 들어, textarea 필드에서는 'rows="5" cols="60"'과 같은 속성을 제공하거나, 'style="border:1px solid silver"'와 같은 스타일 정보를 전달할 수 있습니다.classOrStyle: showErrors 매크로의 경우, 각 오류를 감싸는 span 요소가 사용하는 CSS 클래스의 이름입니다. 아무 정보도 제공되지 않거나 값이 비어 있으면, 오류는 <b></b> 태그로 감싸집니다.다음 섹션에서는 매크로 예제를 간략히 설명합니다.
formInput 매크로는 path 파라미터(command.name)와 추가 attributes 파라미터(다음 예제에서는 비어 있음)를 받습니다. 이 매크로는 다른 모든 폼 생성 매크로와 마찬가지로 path 파라미터에 대해 암시적인 Spring 바인딩을 수행합니다. 바인딩은 새 바인딩이 발생할 때까지 유효하므로, showErrors 매크로는 path 파라미터를 다시 전달할 필요가 없습니다. 이는 마지막으로 바인딩이 생성된 필드에 대해 동작합니다.
showErrors 매크로는 separator 파라미터(주어진 필드에서 여러 오류를 구분하는 데 사용되는 문자)를 받고, 두 번째 파라미터로 클래스 이름이나 스타일 속성도 허용합니다. FreeMarker는 attributes 파라미터에 대한 기본값을 지정할 수 있다는 점에 유의하십시오.
다음 예제는 formInput과 showErrors 매크로를 사용하는 방법을 보여줍니다:
1<@spring.formInput "command.name"/> 2<@spring.showErrors "<br>"/>
다음 예제는 폼 조각의 출력을 보여주며, name 필드를 생성하고 필드에 값이 없는 상태에서 폼이 제출된 후 검증 오류를 표시합니다. 검증은 Spring의 검증 프레임워크를 통해 수행됩니다.
생성된 HTML은 다음 예제와 유사합니다:
1Name: 2<input type="text" name="name" value=""> 3<br> 4 <b>required</b> 5<br> 6<br>
formTextarea 매크로는 formInput 매크로와 동일한 방식으로 동작하며 동일한 파라미터 목록을 받습니다. 일반적으로 두 번째 파라미터(attributes)는 textarea에 대한 스타일 정보 또는 rows와 cols 속성을 전달하는 데 사용됩니다.
HTML 폼에서 일반적인 UI 값 선택 입력을 생성하기 위해 네 가지 선택 필드 매크로를 사용할 수 있습니다:
formSingleSelectformMultiSelectformRadioButtonsformCheckboxes위 네 매크로 각각은 폼 필드에 대한 값과 해당 값에 대응하는 label을 포함하는 Map 형태의 option을 받습니다. value와 label은 동일할 수 있습니다.
다음 예제는 FTL에서 라디오 버튼에 대한 예제입니다. 폼-백킹 객체는 이 필드에 대해 'London'이라는 기본값을 지정하므로 검증은 필요하지 않습니다. 폼이 렌더링될 때, 선택할 전체 city 목록은 모델에서 'cityMap'이라는 이름의 참조 데이터로 제공됩니다.
다음 listing은 예제를 보여줍니다:
1... 2Town: 3<@spring.formRadioButtons "command.address.town", cityMap, ""/><br><br>
앞의 listing은 cityMap의 각 값에 대해 하나의 라디오 버튼을 렌더링하며, separator로 ""를 사용합니다. 추가 속성은 제공되지 않습니다(매크로의 마지막 파라미터가 없음). cityMap은 맵의 각 key-value pair에 대해 동일한 String을 사용합니다. 맵의 key는 폼이 실제로 POST 요청 파라미터로 제출하는 값입니다. 맵 value는 사용자가 보는 label입니다.
앞의 예제에서, 세 개의 잘 알려진 city와 폼 백킹 객체의 기본값이 주어지면, HTML은 다음과 유사합니다:
1Town: 2<input type="radio" name="address.town" value="London">London</input> 3<input type="radio" name="address.town" value="Paris" checked="checked">Paris</input> 4<input type="radio" name="address.town" value="New York">New York</input>
애플리케이션이(예를 들어) 내부 코드로 city를 처리해야 하는 경우, 다음 예제에서 보듯이 적절한 key를 가진 코드의 맵을 생성할 수 있습니다:
1protected Map<String, ?> referenceData(HttpServletRequest request) throws Exception { 2 Map<String, String> cityMap = new LinkedHashMap<>(); 3 cityMap.put("LDN", "London"); 4 cityMap.put("PRS", "Paris"); 5 cityMap.put("NYC", "New York"); 6 7 Map<String, Object> model = new HashMap<>(); 8 model.put("cityMap", cityMap); 9 return model; 10}
1protected fun referenceData(request: HttpServletRequest): Map<String, *> { 2 val cityMap = linkedMapOf( 3 "LDN" to "London", 4 "PRS" to "Paris", 5 "NYC" to "New York" 6 ) 7 return hashMapOf("cityMap" to cityMap) 8}
이제 코드는 라디오 값이 관련 코드가 되도록 출력을 생성하지만, 사용자는 여전히 더 사용자 친화적인 city 이름을 보게 됩니다. 다음과 같습니다:
1Town: 2<input type="radio" name="address.town" value="LDN">London</input> 3<input type="radio" name="address.town" value="PRS" checked="checked">Paris</input> 4<input type="radio" name="address.town" value="NYC">New York</input>
앞에서 설명한 폼 매크로의 기본 사용은 HTML 4.01을 준수하는 HTML 요소를 생성하고, Spring의 바인드 지원에서 사용하는 web.xml 파일에 정의된 HTML 이스케이프 기본값을 사용합니다. 태그를 XHTML 준수로 만들거나 기본 HTML 이스케이프 값을 재정의하려면, 템플릿(또는 템플릿에서 볼 수 있는 모델)에 두 개의 변수를 지정할 수 있습니다.
이를 템플릿에서 지정하는 장점은, 폼의 서로 다른 필드에 대해 서로 다른 동작을 제공하기 위해 템플릿 처리 중 나중에 다른 값으로 변경할 수 있다는 점입니다.
태그에 대해 XHTML 준수로 전환하려면, 다음 예제에서 보듯이 xhtmlCompliant라는 이름의 모델 또는 컨텍스트 변수에 대해 true 값을 지정하십시오:
1<#-- for FreeMarker --> 2<#assign xhtmlCompliant = true>
이 지시문이 처리된 후에는 Spring 매크로에 의해 생성된 모든 요소가 이제 XHTML 준수입니다.
비슷한 방식으로, 다음 예제에서 보듯이 필드별로 HTML 이스케이프를 지정할 수 있습니다:
1<#-- until this point, default HTML escaping is used --> 2 3<#assign htmlEscape = true> 4<#-- next field will use HTML escaping --> 5<@spring.formInput "command.name"/> 6 7<#assign htmlEscape = false in spring> 8<#-- all future fields will be bound with HTML escaping off -->
Thymeleaf
Groovy Markup