Translatable text fields can be used to allow the user to provide a different value for all of the different languages they have on their community. If only one language is installed, then a single text field is shown instead.
Translatable fields are commonly used for when an administrator has to provide the name for something which may need to be different depending on the language.
Translatable fields are designed to be used inside the AdminCP only. They are not intended for use by users on the front-end.
The Translatable class works with the three text field types available to IPS4 forms: text inputs, textareas and WYSIWYG editors. The class takes care of creating the underlying text fields for you. Values are saved into the language system, and retrieved later for use.
To use translatable fields in your code, you use the \IPS\Helpers\Form\Translatable class within the Form Helper.
Creating the element
When creating the element, your $options parameter requires at least two values:
-
app
The key of the application that owns the language string -
key
A unique key for this language string (as with standard language strings, alphanumeric only). If you are displaying a "create" form for something which hasn't been created yet, you can pass NULL as the key.
Unlike other fields, the $defaultValue must be NULL. The class will automatically fill in the current value for the key by fetching it from the language system.
For example, the code to create your element will look something like:
$form->add( new \IPS\Helpers\Form\Translatable( 'my_translatable_field', NULL, TRUE, array( 'app' => 'app', 'key' => 'my_language_string' ) ) );
This adds a standard single-line text input to the form. To create a textarea instead, add a textArea key to your $options array, set to TRUE.
To create a WYSIWYG editor, add an editor key to your $options array. The value of editor should be an array that contains the options accepted by the \IPS\Helpers\Form\Editor class.
Handling submissions
When processing a form containing Translatable fields, you must save the returned values to the language system manually, like so:
if ( $values = $form->values() ) { \IPS\Lang::saveCustom( 'app', 'my_language_string', $values['my_translatable_field'] ); // Other field processing... }
Report Document