Module: Editor
Version: 18.02 +
Description
Up to Futurama version 18.02 the text management of Futurama could be divided into two categories: text management outside the Futurama definition models (for example HTML-files and XSLT-files) and text management within the Futurama definition models. For the second category knowledge of the Futurama Editor, and building applications with this Futurama Editor was necessary in order to change texts. This also meant that setting up a multilanguage Futurama application took some time, and had to be done by a developer of the Futurama models. In Futurama version 18.02 functionality is added to read text resources from a resource document. This implies that text management for all the texts in a Futurama application can be done without any knowledge of building applications with Futurama. This makes it also very easy to make a Futurama application multi-language (see the paragraph “Multi-language”). At this page is explained how to set up a text resource document to be used in your Futurama application.
From Futurama release 19.03 onwards it is possible to use PageData in Futurama Output objects (i.e. HTMLInclude, Button, GraphConverter etc.). PageData is functionality that makes it possible to put dynamic content into HTML files or Futurama Output objects. Before, when you wanted to put dynamic content into HTML files you had to turn the HTML into an XSLT file. This conversion requires experience with XSLT. The use of PageData functionality also reduces the use of Action objects in your Futurama model, because you do not have to set dynamic texts of the Output object with an Action object anymore. For more information about PageData see the paragraph “Dynamic texts with PageData”.
Concept
Document properties
To use the text management functionality, there are two new properties that have to be defined within the Document (see the document page). The first property that has to be defined is the LanguageID. This property has to be a reference to an object of type long, such as a Fixed or a UserVariable. The latter is typically used in the situation of Multi-language where the user can change between languages. With this property the language is defined that is used for the text, where 0 is the first language, 1 is the 2nd language etc. For the second property, a ResourceDocument has to be defined. An example of the structure of such a ResourceDocument is given below. Here is also described how the texts can be defined within a ResourceDocument.
ResourceDocument
The ResourceDocument that is used within the Document, has to be an xml-file with a predefined structure. This doesn’t mean that the Resources have to be defined within xml, but have to be converted to the proper xml-structure in order to be used. It is for example possible to convert an Excel file to XML within Futurama (using the formula Convert Excel to XML) and then use an XSLT to convert this to the proper xml-structure. An example of this can be found below. The XML that is used as ResourceDocument has to have the next structure:
<ResourceManager xmlns="http://www.ActuIT.nl/DataTypes/Resources/" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
<languages>
<arr:string>NL</arr:string>
<arr:string>EN</arr:string>
</languages>
<resources>
<Resources>
<ResourceID>Title</ResourceID>
<ResourceData>
<translations>
<arr:string>TitelNL</arr:string>
<arr:string>TitleEN</arr:string>
</translations>
</ResourceData>
</Resources>
<Resources>
<ResourceID>Weblabel</ResourceID>
<ResourceData>
<translations>
<arr:string>Weblabel_NL</arr:string>
<arr:string>Weblabel_EN</arr:string>
</translations>
</ResourceData>
</Resources>
</resources>
</ResourceManager>
Within the the different languages are defined that are used in the application. Below this, the resources are defined. For every text, a different section “Resources” is created. Within this section, the ResourceID is defined and the texts are defined for the different languages. Below, in the paragraph “Defining texts within Futurama”, the property ResourceID will be explained.
Within this example 2 different languages are used, Dutch and English. In the section at the top of the example, is defined that the texts with LanguageID 0 is Dutch and the texts with LanguageID 1 is English. If the LanguageID is 0, the first translation will be used. If the LanguageID is 1, the second translation will be used. Depending on the number of languages that are defined within this xml, the website can create the text. If only 1 language is used, the second string within and have to be deleted.
Defining texts within Futurama
When the text is created using a ResourceDocument, the texts, that are used in the Futurama Editor, have to be defined in a different way. The resources within the ResourceDocument are used for all the text properties within Futurama. With the ResourceDocument the text will be generated, depending on the LanguageID. Normally the text within, for example, a weblabel is defined as “Weblabel”. When using a ResourceDocument, the text definitions have to be changed. Instead of defining a text, a ResourceID from the ResourceDocument is used. When you want to use the Weblabel defined in the example above, you need to define the text property within the weblabel as follows: “{{Resource:Weblabel}}”. Depending on the LanguageID, the text of the Weblabel is now loaded from the ResourceDocument. When the LanguageID is 0, the text “Weblabel_NL” will be shown within the weblabel. When the LanguageID is 1, the text “Weblabel_EN” will be shown within the weblabel on the website.
It is also possible to define texts within a subdocument of a Futurama application. In this situation, it isn't possible to define a new resource document within the different subdocuments. The resources that are defined within the Futurama application will be used within all the subdocuments of this application.
Changing and testing texts
Once the structure of the ResourceDocument with texts is set, changes to this document can be made. For example adding another language, or change existing texts. Suppose you have a Futurama Website application and the structure of the ResourceDocument is used. When you open your Futurama application in your browser, Futurama will load the ResourceDocument in cache. This improves the performance of your application as Futurama does not have to load this document for each new request. However this also means that changes in the ResourceDocument are not immediately effected after replacing the old ResourceFile by a new one (as the version that is in cache will be used). Actually the new document is used after the application pool of your Futurama application is reset.
For developing purposes it is not desirable to reset the application pool for each change of the ResourceDocument. This can be prevented by using the ClearCache object within your Futurama document with the ResourceFile as TargetObject. When using text management in Vision, the TargetObject of the ClearCache is set to the VisionReference (see more information in the secion 'Text management in Vision' below). Each time this ClearCache is executed the ResourceFile will be loaded again. Make sure you don’t execute the ClearCache each new session, but only at the moments you replace the ResourceDocument by a new version. This can be done by adding a parameter in the URL and read the value of this parameter using the ReadRequestParameter formula. The value of the parameter can be used as a condition on the ClearCache object. So only when this parameter is added in the url, or only when the value of this parameter is changed, the new ResourceDocument will be read. With this concept it is possible only to read the ResourceDocument again when you actually want to (when you replace the document by a new version).
Multi-language
Description
Using the text management with the ResourceDocument, it is easy to make a website multi-language. Within the ResourceDocument, the different languages and the resources that need to be used can be defined. When a new language has to be added to the website, only a new line needs to be defined at the languages and at the different resources that are used. Next to this, the LanguageID within the application will define which language to use.
Example defining paths
When using multi-language, you can also use a ResourceID to define the paths to different HTML or XSLT files. You can define the full path within the ResourceDocument, or define part of the path that is different between the languages.
Define full path:
“{{Resource:Path}}”
Define part of the path:
“data\{{Resource:Language}}\Introduction.html”
Define part of the file name:
“data\XSLT\Introduction{{Resource:Language}}.html”
LanguageID within XSLT
When a LanguageID is used within Futurama, this LanguageID can also be used within an XSLT file. Within the XSLT, the attribute @LanguageID is available. Within the XSLT, for example the text “” can be used to get the LanguageID that is used. With this attribute, different texts can be defined within the XSLT for the languages that are used.
Resources within HTML
Resources can be used directly into an HTML file by simply replacing the text by “{{Resource:text}}”. Note that when the text is long, it might be considered to create separate HTML files, for the different languages, containing the text and use a ResourceID to refer to the proper HTML file.
Text management in Vision (21.01+)
Up to Futurama 20.12 it was only possible to use a local file (i.e. Excel or XML file) for text management. From Futurama 21.01 it is also possible to use the text management in Vision. Within the Vision Management Site you can define the resources. See this page for more information. When using text management in Vision, the ResourceDocument can be retrieved from Vision using the VisionReference GetResourceManagerXML. The steps to import the resources using this VisionReference are explained below.
Importing resources using a VisionReference
When calling the VisionReference GetResourceManagerXML, the XML containing the ResourceDocument is returned in the result. In the Futurama Editor the following steps can be performed for importing resources from the result:
- Create a VisionReference and select the Data/GetResourceManagerXml method. No parameters are required.
- Create an XmlNode with the created VisionReference as source
- Create an XmlField under the created XmlNode with an XPath to the value of 'ResourceManagerXml' with Type string.
- For the ResourceDocument property under Document make a reference to the created XmlField.
Example
Example 1 (ResourceDocument from Excel)
Use an Excel file as ResourceDocument.
Downloads
Download the files that are used for the example MultiLanguage.
Description
After downloading the file, follow the next steps:
- Create a local website application, using Futurama 18.02
- Extract the files from the zip-file and place them within this website
Within the zip-file, you will find an example Futurama web application, an Excel file and an XSLT file.
Within this application, the next steps are executed:
- The formula Convert Excel to XML is used to read the Excel file with the resources and convert it to XML.
- The XML of the converted Excel file isn’t in the correct format yet and is converted with the provided XSLT file.
- The XML that is made with the XSLT is used as ResourceDocument. And an UserVariable is used as LanguageID for the document.
- On the website two buttons are made. The first button will change the LanguageID to 0 (Dutch) and the second will change the value to 1 (English).
- Using the resources, the text of the title and weblabel are defined as described in the paragraph “Defining texts within Futurama”.
- Depending on the LanguageID, the text of the title and weblabel is filled on the website.
Conversion
When making a new application, the procedures stated above can be followed right from the start regardless of the Futurama application to be unilingual or multilingual. In practice, however, there often already is an existing Futurama application. In this paragraph a step-by-step approach is presented that can be followed to convert an existing application into an application where all the text is defined outside the Futurama Document. Text management, including making the application multilingual, can then be done without any knowledge of building applications with Futurama.
Before commencing with the conversion it is recommended to review the example given above, especially for steps 1 and 2.
Creating the Excel file
As stated above the ResourceDocument containing all the texts has to be an XML file. It is also possible to use an Excel document instead and have it transformed to XML by Futurama. For most users Excel is more convenient to work with than XML. For this reason the latter approach is used in this step-by-step plan.
- Download the zip-file from the example. The Excel file ResourceDocument.xsls found in here serves as the basis for the ResourceDocument.
- Remove row 2 and 3, these texts are examples only. Don’t remove the first row.
- The Excel file is set up for two languages (NL and EN). If the application is unilingual, just remove column C.
- When converting the application all texts have to be replaced by ResourceID of the format {{Resource:}}. Instead of needing to repeatedly type these texts it is possible to create an extra column in the Excel file that automatically composed the text to be copied. The Excel formula that can be used is “={{Resource:"&A2&"}}".
- Like the previous step, this step is also optional. In order to prevent duplicate ResourceIDs the Excel file can be extended with an extra column that counts the number of occurrences of every ResourceID in column A. The Excel formula COUNTIF() is typically suited for this: =COUNTIF(A:A;A2).
- Like the previous steps, this step is also optional. In order to prevent creating multiple ResourceIDs that contain exactly or nearly exactly the same text extend the Excel file with an extra column that counts the number of occurrences of every text. The Excel formula COUNTIF() is once again suited for this.
The Excel file, although still containing only the headers, is ready to be imported.
Importing and transforming Excel file to XML in Futurama
The next step is to import the Excel file into Futurama and transform it to XML. For this transformation the XSLT file ConvertResourceSheet.xslt is used. This file can also be found in the zip-file mentioned above.
- Follow the steps in the example to import the Excel file and transform it to XML. This has to be done in the Futurama Document that contains the objects that make up the website (such as the WebPages).
- A common way, though not the only one, of offering the choice between languages on a website is by a set of buttons (often with a flag) on which the user can click to choose a specific language. This method is also shown in the example. In the steps below it is assumed this method is also chosen.
- Make sure the properties LanguageID and ResourceDocument of the Document refer to the UserVariable containing the ID of the language and the XML resulting from the transformation of the Excel file respectively.
When importing an Excel file it is important to make sure that the Range in Excel which is referred to by the formula Convert Excel to XML contains all the data. Data that is not covered by the Range is omitted. It is also not allowed to have blank Cells in the Excel Range.
Now that the preparatory work has been done, the following steps explain how the several types of files containing texts as well as the texts defined in Futurama can be converted. Note that for a unilingual setting only the steps regarding the texts in Futurama Documents have to be executed; all other texts already exist outside Futurama.
HTML and XSLT files
HTML files are supportive files containing the HTML that will be rendered in the webapplication using HTMLInclude. XSLT files contain the definition of how XML data, generated by Futurama, is to be transformed into HTML using a XmlConverter which in turn will be rendered in the webapplication. The following steps explain first the approach that can be taken to convert these files in a multilingual setting.
There are in essence two approaches when it comes to HTML and XSLT files:
- For every file, the translation is added to the existing file. The upside is that the number of files will remain the same. The downside is that the contents of the resulting mixed files will be more difficult to interpret. For HTML files the ResourceID can be inserted into the HTML file itself (see the paragraph “Resources within HTML”).
- A copy is made of every file and the translation is performed in the copy. The downside of this method is that the number of files is essentially doubled. The upside is that a clear distinction is made between the languages, each file is far easier to translate and to interpret and no files have to be changed to another type.
In the following steps the second method is used. It is assumed that all HTML and XSLT files are located in subdirectories of a single directory “data”.
- In the main directory “data” make two new root-directories for each language e.g. “dataNL” and “dataEN”. Note that these names will be defined by a ResourceID.
- Copy all directories in the original “data”, except of course for “dataNL” and “dataEN”, into the new directories.
- Define in the Excel sheet a ResourceID (e.g. “rootpath”) with values “dataNL” and “dataEN” i.e. the names of the new directories.
- In the Futurama Editor replace in the property HTMLFileName of every HTMLInclude object the term ‘data’ by ‘data\{{Resource:rootpath}}’.
- In the Futurama Editor replace in the property XSLTFileName of every XmlConverter object the term ‘data’ by ‘data\{{Resource:rootpath}}’.
The only task remaining is to translate the text in the files in de directory “dataEN”.
Tooltips
Tooltips are texts or images that appear when hovering over or clicking on an element in a website. They are often connected to info-buttons. Tooltips containing fixed contents are usually defined outside Futurama, whereas tooltips that contain variable contents are often defined within the Futurama Document itself. The latter will be discussed below in the paragraph Text in Futurama document(s). Fixed tooltips are usually defined in a single JavaScript file e.g. tooltips.js. When tackling single files the following approach can be followed:
- Rename the file by adding a language extension to the name e.g. tooltipsNL.js
- Copy the file and change the language extension to e.g. tooltipsEN.js.
- Define in the Excel sheet a ResourceID (e.g. “extension” or “fileextension”) with values “NL” and “EN” i.e. the extensions of the new filenames.
- In the Futurama document search for the HTMLInclude object(s) that import the JavaScript file
- Add the ResourceID to the property HTMLCode. This will result in something like “………../tooltips{{Resource:extension}}.js”
The only task remaining is to translate the text in the new file.
Note that the ResourceID defined in step 3 can be used for all files, so it is often practical to use a generic name for this ResourceID. Note also that the approach followed here is not limited to JavaScript files (such as tooltips) but applies to all files. Another example are image files.
Images
Images are varied and range from a small arrow or a checkmark to webpage spanning background images, headers and buttons. When tackling images the approach to be taken depends on the number of images that have to be ‘translated’.
- When there are only a limited number of images containing text that will have to be translated it is most convenient to just create a cousin and add an extension to it’s name, analogous to the approach followed by Tooltips.
- When there are many images that need a translated ‘cousin’ it pays off to create a separate directory for every language, analogous to the approach followed by HMTL and XSLT files.
Templates
Templates are often stored in a single directory. The method for tackling HTML and XSLT files can therefore also be applied here. Unlike HTML and XSLT files however, the location of the templates is often stated in the section in the configuration file and read using the ReadConfigKey Formula. It is not possible to have a ResourceID in a configuration file. Instead the appSetting containing the main directory and the ResourceID containing the rootpath can be concatenated inside the Futurama Document to compose the complete path to the template directory.
Note that this approach can be followed for all files whose location is defined in the configuration file.
Text in Futurama Documents
In a typical application a lot of text is already defined outside the Futurama Document. In addition there will also be text defined within the Document e.g. text on Buttons, WebLabels, HTMLIncludes, Graphs as well as text that is composed by Formulas. When tackling these objects the following steps can be followed:
- Work through one WebPage or Node at a time
- Select the WebPage/Node and then select Expand All. This will make sure no text is omitted because the object containing it is not visible.
- For every text that is encountered do the following:
- Add the text to the Excel file
- Create a ResourceID with a meaningful name e.g. “TitleHomePage”.
- Add the translation to the Excel sheet. If the translation is not yet known, add a dummy text.
- Replace the text in the Futurama Editor by the term {{Resource:xxx}} where xxx is the chosen name e.g. {{Resource:TitleHomePage}}
- Expand the Range in Excel to cover the newly created Resource.
When going through the entire Document it pays off to keep an eye for places where small changes to the model can save a lot of work:
- WebLabel objects containing long texts are better replaced by an HTMLInclude object and the text defined in an HTML file.
- Formulas that concatenate texts are often tedious to translate for they often contain many small texts that each has to be replaced by a ResourceID. Error messages are common examples of these kind of Formulas. A good alternative is to model the text in an XSLT file and to use an XmlConverter.
Dynamic texts with PageData
To use PageDate functionality you have to define an XmlBuilder where you put the elements for your dynamic content. ‘PageData’ has to be configured per ‘WebPage’ object that contains the Output object that you want to give dynamic values. In the property ‘PageData’ of the WebPage you have to set a reference to the XmlBuilder you defined.
To use PageData you have to define a string in the form of {{PageData:testString}}, where ‘testString’ is the name of an element from your XmlBuilder. Add {{PageData:testString}} to the property of the Output object and it will be replaced by the value of ‘testString’.
For example, you can apply PageData to the ‘Text’ property of a ‘Button’ (or other Output objects), but also to the properties ‘CssClass’ or ‘Tooltip’. PagaDate is added to HTML as follows:
Dynamic text in a external file: {{PageData:testString}}
It is also possible to make a simple if-construction with PageData. You have to add an element to your XmlBuilder that returns a Boolean. For example:
{{if:PageData:testCondition}}Value if True{{/if}}
Related Topics
- Document: Within the document, the LanguageID and ResourceDocument properties have to be defined.
- ClearCache: This object can be used to update the ResrouceFile that is used.
- Convert Excel to XML: This formula can be used to read an Excel file and use this file as ResourceDocument.
- HTMLInclude: The code or file name of this object can be changed using a ResourceDocument.
- XmlConverter: The text or path of this object can be changed using a ResourceDocument.
- DocConverter: The different text properties of this object can be changed using a ResourceDocument.
- GraphConverter: All the text property of this object can be changed using a ResourceDocument.
- WebLabel: The text property of this object can be changed using a ResourceDocument.
- Button: The text property of this object can be changed using a ResourceDocument.
- CheckBox: The text property of this object can be changed using a ResourceDocument.
- TextBox: The text property of this object can be changed using a ResourceDocument.
- RadioButton: The text property of this object can be changed using a ResourceDocument.
- UserVariable: The text property of this object can be changed using a ResourceDocument.
- Fixed: The text property of this object can be changed using a ResourceDocument.
- Formula: The text property of this object can be changed using a ResourceDocument.
- DataTable: The text property of this object can be changed using a ResourceDocument.
- WebPage: Within the WebPage, the PageData property has to be defined
- XmlBuilder: Within an Xmlbuilder you have to define the elements for PageData
- XmlNode: Within an XmlNode you can retrieve the result of the VisionReference
- XmlField: Within an XmlField you read the ResourceDcoument from the VisionReference result
Feedback
If you have any questions about this subject or if you want to provide us feedback please send us an e-mail.
Updated: 2021-01-27