Using Velocity Tools in Templates ================================= Overview -------- Velocity Tools are powerful utilities that extend Apache Velocity templates with specialized functionality for common operations like date formatting, mathematical calculations, and number formatting. These tools are automatically available in your templates and provide a rich set of methods to manipulate and format data dynamically. The tools are accessed using the dollar sign (`$`) followed by the tool name and method. For example, `$math.add(5, 3)` uses the MathTool to perform addition. Available Tools --------------- NSG provides several built-in tools: - **Date Tool** (`$date` and `$dateTime`) - Format dates and times, work with time zones, and get timestamps - **Math Tool** (`$math`) - Perform mathematical operations - **Number Tool** (`$number`) - Format and display numbers with custom patterns Date Tool --------- The Date Tool provides comprehensive date and time formatting capabilities, including timezone support and timestamp conversion. Basic Date Formatting ^^^^^^^^^^^^^^^^^^^^^ Format dates using custom patterns: .. code-block:: none Date: $date.format('EEEE d MMMM HH:mm z', $testDate, $dateTime.defaultLocale, $dateTime.get('America/Los_Angeles')) *Output: `Thursday 30 September 17:00 PDT`* `$date.format()` is a tool call that takes following arguments: * date/time format * timestamp value. This can be a constant or the value of object attribute, for example you can call `$date.format('format', $alert.activeSince)` * locale (optional) * timezone (optional) Tool `$date.format()` returns date and time passed as second argument, formatted according to the first argument. If locale and timezone are provided, the date/time will be formatted according to the locale and converted to the requested time zone, taking into account possible daylight shift. last two arguments are optional. If you want to pass timezone info, you must also pass locale. Get standard timezone objects by calling `dateTime` tool as shown in the example, it accepts standard timezone names such as `America/Los_Angeles` or `UTC`. Note that this takes care of the daylight savings shift automatically. Supported formats ^^^^^^^^^^^^^^^^^ Here is a non-exhaustive list of date/time formats supported by the Date Tool Combined date and time formats: .. code-block:: none $dateTool.format('default', $testDate) $dateTool.format('full', $testDate) $dateTool.format('long', $testDate) $dateTool.format('medium', $testDate) $dateTool.format('short', $testDate) Gives this in the output: .. code-block:: none 03-Jan-2012 00:00:00 Tuesday, 3 January 2012 00:00:00 o'clock GMT 03 January 2012 00:00:00 GMT 03-Jan-2012 00:00:00 03/01/12 00:00 To get just the date without time, add sufix '_date': .. code-block:: none $dateTool.format('default_date', $testDate) $dateTool.format('full_date', $testDate) $dateTool.format('long_date', $testDate) $dateTool.format('medium_date', $testDate) $dateTool.format('short_date', $testDate) Gives this in the output: .. code-block:: none 03-Jan-2012 Tuesday, 3 January 2012 03 January 2012 03-Jan-2012 03/01/12 To get just the time, add suffix '_time' .. code-block:: none $dateTool.format('default_time', $testDate) $dateTool.format('full_time', $testDate) $dateTool.format('long_time', $testDate) $dateTool.format('medium_time', $testDate) $dateTool.format('short_time', $testDate) Gives this in the output: .. code-block:: none 00:00:00 00:00:00 o'clock GMT 00:00:00 GMT 00:00:00 00:00 Custom formatting is also supported: "YYYY/MM/DD HH:mm:ss" For more details on date/time format patterns, see the `SimpleDateFormat documentation `_. .. list-table:: Date/Time Format Letters :header-rows: 1 :widths: 10 30 15 45 * - Letter - Date or Time Component - Presentation - Examples * - G - Era designator - Text - AD * - y - Year - Year - 1996; 96 * - Y - Week year - Year - 2009; 09 * - M - Month in year (context sensitive) - Month - July; Jul; 07 * - L - Month in year (standalone form) - Month - July; Jul; 07 * - w - Week in year - Number - 27 * - W - Week in month - Number - 2 * - D - Day in year - Number - 189 * - d - Day in month - Number - 10 * - F - Day of week in month - Number - 2 * - E - Day name in week - Text - Tuesday; Tue * - u - Day number of week (1 = Monday, ..., 7 = Sunday) - Number - 1 * - a - Am/pm marker - Text - PM * - H - Hour in day (0-23) - Number - 0 * - k - Hour in day (1-24) - Number - 24 * - K - Hour in am/pm (0-11) - Number - 0 * - h - Hour in am/pm (1-12) - Number - 12 * - m - Minute in hour - Number - 30 * - s - Second in minute - Number - 55 * - S - Millisecond - Number - 978 * - z - Time zone - General time zone - Pacific Standard Time; PST; GMT-08:00 * - Z - Time zone - RFC 822 time zone - -0800 * - X - Time zone - ISO 8601 time zone - -08; -0800; -08:00 Working with Time Zones ^^^^^^^^^^^^^^^^^^^^^^^ Format dates in different time zones: .. code-block:: none ## UTC timezone Date: $date.format('EEEE d MMMM HH:mm z', $testDate, $dateTime.defaultLocale, $dateTime.utc()) ## Specific timezone Date: $date.format('EEEE d MMMM HH:mm z', $testDate, $dateTime.defaultLocale, $dateTime.get('America/Los_Angeles')) Unix Timestamps ^^^^^^^^^^^^^^^ Tool `$dateTime.timestamp()` returns current time as unix timestamp (in seconds). Tool `$dateTime.timestampMs()` returns timestamp in milliseconds: .. code-block:: none ## Unix timestamp in seconds Current time: $dateTime.timestamp() ## Unix timestamp in milliseconds Current time (ms): $dateTime.timestampMs() you can apply `$date.format()` to the current time if you need to format it: .. code-block:: none Current time: $date.format('EEEE d MMMM HH:mm z', $dateTime.timestamp()) Current time: $date.format('EEEE d MMMM HH:mm z', $dateTime.timestamp(), $dateTime.defaultLocale, $dateTime.get('America/Los_Angeles')) Math Tool --------- The Math Tool enables mathematical calculations directly within your templates [[4]](https://velocity.apache.org/tools/1.4/generic/MathTool.html). Basic Operations ^^^^^^^^^^^^^^^^ Perform arithmetic operations on variables: .. code-block:: none Sum: $math.add($a, $b) Product: $math.mul($a, $b) If `$a = 10` and `$b = 5`, this produces: *Output: `Sum: 15, Product: 50`* Advanced Calculations ^^^^^^^^^^^^^^^^^^^^^ Combine multiple operations for complex calculations: .. code-block:: none ## Calculate tax and total Tax (10%): $math.mul($amount, 0.1) Total: $math.add($amount, $math.mul($amount, 0.1)) Number Tool ----------- The Number Tool provides flexible number formatting capabilities [[1]](https://velocity.apache.org/tools/devel/apidocs/org/apache/velocity/tools/generic/NumberTool.html). Custom Number Formatting ^^^^^^^^^^^^^^^^^^^^^^^^ Format numbers using Java's DecimalFormat patterns: .. code-block:: none Formatted: $number.format('#,##0.00', $value) If `$value = 1234.5678`, this produces: *Output: `Formatted: 1,234.57`* Currency Formatting ^^^^^^^^^^^^^^^^^^^ Format numbers as currency: .. code-block:: none Amount: $number.format('$#,##0.00', $amount) If `$amount = 1234.56`, this produces: *Output: `Amount: $1,234.56`* Best Practices -------------- 1. **Use appropriate tools for data types**: Use the Number Tool for numeric formatting rather than trying to format numbers manually. 2. **Specify time zones explicitly**: When working with dates, always specify the time zone to ensure consistent output across different environments. 3. **Combine tools for complex operations**: Tools work well together - use Math Tool for calculations and Number Tool for formatting the results. 4. **Leverage conditional logic**: Use `#if` statements to show different content based on your data. 5. **Format for your audience**: Choose number and date formats that match your users' expectations and locale. These tools provide the foundation for creating dynamic, data-driven templates that can adapt to different contexts while maintaining consistent formatting and presentation.