TextTool (Language Viewtool)

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).

Parameters

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.