This section describes conventions we have found useful for choosing
names, such as ID and NAME attributes.
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, usually adding or editing a database record.
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.
-
-