TextTool - Documentation topics on: global language variables,glossarywebapi,languagewebapi,messagetool,texttool,velocity tools,.

TextTool

The TextTool Velocity viewtool allows you to access the values of dotCMS Language variables from within your Velocity code.

Note: This tool should only be used in the request scope.

Methods and Usage

The Text Tool supports the following methods. (Please see Parameters, below, for a description of each of the parameters).

MethodReturn
Type
Description
$text.get(key)
$text.key
StringRetrieves the value of the Language variable specified by the key in the current user's selected language'.
$text.get(key, languageId)StringRetrieves the value of the Language variable specified by the key, in the specified language.
$text.canDefaultContentToDefaultLanguage()BooleanReturns the value of the DEFAULT_CONTENT_TO_DEFAULT_LANGUAGE property.
$text.canDefaultPageToDefaultLanguage()BooleanReturns the value of the DEFAULT_PAGE_TO_DEFAULT_LANGUAGE property.
$text.canDefaultWidgetToDefaultLanguage()BooleanReturns the value of the DEFAULT_WIDGET_TO_DEFAULT_LANGUAGE property.
$text.getBoolean(key)BooleanReturns the value of the specified Language variable in the current user's selected language, interpreted as a Boolean.
$text.getBoolean(key, languageId)BooleanReturns the value of the specified Language variable in the specified language, interpreted as a Boolean.
$text.getDefaultLanguage()StringReturns the Default language configured for dotCMS (as a language descriptor).
$text.getFloat(key)FloatReturns the value of the specified Language variable in the current user's selected language, interpreted as a floating point number.
$text.getFloat(key, languageId)FloatReturns the value of the specified Language variable in the specified language, interpreted as a floating point number.
$text.getFromSessionLanguage(key)StringReturns the value of the specified Language variable for the language set in the user's session.
$text.getFromUserLanguage(key)StringReturns the value of the specified Language variable for the language set ???????.
$text.getInt(key)IntegerReturns the value of the specified Language variable in the current user's selected language, interpreted as a whole number.
Note: The language variable must be entered into dotCMS as a whole number (without any decimal places), or this method will return zero (the whole number portion of a floating point number will not be returned).
$text.getInt(key, languageId)IntegerReturns the value of the specified Language variable in the specified language, whole number.
Note: The language variable must be entered into dotCMS as a whole number (without any decimal places), or this method will return zero (the whole number portion of a floating point number will not be returned).
$text.getLanguage(languageId)StringReturns a Language descriptor for the language with the specified language code.
$text.getLanguage(languageCode, countryCode)StringReturns a Language descriptor for the specified language code and country code, only if a language is configured which uses those codes.
Note: If you specify a language code and country code combination which are not configured in dotCMS, this method returns only a dash (e.g. -). You may use this to determine if a particular combination of language code and country code are configured in dotCMS.
$text.getLanguages()List of StringsReturns a list language descriptors of all the languages configured in dotCMS.

Parameters

ParameterTypeDescription
keyStringThe Language Key of a Language variable defined in the dotCMS Language configuration screen.
languageIdStringThe language ID assigned to a language configured in dotCMS.
Note: Although the language ID assigned by dotCMS is always an integer, the language ID must be passed to all methods as a String.
languageCodeStringA valid language code identifying a language configured in dotCMS.
countryCodeStringA valid country code identifying the country of a language configured in dotCMS.

Language Descriptors

The Text Tool methods return information about the configured languages as a language descriptor, which displays the language code, followed by a dash, followed by the country code, all in lower case. For example, when identifying the default configured language (U.S. English), the Text Tool methods display the following:

en-us

Examples

Check and Retrieve the Value of a Language Variable

The following code checks to see if a Language variable has been defined in the currently selected language; if it has, the code displays the language variable without specifying a language (so it will display in the currently selected language), otherwise it displays the value of the variable in the default language.

#if( $utilMethods.isSet($!text.greeting) )
    <p>$text.get("greeting")</p>
#else
    <p>$text.get("greeting", "1")</p>
#end

Check if a Specific Language and Country Is Defined

The following code checks to see if a specific combination of language (es, for Spanish) and country (MX, for Mexico) is defined in dotCMS.

#if( $text.getLanguage( "es", "MX" ) != "-" )
    ...
#end

Display a List of All Configured Languages

The following code lists the language descriptors of all languages configured in your dotCMS system:

<h2>Installed Languages:</h2>
<ul>
#foreach($lang in $text.getLanguages())
    <li>$lang</li>
#end
</ul>

Toolbox.xml Configuration

The Text Tool is enabled by default in dotCMS. To ensure the Text Tool is enabled, verify that the following lines exist in your toolbox.xml file:

<tool>
    <key>text</key>
    <scope>request</scope>
    <class>org.apache.velocity.tools.struts.MessageTool</class>
</tool>

Additional Notes

  • The Text Tool provides a Velocity Viewtool mapping to the dotCMS LanguageWebApi class.
  • The LanguageWebApi class is also available via several other mappings, such as $globalvars and $glossary.
    • However other mappings of the LanguageWebApi are deprecated, and may not be supported in future versions.
    • Therefore, for all new development, you should access the Text Tool methods using the $text Viewtool mapping.
  • For more information on configuring languages in dotCMS, please see the Language Configuration documentation.
  • For complete documentation on this viewtool, please see the LanguageWebApi documentation.