Table of Contents
Imps are small helpers, providing different functionality an implementer can use in portlets, supporting TemplateEngine2.
Imps must be configured in Portalconfiguration file, see Section 8.4, “formatter-section” for detailed information. They provide basic functionality that shall be available in an easy and convenient way in every template. Generally, all configured imps are available through
$portal.imps.[id]
Format a date in a standard or custom format, centrally managed and
localizable. The class used is
Class
com.gentics.portalnode.formatter.GenticsDateFormatter
.
By default, this imp will support the formats
short
,
date
and
time
(and any custom format passed to the methods
directly). With the parameter
configuration
you can configure the path to a custom configuration
file.
Date formats have to be defined in
META-INF/config/formatter/dateformatter.xml
for
use with the dateformatter's methods. See http://java.sun.com/j2se/1.4.2/docs/api/java/text/DateFormat.html
and http://java.sun.com/j2se/1.4.2/docs/api/java/text/SimpleDateFormat.html
for detailed information on formatting styles. Here is an example
configuration:
<?xml version="1.0" encoding="ISO-8859-1"?> <!-- date formatter information --> <date-formats default="STANDARD"> <date-format id="STANDARD" defaultdate="MEDIUM" defaulttime="MEDIUM"/> <date-format id="short" defaultdate="SHORT" defaulttime="SHORT"/> <date-format id="time" defaulttime="SHORT"/> <date-format id="date" defaultdate="MEDIUM"/> <date-format id="custom" defaultdate="dd.MM.yyyy" defaulttime="HH:mm"> <date language="de">dd.MM.yyyy</date> <date language="en">dd/MM/yyyy</date> <time language="de">HH:mm</time> <time language="en">hh:mm a</time> </date-format> </date-formats>
Instead of the Formats SHORT
, MEDIUM
,
STANDARD
, LONG
and FULL
of the DateFormat
class, it is also possible to use the Date and Time Patterns of
the SimpleDateFormat
class - this also applys for all Imp methods which
have a parameter 'format'.
The subnodes
<date>
and
<time>
can be used for language specific date/time formats.
Note that it is generally NOT necessary to define
language specific formats for just generating
formats that print e.g. month names. Month names
will automatically be output in the current or given
language. The language specific date/time formats
are necessary, when the FORMAT itself shall be
different, depending on the language. E.g. the
separation characters between day, month and year
shall be
.
for german and
/
for english.
All formats have to be predefined in file
dateformatter.xml
.
Table 4.1. Methods
Template Syntax | Description |
---|---|
$portal.imps.date.format() | retrieve current date formatted as defined in dateformatter.xml |
$portal.imps.date.format(date) | format provided "date" as defined in file dateformatter.xml |
$portal.imps.date.format(date, format) | format provided "date" with "format" defined in file dateformatter.xml |
$portal.imps.date.format(date, format, languagecode) | format provided "date" in the given language with "format" defined in file dateformatter.xml |
$portal.imps.date.format(format) | get current date formatted with "format" which is defined in file dateformatter.xml |
$portal.imps.date.format(format, languagecode) | get current date formatted in the given language with "format" which is defined in file dateformatter.xml |
$portal.imps.date.parse(formatteddate) | parse string "formatteddate" into a date object |
$portal.imps.date.parse(formatteddate, format) | parse string "formatteddate" which accords to "format" into a date object |
$portal.imps.date.parse(formatteddate, format, languagecode) | parse string "formatteddate" which accords to "format" in the given language into a date object |
$portal.imps.date.fromTimestamp(timestamp) | parse a unix timestamp into a date object |
$portal.imps.date.formatDate(*) | deprecated. use format(*) instead. |
$portal.imps.date.parseDate(*) | deprecated. use parse(*) instead. |
$portal.imps.date.getRfc3339Timezone() | Get current timezone, formatted according to http://www.ietf.org/rfc/rfc3339.txt |
$portal.imps.date.getRfc3339Timezone(date) | Get timezone of given date, formatted according to http://www.ietf.org/rfc/rfc3339.txt |
$portal.imps.date.socialTime(date) |
Print the given time in a "social time" format, e.g. like "10 seconds ago". The i18n Keys for localization are (
|
The GenticsDateFormatter may be used to format dates in the way that it was defined in the dateformatter.xml file. Syntax:
$portal.imps.date.format() ## Mar 6, 2006 1:31:46 PM $portal.imps.date.format("date") ## Mar 6, 2006 $portal.imps.date.format("time") ## 1:31 PM $portal.imps.date.parse("Mar 6, 2006 1:31:46 PM", "STANDARD").hours ## 13
The Number Formatter Imp provides you with automated formatting for
decimal numbers, currencies and filesizes. Locales are also taken
into account. Furthermore it provides you with rounding facilities.
The class used is
com.gentics.portalnode.formatter.GenticsNumberFormatter
.
There are no configuration parameters.
These are the methods provided by the Number Formatter. Please keep in mind that decimal numbers have to be provided as strings since velocity is incapable of handling floating point notation directly. All floating point numbers are formatted according to the portal's current locale.
Table 4.2. Methods
Template Syntax | Description |
---|---|
$portal.imps.number.floor(string) | top the given value down |
$portal.imps.number.ceil(string) | round the value up |
$portal.imps.number.round(string, [int]) | will round a floating point value for you. if you want to round to a specific precision use the optional parameter to set the number of digits to display. |
$portal.imps.number.currency(string, [string]) | this function ist used to format a floating point value according to locale settings. A desired locale (eg. en_US, de_AT, ...) may be provided via the second (optional) parameter. If there is no locale provided the function will stick to the portal's locale which is currently selectet and therefore will adapt output if the user switches between languages. |
$portal.imps.number.filesize(string, [int]) | automatically convert a filesize provided in bytes to the highest unit possible. Currently the largest unit supported is Yottabyte (YB, equals 2^80) which should suit well for all tasks. Decimal prcision can be defined using the second (optional) parameter. If left out a precision of 2 is applied by default. |
$portal.imps.number.bytesTo(string, string, [precision]) | convert a filesize from bytes to a desired target unit. The filesize is filled in as the first parameter, the desired unit es the second. Units supported are: "B", "KB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB". The third (optional) parameter describes the decimal precision which is applied to the output and defaults to 2. |
$portal.imps.number.format(string) | format a number according to current locale |
Here are some basic use cases of the Number Formatter.
$portal.imps.number.ceil("17.25") ## Output: 18 $portal.imps.number.floor("17.25") ## Output: 17 $portal.imps.number.round("17.25") ## Output: 17 $portal.imps.number.round("17.25",1) ## Output: 17.3 $portal.imps.number.currency("17.25") ## Output: €17,25 $portal.imps.number.currency("17.25","en_US") ## Output: $17.25 $portal.imps.number.filesize("1048576") ## Output: 1 MB $portal.imps.number.filesize("150000", 2) ## Output: 146.48 KB $portal.imps.number.bytesTo("1048576", "KB") ## Output: 1024.00 KB $portal.imps.number.bytesTo("1048576", "MB") ## Output: 1.00 MB $portal.imps.number.format("1048576.123") ## Output; 1,048,576.123
Format or work with strings for usage in teasers, html, javascript,
etc. The class used is
com.gentics.portalnode.formatter.GenticsStringFormatter
. There are no configuration parameters.
![]() | Note |
---|---|
All methods requiring a regular expression use the syntax as described in the Java API documentation for the class |
Table 4.3. Methods
Template Syntax | Description |
---|---|
$portal.imps.string.escapeHTML(string) | escapes special characters (like '<', '>', '&') with entities |
$portal.imps.string.escapeJS(string) | escapes special javascript characters (like '\', ''', '"') with \ to make them save for output in javascript strings |
$portal.imps.string.stripML(string) | Removes the embedded HTML tags from user input string to prevent potential problems (in fact it removes anything beginning with < and ending with > ). |
$portal.imps.string.trim(string, length) | trims the given string to be no longer than length characters |
$portal.imps.string.regexp(string, pattern, replacement) | replaces in string all occurances of pattern with replacement |
$portal.imps.string.testRegex(string, regex) | tests whether string matches regex |
$portal.imps.string.trimWords(string, length) | trims all words in string to be no longer than length. longer words are trimmed using ... as ellipsis. |
$portal.imps.string.trimWords(string, length, ellipsis) | trims all words in string to be no longer than length. longer words are trimmed using ellipsis. |
$portal.imps.string.trimWords(string, length, ellipsis, template) | trims all words in string to be no longer than length. longer words are replaced by template, where $trimmedword will be replaced by the trimmed word and $word with the original one |
$portal.imps.string.encodeURL(string[, string]) | URL - encodes the specified String and returns it. The encoding used to get the bytes for unsafe characters defaults to "utf-8" but may be given as second parameter (e.g. "iso-8859-1"). |
$portal.imps.string.implode(Array/Collection, seperator) | Converts the given array or collection into a string seperating the items with the given string seperator. |
$portal.imps.string.implode(Array/Collection, separator, prefix, postfix) | See above. In addition the items will be pre and postfixed. |
$portal.imps.string.toUpper(string) | Converts the given string to all uppercase. |
$portal.imps.string.md5(string) | Compute the md5 hash of the given String. |
Example 4.1. implode
Convert an array of numbers into a special string.
Array: [1,2,3] Separator: ; Prefix: ( Postfix: ) Result: (1);(2);(3)
Example 4.2. escapeHTML
Fill a HTML textbox inside a velocity template with an escaped value.
<textarea name="text"> $portal.imps.string.escapeHTML($value) </textarea>
Example 4.3. escapeJS
<script language="JavaScript"> var message = "$portal.imps.string.escapeJS($value)"; alert(message); </script>
The RuleMatcherImp is used to evaluate rules in templates. The
corresponding class is
com.gentics.portalnode.formatter.GenticsRuleMatcherImp
. There are no configuration parameters for the
RuleMatcherImp.
Query any data accessible by supported datasources by rules, loop
through results. Support for nestable queries. The class used is
com.gentics.portalnode.formatter.DatasourceQueryImp
. There are no configuration parameters.
Table 4.5. Methods
Template Syntax | Description |
---|---|
$portal.imps.query.rule = [rulestring] | set the primary rule (for fetching objects) |
$portal.imps.query.sortBy = [sortBy] | Sort results by a certain attribute; may also contain a comma separated list of attributes. (optional) |
$portal.imps.query.sortOrder = [sortOrder] | set the sortorder to be used. Possible values
are:
|
$portal.imps.query.data.[id] = [data] | set the data parameter [id] to the value [data]. Data parameters can be evaluated in rules and subrules |
$portal.imps.query.subrules.[id] = [subrulestring] | set a named subrule. Subrules can be used in primary rules and other subrules |
$portal.imps.query.result | Get the list of objects filtered by the primary rule |
$portal.imps.query.count | Get the number of objects filtered by the primary rule |
$portal.imps.query.reset() | Reset all previously set rules, subrules and data |
$portal.imps.query.versionDate | Property versionDate (date to be used for
versioned queries if the datasource supports
versioning) |
$portal.imps.query.resetVersionDate() | Reset property versionDate (query on current
data) |
$portal.imps.query.versioning | True when the datasource supports versioning false if not |
$portal.imps.query.getDifference(List list1, List list2) | Get the difference of list1 and list2, that means a list of objects contained in list1 but not in list2 |
$portal.imps.query.getDifferenceCount(List list1, List list2) | Get the difference count of list1 and list2, that means the number of objects contained in list1 but not in list2 |
$portal.imps.query.getIntersection($list1, $list2) | Get the intersection of list1 and list2, the result is a list of pairs, every element holds in $pair.left the object from $list1 and in $pair.right the object from $list2 |
$portal.imps.query.prefillAttributes = [attributeslist] | Set a list of attributes (including linked objects and their attributes) that shall be prefilled in the fetched objects (increased performance) |
## get all companies #set ($portal.imps.query.rule = "object.obj_type == 50001") #set ($companies = $portal.imps.query.result) ## for each company, get all users #set ($portal.imps.query.rule = "object.obj_type == 50000 && object.organisation == data.organisation") #set ($portal.imps.query.prefillAttributes = ['firstname','lastname']) #foreach ($company in $companies) #set ($portal.imps.query.data.organisation = $company.contentid) #set ($portal.imps.query.sortOrder = "ASC") #set ($portal.imps.query.sortBy = "lastname") #set ($users = $portal.imps.query.result) <table> #foreach($user in $users) <tr> <td>$user.firstname</td> <td>$user.lastname</td> </tr> #end </table> #end
Can be used for calculations in templates. The calculator imp
supports arbitrary calculator variables that can be used
independently. The class used is
com.gentics.portalnode.formatter.CalculatorImp
.
There are no configuration parameters.
Table 4.6. Methods
Template Syntax | Description |
---|---|
$portal.imps.calc.[id].reset() | reset the calculator variable [id] to 0 |
$portal.imps.calc.[id].add([number]) | add a value to the calculator variable [id] |
$portal.imps.calc.[id].sub([number]) | subtract a value from the calculator variable [id] |
$portal.imps.calc.[id].mult([number]) | multiply the calculator variable [id] with a value |
$portal.imps.calc.[id].div([number]) | divide the calculator variable [id] by a value |
$portal.imps.calc.[id].precision = [int] | set precision to be used for calculations |
$portal.imps.calc.get([id]) | See $portal.imps.calc.[id] |
$portal.imps.calc.[id] | get the current value of the calculator variable [id] |
$portal.imps.calc.[id].format | get the current value of the calculator variable [id] formatted according to current locale |
## reset the variables mycalc1 and mycalc2 $portal.imps.calc.mycalc1.reset() $portal.imps.calc.mycalc2.reset() ## change the variables $portal.imps.calc.mycalc1.add("1.5") $portal.imps.calc.mycalc2.sub("7000") $portal.imps.calc.mycalc2.add($portal.imps.calc.mycalc1) ## mycalc2 should now be -6998.5 Result: mycalc2 = <strong>$portal.imps.calc.mycalc2</strong>
Can be used to generate Plinks (links to content). The class used is
com.gentics.portalnode.formatter.GenticsPLinkImp
.
There are no configuration parameters.
Table 4.7. Methods
Template Syntax | Description |
---|---|
$portal.imps.link.to([contentid]) | Generate the URL to the given contentid. The URL will not be XML escaped. When this method is used inside a GenticsContentModule, the link will automatically be directed to that portlet, otherwise the portal-wide configured plinkprocessor will be used. |
$portal.imps.link.to([contentid], [escapeXML]) |
Generate the URL to the given
contentid. When
escapeXML
is set to
true
, the generated URL will be XML
escaped. When this method is used
inside a GenticsContentModule, the
link will automatically be directed
to that portlet, otherwise the
portal-wide configured
plinkprocessor will be used.
|
$portal.imps.link.to([contentid], [portletid]) | Generate the URL to the given contentid. The URL will not be XML escaped. The URL will be directed to the portlet [portletid]. |
$portal.imps.link.to([contentid], [portletid], [escapeXML]) |
Generate the URL to the given
contentid. When
escapeXML
is set to
true
, the generated URL will be XML
escaped. The URL will be directed to the portlet [portletid].
|
The VelocityToolsImp is a wrapper for the Velocity Tools. The syntax of each Tool is described on the Velocity Tools Website.
Optionally it is possible to configure the location of a xml file (toolbox.xml) as used by XMLToolboxManager.
For this define the parameter configuration
with the file path to the .xml file. (System properties ${myprop} are resolved)
The following default VelocityTools are available without changing configuration:
$portal.imps.velocityTools.date
- DateTool$portal.imps.velocityTools.math
- MathTool$portal.imps.velocityTools.number
- NumberTool$portal.imps.velocityTools.render
- RenderTool$portal.imps.velocityTools.esc
- EscapeTool$portal.imps.velocityTools.alternator
- AlternatorTool$portal.imps.velocityTools.parser
- ParserTool$portal.imps.velocityTools.list
- ListTool$portal.imps.velocityTools.sort
- SortTool$portal.imps.velocityTools.iterator
- IteratorToolExample 4.4. Simple Example of the usage of EscapeTool and RenderTool
## We don't want to type the whole path each time... #set( $tools = $portal.imps.velocityTools ) #set( $torender = "$tools.esc.getHash()set( $tools.esc.getD()harhar = 'World' ) \ Hello $tools.esc.getD()harhar !!!" ) Rendering: $torender <pre>$tools.render.eval( $ctx, $torender )</pre>
Can be used to generate internationalized output in templates. The class used is
com.gentics.portalnode.formatter.I18nImp
.
There are no configuration parameters.
Table 4.8. Methods
Template Syntax | Description |
---|---|
$portal.imps.i18n.language | The currently set language, or null if the Imp shall use the current portal language. Note that setting the language of an I18nImp does not affect the portal language. |
$portal.imps.i18n.resetLanguage() | Method to reset the currently used language. |
$portal.imps.i18n.translate(String key) | Translate the given key into the current language (either set by $portal.imps.i18n.language or the portal language). |
$portal.imps.i18n.translate(String key, String languageId) | Translate the given key into the language with id languageId . |
Can be used to sort Resolvables by arbitrary properties. The class used is
com.gentics.portalnode.formatter.SortImp
.
There are no configuration parameters.
![]() | Note |
---|---|
Implementation note: The given sort properties might
also be paths to properties of resolved subobjects.
The general syntax for sort properties is
|
Table 4.9. Methods
Template Syntax | Description |
---|---|
$portal.imps.sorter.sort(Collection collection, String[] properties[, boolean caseSensitive][, String languageCode]) |
Sort the given collection (might
also be an array or a map) by
the given list of properties.
The sortorder can be
independently set for each
property in the list. When
sorting by only one property,
one can also pass a single
String instead of an array of
Strings as value for the
parameter
The function parameter
The function parameter
|
This Imp can be used to get content from a given URL and include it into the template. The class used is
com.gentics.portalnode.formatter.URLIncludeImp
.
There are no configuration parameters.
Table 4.10. Methods
Template Syntax | Description |
---|---|
$portal.imps.url.include(String url[, int cacheLifeTime[, int timeout[, String defaultContent]]]) |
Will include the content fetched from the given
The content will be cached for
The parameter
If the parameter |