String Tables

One of the strengths of StudioWorks is the ability to create applications that can be switched on-the-fly to display labels, tooltips, reports, and titles in different languages.

StudioWorks originally accomplished multi-language support using the String Tables functions provided by Omnis Studio. In the 2006-01-31 release we moved to storing the labels and tooltips for different languages in a cached list in the oStringTables object. Even though StudioWorks is not longer using the Omnis Studio string tables, for backwards compatibilty we continue to use the oStringTables object and refer string tables in the code and documentation.

Whether you are developing an application for a single language or multiple languages there is virtually no extra effort on your part. In fact, the technique used by StudioWorks for implementing mutliple languages saves you a lot of typing!

StudioWorks maps string tables and rows to database tables and columns.

• For each table in the database there is a matching string table by the same name.
• For each column in a table there is a matching row in the string table.
• Columns are added to the string tables for each language. Each language use 3 columns. The columns contain the language text for: labels, tooltips, and abbreviations.

String Tables Locations

String tables are loaded by StudioWorks when you Reload String Tables.

StudioWorks lets you store the language text for the application in three possible locations:

1. Database - Customer localization changes to string tables are stored in a stringtables record in the refs servertable. A separate record is created for each language that is modified. (en-us, fr, it, etc.)
2. Text File - Developer changes to StudioWorks default text and additional languages can be stored in a tab delimited files in the APP/startupitems folder. One file per language. The file is named stringtables_*.txt where the * suffix is the language ID. (stringtables_en-us.txt, stringtables_fr.txt, stringtables_it.txt)
3. Meta-Data - Language translations are stored in the meta-data of schema classes in the Omnis Studio libraries. The language can be stored in the meta-data of the StudioWorks core libraries is en-us. Developers are not required to use en-us in their own meta-data. A French developer writing an application primarily for use in the French langauge would enter his/her own meta-data in French. The French developer would then need to create a stringtables_fr.txt file with translations for the StudioWorks core libraries meta-data only.

When you Reload String Tables the meta-data text is loaded into its own set of columns, the stringtables_*.txt files are loaded second, each adding their own language columns as needed, the database string tables are loaded last and overwrite any text file language values. The last value overwrites and previous values.

String Tables Text

For each language the text is stored in 3 parts.

1. Label - This is the label beside the entry field. It could also be a window title, report title, button text, or menu line text.
2. Tooltip - This is the tooltip displayed when you hover your mouse over a field.
   
   Do not repeat the label text in the tooltip. Only enter a tooltip if there is additional information that would be helpful to the user. The tooltip is normally in the form of a sentence up to a maximum of 255 characters.
3. Abbreviation - This is the text displayed in the column headers of lists and reports. The abbreviation defaults to the label. Only enter an abbreviation if you need something shorter than the label.

String Tables Master List

The string tables list is held in the oStringTables object class which is instantiated by the task variable stb.

The string tables master list has the following base columns:

1. stbname The name of the string table. e.g. Mn = Menus, Wn = Windows, Author = Author
2. stbid The ID of the string table row. e.g SaveChanges, CloseApplication The ID must be unique within each table.
3. metadata__label Label text. This text appears in field labels, menu names, menu lines, report names, window names.
4. metadata__tooltip Tooltip text (optional). This text appears in tooltips for fields and buttons.
5. metadata__abbrev Abbreviation text (optional - defaults to label test). This text appears in list column headers and report column header, push button text.

For each language loaded by from the string tables text files or the database the string tables master list adds 3 columns. The following example is for fr (French).

1. fr__label
2. fr__tooltip
3. fr__abbrev

String Tables Meta-Data

The base language text for your application is stored in the schema and query classes. The StudioWorks meta-data uses en-us (English US). The primary way of entering the language text is with the SQL Meta-Data Editor which you access from the Programmer Menu.

The SQL Class Editor tab pane has string table fields for:

1. Label (Singular) - The singular form word to describe the records store in the server table. e.g. sBook = Book
2. Label (Plural) - The plural form word to describe the records store in the server table. e.g. sBook = Books
3. String Table Name - The string table to be used when translating the column name IDs to language text. e.g. sBook = Book

The above text is used to generate the Tbl and Tblplural string tables. The values would be mapped in the string tables master list as follows:

stbname = Tbl, stbid = Book, en-us__label = Book
stbname = Tblplural, stbid = Book, en-us__label = Books

The SQL Class Columns Editor tab pane has string table fields for:

1. Label The label text for the column. e.g. DateDeposited = Date Deposited
2. Tooltip The tooltip for the column. (optional) eg. The date the payment was deposited. Not the date received.
3. Abbreviation Shortened text for the column. (optional) e.g. Deposited

If the above column belonged to the sCashreceipts schema class, the values would be mapped in the string tables master list as follows:

stbname = Cashreceipts
stbid = DateDeposited
metadata__label = Date Deposited
metadata__tooltip = The date the payment was deposited. Not the date received.
metadata__abbrev = Deposited

Each query class column defaults to using the meta-data from its schema class. If you point a query class to a specific string table in the SQL Class Editor tab you can map all of the columns to different language text. This is useful if records in one table have different uses. e.g. An Organization server table could contain names of businesses as well as households. A window for editing household records can have different labels if you create a qHouseholds query class and point it to a Household string table. (You can create an sHousehold_stb schema class which is not mapped to a servertable in the database. See Substitute String Tables.)

Non-database related string tables can be created using dummy schema classes. These schema classes do not map to server tables and the schema class name is appended with _stb, or _listdef. e.g. sMn_stb

The string table name is calcuated using the cap() value of the schema class name minus the s prefix and the _stb suffix. e.g. sSomeName_stb is loaded as the string table name Somename

You can add further suffixes after the _stb suffix to define subgroups of a string table. (e.g. sMn_stb_reports, sMn_stb_buttons, ....) I do this if an _stb schema class gets too big.

Each column name in the schema class becomes an stbid in the string table list. The column description is used as the default language text. You can include a tooltip and abbreviation by delimiting them with the backquote character in the column description text.

The handy thing with storing the string tables in schema and query classes is that while you are writing code you can quickly look up any stbname and stbid in the F9 Catalog > Schemas tab. The _stb and _listdef schemas even display the label text in a tooltip when you hover over them in the F9 Catalog.

String Tables Text File

You can store string table information in a stringtables_*.txt tab delimited text file which you locate in the APP/startupitems folder. StudioWorks loads the stringtables_*.txt file during startup. Only the language columns matching the _* file name suffix will be loaded by StudioWorks. This file is required for adding languages to your StudioWorks application.

String Tables Database

Customer changes to string tables text, whether to the base language or for additional languages, are stored in the database in a special record in the Refs table. One stringtable records is created for each language.

The String Tables Editor can be used for making changes to string tables or even adding new languages and saving them to the database. Changes are automatically saved to the database. Only modified values/rows are saved to the database. If the customer changes the text for 5 stbids, there will only be 5 rows in that language saves to the database.

Developers should use the stringtables_*.txt files for adding languages to their application.

Customers should use the String Tables Editor for making their own custom changes to the language text. Those changes are saved to their own database.

To delete a language from the database:

1. Select String Tables in the Database in the Show droplist field in the toolbar.
2. Select the language you wish to delete in the Langauge droplist field in the toolbar.
3. Click the Delete Language trash can icon in the toolbar.

String Tables Object

The oStringTables object class is the processor for all string tables operations in StudioWorks. The object is instantiated by the startup task variable, stb.

Right-click on stb > and select Interface Manager to see the various public methods available to your StudioWorks application code.

Most of the code that interacts with the string tables object is built into the StudioWorks framework.

The following sample code shows 3 different ways to get the current language text for the reports menu title.

; (pStbName,pStbID,pfLabel_opt,pfTooltip_opt,pfAbbrev_opt)
Do stb.$getTextTooltipAbbrev('Mn','Reports',Label,Tooltip,Abbrev) Returns bTranslatedOK

; (pStbName,pStbID)
Do stb.$retText('Mn','Reports') Returns Label

Calculate Label as 'Mn.Reports'
Do stb.$translateString(Label) Returns bTranslatedOK

Reload String Tables

If you make a change to your application which affects the string tables you will need to reload the string tables in order to see the new or modified string table text. To do this in StudioWorks select Programmer Menu > Rebuild String Tables.

Cached String Tables

Each time you Rebuild String Tables, StudioWorks reloads the string tables from the various string tables locations. StudioWorks loads all the string tables into a master list and saves the master list to the your application preferences.

Do app_prefs.$:StringTables_MasterList.$assign(MasterList))

This saved list is referred to as a cached list.

During startup StudioWorks checks the applications preferences for a cached string tables master list and if found, loads the cached list. This negates the need for rebuilding the string table list during startup and greatly speeds the startup time of your application.

Substitute String Tables

By default each column in a query class points to the string table specified by column's source schema class.

You can point a query class to a different string table by changing the String Table Name in SQL Class Editor tab of the SQL Meta-Data Editor.

For this section we will use the StudioWorks template library module sw_Contacts4_template which uses a substitute string table for the Household series of window instances.

We will limit our discussion to the following tables in the contacts module:

1. Org - contains organizations and households.
   
   The isHousehold field is used to specifiy if a records in the table is a household. If a record is a business, charity, or something other than a household this field is set to zero.
2. Person - contains people.
3. Orgperson - joins people to organizations/households. One of the fields in the Orgperson table specifies the role the person has related to the organization/household.

The Org table is being used to store both organizations (businesses, charities, non-profits, ...) and households.

To keep things simple for the user we want to use different window classes, field labels, and tooltips when the users is searching, listing, and editing household records. Rather than entering an Organization Name, we will want them to entering a Household Name, even though both fields point to OrgName column in the database.

To accomplish this we do the following:

1. Create a schema class named, sHousehold_stb.
   
   The $servertablename property of the schema class is left empty because this is not an actual table in the database. The _stb suffix tells StudioWorks that this is a schema class to be used as a string table. StudioWorks will use the description column values of the schema class for the string table text. You can include the tooltip and abbreviation text by delimiting them in with backquote characters.
2. Create a query class named, qHousehouldList. It can be exactly the same as qOrgList.
3. Create a query class named, qHousehouldEdit. It can be exactly the same as qOrgEdit.
4. Using the SQL Meta-Data Editor, select qHousehouldList, and set its String Table Name field to Household.
   
   This tells StudioWorks to use the Household string table, rather than the Org string table for this query class.
5. Select qHousehouldEdit, and set its String Table Name field to Household.
6. In oWindowsList > $addCustomWinInstID > add the custom window instances, HouseholdList, and HouseholdEdit.
   
   This adds the custom window instances to the list of WinInstIDs for the library.
7. In oMenusList > $addNavigationWinInstID > add the window instance, HouseholdList.
   
   This adds the window instance to the navigation treelist.
8. Add HouseholdList and HouseholdEdit to the sWn_stb schema class.
   
   This adds the window instances to the Tbl and Tblplural string tables for the window instance title and navigation menu.
9. Rebuild String Tables which also rebuilds the SQL lists, windows list, and menus list.
   
   StudioWorks will now use the sHousehold_stb text for the labels and tooltips in the HouseholdList and HouseholdEdit window instances.

String Table Tags

You can embed the string table text of another string table row using <stb> tags.

The name of a window instance which displays a list of records often uses the plural name which has been specified for the base schema class used to fetch the records.

1. The WinInstID, AuthorList, displays a list of records from the sAuthor schema class of the Author server table.
2. sAuthor has the Label (Plural) set to Authors.
3. StudioWorks generates: stbname=Tblpural, stbid=Author, en-us__label=Authors
4. In the sWn_stb (Windows) schema class you can create the following entry:
   
   Column name (maps to the stbid): AuthorList
   Description (maps to the __label column) : <stb>Tblplural.Author</stb>
   
   This tells the oStringTables object to use the language text from Author in the Tblplural string table.

You can embed <stb> tags anywhere in the language text string. For example:

The <stb>Tbl.Author</stb> record could not be deleted from the list of <stb>Tblplural.Author</stb>.

Do not point embed <stb> tags within <stb> tags.

String Tables Default Language

The default language used by StudioWorks is en-us (English US). If the language text for a different language is not found, the default language text will be returned instead.

String Tables Languages

The oStringTables property method $:AllLanguagesList returns a list of possible languages.

; Get the all languages list from the string tables object.
Do stb.$:AllLanguagesList() Returns List

The list that is returned has 2 columns (displaytext,languagecolname). The list is suitable for use in a droplist field.

The oStringTables property method $:LanguagesList returns a list of the currently available languages. The list is generated by reviewing the language columns in the string tables master list. If you add a language it will automatically be included in the list returned by this method. The current line in the list will be set to the current language.

; Get the current languages list from the string tables object.
Do stb.$:LanguagesList() Returns List

To find out the current language:

; Get the current language column name from the string tables object.
Do stb.$:LanguageID Returns CurrLanguageID

Adding a Language

In order for a language to show up in the Sign-In window's languages droplist it has to be included in the columns of the stringtables_*.txt tab delimited file. The column names must follow the correct syntax exactly, using the language ID, etc.

To add a langauge using the StudioWorks String Tables Editor:

1. Programmer Workbench > String Tables tab > String Tables Editor tab.
2. Click the Languages droplist to see whether or not the language you want to add is already listed. If it shows up in the list, the language is already added in either a startupitems/stringtables_*.txt file or in the database.
3. If the language you want to add is not listed in the Languages droplist, click the Add a Language button next to the droplist.
4. You will be prompted with a list of all possible languages (more can be added). Select the language you want to add and continue. This adds 3 columns (text, tooltip, abbrev) to the string tables list for that language.
5. The complex grid columns in the String Tables Editor are now pointed to the selected language's columns.
6. Click the Edit button to modify the language text.
• Green background uses the default base language text. (The is useful for UK vs USA where many words are the same spelling.)
• White background indicates different text than the base language text.
• Abbrev will default to the Label text if left empty.
7. When you have completed a little bit of editing click the Export Selected Tables button. You will be prompted for a file name and location. Use the default file name of stringtables.txt, unless you are creating multiple files which will be merged last one.
8. Open the exported file in Excel. Note the syntax of the column headings in the first few lines of the file.
9. Put the exported file in your startupitems folder.
10. Close and reopen your StudioWorks app.
11. All going well, the language you added will now be listed in the Languages droplist of the Sign-In window.
12. Select the new language and continue with signing in. All going well the labels where you set the text for your new language will appear instead of the default language. If new language text is not found for a label StudioWorks will default to the base language.

Once you have created a stringtables_*.txt file any additional changes have to be done manually in Excel. One benefit of the stringtables_*.txt file is that you can send the file to a translator, they can add the additional language text, and then send the file back to you.

If you are doing a lot of modifications to string tables files you may want to write a small Omnis Studio app which can load and merge various string tables text files. Only a few StudioWorks developers are writing multi-language apps, so if you are one of them, we're counting on your creativity to add these types of enhancements. It is possible to break the string tables text file into multiple files for separate tables and/or separate languages and get StudioWorks to load all of the string table files during startup.

StudioWorks Documentation - Copyright 2005 Vencor Software