Smalltalk/X Webserver

Documentation of class 'ResourcePack':

Class: ResourcePack

Inheritance
Description
Class protocol
Instance protocol
Examples

Inheritance:

   Object
   |
   +--Collection
      |
      +--Set
         |
         +--Dictionary
            |
            +--ResourcePack
               |
               +--UISettings
               |
               +--ViewStyle

Package:: stx:libview

Category:: Interface-Internationalization

Version:: rev: 1.142 date: 2009/11/05 14:46:11; user: cg; file: ResourcePack.st directory: libview; module: stx stc-classLibrary: libview

Author:: Claus Gittinger

Description:

This class supports easy customization of smalltalk code (i.e. internationalization
and viewStyle adaption).
ResourcePacks are class specific, meaning that every subclass of View
and ApplicationModel has an instance of ResourcePack (instVar called 'resources') 
which is created when the first instance of the view/app is created,
and cached in a class-instVar (so the file is only read once).

The resourcePack consists of a mapping from strings to values, which are
then used in labels, buttons, menus etc.
The resourcePack initializes itself from a file found in 'resources/<className>.rs',
where 'className' is built by the usual abbreviation mechanism (see abbrev-files).

Conditional mappings are possible, by including lines as:
    #if <expression>
    #endif
in the resourcefile. Example:
file 'foo.rs':
    #if Language == #de
    'abort' 'Abbruch'
    #endif
    #if Language == #fr
    'abort' 'canceller'
    #endif

the corresponding resource-strings are accessed (from methods within the class)
using:
    resources string:'abort'

returning the mapped string (i.e. 'Abbruch' if the global Language is set
to #de)..

If no corresponding entry is found in the resources, the key is returned;
alternatively, use:
    resources string:'foo' default:'bar'
which returns 'bar', if no resource definition for 'foo' is found.

Translations can also include arguments, such as:
    resources string:'really delete %1' with:fileName

This scheme has the advantage, that you can write your programs using your
native language strings. Later, when new languages are to be supported,
simply create a resource file for the class and add translations for
all those strings. (find the keys by looking at users of resource or senders
of 'string:*').
Notice, that the grammar of different languages may imply a reordering,
so the above string becomes the german 'wollen Sie %1 wirklich löschen';
so using percent-placeholders is much better than simple concatenations of
arguments to the question.

More languages can be added later without any change in the code,
recompilation or the like. 
Even by people without access to the source code i.e. which only have the 
applications binary.

Also, unsupported languages' strings are simply left unchanged - if you
write your application in (say) english, and only plan to use it in english,
no additional work is required (i.e you dont need a resource file then).
Strings for unknown languages will come in english 
(which is better than nothing or empty button labels ;-)

Summary:
    in subclasses of View and ApplicationModel,
    instead of writing:

            ...
            b := Button label:'press me'
            ...

    always write:

            ...
            b := Button label:(resources string:'press me')
            ...

    if your class is not a subclass of one of the above, AND you need
    resource translations, you wont inherit the resources variable
    (which is automatically initialized).
    In this case, you have to ask the ResourcePack class explicitely for
    a corresponding package:

            ResourcePack for:aClassName

    as an example, see how the Date class gets the national names of
    week & monthnames.

Debugging:
    in the past, it happened that strings as returned by me were modified by someone else
    (replaceAll:with:) and then lead to invalid presentation in the future.
    To detect any bad guy which writes into one of my returned strings, set the DebugModifications
    classVar to true. Then I will return ImmutableStrings which trap on writes.

Class protocol:

initialization

flushCachedResourcePacks: forget all cached resources - needed after a style change
initialize

instance creation

for: aClass: get the full resource definitions for aClass (i.e. with super packs).
Also leave the resulting pack in the cache for faster access next time.
for: aClass cached: cached: get the full resource definitions for aClass (i.e. with super packs).
Also leave the resulting pack in the cache for faster access next time.
forPackage: package: get the full resource definitions given a package id (such as stx:libbasic').
Also leave the resulting pack in the cache for faster access next time.
forPackage: package cached: cached: get the full resource definitions given a package id (such as stx:libbasic').
Also optionally leave the resulting pack in the cache for faster access next time.
forPackage: package resourceFileName: resourceFileName cached: cached: get the full resource definitions given a package id (such as stx:libbasic').
Also optionally leave the resulting pack in the cache for faster access next time.
fromFile: aFileName: get the resource definitions from a file in the default directory.
fromFile: aFileName directory: dirName: get the resource definitions from a file in a directory.
fromFile: aFileName directory: dirName cached: cached: get the resource definitions from a file in a directory.
Uncached low-level entry.

private

addToCache: aPack
searchCacheFor: aClassOrFileName

utilities

extractEncodingFromLine: lineString
processResourceLine: lineString encoding: encodingSymbolOrEncoder file: fileName printErrorWith: printError for: aResourcePack: process a single valid line (i.e. #ifdef & #include has already been processed)
processResourceLine: lineString encoding: encodingSymbolOrEncoder file: fileName printErrorWith: printError for: aResourcePack keepUselessTranslations: keepUselessTranslations: process a single valid line (i.e. #ifdef & #include has already been processed)

Instance protocol:

accessing

array: anArray: translate a collection of strings
at: aKey: translate a string
at: aKey default: default: translate a string
at: aKey ifAbsent: defaultValue: translate a string; search here, in my projects pack and in my superpack(s)
localAt: aKey: translate a string.
Some special 'intelligence' has been added:
if no value for aKey is found,
lookup aKey with first character caseChanged and change the results first characters case.
or aKey starts with a '\', then lookup aKey without '\' and prepend '\' to the result.
or aKey ends with a '\', then lookup aKey without '\' and append '\' to the result.
or aKey ends with a ':', then lookup aKey without ':' and append ':' to the result.
or aKey ends with a '=', then lookup aKey without '=' and append '=' to the result.
or aKey ends with a '.', then lookup aKey without '.' and append '.' to the result.
or aKey ends with a ',', then lookup aKey without ',' and append ',' to the result.
or aKey ends with a '?', then lookup aKey without '?' and append '?' to the result.
or aKey ends with a '!', then lookup aKey without '!' and append '!' to the result.
or aKey ends with a ' ', then lookup aKey without ' '.
or aKey ends with a ' ...', then lookup aKey without ' ...' and append '...' to the result.
or aKey ends with a '...', then lookup aKey without '...' and append '...' to the result.
or aKey includes '&', then lookup aKey without '&'.

This means, that only a single translation is required to provide local translations for
things like
'search'
'search:'
'search...'
name: aKey default: default: translate a string.
Obsolete - use #string:default:

** This is an obsolete interface - do not use it (it may vanish in future versions) **
string: s: translate (retrieve) a string - if not present, return s
string: s default: defaultString: translate (retrieve) a string - if not present, return defaultString
string: s default: defaultString with: arg: translate and expand arg
string: s default: defaultString with: arg1 with: arg2: translate and expand args
string: s default: defaultString with: arg1 with: arg2 with: arg3: translate and expand args
string: s default: defaultString with: arg1 with: arg2 with: arg3 with: arg4: translate and expand args
string: s default: defaultString withArgs: argArray: translate and expand args
string: s with: arg: translate and expand arg
string: s with: arg1 with: arg2: translate and expand args
string: s with: arg1 with: arg2 with: arg3: translate and expand args
string: s with: arg1 with: arg2 with: arg3 with: arg4: translate and expand args
string: s with: arg1 with: arg2 with: arg3 with: arg4 with: arg5: translate and expand args
string: s withArgs: argArray: translate and expand args - allow text as arguments
stringWithCRs: s: translate (retrieve) a string - if not present, return s
stringWithCRs: s with: arg: translate, replace \'s with CRs and finally expand arg.
CR-replacement is donw before args are inserted
i.e. if any arg contains a backslash (DOS filenames), those are not translated.
stringWithCRs: s with: arg1 with: arg2: translate, replace \'s with CRs and finally expand args.
CR-replacement is donw before args are inserted
i.e. if any arg contains a backslash (DOS filenames), those are not translated.
stringWithCRs: s with: arg1 with: arg2 with: arg3: translate, replace \'s with CRs and finally expand args.
CR-replacement is donw before args are inserted
i.e. if any arg contains a backslash (DOS filenames), those are not translated.
stringWithCRs: s with: arg1 with: arg2 with: arg3 with: arg4: translate, replace \'s with CRs and finally expand args.
CR-replacement is donw before args are inserted
i.e. if any arg contains a backslash (DOS filenames), those are not translated.
stringWithCRs: s with: arg1 with: arg2 with: arg3 with: arg4 with: arg5: translate, replace \'s with CRs and finally expand args.
CR-replacement is donw before args are inserted
i.e. if any arg contains a backslash (DOS filenames), those are not translated.
stringWithCRs: s withArgs: argArray: translate, replace \'s with CRs and finally expand args.
CR-replacement is done before args are inserted
i.e. if any arg contains a backslash (DOS filenames), those are not translated.

accessing-internals

name: aKey: translate a string
packsClassName
packsClassName: aString
packsClassOrFileName
packsClassOrFileName: aString
projectPack
projectPack: anotherResourcePack
superPack
superPack: anotherResourcePack

file reading

fileReadFailed: return true, if the pack does not really contain
valid translations, since the fileRead failed.
However, all inherited translations are still available
through the receiver
nonexistingFileRead: asked to read definitions for a non-existing file.
Here, this is legal and ignored (typically using inherited resources).
However, subclasses (such as styleSheet) may flag it as an error.
processLine: lineString encoding: encodingSymbolOrEncoder file: fileName printErrorWith: printError: process a single valid line (i.e. #ifdef & #include has already been processed)
readFromFile: fileName directory: dirName: read definitions from a file in a directory
readFromResourceStream: inStream in: dirName: read definitions from a stream. The dirName argument is required to
specify where #include files are searched for.
Return true, if the style sheet could be read without errors, false otherwise.

printing & storing

displayString

normally, resources are found in files named after their classes sourcefile For example, the FileBrowsers resources are found in 'FBrowser.rs'. For the examples below, we process resources from a constant string; this is NOT representative.


    |stream res|

    stream := ReadStream on:'
foo  ''the translation for foo''
#if Language == #de
bar  ''die deutsche uebersetzung von bar''
baz  ''baz hat den Wert %1''
#endif
#if Language == #fr
bar  ''bar en francaise''
baz  ''%1, c''''est baz''
#endif

'.

    res := ResourcePack new readFromResourceStream:stream in:nil.

    Transcript showCR:'baz is translated to: ' , (res string:'baz' with:'1234').
    Transcript showCR:'bar is translated to: ' , (res string:'bar').
    Transcript showCR:'foo is translated to: ' , (res string:'foo').
    Transcript showCR:'fooBar is translated to: ' , (res string:'fooBar').

set the Language to french:


    Language := #fr

and repeat the above. back to english:


    Language := #en

back to german:


    Language := #de

ST/X 6.1.1; WebServer 1.620 at exept:8081; Wed, 23 May 2012 20:57:05 GMT