by Catalin Rotaru <firstname.lastname@example.org>
Last Modified: 25/Jun/1999, v1.00
SummaryThis document details the Mozilla's i18n module extensibility model. It was developed as part of the work on the Charset Converters, but it should be general enough to be used in any other area of the product.
User scenarioAdding a new charset (x-my-charset) in the system.
- Write an Unicode Decoder and assign it the right ProgID (.../uconv/decoder/x-my-charset)
- Write the Unicode Encoder and assign it the right ProgID (.../uconv/encoder/x-my-charset)
- Write the additional info:
- Charset aliases (x-my-charset1, x-my-charset2, x-my-charset3)
- Human readable name ("My Charset")
- Purpose of this charset ("browser-decode = yes, browser-encode = yes, mail-decode = yes, mail-encode = no")
- Be able to use the added decoder when viewing documents.
- Be able to use the added encoder when saving documents.
- Recognize the added aliases
- Have the new Charset added in the Character Set menu in browser, composer, mail viewer and not in the mail composer.
DetailsA component is the actual xpcom component (in our scenario the Charset Converter) plus some additional component info (like human readable name, charset aliases, etc). To note that some very general subset of this this additional info is actually the xpcom info (CSID, ProgID, etc.) or becoming that (see the human readable name in COM).
A components user is a piece of code managing and using a set of components of the same type (Example: the Character Set menu). In order to manage the needed components, it will usually use a components list.
Adding a new component
Adding a new xpcom component to the system is handled by the xpcom module through the self registration process. The dll is dropped in the components directory, then the self-registration code is called and the component is registered. Now, the components user's responsibility is to get its list of available components by requesting it from xpcom [D1].
Details - Component infoThe additional component info is localizable data, so we should use property files. Each component comes with an attached property file. At the registration time, the location of the file gets stored under a key in the registry. The components user gets the location from the registry and then the data from the file. The registry key could be like: "ProgID/properties" Con: you cannot add component info without having a component. If this is a requirement, different key naming scheme can be easily designed.
In order to keep a small number of property files, the keys for the "key-value pair) should have this format: "component_name.actual_key" This way, one file can hold properties for more components. (Just as a DLL can hold more than one component)
The components user can also come with its own set of info for the components it uses. Then at runtime, it will first search in the component's file, then in the components user's file, then fall back to some default. This way, the database of components info may be either distributed or centralized, and the data can be extended in both fashions.
These keys are like a communication protocol between components and components users. A certain type of component (Unicode Converter) should present a certain set of attributes (aliases, human readable name, etc)
For our example:
x-my-charset.human-name = "My Charset"
x-my-charset.alias = x-my-charset1, x-my-charset2, x-my-charset3
x-my-charset.browser-decode = 1
x-my-charset.browser-encode = 1
x-my-charset.mail-decode = 1
x-my-charset.mail-encode = 0
Possible alternative ways to provide the component info:
- Xpcom object implementing an "info" interface. Pros: better protocol checking. Cons: too costly (object has to be instantiated when interrogating), non extensible.
- All data stored in registry. Pros: better performance. Cons: not human readable/editable, more complex storing/retrieving protocol required.
Details - Components listThe list has to:
a) have a default localizable value
b) be customizable
c) be persistent between work sessions
d) be kept in sync with the list of components obtained from xpcom
So our Character Set menu should initially read the list of charsets
from its own property file, then store it in the registry or as a preference.
The list should be editable. The actual menu is created using the list
and getting the info from the various property files. Whenever a component
is added/removed, the list will be updated...
Example: initial list on disk:
charset_menu = x-my-charset-4, x-my-charset-3
charset_complete_list = x-my-charset-4, x-my-charset-3, x-my-charset-2, x-my-charset-1 # for sync
- [D1] We need a mechanism to get from xpcom a list of "all the components of a certain type". The plan is to have an API for ProgrID matching. Owner: dp. Deadline: M9
- [I2] Possible performance hit from using property files. We could cache data in a registry.
- [I1] What's the ID/cache key for a component?
c) CSID + DLL time + DLL size