TextTool (Language Viewtool)

Last Updated: Mar 31, 2023
documentation for the dotCMS Content Management System

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

The following example shows how the TextTool is mapped in the toolbox.xml file:

<tool>
    <key>text</key>
    <scope>request</scope>
    <class>com.dotcms.rendering.velocity.viewtools.LanguageViewtool</class>
</tool>

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

Aliases

The TextTool has multiple aliases, each of which identically map to the LanguageViewtool class with request scope. Thus, while the examples on this page use $text, the following keys are equally valid for invoking this viewtool, and can be used interchangeably:

  • $languagewebapi
  • $langbackendwebapi
  • $globalvars
  • $glossary

Please use whichever one best promotes readability or conceptual clarity.

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

List All Configured Languages

The following code lists the language descriptors and key properties of languages configured in your dotCMS system:

#set($languages = $text.getLanguages())
Available Languages:
<ul>
    #foreach($lang in $languages)
    <li>lang: ${lang}</li>
    <li>
        <ul>
            <li>language_id: $!{lang.id}</li>
            <li>countryCode: $!{lang.getCountryCode()}</li>
            <li>languageCode: $!{lang.getLanguageCode()}</li>
            <li>language: $!{lang.getLanguage()}</li>
        </ul>
    </li>
    #end
</ul>

An example of the above code's output:

Available Languages:
<ul>
    <li>lang: en-us</li>
    <ul>
        <li>language_id: 1</li>
        <li>countryCode: US</li>
        <li>languageCode: en</li>
        <li>languageCode: English</li>
    </ul>
    <li>lang: fr-ca</li>
    <ul>
        <li>language_id: 4600065</li>
        <li>countryCode: CA</li>
        <li>languageCode: fr</li>
        <li>language: French</li>
    </ul>
</ul>

(Thanks to Dave Hess for improving this example!)

Additional Info

For more information on configuring languages in dotCMS, please see the Language Configuration documentation.

On this page

×

We Dig Feedback

Selected excerpt:

×