FreeMarker פעולות נפוצות
1. הקדמה
FreeMarker הוא מנוע תבניות, כתוב בג'אווה, ומתוחזק על ידי קרן אפאצ'י. אנו יכולים להשתמש בשפת התבניות FreeMarker, המכונה גם FTL, כדי ליצור פורמטים רבים מבוססי טקסט כמו דפי אינטרנט, דוא"ל או קבצי XML.
במדריך זה נראה מה אנחנו יכולים לעשות מחוץ לקופסה עם FreeMarker, אם כי שימו לב שהוא ניתן להגדרה למדי ואפילו משתלב יפה עם אביב.
בואו נתחיל!
2. סקירה מהירה
כדי להזרים תוכן דינמי לדפים שלנו, עלינו השתמש בתחביר ש- FreeMarker מבין:
- ${…} בתבנית יוחלף בפלט שנוצר עם הערך האמיתי של הביטוי בסוגריים המתולתלים - אנחנו קוראים לזה אינטרפולציה - כמה דוגמאות הן ${1 + 2} ו $ {variableName}
- תגי FTL דומים לתגי HTML (אך מכילים # אוֹ @) ו- FreeMarker מפרשים אותם, למשל
- הערות ב- FreeMarker מתחילות עם <#– ולסיים עם –>
3. תג הכלול
ה- FTL לִכלוֹל הנחיה היא דרך עבורנו לעקוב אחר עקרון ה- DRY ביישום שלנו. נגדיר את התוכן החוזר בקובץ ונשתמש בו מחדש בתבניות FreeMarker שונות עם יחיד לִכלוֹל תָג.
מקרה שימוש כזה הוא כאשר אנו רוצים לכלול את קטע התפריט בתוך עמודים רבים. ראשית, נגדיר את קטע התפריט בתוך קובץ - נקרא לו menu.ftl - עם התוכן הבא:
לוח מחוונים הוסף נקודת קצה חדשהובדף ה- HTML שלנו, בואו נכלול את הנוצרים menu.ftl:
דף לוח המחוונים
ואנחנו יכולים גם לכלול FTL בשברים שלנו, וזה נהדר.
4. טיפול בקיום ערך
FTL ישקול כל דבר ריק ערך כערך חסר. לפיכך, עלינו להיות זהירים במיוחד ו הוסף לוגיקה לטיפול ריקבתוך התבנית שלנו.
אנחנו יכולים להשתמש ב- ?? מפעיל כדי לבדוק אם קיים מאפיין, או נכס מקונן. התוצאה היא בוליאנית:
$ {תכונה ??}אז בדקנו את המאפיין עבור ריק, אבל זה לא תמיד מספיק. בואו נגדיר ערך ברירת מחדל כתרופת ערך לערך חסר זה. לשם כך אנו זקוקים ל ! מפעיל שמוצב אחרי שם המשתנה:
$ {attribute! 'ערך ברירת מחדל'}באמצעות סוגריים עגולים נוכל לעטוף תכונות מקוננות רבות.
לדוגמה, כדי לבדוק אם התכונה קיימת ויש לה נכס מקונן עם נכס מקונן אחר, אנו עוטפים הכל:
$ {(attribute.nestedProperty.nestedProperty) ??}לבסוף, אם הכל יחד, נוכל להטמיע אותם בתוכן סטטי:
המבחן קיים רכוש סטודנטים: $ {סטודנט ??? ג}
שימוש בערך ברירת מחדל לסטודנט חסר: $ {student! 'John Doe'}
עוטף נכסים מקוננים של סטודנטים: $ {(student.address.street) ??? c}
ואם סטוּדֶנט היו ריקהיינו רואים:
המבחן קיים רכוש סטודנטים: שקר
שימוש בערך ברירת מחדל עבור תלמיד נעדר: ג'ון דו
עוטף נכסים מקוננים של תלמידים: שקר
שימו לב הנוסף ? ג הנחיה ששימשה לאחר ??. עשינו את זה כדי להמיר את הערך הבוליאני למחרוזת קריאה אנושית.
5. התג If-Else
מבני בקרה קיימים ב- FreeMarker, וה- if-else המסורתי כנראה מוכר:
בזמן ש אחר אם ו אַחֵר סניפים הם אופציונליים, התנאים חייבים להגיע לערך בוליאני.
כדי לעזור לנו בהערכות שלנו, סביר להניח שנשתמש באחת מהבאות:
- x == y לבדוק הוא איקס שווה ל y
- x! = y לחזור נָכוֹן רק אם איקס שונה מ y
- x lt y אומר ש איקס חייב להיות קטן יותר מ- y אנחנו יכולים גם להשתמש < במקום לט
- x gt y מעריך ל נָכוֹן רק אם איקס הוא גדול יותר מאשר y אנחנו יכולים להשתמש > במקום gt
- x lte y בדיקות אם איקס הוא פחות או שווה ל- y - האלטרנטיבה ל lte הוא <=
- x gte y בדיקות אם איקס גדול או שווה ל- y החלופה של gte הוא> =
- איקס?? כדי לבדוק את קיומו של איקס
- רצף? seq מכיל (x) מאמת את קיומו של איקס בתוך רצף
חשוב מאוד לזכור את זה FreeMarker מחשיב> = ו> כתווים סגורים לתג FTL. הפיתרון הוא לעטוף את השימוש בסוגריים או להשתמש gte אוֹ gt במקום זאת.
לשים את זה יחד, עבור התבנית הבאה:
$ {status.reason}
חסר מעמד!
בסופו של דבר אנו מקבלים את קוד ה- HTML המתקבל:
404 לא נמצא
חסר מעמד!
6. מיכלים של משתני משנה
ב- FreeMarker יש לנו שלושה סוגים של מכולות עבור משתני משנה:
- האש הם רצף של זוגות ערך-מפתח - המפתח חייב להיות ייחודי בתוך החשיש ואין לנו הזמנה
- רצפים הן רשימות שבהן יש לנו אינדקס המשויך לכל ערך - עובדה ראויה לציון היא שמשתני משנה יכולים להיות מסוגים שונים
- אוספים הם מקרה מיוחד של רצפים שבהם איננו יכולים לגשת לגודל או לאחזר ערכים לפי אינדקס - עדיין נוכל לחזור עליהם באמצעות רשימה תייג אם כי!
6.1. פריטים מפטרים
אנו יכולים לחזור על מיכל בשתי דרכים בסיסיות. הראשון הוא המקום בו אנו חוזרים על כל ערך ומתחוללים היגיון לכל אחד מהם:
או, כאשר אנו רוצים לחזור על א בְּלִיל, גישה למפתח ולערך:
הצורה השנייה חזקה יותר מכיוון שהיא מאפשרת לנו גם להגדיר את ההיגיון שאמור לקרות בשלבים שונים של החזרה:
ה פריט מייצג את שמו של המשתנה הלולאה, אך אנו יכולים לשנות את שמו למה שאנחנו רוצים. ה אַחֵר סניף הוא אופציונלי.
לדוגמא מעשית, הגדירו היטב תבנית בה אנו מציגים כמה סטטוסים:
- $ {status}
אין סטטוסים זמינים
זה יחזיר לנו את ה- HTML הבא כאשר המכולה שלנו תהיה ["200 אישור", "404 לא נמצא", "500 שגיאת שרת פנימית"]:
- 200 בסדר
- 404 לא נמצא
- 500 שגיאת שרת פנימית
6.2. טיפול בפריטים
חשיש מאפשר לנו שתי פונקציות פשוטות: מקשים כדי לאחזר רק את המפתחות הכלולים, ו ערכים כדי לאחזר רק את הערכים.
רצף מורכב יותר; אנו יכולים לקבץ את הפונקציות השימושיות ביותר:
- חתיכה ו לְהִצְטַרֵף כדי לקבל תת רצף או לשלב שני רצפים
- לַהֲפוֹך, סוג, ו מיין לפי לשינוי סדר האלמנטים
- ראשון ו אחרון ישיג את האלמנט הראשון או האחרון, בהתאמה
- גודל מייצג את מספר האלמנטים ברצף
- seq מכיל, seqIndexOf, או seqLastIndexOf לחפש אלמנט
7. סוג טיפול
FreeMarker מגיע עם מגוון עצום של פונקציות (מובנות) הזמינות לעבודה עם אובייקטים. בואו נראה כמה פונקציות נפוצות.
7.1. טיפול במיתרים
- url ו urlPath יימלט URL ממחרוזת, למעט זה urlPath לא יברח מקוטע /
- jString, jsString, ו jsonString תחול את כללי הבריחה עבור Java, Javascript ו- JSON, בהתאמה
- capFirst, uncapFirst, מקרה עליון, lowerCase ו לְנַצֵל שימושיים לשינוי המקרה של המחרוזת שלנו, כמשתמע משמותיהם
- בוליאני, תַאֲרִיך, זְמַן, תאריך שעה ו מספר הן פונקציות להמרה ממחרוזת לסוגים אחרים
בואו נשתמש בכמה מהפונקציות הללו:
$ {'// myurl.com/?search=Hello World'? urlPath}
$ {'משתמש "בטקסט'? JsString}
$ {'הערך שלי? upperCase}
$ {'2019-01-12'? תאריך ('yyyy-MM-dd')}
והפלט עבור התבנית לעיל יהיה:
http% 3A // myurl.com /% 3Fsearch% 3DHello% 20World
הערך שלי
באמצעות \ "בטקסט
12.01.2019
בעת השימוש ב- תַאֲרִיך פונקציה, העברנו גם את התבנית לשימוש לניתוח אובייקט String. FreeMarker משתמש בפורמט המקומי אלא אם כן צוין אחרת, למשל ב- חוּט פונקציה זמינה עבור אובייקטים תאריך.
7.2. טיפול במספרים
- עָגוֹל, קוֹמָה ו תִקרָה יכול לעזור בעיגול מספרים
- שרירי בטן יחזיר את הערך המוחלט של המספר
- חוּט ימיר את המספר למחרוזת. אנו יכולים גם להעביר ארבעה פורמטי מספרים שהוגדרו מראש: מַחשֵׁב, מַטְבֵּעַ, מספר, או אָחוּז או להגדיר פורמט משלנו, כמו [ “0.###” ]
בואו נעשה שרשרת של כמה פעולות מתמטיות:
$ {(7.3? עגול + 3.4? תקרה + 0.1234)? מחרוזת ('0. ##')}
וכצפוי, הערך המתקבל הוא 11.12.
7.3. טיפול בתאריכים
- .עַכשָׁיו מייצג את תאריך השעה הנוכחי
- תַאֲרִיך, זְמַן ו תאריך שעה יכול להחזיר את קטעי התאריך והשעה של האובייקט תאריך שעה
- חוּט להמיר זמני תאריך למחרוזות - נוכל גם לעבור את הפורמט הרצוי או להשתמש בתבנית שהוגדרה מראש
כעת אנו מקבלים את השעה הנוכחית ומבנים את הפלט למחרוזת המכילה רק את השעות והדקות:
$ {. now? time? string ('HH: mm')}
ה- HTML שנוצר יהיה:
15:39
8. טיפול בחריגים
נראה שתי דרכים לטפל בחריגים עבור תבנית FreeMarker.
הדרך הראשונה היא להשתמש ניסיון להתאושש תגיות כדי להגדיר מה עלינו לנסות לבצע וגוש קוד שצריך לבצע במקרה של שגיאה.
התחביר הוא:
שניהם לְנַסוֹת ו לְהַחלִים תגים הם חובה. במקרה של שגיאה, הוא מחזיר את החסימה שניסתה ויבצע רק את הקוד ב- לְהַחלִים סָעִיף.
בהתחשב בתחביר זה, נגדיר את התבנית שלנו כ:
מתכונן להערכה
התכונה היא $ {attributeWithPossibleValue ??}
תכונה חסרה
בוצע עם ההערכה
מתי attributeWithPossibleValue חסר, נראה:
מתכונן להערכה
תכונה חסרה
בוצע עם ההערכה
והתפוקה מתי attributeWithPossibleValue קיים הוא:
מתכונן להערכה
התכונה היא 200 בסדר
בוצע עם ההערכה
הדרך השנייה היא להגדיר את FreeMarker מה צריך לקרות במקרה של חריגים.
בעזרת Spring Boot, אנו מגדירים זאת בקלות באמצעות קובץ מאפיינים; להלן מספר תצורות זמינות:
- spring.freemarker.setting.template_exception_handler = לסדר מחדש משליך מחדש את החריג
- spring.freemarker.setting.template_exception_handler = ניפוי באגים מוציא את מידע מעקב הערימה ללקוח ואז משליך מחדש את החריג.
- spring.freemarker.setting.template_exception_handler = html_debug מוציא את מידע מעקב הערימה ללקוח, מעצב אותו כך שהוא יהיה בדרך כלל קריא היטב בדפדפן ואז משליך מחדש את החריג.
- spring.freemarker.setting.template_exception_handler = התעלם מדלג על ההוראות הכושלות ומאפשר לתבנית להמשיך לבצע.
- spring.freemarker.setting.template_exception_handler = ברירת מחדל
9. שיטות שיחה
לפעמים אנחנו רוצים להתקשר לשיטות Java מתבניות FreeMarker שלנו. כעת נראה כיצד לעשות זאת.
9.1. חברים סטטיים
כדי להתחיל לגשת לחברים סטטיים, נוכל לעדכן את תצורת FreeMarker הגלובלית שלנו או להוסיף StaticModels הקלד תכונה על המודל, תחת שם התכונה סטטיסטיקות:
model.addAttribute ("סטטיקה", DefaultObjectWrapperBuilder חדש (גרסה חדשה ("2.3.28")) .build (). getStaticModels ());הגישה לאלמנטים סטטיים היא ישר קדימה.
ראשית, אנו מייבאים את האלמנטים הסטטיים של המחלקה שלנו באמצעות תג הקצאה, ואז מחליטים על שם ולבסוף, דרך הכיתה של Java.
כך נייבא מתמטיקה בכיתה בתבנית שלנו, הראה את ערך הסטטי פאי שדה, והשתמש בסטטי פאו שיטה:
ערך PI: $ {MathUtils.PI}
2 * 10 הוא: $ {MathUtils.pow (2, 10)}
ה- HTML שנוצר הוא:
ערך PI: 3.142
2 * 10 הוא: 1,024
9.2. חברי שעועית
קל מאוד לגשת לחברי שעועית: השתמש בנקודה (.) וזה הכל!
לדוגמא הבאה, נוסיף א אַקרַאִי מתנגד למודל שלנו:
model.addAttribute ("אקראי", אקראי חדש ());בתבנית FreeMarker שלנו, בואו ניצור מספר אקראי:
ערך אקראי: $ {random.nextInt ()}
זה יגרום לפלט הדומה ל:
ערך אקראי: 1,329,970,768
9.3. שיטות מותאמות אישית
השלב הראשון להוספת שיטה מותאמת אישית הוא לקיים מחלקה שמיישמת את FreeMarker TemplateMethodModelEx ממשק ומגדיר את ההיגיון שלנו בתוך ביצוע שיטה:
class class LastCharMethod מיישם TemplateMethodModelEx {exec אובייקט ציבורי (ארגומנטים של רשימה) זורק TemplateModelException}נוסיף מופע של הכיתה החדשה שלנו כתכונה במודל:
model.addAttribute ("lastChar", LastCharMethod חדש ());השלב הבא הוא להשתמש בשיטה החדשה שלנו בתוך התבנית שלנו:
דוגמה אחרונה לתווים: $ {lastChar ('mystring')}
לבסוף, התפוקה המתקבלת היא:
דוגמא לשחרור אחרון: ז
10. מסקנה
במאמר זה ראינו כיצד להשתמש במנוע התבניות FreeMarker בתוך הפרויקט שלנו. התמקדנו בפעולות נפוצות, כיצד לתפעל עצמים שונים וכמה נושאים מתקדמים יותר.
היישום של כל התמציות הללו זמין ב- GitHub.
