Naming Conventions

StudioWorks uses the naming conventions which are documented under the StudioTips - Naming Conventions group.

Reserved Class Names

The following are StudioWorks reserved class names:

• sIcons - schema class used to declare icon names and the icon ID which the the name is mapped to. Normally each libary has an sIcons schema class.
• sMn_stb - schema class used to declare string table IDs for each menu name and menu line in a library. Normally each libary has an sMn_stb schema class.
• sWn_stb - schema class used to declare string table IDs for each window instance name in a library. Normally each libary has an sWn_stb schema class.
• sRefs - used by the References module for the refs database table (References)
• sUsr - used by the SysAdmin module for the usr database table (Users)
• sGrp - used by the SyAdmin module for the grp database table (Groups)
• sMainco - used by the SysAdmin module for the mainco database table (Main Company)

Default Class Names

The StudioWorks framework has some default class names which you can use to your advantage. By following these default class names you can reduce the amount of code you write.

The StudioWorks framework automatically generates two window instance IDs (WinInstID) for every server table based schema class in each library.

1. TablenameList which is calculated using con(cap(ServerTableName),'List')
2. TablenameEdit which is calculated using con(cap(ServerTableName),'Edit')

Each auto generated WinInstID is mapped to a SQL class. The SQL class can either be a query class or a schema class. The StudioWorks framework looks for and maps to either a query class or schema class as follows:

1. StudioWorks looks for a query class by the same name as the WinInstID prefixed with the letter q.
   
   PersonList maps to qPersonList
2. StudioWorks looks for a query class by the same name as the cap(TableName) prefixed with the letter q.
   
   PersonList maps to qPerson
3. StudioWorks looks for a schema class by the same name as the cap(TableName) prefixed with the letter s.
   
   PersonList maps to sPerson

The WinInstID is mapped to the first SQL class which it finds in the order of the above list. If you decide to add a query class later on, you simply need to Rebuild Lists and Windows, and StudioWorks will automatically map the applicable WinInstID to the new query class.

For simple tables, you might never need to create a query class, letting StudioWorks map to the schema class.

For more complex tables you will want to create a List query class to reduce the number or columns, control the order of columns, and/or join to other tables.

For more complex tables you will want to create an Edit query class to control the order of columns, and/or join to other tables.

Each auto generated WinInstID is mapped to a window class. The StudioWorks framework looks for a window class that is the name of the WinInstID prefixed by the letter w. If not found, StudioWorks defaults to using an wList_autoconfig or wEdit_autoconfig as applicable.

Composite Class Names

Composite class names combine several class names.

As you develop query classes which join several schema classes or window classes which contain subwindow window instances you will face the dilemma of deciding on a naming convention for composite class names.

The following StudioWorks naming convention has been developed for composite class names.

For this section we will use the StudioWorks community contacts module (swcContacts4) which has a number of composite classes.

We will limit our discussion to the following tables in the contacts module:

1. Org - contains organizations and households.
   
   The isHousehold field is used to specifiy if a record in the table is a household. If a record is a business, charity, or anything other than a household this field is set to zero. If the records is a household this field is set to one.
2. Person - contains people.
3. Orgperson - joins people to organizations/households. One of the fields in the Orgperson table specifies the role the person has related to the organization/household.
   
   The Orgperson is a composite table name.

The contacts module maps the following schema classes to the tables:

1. sOrg to Org
2. sPerson to Person
3. sOrgperson to OrgPerson

The contacts module has the following basic query classes which map to WinInstIDs.

1. qOrgList maps to the WinInstID, OrgList, for listing Org records.
2. qOrgEdit maps to the WinInstID, OrgEdit, for editing an Org record.
3. qPersonList to maps to the WinInstID, PersonList, for listing Person records
   
   (qPersonList does not exist, so StudioWorks maps sPerson to the WinInstID, PersonEdit, for editing a Person record.)
4. qOrgperson maps to the WinInstID, OrgpersonList, for listing Orgperson records.
   
   Note: qOrgperson joins Org, Person, and Orgperson including applicable fields from each table.
5. qOrgperson maps to the WinInstID, OrgpersonEdit, for editing an Orgperson record.

The following basic window classes map to the WinInstIDs:

1. wOrgList maps to the WinInstID, OrgList, for listing Org records.
2. wOrgEdit maps to the WinInstID, OrgEdit, for editing an Org record.
3. wPersonList to maps to the WinInstID, PersonList, for listing Person records.
4. wPersonEdit to maps to the WinInstID, PersonEdit, for editing an Person record.
5. wOrgpersonList maps to the WinInstID, OrgpersonList, for listing Orgperson records.
6. wOrgpersonEdit maps to the WinInstID, OrgpersonEdit, for editing an Orgperson record.

Things get a bit more complicated when we combine basic window classes inside container window classes.

1. A custom WinInstID, OrgEditOrgpersonList, is declared in the oWindowsList object.
2. A special window class, wOrgEditOrgpersonList, instantiates the window class, wOrgEdit, in a subwindow field and allows the user to edit an organization record. It instantiates the window class, wOrgpersonList, in another subwindow field and displays a list of the persons joined to the organization being edited.

The naming convention for a composite WinInstID and its container window class is to list each contained WinInstID in the intended order of use. We we easily see from the WinInstID, OrgEditOrgpersonList, that it contains the WinInstID, OrgEdit, and the WinInstID, OrgpersonList.

The composite class names naming convention is only a guideline. If you get into a composite class that has many subwindow the above naming convention gets very messy and you will need to come up with a name that as clearly as possible states what the window class accomplishes.

For example, in the swcTasks module, there is a composite window that has 5 subwindows. The window allows use to view and select any projects, categories, and project member. It lists the tasks for the selection and allows the user to edit, add, delete tasks. This composite window has been named, wTaskViewer.

You may have a situation where you have a shell window which contains numerous subwindows. The Database Administration window in swBase4 is a good example of a shell window. It uses a tab pane object with each tab instantiating a different subwindow. I had tried several different names for the shell window. (wDBAdminShell, wDBAdminContainer, wDBAdminTabs). Eventually, I found it was cleanest to simply name the shell window, wDBAdmin. In the F2 Browser the wDBAdmin window class nicely sorts above all the subwindows.

Substitute Class Names

There may be situations where you use a substitute string table for a certain table.

An example of this is in the StudioWorks community contacts module. In this module the Org table is used for storing organizations and households.

In the sOrg schema meta-data the OrgName column label is Organization Name.

For presenting household records a substitute string table sHousehold_stb is used. In the sHousehold_stb schema class the OrgName column label is Household Name.

Special query classes are created which have their String Table Name meta-data value set to Household. (See String Tables > Substitute String Tables)

The naming convention for the substitute classes is to replace the base table name with the substitute base name. So for the household related classes, Org is replaced with Household as follows:

1. The query class, qHouseholdList, is used to fetch and list records where isHousehold=1.
2. The query class, qHouseholdEdit, is used to fetch and insert/update a record where isHousehold=1.
3. The WinInstID, HouseholdList, lists Org records where isHousehold=1.
4. The WinInstID, HouseholdEdit, is used to edit an Org record where isHousehold=1.

If you want to create a series of classes which list and edit both the base and substitute records you would concatenate the base name and the substitute name. To include organization and household records in the same list we would create classes and declare window instances as follows:

1. The query class, qOrgHouseholdList, is used to fetch and list records where isHousehold could be zero or one.
2. The query class, qOrgHouseholdEdit, is used to fetch and insert/update a record where isHousehold could be zero or one.
3. The WinInstID, OrgHouseholdList, lists Org records where isHousehold could be zero or one.
4. The WinInstID, OrgHouseholdEdit, is used to edit an Org record where isHousehold could be zero or one.

StudioWorks Documentation - Copyright 2005 Vencor Software