Doco Home Hints Home

Useful Conventions for Choosing Names

This section describes conventions we have found useful for choosing names, such as ID and NAME attributes.

There is another page on names in the Tools section - it describes the names generated by Platypus, such as variable names in the generated Java.

Workflow and PO naming scheme

Our naming scheme for workflows and POs is introduced in the Overview. Here we present some more details.

We use the following names for roles within a workflow:

Query: gathers info for a database query
Results: displays retrieved/computed data
List: lists options, from query, for further work
Commit: adds a record to database without being displayed
Form: data entry or update.

We often use the following prefixes at the start of a workflow name, indicating what kind of operation the entire workflow performs:

Add: add a new record to the database
New: like Add.
Edit: updates existing records in the database
Update: like Edit.
Delete: remove a record from the database.

Report workflow names don't have a prefix (in our experience). They seem to be well enough signaled by being in the 'reports' directory.

Frameset Presentation Objects

XMLC requires a special option to handle HTML containing framesets. Presentation objects containing framesets must end in Frameset for the Makefile system to invoke XMLC with the required option.

ID Names

ID names occur through all parts of the presentation layer, and its interface with the business layer. In more detail, ID names occur:

Prototype HTML
ID names are the values of ID attributes in the prototype HTML. Thus, an ID name uniquely specifies a dynamic node within a PO.
Developers configuration
Each ID name in a PO should have a section in the PO's conf file. Each ID name in the applciation may also have a section in the global developers configuration.
DOM class interface
The DOM class for a PO has a public method, getIdNameElement(), for each dynamic node in the PO.
Manipulation and BASE class Java
The ID Names form the basis of many variables declared in these presentation layers classes.
PO - BO interface
The ID Names form the basis of requests for data from the presentation layer to the business layer.

An ID name must be unique within an HTML document, and therefore unique within a PO. However, an ID name may be reused in several POs throughout the app.

It is wise to only reuse an ID name between POs where it serves the same role in the POs. This allows the ID name be put in the global IDS section in the developers configuration.

We use the following conventions when choosing ID names:

Value from database via an access
If the database field is in the database table referenced by the access, the ID name should be the database field name. This includes getting the ObjectId for a drill-down's URL.
Database access
ID attributes in some types of node are interpreted by ConfigGen as indicating that node corresponds to a database access. These nodes should have ID attribute TableNameTable.
Pulldowns
A pulldown needs up to two names for retrieving data from the business layer. It uses a pulldownkey to retrieve the list of options, and an ID name to set the option selected in the served page.
If the list of options is hard coded in the HTML, rather than retrieved from the special database table, the pulldownkey is not needed.
If the option selected in the served page is not set to data from the business layer, the ID name is not needed for the business layer interface.
The pulldownkey and the ID name used for retrieving values from the business layers may be the same (ie, they exist in different name spaces).
Usually, the most sensible choice for the pulldownkey will be the same as the choice for the ID name. If it isn't, the choice of ID name should be based on the name used elsewhere in the app to retrieve data from the business layer, and the pulldownkey can be edited in the developers configuration.
Query string
Dynamic nodes which will be filled with values taken from the query string should probably have a name based on the name on the query string. However, this is much less important than the selection of ID names for interacting with the business layer.