#36 - Kiegészítő információk

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]

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]