In the user interface for Java-client applications and applets, the
Insert button in the Titles panel has a list of kinds of tokens that
users can insert in a title, subtitle, or footnote. The tokens are substitutes for variable
information, such as the name of the dimension, a dimension member, the current date, and so on.
The TokenSubstitution
interface, in the oracle.dss.dataView
package,
defines methods for a handler that manages the substitution of the text for the token.
The default token substitution handler is the TokenSubstitutionAdapter
class,
which implements the TokenSubstitution
interface. The
TokenSubstitutionAdapter
class is also in the oracle.dss.dataView
package. The TokenSubstitutionAdapter
provides substitution for a dimension token,
a dimension member token, and a token that includes both the dimension name and the dimension
member.
You can either replace the default handler or extend it to add your own tokens to the tokens that the default handler supplies.
For each token that you want to use, you must provide the following strings:
Token -- The String
that appears in the title, subtitle, or footnote text box.
This String
should be localizable.
For example, you might add a token that allows users to insert the current date. The token that appears in the text box might be "&Date".
Parsed string -- The String
that actually appears in the title, subtitle, or
footnote of the Dataview
.
For example, for the date token, you would get the current date and provide a
String
representation, such as "24 March 2002".
ListItem
-- The String
that appears in the Insert list as
something the user can insert. This String
should be localizable.
For example, for the date token, the ListItem
might be "Date".
Key -- The String
that the user-interface panel uses internally to identify the
token. This must not be localizable. It must be exactly the same String
in all
languages.
The user interface asks the token substitution handler for the different strings that
it needs. The user interface passes one kind of string to the handler as it requests another
kind of string. For example, the user clicks on an item in the drop-down list, to identify the
kind of token that they want in the text. In response, the user interface gets the selected
ListItem
and calls the getToken
method in the
TokenSubstitution
, to get the token that should be displayed in the text field of
the panel.
Your implementation of the TokenSubstitution
is responsible for providing the
kind of string that the user interface requests.
The user interface uses the different kinds of strings as follows:
The user interface gets an array of ListItem strings from the token substitution handler and displays the list in the Insert drop down list box.
When the end user selects one of the list items, the user interface gets the selected
ListItem
, and passes it to the token substitution handler, in a request for a
token to display in the JTextField
.
The user interface inserts the token into the JTextField
where the user
specifies text for the title, subtitle, or footnote.
The user interface passes the entire String
from the JTextfield
,
including the token, to the token substitution handler, requesting a String
that
has the key instead of the token. This is the unparsed String
.
To get the text that appears in the Dataview
, the user interface passes the
unparsed String
to the token substitution handler and requests a parsed
String
. In the parsed String
, the token substitution handler must
replace the key with the actual text that should appear in the Dataview
.
When the Dataview
is saved, the unparsed String
is stored as the
value of the Text
property.
When you implement the TokenSubstitution
interface, you must register your
implementation with the Dataview
, in order for your handler to be effective.
To register your token substitution handler, call the setTokenSubstitution
method of the Dataview
.
You can extend oracle.dss.dataView.TokenSubstitutionAdapter
to add tokens to
the default list. In the extension of the default handler,
your override of the getListItems
method should call
super.getListItems
and then add your ListItems
to the list from the
superclass. In your overrides of other methods, you should check the parameter value to see if
it corresponds to one of your tokens. If it is one of your tokens, your method should handle it.
If not, you call the method of the superclass.