Vision ToolKit Class: Interface

The Vision Interface ToolKit has been created to provide a set of classes and messages that aid in interfacing with environments external to Vision. This ToolKit enables you to standardize your interactions with Vision and provides protocol for arbitrary expression evaluation, structured data extraction, and parameterized queries. The Vision FormatTools ToolKit has been created to provide a modular approach for generating output that can be formatted for different environments without changing the methods that produce the output.

Overview

The Interface class is used to support the protocol for interacting with Vision via a standard set of messages. As with all ToolKits, subclasses of the Interface ToolKit are named relative to Interface. The subclass hierarchy is shown below: 

  Object
        |
     ToolKit
        |
        Interface
           |
           Interface Constant
           Interface ErrorLog
           Interface External
              Interface HtmlAccess
           Interface Global
           Interface Workspace
              Interface ApplicationWS
              Interface ExtractWS

Most of these class are used to organize protocol and are not directly instantiated. The Interface Workspace subclasses are used directly and can be instantiated as needed.

The class Interface Workspace is an abstract class used to define common protocol for different types of structured query. The subclass Interface ApplicationWS supports parameterized application execution. The subclass Interface ExtractWS supports structured data extraction in a number of different formats. Naming dictionaries have been set up for each of the Workspace subclasses. These dictionaries are accessible via Interface Named ApplicationWS and Interface Named ExtractWS. When you create a new instance in either of these classes using the createInstance: message, the name will automatically get added to the appropriate naming dictionary.

The other subclasses of Interface are used to support interactions with any of these classes. The Interface Constant class is used to define messages that return constant values used by the various subclasses. The Interface Global class is used to define properties that are set and accessed by the workspace classes. The Interface ErrorLog class provides protocol to standardize error reporting. The Interface External class is an abstract class that is subclassed to define protocol specific to an external environment. The Interface HtmlAccess class is included here.

Because all these classes inherit from and are named at Interface, methods defined at any of the subclasses can reference the other classes using a relative name. For example: 

  Interface ApplicationWS 
  defineMethod: 
  [ | displayGlobalMessages |
    Global displayMessages ;
  ] ;
is equivalent to:
  Interface ApplicationWS 
  defineMethod: 
  [ | displayGlobalMessages |
    ^global Interface Global displayMessages ;
  ] ;

Running Arbitrary Expressions

At its simplest level, the Interface class can execute an arbitrary Vision expression supplied as a block or a string. For example: 

  Interface runExpression: "2 + 2" ;
or
  Interface runExpression: [ 2 + 2 ] ;
An arbitrary amount of output can be returned. For example: 
  Interface runExpression: 
     "Currency masterList 
         sortUp: [ name ] .   
      do: [ code print: 5 ; name print: 25 ; usExchange printNL ] ;
     " ;
generates:
  AUD  Australian Dollar             1.34
  BEF  Belgian Franc                29.93
  GBP  British Pound                 0.65
  CAD  Canadian Dollar               1.35
  . . .
Although these expressions could be evaluated by Vision directly without using the Interface class, this class allows you to take advantage of other interface capabilities such as globals and buffering.

Globals

There are a number of global variables that you can set to control access and display. The variables currently defined are:

Variable Definition Comments
Date As of date for expression evaluation. Today's date by default.
Currency Currency used to express monetary values. Local currency by default.
Delimiter Delimiter to use to separate values in output. No delimiter by default.

A global value remains in effect for the remainder of your Vision session or until you reset the value. To reset all globals to their default values use one of:

  Interface resetGlobals ;
or
  Interface Global reset ;
To set a global value, use one or more of the following messages, sent to Interface Global:

  • setDateTo: date
  • setCurrencyTo: currency
  • setDelimiterTo: character

The value supplied for date can be any valid date or numeric equivalent. The value supplied for currency can be any Currency object or a string that converts to a Currency (e.g., "BEF" ; "CAD"). The value supplied for character can be any string value. For example: 

  Interface Global reset
     setDateTo: 93 . setDelimiterTo: "|" ;

  Interface runExpression: 
     " Currency masterList 
         sortUp: [ name ] .   
       do: [ code print: 5 ; name print: 25 ; usExchange printNL ] ;
     " ;
generates:
  AUD  |Australian Dollar        |     1.48|
  BEF  |Belgian Franc            |    36.12|
  GBP  |British Pound            |     0.68|
  CAD  |Canadian Dollar          |     1.33|
  . . .
In this example, the exchange rate data is retrieved as of year-end 1993 and the output is delimited by the "|" character. Notice that the "set" messages all return the Interface Global object so multiple messages can be streamed in a sequence as shown here. You can send the profile message to see the current global settings: 
  Interface Global profile ;
generates:
  Current Interface Globals
  Date:          12/31/1993
  Currency:       Undefined       NA 
  Delimiter:     |

Buffering results

You can limit the number of lines of output returned using the setRowLimitTo: message defined at Interface. For example: 

  Interface resetGlobals ;
  Interface setRowLimitTo: 2 ;
  Interface runExpression: 
     "Currency masterList 
         sortUp: [ name ] .   
      do: [ code print: 5 ; name print: 25 ; usExchange printNL ] ;
     " ;
generates:
  AUD  Australian Dollar             1.34
  BEF  Belgian Franc                29.93
Set the limit to 0 to suppress all output. To retrieve a subset of rows use the displayRowsFrom:to: message. For example: 
  Interface displayRowsFrom: 2 to: 5 ;
generates:
  BEF  Belgian Franc                29.93
  GBP  British Pound                 0.65
  CAD  Canadian Dollar               1.35
  DKK  Danish Krone                  5.63
To display size information about the last expression run, use the displayCounts message: 
  Interface displayCounts ;
generates:
   Characters:      4628
         Rows:       167
  Max Columns:         3
These values indicate the total size, total rows, and maximum number of columns for the entire output buffer independent of the number of rows you actually displayed.

Structured Data Extraction

The class Interface ExtractWS is used to specify requests for 2-dimensional extracts of Vision data. Six extraction formats are available:

RowsColumnsFor
EntitiesItemsDate
ItemsEntitiesDate
EntitiesDatesItem
DatesEntitiesItem
ItemsDatesEntity
DatesItemsEntity

An Entity refers to a Vision subclass that defines "Named" elements such as Company, Industry, or Account. An EntityList can be supplied as an explicit list of instances for an Entity class. Alternatively, the list can be derived using a supplied Vision expression. For example, you can extract data for a list of companies for an industry using the expression [companyList].

A Date refers to an absolute or relative date. Absolute dates can be integers or strings in the form YY, YYMM, YYMMDD, or YYYYMMDD. The constant ^today can also be used. Relative dates can be expressed as: 

  { + -}  ##  offset
where ## is an integer and offset is one of days, businessDays, months, monthEnds, monthBeginnings, quarters, quarterEnds, quarterBeginnings, years, yearEnds, or yearBeginnings (e.g., -3 monthEnds). More information on date creation is available.

An Item refers to a Vision expression that can be evaluated for the entity or entity list supplied. This can be a simple message such as "price" or a multi-message expression such as "company industry sector name". Item qualifiers for date and currency can be appended to the item name using the "@". The complete format for specifying an item is: 

  expression@date@currency@path
where:

ElementDefinitionDefault
expression Message or Vision expression to which the current entity or entity list objects respond (note - expression is prefixed by path element, if supplied) Must be supplied
date Absolute or relative date Global date if set, otherwise today
currency Currency identifier Global currency if set, otherwise local currency
path Vision expression to which current entity or entity list objects respond Optional. Prefix to expression if present.

The "." character can be substituted for the "@" character to separate item specification components. Unneeded elements can be omitted. For example the following Item specifications can be defined for an entity class Company which responds to the expressions price and industry sales:

Item SpecificationDefinition
"price" price as of the current default date and currency
"price@9309" price as of 9/30/93
"price@-1 years" price as of 1 year prior to the current global date
"price@93@CAD" 1993 price in Canadian dollars
"price@@CAD" price as of the current global date in Canadian dollars
"industry sales" sales for company's industry
"industry sales@-1 years@CAD" industry sales for prior year in Canadian dollars
"sales@@@industry" industry sales using path element
"sales@-1 years@CAD@industry" industry sales for prior year in Canadian dollars using path element

The remainder of this section describes the extraction process and includes the following topics:

Specifying Extraction Requests

An extraction request must include an orientation and an entity type. The following orientation values have been defined:

OrientationDefinition
EIEntity x Item
IEItem x Entity
ITItem x Time
TITime x Item
TETime x Entity
ETEntity x Time

The entity type can be any Entity subclass defined in your database.

You need to supply a list of values to form the rows and columns of your extract and a single value representing the remaining dimension. The types of values supplied will depend on the orientation and entity type you select. For example, if your orientation is "EI" and your entity type is Company, you will need to supply a list of companies to form the rows of your extraction, a list of item specifications to form the columns of your extraction and an optional date. If your orientation is "IT", you will need to supply a list of item specifications to form the rows of your extraction, a list of dates to form the columns of your extraction and a single company identifier.

The following messages are used to define the data you wish to extract:

MessageSampleUsage
setOrientationTo: "EI" Required.
setEntityTypeTo: Company Required.
setEntityTo: "IBM" Required for "IT" and "TI" orientations. Also used for derived entity lists.
setEntityListTo: "IBM, GM, XON" Required for "EI", "ET", "IE", and "TE" orientations. Can be used to set an explicit list or to derive a list from the current entity.
setDateTo: 961215 Defaults to Global date if not set.
setDateListTo: 93, 92, 91 Required for "IT", "TI", "ET", and "TE" orientations.
setItemTo: "price@93" Required for "ET" and "TE" orientations.
setItemListTo: "name","price@93","sales@@@industry" Required for "EI", "IE", "IT", and "TI" orientations.

For example, the following extract requests price and industry sales data for a list of companies: 

  Interface ExtractWS
      setOrientationTo: "EI" .
      setEntityTypeTo: Company .
      setEntityListTo: "IBM, GM, XON" .
      setItemListTo: "ticker", "price", "price@93", "industry sales" .
  run ;
generating
:
           3         4 
   IBM    129.00     56.50 221318.33 
   GM     53.62     54.88 359988.98 
   XON     88.62     63.12 195283.44
The first line displays the total number of rows and columns in the extraction. The row count does not include this totals line. In this example, data is extracted for the 3 entities defined as the row dimension for the four data items defined in the column dimension.

Extraction Options

A number of options are available to control the appearance of the extraction. You can use the global options defined for the general Interface class to control the default date, currency, and delimiter. You can use the buffering options defined for the general Interface class to control the lines of output returned. For example: 

  Interface ExtractWS
      setDelimiterTo: "," .
  run ;
generating
:
            3,         4, 
   IBM,    129.00,     56.50,221318.33,
   GM,     53.62,     54.88,359988.98,
   XON,     88.62,     63.12,195283.44,
Notice that you did not need to respecify the entire query. You only need to set the new options and rerun the extract.

Several additional messages are available to optionally control components of your extraction output. The messages setColumnLabelsOn and setColumnLabelsOff are used to indicate if column headings should be displayed. The default value is "off". If it is set to "on", the headers are displayed in a row above the first row of extracted data. The messages setRowLabelsOn and setRowLabelsOff are used to indicate if row labels should be displayed. The default value is "off". If it is set to "on", an additional column is displayed to the left of the first column of extracted data. The messages setScalarLabelOn and setScalarLabelOff are used to indicate if the scalar value should be displayed. The default value is "off". If it is set to "on", the value is displayed in the row above and in the column to the left of the top left extraction value. The counts displayed in the first line of extraction output are adjusted to include labels, when present.

The message setNumberFormatTo: can be used to set the width, decimal places, and a comma indicator for any numeric data displayed. The value should be a number in the form: 

  width.decimal
such as 15.3 to indicate that numbers should be displayed with an overall width of 15 characters with 3 decimal places. To indicate that the numbers should be printed with commas, specify the value as a string in the form: 
  "width.decimal,"
If the "," character appears anywhere in the format, numeric data will be displayed with commas.

For example: 

  Interface ExtractWS
     setDelimiterTo: "|" .
     setScalarLabelOn
     setColumnLabelsOn
     setRowLabelsOn
     setNumberFormatTo: "15.3," .
  run ;
generates:
          4|        5|
  2/27/1997|ticker|price|price@93|industry sales|
  45920010|IBM|        129.000|         56.500|    221,318.330|
  37044210|GM|         53.625|         54.875|    359,988.980|
  30229010|XON|         88.625|         63.125|    195,283.440|

The counts in the first line reflect the additional row and column for the labels. The delimiter has been changed to the "|" character and the numeric data has been reformatted.

You can create blank rows and columns in your output by including blank value in your entity, date, and/or item lists. A blank column is signified by two consecutive delimiter characters. For example: 

  Interface ExtractWS
      setEntityListTo: "IBM", "", "GM", "XON" .
      setItemListTo: "ticker", "price", "", "industry sales" .
  run ;
generates:
          5|        5|
  2/27/1997|ticker|price||industry sales|
  45920010|IBM|        129.000||    221,318.330|
  |||||
  37044210|GM|         53.620||    359,988.980|
  30229010|XON|         88.620||    195,283.440|

The reset message can be sent to the Interface ExtractWS class to clear all the values. The profile message can be used to display the current settings.

Entity by Item Extractions

The Entity by Item ("EI") and the Item by Entity ("IE") orientations enable you to extract one or more items for one or more entities as of a specific date. The item specifications can be used to override this date for specific items. You use the setEntityListTo: message to specify the list of entity and the setItemListTo: message to specify the list of items. The setDateTo: message is used to set the scalar date. If no date is set, the current value of the Global date is used.

The entity list can be set in one of two ways. You can explicitly supply a list of entity identifiers that correspond to the current entity type. This list can be supplied as a list of strings or a a single string containing comma-separated identifiers. For example: 

  Interface ExtractWS
       setOrientationTo: "EI" .
       setEntityTypeTo: Company .
       setEntityListTo: "IBM", "GM", "XON" .   #--  list of strings
       setItemListTo: "ticker", "price", "price@93" .
  run ;
or
  Interface ExtractWS
       setOrientationTo: "EI" .
       setEntityTypeTo: Company .
       setEntityListTo: "IBM, GM, XON" .       #--  single string
       setItemListTo: "ticker", "price", "price@93" .
  run ;
These forms both set the entity list to the three companies indicated. You can also derive a set of entities by supplying a Vision expression that evaluates to a list when sent to a specific entity. For example, if the class Industry responds to the message companyList with the list of companies in that industry, you could generate a list of company entities using: 
  Interface ExtractWS
       setOrientationTo: "EI" .
       setEntityTypeTo: Industry .
       setEntityTo: "Auto" .
       setEntityListTo: [ companyList ] .
       setItemListTo: "ticker", "price", "price@93" .
  run ;
This assumes that the expression: 
  Named Industry Auto companyList
returns the list of companies you wish to extract. Note that in this case you set the entity type to Industry and supplied the id for a specific instance of this class. Since the returned list is a list of companies, the item list you supply should specify expressions that are applicable to company objects.

Item by Time Extractions

The Item by Time ("IT") and the Time by Item ("TI") orientations enable you to extract one or more items for one or more dates for a specific entity. You use the setItemListTo: message to specify the list of items and the setDateListTo: message to specify the list of dates. The setEntityTo: message is used to set the scalar entity value. This value must be an identifier for the entity type specified. The date list can be any combination of absolute and relative dates. The item list should specify items that are applicable to the entity type selected. For example: 

  Interface ExtractWS
       setOrientationTo: "IT" .
       setEntityTypeTo: Company .
       setEntityTo: "IBM" .
       setDateListTo: 95, 94, -5 years .
       setItemListTo: "sales", "cash" .
       setScalarLabelOn
       setColumnLabelsOn
       setRowLabelsOn
  run ;
Note that relative dates are relative to the scalar date, if specified. Otherwise, the global date is used to compute relative dates.

Entity by Time Extractions

The Entity by Time ("ET") and the Time by Entity ("TE") orientations enable you to extract data over time for one or more entities for a specific item. You use the setEntityListTo:message to specify the list of entities and the setDateListTo: message to specify the list of dates. The setItemTo: message is used to set the scalar item value. The entity list can be set using the same rules described for the Entity by Item orientation. The date list can be set using the same rules described for the Item by Time orientation.

Multiple Extraction Workspaces

You can create and name multiple workspaces for your extractions. To create two new extraction workspaces, use:

  Interface ExtractWS createInstance: "Extract1" ;
  Interface ExtractWS createInstance: "Extract2" ;
Access to these workspaces is provided via Interface Named ExtractWS. For example:
  Interface Named ExtractWS Extract1
accesses the first workspace and
  Interface Named ExtractWS Extract2
accesses the second one. Any of the extraction messages can be used with any workspace. For example:
  Interface Named ExtractWS Extract2
       setOrientationTo: "IT" .
       setEntityTypeTo: Company .
       setEntityTo: "IBM" .
       setDateListTo: 95, 94, -5 years .
       setItemListTo: "sales", "cash" .
       setScalarLabelOn
       setColumnLabelsOn
       setRowLabelsOn
  run ;

  Interface Named ExtractWS Extract2
       setEntityTo: "GM" .
  run ;
You can delete a named workspace using the deleteInstance message. For example:
  Interface Named ExtractWS Extract2 deleteInstance ;

Parameterized Applications

The Interface ApplicationWS class is used to provide a standardized mechanism for supplying any number of parameters to an application. In general, it is used to provide a modular interface to environments that need to interact with Vision with a minimal amount of syntax-specific knowledge. The external environment needs to know the name of the application, the order and/or names of its inputs, and what it wants to do with the output. The application details are delegated to a Vision method which interprets and processes the inputs and presents results.

To interact with the Interface ApplicationWS class, you need to specify an application name and a list of parameter values. Two general formats are available: 

  Interface ApplicationWS runWith: "appName", p1, p2, ... pn ;
and
  Interface ApplicationWS 
       setApplicationTo: "appName" .
       set: "param1" to: p1 .
       set: "param2" to: p2 .
       set: "paramn" to: pn .
  run ;
In the first format, you supply a list of inputs to the runWith: message where the first element in this list is the name of the method to run and the remaining list elements are the input values. The method should be defined at the Interface ApplicationWS class and contains the rules to interpret and process the inputs based on their order in the parameter list.

In the second format, you explicitly set the application and parameter values by name. In this example, three parameters are explicitly named and assigned values.

The reset message is used to clear the current application and any parameters that have been set by name or via a parameter list. This message does not clear the Global values. The profile message displays the current application and parameter values.

The runWith: message executes the reset message prior to updating the parameter list. The set:to: messages do not. If desired, you can use a combination of the parameter list and named parameters using:

  Interface ApplicationWS
     reset resetGlobals
     setApplicationTo: "appName" .
     setParameterListTo: p1, p2, p3 .
     set: "extraParameter" to: TRUE .
  run ;

The remainder of this section describes parameterized applications in more detail and includes the following topics:

Pre-defined Applications

Two applications have been pre-defined: Profile and GetValue.

The Profile application requires two parameters - the class of the object to profile and the id of the object to profile. These parameters can be supplied as a list or as named parameters using the following rules:

ParameterList Positionnamed id
class identifier 1 "classId"
instance identifier 2 "id"

For example:

  Interface ApplicationWS 
     runWith: "Profile", Currency, "USD" ;
returns a profile for the Currency object representing US Dollars and:
  Interface ApplicationWS 
     reset
     setApplicationTo: "Profile" .
     set: "classId" to: Currency .
     set: "id" to: "CAD" .
     run ;
returns a profile for the Currency object representing Canadian Dollars.

You can supply up to four parameters to the GetValue application - the class of the object, the id of the object, the data item to retrieve, and an optional path used to navigate to the item. These parameters can be supplied as a list or as named parameters using the following rules:

ParameterList Positionnamed id
class identifier 1 "entityType"
instance identifier 2 "entityId"
item to retrieve 3 "item"
optional path to item 4 "path"

For example:

  Interface ApplicationWS 
     runWith: "GetValue", Currency, "CAD", "usExchange" ;
returns the value of the Canadian exchange rate as of the current date. You can use the global and buffering options defined for the general Interface class to control the default date, currency, delimiter, and buffering. For example:
  Interface Global setDateTo: 93 ;
  Interface ApplicationWS 
     runWith: "GetValue", Currency, "CAD", "usExchange" ;
returns the value of the Canadian exchange rate as of year-end 1993.

The supplied entity can be a string containing a comma-separated list of identifiers. In this case, a multi-line report will be returned displaying one line for each entity id that is valid for the class. For example:

  Interface ApplicationWS 
     resetGlobals
     runWith: "GetValue", Currency, "BEF, GBP, CAD", "usExchange" ;
generates:
  id    usExchange
  BEF       29.93 
  GBP        0.65 
  CAD        1.35

Creating Parameterized Applications

Applications name methods defined at the Interface ApplicationWS class. Each method retrieves and interprets the inputs supplied and takes the appropriate action based on the inputs. Standardized error logging facilities are available.

The message getParameter: can be called from within an application method to retrieve the value of supplied parameter. If the argument to this message is a number, the parameter is retrieved positionally from the supplied parameter list. If the argument to this message is a string, the parameter associated with the name indicated by the string is retrieved. For example, a basic profile application can be defined to accept two inputs, the class and the instance id, then run the profile message for this object: 

  Interface ApplicationWS defineMethod: [ | BasicProfile |
     !class <- ^self getParameter: 1 ;
     !id <- ^self getParameter: 2 . stripBoundingBlanks ;
     !entity <- id as: class ;
     entity profile ;
  ] ;
To run:
  Interface ApplicationWS runWith: "BasicProfile", Currency, "CAD" ;
Alternatively, you could have defined this method to use named parameters:
  Interface ApplicationWS defineMethod: [ | BasicProfile |
     !class <- ^self getParameter: "class" ;
     !id <- ^self getParameter: "objectId" . stripBoundingBlanks ;
     !entity <- id as: class ;
     entity profile ;
  ] ;
To run:
  Interface ApplicationWS reset
     setApplicationTo: "BasicProfile" .
     set: "class" to: Currency .
     set: "objectId" to: "CAD" .
     run ;
You could also define this method to accept either order-based or named parameters. The getParameter:orName: message will retrieve the parameter positionally if present, by name otherwise. For example: 
  Interface ApplicationWS defineMethod: [ | BasicProfile |
     !class <- ^self getParameter: 1 orName: "class" ;
     !id <- ^self getParameter: 2 orName: "objectId" .
          stripBoundingBlanks ;
     !entity <- id as: class ;
     entity profile ;
  ] ;
To run:
  Interface ApplicationWS runWith: "BasicProfile", Currency, "CAD" ;
or
  Interface ApplicationWS reset
     setApplicationTo: "BasicProfile" .
     set: "class" to: Currency .
     set: "objectId" to: "CAD" .
     run ;

Error Handling

The prior application does not test on the validity of the inputs. You can add explicit tests and error messages directly to the method. For example: 

  Interface ApplicationWS defineMethod: [ | BasicProfile |
     !class <- ^self getParameter: 1 ;
     !id <- ^self getParameter: 2 . stripBoundingBlanks ;
     !entity <- id as: class ;
     entity isEntity
       ifTrue: [ entity profile ]
      ifFalse: [ ">>> Bad class or id supplied." printNL ];
  ] ;

  Interface ApplicationWS runWith: "BasicProfile", Currency, "XYZ";
generates:
  >>> Bad class or id supplied.
You can create whatever conventions you need to report errors in this fashion. A logging mechanism has been included as part of the Interface class to standardize error reporting and queue any error messages generated until the end of the application's execution. The message post:for:with: has been defined for the class Interface ErrorLog to store an error message. For example:
  Interface ApplicationWS defineMethod: [ | BasicProfile |
     !class <- ^self getParameter: 1 ;
     !id <- ^self getParameter: 2 . stripBoundingBlanks ;
     !entity <- id as: class ;
     entity isEntity
       ifTrue: [ entity profile ]
      ifFalse: 
        [ ErrorLog post: "Bad class or id supplied."
                   for: ^self with: class, id
        ] ;
  ] ;

  Interface ApplicationWS runWith: "BasicProfile", Currency, "XYZ" ;
generates:
  Transaction #: 1       
  Error: Bad class or id supplied.
     in:  Interface ApplicationWS :  Default
     Input: Currency Default
     Input: String XYZ
The current error log is automatically displayed after the application has run. If more than one error were encountered, they would each be listed in this format. The errors will always be displayed at the end of any application execution. This enables you to run some parts of an application even when an error is encountered. For example:
  Interface ApplicationWS defineMethod: [ | BasicProfile |
     !class <- ^self getParameter: 1 ;
     !id <- ^self getParameter: 2 . stripBoundingBlanks ;
     !entity <- id as: class ;
     entity isEntity
      ifFalse: 
        [ ErrorLog post: "Bad class or id supplied."
                   for: ^self with: class, id
        ] ;
     #-- run it any way
     "This profile is run whether the entity is found or not." printNL ;
     entity profile ;
  ] ;

  Interface ApplicationWS runWith: "BasicProfile", Currency, "XYZ" ;
generates:
  This profile is run whether the entity is found or not.
  Class:                        Undefined
  Code:                               NA 
  Created:                            NA 
  Is Default:                   TRUE
  Is Active:                    TRUE
  Transaction #: 1       
  Error: Bad class or id supplied.
     in:  Interface ApplicationWS :  Default
     Input: Currency Default
     Input: String XYZ

Multiple Application Workspaces

You can create and name multiple workspaces for your applications. To create two new workspaces, use:

  Interface ApplicationWS createInstance: "App1" ;
  Interface ApplicationWS createInstance: "App2" ;
Access to these workspaces is provided via Interface Named ApplicationWS. For example:
  Interface Named ApplicationWS App1
accesses the first workspace and
  Interface Named ApplicationWS App2
accesses the second one. Any of the application messages can be used with any workspace. For example:
  Interface Named ApplicationWS App2
      runWith: "BasicProfile", Currency, "CAD" ;
You can delete a named workspace using the deleteInstance message. For example:
  Interface Named ApplicationWS App2 deleteInstance ;
You can also make subclasses of the Interface ApplicationWS class to group related applications together. For example, you may want to separate administrative applications from analyst applications:
  Interface ApplicationWS 
      createSubclass: "AdminApps" at: Interface ;
  Interface ApplicationWS 
      createSubclass: "AnalystApps" at: Interface ;
  Interface ApplicationWS showInheritance ;
You define and run methods for the subclasses the same way you do for the parent ApplicationWS class.

The FormatTools ToolKit

The Vision FormatTools ToolKit has been created to provide a modular approach for generating output that can be formatted for different environments without changing the methods that produce the output. As with all ToolKits, subclasses of the FormatTools ToolKit are named relative to FormatTools. The subclass hierarchy is shown below: 

  Object
     |
  ToolKit
     |
     FormatTools
        |
        FormatTools Html
By default, the subclass FormatTools Html is included with this ToolKit. You can create any number of additional subclasses, as needed.

Messages are defined at the FormatTools class to generate "vanilla" versions of basic formatting tags. Messages are redefined at subclasses of FormatTools to generate tags that are appropriate to that formatting environment.

For example, the message bold: can be defined to format the supplied parameter with bold tags. By default, you just return the argument. In the Html environment, you surround the output with the tags < b> and </b>. The following methods implement this behavior:

  FormatTools defineMethod: [ | bold: object |
     object asString
  ] ;

  FormatTools Html defineMethod: [ | bold: object | 
     [ "< b>" print ; object print ; "</b>" print ;
     ] divertOutput
  ] ;
The expression:
  FormatTools bold: "xyz" . print ;
displays the undecorated string and the expression:
  FormatTools Html bold: "xyz" . print ;
displays the bold tags.

The message FormatTools is defined at Object to return the parent FormatTools class by default. You can use the evaluate: message to rebind the FormatTools message to one of the subclasses. For example, define a method at the Currency class to display the code in bold followed by the name of the instance:

  Currency defineMethod: [ | demoFormat |
     FormatTools bold: code . print ;
     name printNL ;
  ] ;
Run this method using: 
  Named Currency CAD demoFormat ;
generating:
  CAD Canadian Dollar
Note that no special formatting appears since the default bold: message just prints its argument. Run the same expression within an evaluate: block:
  FormatTools Html evaluate:
     [ Named Currency CAD demoFormat ; ] ;
generating:
     < b> CAD</b> Canadian Dollar
Because the demoFormat message was invoked from within the FormatTools Html evaluation block, this version of the bold: message is executed.

A number of sample formatting messages have been defined in this toolkit with default and "Html" behavior. You can customize these messages to suit you environment's needs and create new ones to capture different types of formatting requirements. Formatting messages include:

Modes
beginPreserveMode
endPreserveMode

Titles and Sections
buildTitle: stringList over: span
buildTitle: stringList over: span withStyle: optionList
buildCommentBlock: string over: span
buildOptionsBar: string
buildSectionBreakOver: span alignedTo: alignment

Styles
bold: string
italic: string
center: string
buildItemList: stringList

Links
buildLinkForApp: app withLabel: label andParams: plist
buildLinkForApp: app withLabel: label
buildLink: link withLabel: label
buildLink: link withPath: path withLabel: label
buildImage: file withAlt: alt
buildImage: file withPath: path withAlt: alt
buildLinkForApp: app withCheck: block andLabel: txt andParams: plist
buildLinkForAppZeroCheck: app withLabel: txt andParams: plist
buildURLForApp: app andParams: plist

Tables

Format Mode Messages

beginPreserveMode
endPreserveMode

These messages are used to mark the start and end of a section of text that should not be "formatted". The default versions of these messages do not do anything. The "Html" versions generates the < pre> and </pre> tags.

Title and Section Formatting

buildTitle: stringList over: span
buildTitle: stringList over: span withStyle: optionList

This message is used to format a title. The first parameter is a string or a list of strings. The second parameter is a number representing the number of columns. If the optionList parameter is supplied, it may contain up to four elements: a font string, a color string, a font size, and a boolean indicating if the title should be centered. The default version of this message centers each string in the list over the number columns indicated by the second parameter. The "Html" version prints the first string within < h3> and </h3> tags and subsequent strings within < h4> and </h4> tags. The entire title is printed within < center> and </center> tags. The second parameter is not used by this version of the method. For example:

  Currency defineMethod: [ | demoFormat |
     FormatTools buildTitle: "Currency Report" over: 80 . print ;
     code print ; " " print ; name printNL ;
  ] ;

  Named Currency CAD demoFormat ;
generates:
                           Currency Report

  CAD Canadian Dollar
The title is centered over 80 columns. Running the same expression within an evaluate: block:
  FormatTools Html evaluate:
     [ Named Currency CAD demoFormat ; ] ;
generates:
  < center>
  < h3> Currency Report </h3>
  </center>< p>
  CAD Canadian Dollar
Because the demoFormat message was invoked from within the FormatTools Html evaluation block, this version of the message is executed.

buildCommentBlock: string over: span

This message is used to format a centered block of information. The first parameter is a string. The second parameter is a number representing the number of columns. The default version of this message breaks the string on the newLine character and centers each line. The "Html" version prints the string within blockquote, center, hr, and p tags.

buildOptionsBar: string

The default version of this message does nothing. The "Html" version formats the supplied string within center tags followed by a horizontal line.

buildSectionBreakOver: span alignedTo: alignment

This message formats a horizontal line whose size and alignment is based on the supplied parameters. The default version of this message creates the line from the '-' character. Its length is the value of the first parameter. If the second parameter contains the string "center" or "right" the line will be justified accordingly, otherwise, the line will be printed left-justified. The "Html" version supplies the two parameters to the hr tag as settings for the align and width values.

Format Style Messages

bold: string

This message formats the supplied string within bold tags. In the default version of this message, there are no tags. In the "Html" version, the string is formatted within the < b> </b> tags.

italic: string

This message formats the supplied string within italic tags. In the default version of this message, there are no tags. In the "Html" version, the string is formatted within the < i> </i> tags.

buildItemList: string

This message returns the supplied string with no extra formatting in the default version . In the "Html" version, the string is formatted within the < ul> and </ul> tags. The supplied string is broken into lines and each line is prefixed with the < li> tag.

The various "build link" messages are used to generate references to other documents, including documents dynamically generated by Vision using inputs from the current document. These messages are discussed in detail in the document Vision Interfaces: Sample Html Access.

Interfacing to Html

Web browsers such as Netscape and Internet Explorer offer an excellent mechanism for delivering documents that can be dynamically generated by Vision. The Interface and FormatTools ToolKits provide a means for standardizing your requests for information and returning the results in a form that can be displayed by a browser.

In general, you can use Html and its numerous extensions such as JavaScript and Java applets to design interfaces that request specific inputs from a user. These inputs can be submitted to Vision via a cgi or alternative interface program to access the appropriate information from Vision, dynamically generated based on the inputs supplied and formatted correctly for the browser. The returned documents can have embedded links to other documents, including requests for additional information from your Vision database.

Vision's role in generating dynamic Html documents is described in: Vision Interfaces: Sample Html Access.

Related Topics