Library of localized label/hint/help/alert messages

[ebruchez]

The idea would be to allow to create a localized "Name" label, for example, and DnD associate it with a given form control. Then the label would come in with all existing translations.

Questions/ideas:

• How would labels be created and stored?
  • specific translation editor
    • could be special form (see also UI to configure properties #2238)
    • must run in Form Runner
    • but form definition doesn't need to be created by Form Builder
    • singleton form
    • could version data later?
    • should we handle singleton for a "global" library vs. one per app?
    • support import/export
      • if custom XML, maybe configure XSLT for transform?
  • read/import from existing XML/JSON/Java resource bundles later
• if translations are updated/expanded, those should become available to existing forms (unless a "copy" mode is also available)
• What would happen if translations are removed from the list? Or renamed?
• maybe fr:r() in controls instead of xxf:r() to refer to a resource.
• Form Builder UI
  • DnD from a labels toolbox
  • OR autocomplete from label/etc. fields
  • and/or from Control Settings

+1 from evaluator

[ebruchez]

Open questions:

• Q:Should we be able to force the user to use the Resources Library? That is, the form author cannot enter his/her own labels at all in a certain mode. Mode would be configured globally so that admin can force this? Also available at a form per form setting?
  • A: We propose disabling mix-and-match. This also allows to simply load the Resources Library into the form at runtime, with a possible transformation.
• Q: Should the Resources Library Editor be on a separate page or open in a dialog in the builder? A separate page would be easier and also allow direct linking. A dialog would make things look more integrated.
  • A: For now, separate page.
• Q: We don't have data versioning right now, so we can either embed a specific version of the labels database, or refer to it by pointing to the single version of the data in the database. Later, we can point to a specific version of the data.

[ebruchez]

Editing resources

Form Builder presents the user with a new button, link or URL to a new page or dialog which allows adding, removing, and modifying labels, hints, help resources, and alert resources. We call this the Resources Library Editor.

A resource is identified by a name or key, which can contain periods to indicate an optional hierarchy, and a value, which is the resource or message in a particular language. Each resource with a given key can also be localized in any number of languages so that one value per language is available. The set of keys and values constitutes the Resources Library. When the Resources Library is saved, it becomes available to the form author in Form Builder, and to existing published form definitions. [NOTE: We can consider an option to make the updating of resources for a given form definition a separate step.] In the first version of this feature, there is a single Resources Library, shared among all form definitions.

From the Resources Library Editor, it is possible to export all existing resources to XML, and to import resources from an XML file. The exact format remains to be defined.

From an implementation point of view, the resources are edited with a special singleton form called “orbeon/resources”, and the associated data is stored in the Form Runner database.

In a first version, removing or renaming a resource key which is in use in a given form definition does not cause those form definitions to be updated. Therefore the form author must be careful when renaming or removing resource keys.

Using resources

In Form Builder, when editing labels, hints, help and alert messages, a way is provided to use one of the Resources Library resources instead of entering a text directly. The user does this by selecting the key of the resource to use. Some help is provided to select a key, with a dropdown and/or autocompletion list. After associating a key for the given resource, all languages present in the associated resource are automatically available. When the form author changes the form definition language, the given resource, when it is a label or hint, switches as it usually does when the label or hint is entered directly.

Form definition options

We suggest in the first version of the feature to disallow mix-and-match, in a given form definition, of resources entered directly and resources entered via the Resources Library. An option is provided to configure a form definition to use one mode or the other.

Internal format of the resources

When the form definition uses resources from the Resources Library, the standard “resources instances” of the form definition contains a cacheable, read-only version of the Resources Library instead of the inline resources as is the case now.

Other

The standard Form Runner persistence API can be used to read and write the resources in XML format. This works as it would for other form data, except that the XML will be in a particular format appropriate for the resources. The caller of the API will need to know the “document id” of the resources document.

A translation system would GET the XML document, make changes to it, and then PUT it back with the changes.

[ebruchez]

Questions:

• Should itemsets be part of the Resources Library? In a first iteration, I would think yes. If they are not, or only optionally, then we have the issue of merging, in the form definition, local resources, and resources from the Resources Library.
• Does it make sense to allow grouping of, say, a label and a hint? If you have say a "First Name" control, you would imagine that the hint would go with the label. Maybe P2?
• What about the Explanation text? Probably the same. But the UI needs to be changed so that instead of the text editor, you select a resource key.

[ebruchez]

I think we are contemplating that, like for section templates, resources from the Resources Library that are in use by a given form would be embedded at publish time. This would probably follow the principle of least surprise.

Updating resources would require republishing the form from Form Builder, or from the Home page. The Home page could even have an action specific to just update resources (P2).