Screen Reference Index

Setting Up a New Object Class


Figure 1: Using the Class Library to Build a New Object Class

Each Plato object class is defined by its name, a set of user-definable attributes, and the action associated with it. Together these elements constitute the object class definition. Object classes are always containers of data. However, in addition to this, they may also be references to other objects or files that are external to Plato databases. To begin building a new object class, select an existing object class from the object class list and press the 'add' button to duplicate it. You can choose any object to duplicate, but if you can, choose an object that is as similar as possible to the new class you have in mind to minimze the changes you'll have to make. then make any changes you need to decribe the new class using the editing pane. See Figure 1. Supplying the object class properties should be simple enough, but be aware that you may need to define new object attributes before adding them to the new object's attribute list.

Object Class Properties
Each object class has a small set of basic, common properties: ID, name, description, description template, action type, note type, editor, field attributes, and category. These properties define various aspects of the objects class's behavior and assist in filing it.

class name

A short, descriptive name for the object class that quickly identify any object of its type. Good examples would be "journal," "book," "recipe," and the like. This is a mandatory field. Note that any space characters in your name will automatically be converted to underscore characters by Plato.

class description

A longer description of the object class. Since this a sortable field, it can be used to globally categorize object classes, or simply to provide an expanded description of the object if the object name itself might seem ambiguous when compared to all the other object class names.

class action type

Action types define the behavior of the object. See 'object actions,' below, for descriptions of the various actions.

open as document

This object type will be omitted in the release version.

description template

Allows you to build a description in a tailored way from object class attributes. In this template, any characters may be used. Numeric characters will be interpreted to represent a field by its position in the attribute list. For example, the following attributes:

  author= James Madison
  title = Years of our Days
  publisher = Machree and Sons
  year = 1924

And this description template:

  2, 1 (4)

Will result in this description:

  Years of Our Days, James Madison (1924)

If you leave the description template blank Plato will use the contents of the first field to build the description.

Special use of backslash (/) character

If you preceed a number with a backslash the number will be ignored in the description template. Instead, the number will be used to specify which field will receive the text from imported lists.

class note format

Defines the format of the note field. Choices are 'Rich text (RTF)' or 'plain text'. If you set a note field to plain text, RTF enhancements will not be available for the note. For object classes that have special use by Plato, plain text is mandatory. These object classes are: lists,

class external editor

If the object class action is to load an external file, this field allows you to select a default editor with which to load the file.

class field attributes

Each object class has field attributes that are user definable. This attribute is a list of these fields in the order they will appear when they are displayed. To add, edit, or delete field attributes, click the 'add fields' button.

class category

Categories allow you to better organize large libraries of object classes.

Object Actions
Actions indicates how the object interacts with other objects in defined ways. The following are descriptions of each object action.

Open as folder

Objects of this type should be thought of as file folders, and contain other objects. When you click on them, they "open" to reveal the objects they contain. "Open as Folder" objects can appear in the database tree pane.

Open as list

Objects of this type are the same as "open as folder" objects, but they do not appear in the database tree pane. "Open as list" objects are useful for building nested documents.

Launch file with editor

Objects of this type have an associated application and a filename, and when clicked will open the file with the application.

Launch image

Object references an image external to Plato

Launch web page

Object references a web page

List data in notes field

Object is a list of terms, phrases, or words assembled for study. Objects of this type are data only, but have the special property of containing user-defined lists. User-defined lists are research and study aids.

Data only

Object contains discrete data with no defined relations to other objects outside the object class

Bookmark

Object is an internal reference to a defined portion of a note in another object

Family of categories

Object is a member of a defined category

Multi-dimensional clusters

Object contains references to a set of objects that are related in multiple dimensions

Run script

Object contains a script

xref display settings

Object contains a defined set of xref display settings

xref map settings

Object contains a defined set of zref map settings

Creating and Adding Object Attributes


Figure 2: How the Class Library Setup Controls Attribute Display in Database

When you're building object classes from scratch, you'll probably have to create some attributes first to add to them. It's important to understand how attributes affect the data-entry pane, especially since attributes contain their own rules fo data validation and display. The best way to understand this is the build a few object classes and experiment. Figure 2, above, gives an illustration of the general idea with the cross-reference data type as an example. Most of what follows in the rest of this section is a fairly detailed exposition of object attributes and data types, and their behavior.

Object Attributes


Figure 3: Configuring Object Attributes

Object attributes are listed in the object class edit pane (class field attributes). Press "edit fields" to bring up the add/delete fields pane which will contain a list of the attributes. From this pane you can add new attributes, remove attributes, or rearrange the order of the attributes. However, you cannot configure attributes from here. To configure attributes, go to the attribute library and select the attribute you want to edit, then use the edit pane to make any changes you may want. Object attributes are classified by data type. While Plato object attributes have a variety of possibilities achieved through these numerous data types, they are all store their information either as text or flag (yes/no) data. The various data types are mostly distinguished by various ways of entering and validating data and displaying data. Entering and Validating Data Data can entered from the keyboard or selected from a pre-defined list of data elements. Or you can set up entry to allow both. When data is entered from the keyboard, it can be validated in various ways depending on what type of data is being entered. Here's a list of the general possibilities: Keyboard entry, no validation Text data type Keyboard entry, yes/no toggle Flag data type Keyboard entry, validation of filename File and Path name data types. Input is validated for valid characters and the filesystem is checked to see if the file or path exists. As an option, file and pathnames may be browsed and selected from a popup window. Keyboard entry, validation for numeric form and range Numeric data type. Input is validated for valid numeric characters (0-9 and the decimal point) and a valid range (if specified). Keyboard entry, validation for correct date form Date data type. Input is validated for a proper date, i.e., is there a month, day, and year specified, is the month valid, and is the day valid for the specified month. Note that validation is attempted for whatever order your may enter the day, month, or year. This means that if you are entering the date in certain European formats where the day is to the left of the month, it is possible for the validation routine to confuse the day for the month and vice versa. If the valid day is also a valid month, date validation will assume the leftmost entry of the month and day is the month. The date entry pane will always display what it is "thinking" as you type, so may see its conclusions before accepting them. Keyboard entry, pick list validation Pick List data type (only if configured for a single pick list item). Input is validated from the contents of a list. If the keyboard input does not result in a match from the list, the field may be configuered to allow the new entry to be added to the list. Entry selected from list of valid entries Various data types: pick list, cross reference, field list, and internal list. Note that pick lists can be edited by the user, but cross reference, field, and internal lists are obtained on demand from internal lists that Plato maintains. Entry created automatically from the contents of other attributes Conversion and record key data types. Entry created automatically from templates and variables Read-only Text and Incrementing Numneric data types. *Entry created automatically from Plato* variables System date data type. Displaying Data Most attributes can control the way their data is displayed. The display will not affect the data as it is stored however, because the displayed value is constructed on demand as it is displayed or requested in a script; it is never stored. The stored value varies according to type; see the section on data types, below, for details. Here are the various display options and the data types that support them: Capitalization and proper name display rules** Text data type. Display templates or masks Text, read-only text, numeric, incrementing numeric, conversion data types. *Expansion of Plato* internal variables** Text, read-only text, numeric, incrementing numeric, conversion, system date data types. Filename conversion rules and path hiding Filename and pathname data types. Conversion of spaces Text data type. Date format rules Date data type. Special Data Types Reserved by Plato There are several data types that are reserved for use by Plato. Generally these types are hidden from view, since if you alter them in any way Plato might fail to function properly. However, you may encounter them if you disable protections Plato puts in place to prevent inadvertent changes to such things. Here are the reserved data types along with their functions: Special Date data types These types are reserved for special task-related attributes (start, end, completed dates) and special Plato system attributes (system date) start date end date completed date system date Special bookmark data types These data types are used exclusively by bookmarks and can only be safely altered internally by Plato's bookmark functions. clip offset clip bytes clip parent row clip parent ID clip text Special script data types These data types are used exclusively by scripts and can only be safely altered internally by Plato's script editor. script type script source script output script name folder script script output file Special xref view data typesThese data types are used exclusively by xref view objects. xref: types to display xref: object classes to exclude xref: path xref: auto-open all branches xref: sort results xref: restrict scope to current folder xref: levels to display xref: start point xref: show siblings xref: use in script Special xref map data types These data types are used exclusively by xref map objects. xmap: type xmap: output xmap: elements xmap: labels xmap: spec Special file management related data type The following is used exclusively by Plato file management views. renameable file name

Attribute Data Types
Here is a reference to all the general data types for object attributes, along with with each of their sub-attributes. Plato also has some special data types reserved for its internal use that are explained further below, however these data types are not editable.

text

Text fields will accept any alpha-numeric text. The only validation in such fields is the ensure that the text characters are ASCII characters within the range of ASCII (decimal) 32 to 126.

Text fields are stored interally exactly as they are entered at the keyboard. Display related sub-attributes of text fields are:

case

The case attribute determines how text is displayed with respect to capitalization and word order (for names). Here are the case variables and their effects:

LITERAL No effect (Accepts case as it entered by the user)
UPPER Forces all text to upper case
LOWER Forces all text to lower case
TITLE Forces all text to title case (first letter of each word is upper case). Note that in title case conjunctions and articles are usually not capitalized unless they begin the title or sentence. The list of words the title case algorithm will omit is contained in the PLATO resource file and can be modified to fit special circumstances. See the article on PLATO resources for instructions on modifying resources.
NAME Forces names into the following format: 'last name' [comma] 'first name' 'middle name (or initial).' The first letter of each word is upper case. If a comma is found in the data entered, it will assume the name is already in 'last, first middle' format and leave it alone.

replace_characters

This attribute allows you to replace any characters in the text with another character or set of characters. This is primarily useful when the text in the field will be used for a filename or URL and you want to replace spaces with hyphens or underscore characters. If the field is left blank it will be ignored.

Syntax is as follows:

    [character to replace] = [new character]

Characters may be entered literally, or Plato macro characters may be used as well. Here's an example:

     &space = -

In this example any spaces found will be replaced by hyphens ("-").

If more than one character replacement is entered into this field, seperate each replacement set with commas, as follows:

     &space = -, a = z, &comma = ;

Note that if a comma is part of the replacement formula you must use the Plato macro '&comma' or it will be interpreted as a seperator!

text_mask

Text masks can be used to automate repetitive typing, such as phone numbers with the same area code or prefix. A mask can be set up as follows:

Type the text mask within the text mask field. The text mask can consist of any characters you like (except the percent sign (%), which is used to tell Plato where to insert the text into the mask). Use the "%" character to indicate where the text from the field should be inserted. Example:

    text mask                          =  (555) 444-%
    text entered into text field  =  9137
    text Plato displays            =  (555) 444-9137

text (read only)

Read only text fields will not accept user input. They are intended for static text that doesn't change. Although they have the text mask attribute, any expansion macros in the mask will have no effect since no user input will be accepted. Therefore don't bother to put macros in read-only text fields since they won't be used.

text_mask

numeric

Numeric fields will only accept characters within the range of ASCII (decimal) 48 to 57, plus the decimal point character ASCII 45. Numeric fields may also be validated against a user defined range. PLATO will allow any range as long as lower limit of the range (nn) is less than the higher limit (nnn). Numeric fields are always assumed to be integers. If you wish to use floating point decimal values, you must specify a range and include a decimal point in the range limits. For open-ended ranges, use "any" as the upper limit. For instance:

range = 0.0-any

will accept any floating point number larger than zero.

Numeric fields may also have any of the additional attributes listed below. Numeric attributes must be specified one attribte per line, with each line ending in a semicolon. Here's an example:

    calc = input * 2.34;
    mask = P/###,###.##;
    unit = parsecs;
    range = 3 to 4000;

Numeric fields are stored internally exactly as they are entered at the keyboard. Additional display and validation related sub-attributes for the numeric data type are as follows:

calculation

When calculations are present in numeric or conversion attributes, the result of the calculation will be displayed as the attribute. Calculation formulas are simple arithmetical statements in the form:

    CALC  =  [value1]  [operation]  [value2]

where:

[value1], [value2] are numbers or the numerical contents of object attributes and [operation] is one of the following arithmetical operations:

    +    =  addition
    -    =  subtraction
    *    =  multipication
    \    =  division

When [value1] or [value2] are the numerical contents of object attributes, they must be formatted as follows:

f[attribute ID] will cause the value to be the value of the attribute specified by f[attribute ID]
INPUT will cause the value to be whatever the user puts in the input field.
ANSWER[calculation index] will cause the value to be the answer of a previous calculation (specified by [calculation index], which refers to the line)

Here's an example:

CALC = f464 * INPUT;
CALC = ANSWER1 * 100;

For this example, if the value for the attribute with field ID 464 is 15 and the user input is 24, the displayed value will be 36,000.

Here's an other example:

CALC = f464 / 12;
CALC = f124 * 5;
CALC = ANSWER1 + ANSWER2;

For this example, if the value for the attribute with field ID 464 is 1200 and for field ID 124 is 52, the displayed value will be 360.

mask

Masks should be specified if you want your numbers to be formatted with commas, with a fixed number of places to the right of a decimal, or as currency. When specifying a mask, use '#' to represent each numeral's place. If the number of numeral places shown in the mask must be explicitly observed during data entry, preceed the mask spec with 'L/'. If you want Plato to pad the number with trailing and leading zeros, precede the mask spec with 'P/'. If you want Plato to indicate if a year is BC or AD, preceed the mask spec with 'D/'. When the D/ flag is in effect, 'BC' will be appended to negative numbers; 'AD' to positive numbers. You may not use the 'L/', 'P/', or 'D/' flags in combination. Beyond this, anything goes. Here are some possible masks and their results:

Mask                              Result
-----------------------    -------------------------
no mask                          1234567
###,###,###                  1,234,567
L###,###,###                error (not enough digits)
$###,###,###.##            $12,345.67
###-####                      123-4567
(###) ###-####            123-4567
L/(###) ###-####          error (not enough digits)
### bowling pins            1234567 bowling pins*

*(If you use a mask to specify units in this way, take care that it does not conflict with any unit spec you may have also used.)

range

The range attribute causes numeric fields to be validated against a user defined range. Plato will allow any range as long as lower limit of the range (nn) is less than the higher limit (nnn). Ranges are specified as follows:

range = nn-nnn

Numeric fields are always assumed to be integers. If you wish to use floating point decimal values, you must specify a range and include a decimal point in the range limits. For open-ended ranges, use "any" as the upper limit. For instance:

range = 0.0-any

will accept any floating point number larger than zero.

unit

The unit attribute assigns user-defined units to numeric and conversion fields. Units are not validated; any unit is allowed. Units are specified as follows:

Unit spec              Result
----------------    ----------------
no unit spec          1234567
meters                  1234567 meters
gallons                  1234567 gallons
fishes                    1234567 fishes

numeric, incrementing

Incrementing numeric fields provide a means of automatically issuing a sequential number to a record when it is created. Since the number is automatically provided by Plato, it is read only.

Setting up incrementing numeric fields consists of setting two elements: a counter and a number mask. The counter is what Plato automatically increments when it issues a new record; it can be reset (but be careful--see below). The number mask provides a user-defined format for displaying the number.

Additional sub-attributes of the incrementing numeric data type are as follows:

counter

The counter attribute will be incremented automatically whenever a new object is created of the class that has the counter. For this reason you must be careful to not allow two or more object classes to use the same counter attribute--create a different counter attribute for each object class that needs a counter. If you manually reset the counter and continue to use it in the same object class, you may get duplicate numbers for objects of the class.

mask

conversion

Conversion fields are identical to numeric fields except they will not accept user input. Therefore the 'input' keyword for calculation fields is not recognized. Conversion fields are intended to provide alternate values for other existing attributes. For instance, if you have a numeric field for 'monthly income', you could have a conversion field for 'yearly income' that uses the monthly income field, multiplies it by 12 and displays the result. Whenever you change the 'monthly income' field the conversion will automatically display a corresponding new value.

Additional sub-attributes for the conversion data type are given in the numeric data type.

internal variable

Internal variable fields will not accept user input, but rather display the contents of Plato variables.

variable

Plato internal or text variable. A list of named internal variables is contained in the system settings.

date

Dates can be entered in any format and are fully validated. Any year may be entered from -10,000 to +10,000. Years entered as minus numbers are displayed as positive numbers with "BC" appended.

Ther way date fields are displayed is governed by the date attribue, described below.

date_format

The date attribute governs how a date is displayed. The following formats may be selected for date fields:

Numeric          Written                Roman numeral
formats            formats                formats
-----------      --------------        -------------
03/08/1999    8-Mar-1999          8.III.99
3/8/1999        Mar-8-1999          8.III.1999
03/08/99        8-Mar-99
3/8/99            Mar-8-99
1999.03.08    Mar 1999
1999-03-08    8.Mar.99
                      8.Mar.1999
                      March 8, 1999
                      8 March 1999
                      8 March 99
                      March 1999

Other formats may be added using advanced customization. See xxx.

pick list

Pick lists are fields that check user input against the contents of a list. They can be used to facilitate input by displaying a list of choices to pick from. Turning the 'allow changes' attribute on or off will allow you to add new entries on the fly, or control input by forcing you to pick only from the existing list. The pick list can also be configured to allow multiple entries to be selected by turning the 'allow multiple values' attribute on or off.

allow_changes

When the allow changes attribute is checked, the user may add items to a list or make other changes to it on the fly during data entry.

allow_multiple_values

when checked, the user may pick more than one item from a list.

cross reference

"Cross reference" fields are fields that display a list of all objects in a database of a particular class. Single or multiple objects may be selected from the list and placed in the field. The record containing a cross reference field is automatically cross referenced with whatever objects are listed in the field.

Setting up a cross reference field requires the following:

allow_multiple_values

when checked, the user may pick more than one item from a list.

associate_as

Specifies how an object is to be related to another object. Possible values are:

associate as parent
associate as child

object_class_to_xref

Specifies which object class to cross reference, selected from a list of all object classes.

xref_type

Specifies the cross reference type, selected from a list of all xref types.

file name

File name fields must contain a valid file name. File names must contain the path to the file, otherwise the current path is assumed.

filename_format

There are four options for displaying filenames: windows/DOS, TeX/LaTeX, URL compliant, and hide path. Here are the differences:

Windows/DOS c:\my documents\happy file.txt
TeX/LaTeX c:/my documents/happy file.txt
URL compliant file://c:/my%20documents/happy%20file.txt
Hide path happy file.txt

file_mask

Allows you to create a file mask for browsing files. File name fields usually contain a 'browse' button, which when pressed will open a dialog box containing a view of the Windows file system.

replace_characters

path name

Path name fields must contain a valid path.

filename_format

There are four options for displaying filenames: windows/DOS, TeX/LaTeX, URL compliant, and hide path. Here are the differences:

Windows/DOS c:\my documents\happy file.txt
TeX/LaTeX c:/my documents/happy file.txt
URL compliant file://c:/my%20documents/happy%20file.txt
Hide path happy file.txt

file_mask

Allows you to create a file mask for browsing files. File name fields usually contain a 'browse' button, which when pressed will open a dialog box containing a view of the Windows file system.

replace_characters

record key

The record key data type automatically generates a bibliographic key based on the content of other fields within the record. Record keys are specified by naming a field followed by an optional field operator which specifies the characters from the field that will be used to assemble the key. If the operator is omitted, the entire contents of the field will be used.

key_code

The key code formula is as follows:

[field name]:[operator]

(Note that for multiple field/operator formulas, each formula should be seperated from the next by a space)

Valid operators:

INI = initials (i.e., the first letter from each word in the field)
LNO = last name only (intended for fields that contain names)
FNO = first name only (intended for fields that contain names)
ALN = all last names (intended for fields that contain several names)
LFT# = The leftmost specified number of characters in the field
RGT# = The rightmost specified number of characters in the field

Example:

This record key:

    author:LNO title:INI year

applied to this record:

    author = Hannah Arendt
    title = Between Past and Future
    year = 1968

Will generate this record key:

    ArendtBPAF1968

field list

This is a special data type that allows fields to be selected and ordered for display as columns in a window. It is only useful as a attribute to objects that cause other objects to be displayed in a window, such as folders.

internal list

Internal lists Plato system values that can be selected but not changed or added to.

internal_list_id

ID of the selected internal list. The name of the list is displayed, and is selected from a list of internal Plato lists, as follows:

Valid Objects
Editors
Templates
Signatures
validation lists
scripts
xref types to display
xref path
xref map type
xref map output
xref map labels
xref map elements
xref start point

flag

Flags are simple "yes" or "no" values. The flag value is a toggle during data entry.

This page last updated on 2016.12.19