From e03d0dae857e4cb82bfd4427edec9361b34e892c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A9ter=20Szab=C3=B3?= Date: Thu, 22 Feb 2024 14:48:23 +0100 Subject: [PATCH] =?UTF-8?q?#36=20-=20Kieg=C3=A9sz=C3=ADt=C5=91=20inform?= =?UTF-8?q?=C3=A1ci=C3=B3k?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/additional_information.adoc | 259 +++++++++++++++++++++++++++++++ docs/index.adoc | 2 + 2 files changed, 261 insertions(+) create mode 100644 docs/additional_information.adoc diff --git a/docs/additional_information.adoc b/docs/additional_information.adoc new file mode 100644 index 00000000..8d3a6ac3 --- /dev/null +++ b/docs/additional_information.adoc @@ -0,0 +1,259 @@ += Kiegészítő információk + +== Helpers - Template fájlokban használható helperek + +=== Built-in helperek + +A Handlebars biztosít beépített helpereket, amelyeknek a dokumentációja https://handlebarsjs.com/guide/builtin-helpers.html[itt] található. + +=== Custom helperek + +Lehetőség van a modulban biztosított általános helpereket használni. A példákban a ... részek renderelődnek ki amennyiben a kifejezés igazra értékelődik ki. + +==== Használatuk + +A helperek használata során a helper kulcsszava után kell megadni az adott helperhez tartozó paramétereket. Inline generálás és adatbázisban tárolt template alapú generálás során is felhasználhatóak a helperek. A paraméterek lehetnek beégetett értékek vagy jöhetnek a dokumentumgenerálási hívás során JSON formátumban. + +A helperek kombinálhatók egymással. + +[cols="5%,45%,45%a,5%"] +|=== +Token | Magyarázat | Használat | Ettől a verziótól | + +equals | +Két elem értékét hasonlítja össze, akkor történik renderelés ha igaz a kiértékelés eredménye. | +[source,bash] +---- +{{#if (equals yourField 'white')}} ... {{/if}} +---- +| +0.1.0 | + +before | +Akkor történik renderelés, ha az átadott paraméter korábbi időpont mint a biztosított érték. Utóbbi szintén lehet paraméter. | + +[source,bash] +---- +{{#if (before yourDate '2023-08-13T05:40:55Z')}} ... {{/if}} +{{#if (before yourDate checkDate)}} ... {{/if}} +---- +| +0.1.0 | + +between | +Akkor történik renderelés, ha az átadott paraméter a két biztosított dátum érték közé esik. Utóbbiak szintén lehetnek paraméterek. | +[source,bash] +---- +{{#if (between yourDate '2023-08-13T05:40:55Z' '2023-08-15T05:40:55Z')}} ... {{/if}} +{{#if (between yourDate startDate endDate)}} ... {{/if}} +---- +| +0.1.0 | + +dateMinusMinutes | +Adott dátumból megadott percek kivonása. | + +[source,bash] +---- +{{dateMinusMinutes '2023-08-13T05:40:55Z' 60}} // '2023-08-13T04:40:55Z' lesz a kiértékelés eredménye +{{dateMinusMinutes yourDate 60}} // A következő két példa ugyanezzel a dátummal értékelődik ki +{{dateMinusMinutes yourDate minutesToSubtract}} +---- +| +0.1.0 | + +datePlusMinutes | +A dateMinusMinutes párja, hozzáadunk perceket a kapott dátumhoz. | + +[source,bash] +---- +{{datePlusMinutes '2023-08-13T05:40:55Z' 60}} - '2023-08-13T06:40:55Z' lesz a kiértékelés eredménye +{{datePlusMinutes yourDate 60}} +{{datePlusMinutes yourDate minutesToAdd}} +---- +| +0.1.0 | + +declare | +Új változó létrehozása és azonnali renderelése. Az így létrehozott változók globálisak, függetlenül attól hogy hol hozták létre a template-ekben. | + +[source,bash] +---- +{{declare 'myColor' 'white'}} // azonnal ki is rendereljük a 'white' szót +... +{{#if myColor}} {{myColor}} {{/if}} // 'white' lesz renderelve +---- +| +0.1.0 | + +declareVoid | +Hasonlóan működik mint a declare helper, azonban ez nem rendereli ki azonnal a kapott értéket. A declare kiváltható lenne a declareVoid-dal létrehozott változóval majd azonnali meghívással. | + +[source,bash] +---- +{{declareVoid 'myColor' 'white'}} +... +{{#if myColor}} {{myColor}} {{/if}} // 'white' lesz renderelve +declare helper kiváltása: +{{declareVoid 'myColor' 'white'}} +{{myColor}} // 'white' lesz renderelve azonnal a létrehozás után +---- +| + +0.1.0 | + +formatDate | +A kapott, Java 8 által elfogadott dátum formátumú paraméter átalakítása megadott pattern szerint. A pattern csak dátum formátumot fogad el, ellenkező esetben hibát dob. | + +[source,bash] +---- +yourDate = '2024-01-09'; + +{{formatDate '2023-08-13' 'yyyy.MM.dd'}} // '2023.08.13' +{{formatDate '2023-08-13' 'MM.dd.yyyy'}} // '08.13.2023' +{{formatDate yourDate 'yyyy/MM/dd'}} // '2024/01/09' +---- +| +0.5.0 | + +formatDateTime | +A kapott, Java 8 által elfogadott dátum és idő formátumú paraméter átalakítása megadott pattern szerint. A helper kezeli a teljes ISO dátum formátumú inputot, abból képes pattern segítségével megfelelő output előállítására. A helper képes időzónát is kezelni, amennyiben az output pattern után megadunk egy Java által elfogadott Zone ID-t, a bemenő időpontot átalakítja az időzóna szerinti output-tá. | + +[source,bash] +---- +yourDate = '2024-01-09T15:30:04Z' +yourDateTimeFormat = 'MM.dd-HH:mm' +yourDateFormat = 'yyyy/MM.dd' +yourTimeFormat = 'hh:mm:ss a' + +{{formatDateTime '2023-08-13T05:40:55Z' 'yyyy-MM-dd HH:mm:ss'}} // '2023-08-13 06:40:55' +{{formatDateTime yourDate 'yyyy-MM-dd HH:mm:ss'}} // '2024-01-09 15:30:04' +{{formatDateTime yourDate yourDateTimeFormat}} // '01.09-15:30' +{{formatDateTime yourDate yourDateFormat}} // '2024/01.09' +{{formatDateTime yourDate yourTimeFormat}} // '03:30:04 PM' +{{formatDateTime '2023-08-13T05:40:55Z' 'yyyy-MM-dd HH:mm:ss' 'CET'}} // '2023-08-13 08:40:55' +---- +| +0.5.0 | + +formatTime | + +A kapott, Java 8 által elfogadott idő formátumú paraméter átalakítása megadott pattern szerint. A pattern csak idő formátumot fogad el, ellenkező esetben hibát dob. | + +[source,bash] +---- +yourTime = '15:30:55Z'; + +{{formatTime '15:30:55Z' 'HH:mm:ss'}} // '15:30:55' +{{formatTime yourTime 'h:mm A'}} // '3:30 PM' +---- +| +0.5.0 | + +formatNumber | +Számok formázására használt helper, JAVA-s számformázási konvenciót követve működik | + +[source,bash] +---- +number = 1234.567; +percentage = 0.4567 + +{{formatNumber number '#'}} // "1235", kerekített egész szám +{{formatNumber number '0.00'}} // "1234.57", 2 tizedesre kerekített szám +{{formatNumber number '000000.00'}} // "001234.57", vezető nullákkal feltöltött szám +{{formatNumber number '#,###.##'}} // "1,234.57", vesszővel elválaszott, hármasával csoportosított érték +{{formatNumber number '$#,##0.00'}} // "$1,234.57", pénznem kifejezése +{{formatNumber percentage '0.00%'}} // "45.67%", 0 és 1 közötti érték százalékos kifejezése 0 és 100% között +{{formatNumber number '0.###E0'}} // "1.235E8", tudományos jelölésű szám +---- +| +0.1.0 | + +and | +N érték közti && operátor. Akkor renderelük ha a logikai ÉS operátor igazra értékelődik ki. | + +[source,bash] +---- +{{#if (and falseValue trueValue notExistingValue)}} YES {{else}} NO {{/if}} // "NO" érték renderelődik +{{#if (and trueValue trueValue trueValue)}} YES {{/if}} // "YES" renderelődik mert ugyanaz mindhárom érték és azok igazak +myValue = 'black' +{{#if (and (equals myValue 'black')}} YES {{else}} NO {{/if}} // "YES" renderelődik ki, a változó és a string ÉS kiértékelése igaz +{{#if (and (equals myValue 'white')}} YES {{else}} NO {{/if}} // "NO" renderelődik ki, a változó és a string ÉS kiértékelése hamis + +Kombinált használat: +{{#if (and (equals 'black' 'white') (equals 'white' 'white'))}} YES {{else}} NO {{/if}} // "NO" renderelődik ki, az első hamisra, a második igazra értékelődik ki +---- +| +0.1.0 | + +or | +N érték közötti \|\| operátor. Akkor renderelük ha a logikai VAGY operátor igazra értékelődik ki. | + +[source,bash] +---- +{{#if (or falseValue trueValue notExistingValue)}} YES {{else}} NO {{/if}} // "YES" érték renderelődik +{{#if (or falseValue falseValue falseValue)}} YES {{/if}} // Semmi nem renderelődik ki +myValue = 'white' +{{#if (or myValue 'black')}} YES {{else}} NO {{/if}} // "YES" renderelődik ki, a változó és a string VAGY kiértékelése igaz + +Kombinált használat: +{{#if (or (equals 'black' 'white') (equals 'white' 'white'))}} YES {{else}} NO {{/if}} // "YES" renderelődik ki, hamis VAGY igaz esetén igaz a kiértékelés +---- +| +0.1.0 | + +not | +Logikai ! operátor. A kapott paramétert negálja, ha igaz a kiértékelés akkor renderelünk, ha hamis akkor nem. | + +[source,bash] +---- +{{#if (not falseValue)}} YES {{else}} NO {{/if}} // YES +{{#if (not existingValue)}} YES {{else}} NO {{/if}} // NO +{{#if (not (equals 'black' 'white'))}} YES {{else}} NO {{/if}} // YES +---- +| +0.1.0 | + +in | +Azt vizsgálja hogy a kapott legelső paraméter megegyezik-e a soron következő elemek bármelyikével. | + +[source,bash] +---- +myValue = 'white' +{{#if (in myValue 'black' 'gray')}} YES {{else}} NO {{/if}} // NO +{{#if (in myValue 'black' 'white' 'gray')}} YES {{else}} NO {{/if}} // YES +---- +| +0.1.0 | + +math | + +Alap matematikai műveletek elvégzésére használható helper. Az első paraméter az operátor, a másik két paraméter az operandusok. A használható operátorok listája: + +“+”, “-”, “*”, “/”, “%” + +Hibás operátor esetén a kiértékelés eredménye: “-1”. Egyéb esetben az operandusokon elvégzett, operátornak megfelelő matematikai művelet. | + +[source,bash] +---- +num1 = 5 +num2 = 8 +num3 = 100 +num4 = 20 + +{{math '+' num1 num2}} // 13 +{{math '-' num3 53}} // 47 +{{math '*' num2 num4}} // 160 +{{math '/' num3 num4}} // 5 +{{math '%' num4 num2}} // 40 +{{math 'A' num1 num2}} // -1 +---- +| +0.1.0 | +|=== + +==== További helper-ök + +A projektbe a következő 3rd party helper-ök használhatók: + +* https://github.com/jknack/handlebars.java/blob/v4.3.1/handlebars/src/main/java/com/github/jknack/handlebars/helper/StringHelpers.java[StringHelpers] diff --git a/docs/index.adoc b/docs/index.adoc index 2e93793f..b2ebde88 100644 --- a/docs/index.adoc +++ b/docs/index.adoc @@ -45,4 +45,6 @@ include::install.adoc[leveloffset=+1] include::openapi.adoc[leveloffset=+1] +include::additional_information.adoc[leveloffset=+1] + include::release-notes.adoc[leveloffset=+1]