FreeMarker

Apache FreeMarker – bu HTML, elektron pochta va boshqalar uchun har xil turdagi matn chiqarishni yaratish uchun shablonizator. Spring Framework o'z ichida Spring MVC ni FreeMarker shablonlari bilan ishlatish uchun integratsiyaga ega.

Ko'rinish Konfiguratsiyasi

Quyidagi misol FreeMarker-ni ko'rinish texnologiyasi sifatida qanday sozlashni ko'rsatadi:

@Configuration
@EnableWebMvc
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void configureViewResolvers(ViewResolverRegistry registry) {
        registry.freeMarker();
    }
    // FreeMarker-ni sozlash...
    @Bean
    public FreeMarkerConfigurer freeMarkerConfigurer() {
        FreeMarkerConfigurer configurer = new FreeMarkerConfigurer();
        configurer.setTemplateLoaderPath("/WEB-INF/freemarker");
        return configurer;
    }
}

@Configuration
@EnableWebMvc
class WebConfig : WebMvcConfigurer {
    override fun configureViewResolvers(registry: ViewResolverRegistry) {
        registry.freeMarker()
    }
    // FreeMarker-ni sozlash...
    @Bean
    fun freeMarkerConfigurer() = FreeMarkerConfigurer().apply {
        setTemplateLoaderPath("/WEB-INF/freemarker")
    }
}

Quyidagi misolda XML-da ham ayni narsani qanday sozlash mumkinligi ko'rsatilgan:

<mvc:annotation-driven/>
<mvc:view-resolvers>
    <mvc:freemarker/>
</mvc:view-resolvers>
<!-- FreeMarker-ni sozlash... -->
<mvc:freemarker-configurer>
    <mvc:template-loader-path location="/WEB-INF/freemarker"/>
</mvc:freemarker-configurer>

Bundan tashqari, FreeMarkerConfigurer binini barcha xususiyatlarni to'liq boshqarish uchun e'lon qilish mumkin, bu quyidagi misolda ko'rsatilgan:

<bean id="freemarkerConfig" class="org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer">
    <property name="templateLoaderPath" value="/WEB-INF/freemarker/"/>
</bean>

Shablonlaringiz, avvalgi misolda ko'rsatilganidek, FreeMarkerConfigurer tomonidan ko'rsatilgan katalogda saqlanishi kerak. Agar kontroler welcome ko'rinish nomini qaytarsa, konverter /WEB-INF/freemarker/welcome.ftl shablonini izlaydi.

FreeMarker Konfiguratsiyasi

"Settings" va "SharedVariable" ni FreeMarker’ga to'g'ridan-to'g'ri Configuration ob'ektiga o‘tkazish mumkin (bunga Spring tomonidan boshqariladi), FreeMarkerConfigurer binarda tegishli xususiyatlarini o'rnatib. freemarkerSettings xususiyati uchun java.util.Properties ob'ekti kerak bo'ladi, freemarkerVariables xususiyati uchun esa java.util.Map. Quyidagi misol FreeMarkerConfigurer dan qanday foydalanishni ko'rsatadi:

<bean id="freemarkerConfig" class="org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer">
    <property name="templateLoaderPath" value="/WEB-INF/freemarker/"/>
    <property name="freemarkerVariables">
        <map>
            <entry key="xml_escape" value-ref="fmXmlEscape"/>
        </map>
    </property>
</bean>
<bean id="fmXmlEscape" class="freemarker.template.utility.XmlEscape"/>

FreeMarker’ning Configuration ob'ektiga qo‘llaniladigan sozlamalar va o'zgaruvchilar haqida batafsil ma'lumotni FreeMarker hujjatlarida topishingiz mumkin.

Formani boshqarish

Spring JSP ichida ishlatish uchun teglari kutubxonasini taqdim etadi, boshqa narsalar qatori <spring:bind/> elementini o'z ichiga oladi. Ushbu element ayniqsa, formalarga asosiy form ob'ektlaridan qiymatlarni chiqarishga va Validatordan web yoki biznes darajasida muvaffaqiyatsiz tekshiruvlar natijalarini ko'rsatishga imkon beradi. Spring shuningdek xuddi shunday funksionallikni FreeMarker’da qo‘llab-quvvatlaydi, form kirish elementlarini yaratish uchun qo'shimcha qulay makro elementlar bilan.

Binding Makrolari

Standart makrolar to'plamining qo'llab-quvvatlash vositalari FreeMarker uchun spring-webmvc.jar faylida joylashgan, shuning uchun ular mos ravishda sozlangan dastur uchun har doim mavjud.

Spring'da shablon kutubxonalari tomonidan belgilangan ba'zi makrolar ichki (privat) hisoblanadi, lekin makrolarning aniq cheklovlari yo'q, bu esa barcha makrolarni chaqiruvchi kod va foydalanuvchi shablonlari uchun ko'rinadigan qiladi. Quyidagi bo'limlar faqat shablonlardan to'g'ridan-to'g'ri chaqirilishi kerak bo'lgan makrolarga bag'ishlangan. Agar siz makro kodini bevosita ko'rib chiqmoqchi bo'lsangiz, fayl spring.ftl deb ataladi va org.springframework.web.servlet.view.freemarker paketida joylashgan.

Oddiy Binding

Spring MVC kontroleri uchun form ko'rinish sifatida ishlaydigan FreeMarker shablonlariga asoslangan HTML formalaringizda quyidagi misolda keltirilgan kodni ishlatib, maydon qiymatlariga bog'lanish va har bir kirish maydoni uchun xatolik xabarlarini ko'rsatish mumkin, bu JSP ekvivalentiga o'xshash. Quyidagi misol personForm ko'rinishini ko'rsatadi:

<!-- FreeMarker makrolari namespace'ga import qilinishi kerak.
    "spring" parametriga qo'shilishingizni qat'iy tavsiya qilamiz. -->
<#import "/spring.ftl" as spring/>
<html>
    ...
    <form action="" method="POST">
        Name:
        <@spring.bind "personForm.name"/>
        <input type="text"
            name="${spring.status.expression}"
            value="${spring.status.value?html}"/><br />
        <#list spring.status.errorMessages as error> <b>${error}</b> <br /> </#list>
        <br />
        ...
        <input type="submit" value="submit"/>
    </form>
    ...
</html>

<@spring.bind> sizning komand ob'ektingizning nomini olish uchun "path" argumentini talab qiladi (bu "command", agar siz uni kontroler konfiguratsiyasida o'zgartirmagan bo'lsangiz), undan keyin nuqta va bog'lanishi kerak bo'lgan komand ob'ektining maydon nomi keladi. Shuningdek, nested maydonlar, masalan command.address.streetdan foydalanish mumkin. Makro bind o'z-o'zidan HTML escape logikasi bilan ta'minlangan, bu web.xml'dagi ServletContext kontekst parametr defaultHtmlEscape bo'yicha belgilanadi.

Makro <@spring.bindEscaped> ning alternativ formasi ikkinchi argumentni qabul qiladi, bu aniq ko'rsatadi, xatolik xabarlarining status ta'rifida yoki qiymatlarida HTML escape ishlatish kerakmi. Siz kerakligiga qarab qiymatni true yoki false ga o'rnatishingiz mumkin. Formlar bilan ishlash uchun qo'shimcha makrolar HTML escape'ni foydalanishni osonlashtiradi va siz imkon qadar ushbu makrolardan foydalanishingiz kerak. Ular quyidagi bo‘limda tushuntirilgan.

Kirish Makrolari

FreeMarker uchun qo'shimcha yordamchi makrolar formalar bilan bog'lanishni soddalashtiradi va generatsiya qiladi (inkluding validation xatolarini chiqarishni). Form kirish maydonlarini yaratishda ushbu makrolardan foydalanishga ehtiyoj yo'q, ularni oddiy HTML yoki Spring binding makrolarini to'g'ridan-to'g'ri chaqirish bilan aralashtirib va kombinatsiyalab ishlatish mumkin, biz bu haqida avvalgi bo'limda gaplashgan edik.

Quyidagi makrolarning mavjud tafsilotlari FreeMarker Template (FTL) shablonlarini va har birini qabul qiladigan parametrlar ro'yxatini taqdim etadi:

Yuqoridagi makrolardan har qandayini ishlatish uchun parametrlar ma'noli:

• path: bog'lanish uchun maydon nomi (masalan, "command.name")

• options: kirish maydonida tanlanishi mumkin bo'lgan barcha qiymatlar Mapi. Map kalitlari formadan qaytariladigan qiymatlar bo'lib, komand ob'ektiga bog‘lanadi. Map'da saqlanadigan qiymatlar kalitlar bilan birgalikda formda foydalanuvchi uchun chiqariladi va formadan qaytariladigan qiymatlar bilan farq qilishi mumkin. Odatda, bunday Map kontroler tomonidan ma'lumot sifatida taqdim etiladi. Talab qilinayotgan ishlash logikasiga ko'ra har qanday Map realizatsiyasidan foydalanishingiz mumkin. Tartibli Map uchun mos Comparator bilan SortedMap (masalan, TreeMap) ni va ixtiyoriy Map uchun qiymatlarni kiritilgan tartibda qaytaradigan LinkedHashMap yoki commons-collections dan LinkedMap foydalanishingiz mumkin.

• separator: agar ko'plab opciyalar alohida elementlar (radio yoki katakchalar) sifatida mavjud bo'lsa, u holda ushbu parametr ularni ro‘yxatda ajratish uchun ishlatiladigan belgilar ketma-ketligini o‘z ichiga oladi (masalan, <br>).

• attributes: HTML tegi ichida o‘z ichiga oladigan bo‘layotgan ixtiyoriy belgilar yoki matnlar qo'shimcha qator. Ushbu qator makro tomonidan harf bo'yicha takrorlanadi. Masalan, textarea maydonida atributlar (masalan, 'rows="5" cols="60"') yoki stil ma'lumotini masalan, 'style="border:1px solid silver"' uzatishingiz mumkin.

• classOrStyle: showErrors makrosi uchun – har bir xatoni o'rab turgan span, elementi ichida ishlatiladigan CSS klassi nomi. Agar ma'lumot taqdim etilmasa (yoki qiymat bo'sh), xatolar <b></b> teglari bilan o'rab olinadi.

Keyingi bo‘limlarda makrolar misollari keltirilgan.

formInput makrosi path(command.name) parametrini qabul qiladi va qo'shimcha attributes parametrini (keyingi misolda bo'sh). Ushbu makro, boshqa har qanday forma generatsiya makrosi, Spring’ning "path" parametri bilan bog'lashni amalga oshiradi. Bog’lanish yangi bog’lanish amalga oshirilguncha amal qiladi, shuning uchun showErrors makrosiga "path" parametri yana uzatilishi shart emas – u oxirgi marta bog’langan maydon bilan ishlaydi.

showErrors makrosi bo‘luvchi parametrni (belgilar, bu maydondagi bir nechta xatolarni ajratishda foydalaniladigan) va ikkinchi parametrni qabul qiladi – bu safar klass yoki stil atributi nomi. E'tibor bering, FreeMarker qiymat parametrlarining default qiymatlarini belgilaydi. Quyidagi misolda formInput va showErrors makrolaridan qanday foydalanishni ko'rsatadi:

<@spring.formInput "command.name"/>
<@spring.showErrors "<br>"/>

Quyidagi misolda form fragmenti chiqishi, ism maydoni generatsiyasi va xato validator xabari form bo'sh qiymat bilan jo‘natilgandan keyin qanday chiqishini ko'rsatadi. Validaya Spring’dagi Validation framework yordamida amalga oshiriladi.

Yaratilgan HTML quyidagi misolga o'xshaydi:

Name:
<input type="text" name="name" value="">
<br>
    <b>required</b>
<br>
<br>

formTextarea makrosi formInput makrosidagi kabi ishlaydi va xuddi shunday parametrlar ro'yxatini qabul qiladi. Odatda ikkinchi attributes parametri stil ma'lumotini yoki rows va cols atributlarini textareaga uzatish uchun ishlatiladi.

Tanlash maydonlari uchun FreeMarker'da HTML formalaringizda foydalanuvchi interfeys qiymatlarini standarti tanlash kirishini yaratish uchun to'rtta makrodan foydalanishingiz mumkin:

• formSingleSelect

• formMultiSelect

• formRadioButtons

• formCheckboxes

To'rtta makrolarning har biri foydalanish mumkin bo'lgan qiymat uchun Mapni qabul qiladi, bu qiymat form maydoni uchun va qiymatga mos keladigan belgi. Qiymat va belgi bir xil bo'lishi mumkin.

Quyidagi misolda FTL'da radio tugmalar bilan bog‘liq misol keltirilgan. Form ob'ekti ushbu maydon uchun default qiymat sifatida "London" ni belgilaydi, shuning uchun validatsiya talab qilinmaydi. Forma ko‘rsatilganda, tanlash uchun shaharning to‘liq ro‘yxati modelida "cityMap" nomi bilan ma'lumot sifatida taqdim etiladi. Quyidagi ro'yxatda misol keltirilgan:

...
Town:
<@spring.formRadioButtons "command.address.town", cityMap, ""/><br><br>

Yuqoridagi ro'yxatda har bir cityMap qiymati uchun radio tugmalar qatori ko'rsatilgan va "" separatoridan foydalanilgan. Hech qanday qo'shimcha atribut berilmagan (makroning oxirgi parametri yo'q). cityMap Map'dagi har bir kalit-qiymat juftlik uchun bir xil Stringni ishlatadi. Map kalitlari formadan qaytarib yuboriladigan POST so'rovining parametrlaridir. Map qiymatlari foydalanuvchiga ko'rinadigan etiketkalardir. Yuqoridagi misolda, uchta taniqli shaharning ro'yxati va form ob'ektidagi default qiymat berilgan, HTML quyidagicha ko'rinadi:

Town:
<input type="radio" name="address.town" value="London">London</input>
<input type="radio" name="address.town" value="Paris" checked="checked">Paris</input>
<input type="radio" name="address.town" value="New York">New York</input>

Agar sizning dasturingiz shaharlar bilan ichki kodlar orqali ishlashni ko‘zda tutsangiz (masalan, misolda), quyidagicha kodlar ro'yxatini Map'da yaratishingiz mumkin:

protected Map<String, ?> referenceData(HttpServletRequest request) throws Exception {
    Map<String, String> cityMap = new LinkedHashMap<>();
    cityMap.put("LDN", "London");
    cityMap.put("PRS", "Paris");
    cityMap.put("NYC", "New York");
    Map<String, Object> model = new HashMap<>();
    model.put("cityMap", cityMap);
    return model;
}

protected fun referenceData(request: HttpServletRequest): Map<String, *> {
    val cityMap = linkedMapOf(
            "LDN" to "London",
            "PRS" to "Paris",
            "NYC" to "New York"
    )
    return hashMapOf("cityMap" to cityMap)
}

Endi kodda radio tugma qiymatlari mos keladigan kodlar bo'lib chiqadi, lekin foydalanuvchi hali ham qulayroq shahar nomlarini ko'radi, quyidagi misolda ko'rsatilgandek:

Town:
<input type="radio" name="address.town" value="LDN">London</input>
<input type="radio" name="address.town" value="PRS" checked="checked">Paris</input>
<input type="radio" name="address.town" value="NYC">New York</input>

HTML Escape

Oldinroq tavsiflangan forma makrolari standart HTML 4.01 ga mos keladigan HTML elementlarini yaratishga va web.xml faylingizda belgilangan HTML escape'ni Spring binding qo'llab-quvvatlash vositalari yordamida ishlatilishiga sabab bo'ladi. XHTML bilan mos ravishda elementlar yaratishga yoki default HTML escape'ni nihoyat o'rnatish uchun, shablonlaringizning (yoki modelingizda ko‘rgan joyingizda) ikki o‘zgaruvchini o‘rnatishingiz mumkin. Ularning shablonlar ichida o'rnatilishi afzalligi, ularni keyinchalik shablon ishlov berish jarayonida boshqa qiymatlarga o'zgartirish mumkinligi, shuning uchun formangizning har xil maydonlari uchun turli ish mantig'ini ta'minlash imkoniyatini beradi.

Teglar uchun XHTML mosligi rejimiga o'tish uchun, modelda yoki kontekstda xhtmlCompliant nomli o'zgaruvchiga qiymatini true qilib o'rnating, quyidagi misolda ko'rsatilgandek:

<#-- FreeMarker uchun -->
<#assign xhtmlCompliant = true>

Ushbu direktiva qayta ishlangandan so'ng, Spring makrolar tomonidan yaratilgan barcha elementlar endi XHTML standartiga mos keladi.

Xuddi shunday, har bir maydon uchun HTML escape'ni belgilashingiz mumkin, quyidagi misolda ko'rsatilgandek:

<#-- bu nuqtaga qadar, default HTML escape is used -->
<#assign htmlEscape = true>
<#-- keyingi maydon HTML escape'ni ishlatadi -->
<@spring.formInput "command.name"/>
<#assign htmlEscape = false in spring>
<#-- barcha keyingi maydonlar HTML escape o'chirilgan holda bog'lanadi -->