How-To: Creating a Maintain Table screen

Overview

A Maintain Table screen allows CRUD (Create, Read, Update, Delete [1]) operations for a specific system table/lookup table of openPETRA.

This tutorial outlines the basic steps that are involved in creating a Maintain Table screen, starting off with an existing Maintain Table screen which is then copied and modified.

Types of Maintain Table Screens

There are three types of Maintain Table screens:

• Maintain Table screens which are used for editing the values of a 'Cacheable DataTable'.
  • A 'Cacheable DataTable' usually contains the data of a single database table which is transferred to the Client once and is saved to a local file which resides at the client computer's harddisk at the first client request of the Cacheable DataTable. These datatables are also held in memory (RAM) for quick access. The Cacheable DataTables are managed by a Cache Manager Class on both the client and server side, which make sure that all Cacheable DataTables of all clients are kept up-to-date and in sync, among other things.
    • 'Candiates' for Cacheable DataTables, and therefore for Maintain Table screens which are editing the values of Cacheable DataTables, are database tables that are frequently accessed either by the server or the client or whose contents are frequently displayed, e.g. values for ComboBoxes or Lists.
  • This type of Maintain Table screen is the easiest to do and needs the least programming because the Cache Manager Classes encapsulate most of the functionality that is needed. The person who creates such screens does not need know about the client-server architecture of openPETRA, and needs little programming know-how - therefore such Maintain Table screens are ideally suited for people who join the development of openPETRA.
• Maintain Table screens which are used for editing the values of a single database table that is not a 'Cacheable DataTable'.
  • This type of Maintain Table screen is somewhat more involved than the Maintain Table screens which are editing the values of Cacheable DataTables.
  • More programming is needed, since such a screen uses a WebConnector Class for reading and writing of data from/to the database. One WebConnector Class needs to be created for every screen. These Classes aren't hard to do and follow a standard pattern, but in order for creating those Clases, the programmer needs to know more about the client-server architecture of openPETRA and needs to be a more experienced openPETRA programmer.
• Special Maintain Table screens
  • which
    • edit values of several database tables at once, or
    • need to read in the values of several database tables in order to edit one database table, and/or
    • don't follow the standard 'list/detail' format of the typical Maintain Table screens, and
    • have custom loading/saving routines to update the database.
    • usually are unique within openPETRA and don't resemble each other, so a custom GUI needs to be developed for each screen.
  • Those screens' design and logic is usually similar to many Edit screens and therefore no general principle can be given how they are done. (Most likely a more involved WebConnector Class will be needed for such screens; some screens might even be better done with a UIConnector Class.)
  • For those reasons, an experienced openPETRA developer needs to do those kind of screens.
  • There are not that many Maintain Table screens which fall into this category.

Creating a new Maintain Table screen

The following general instructions can help in creating a simple new Maintain Tables screen based on a similar, existing Maintain Tables screen. (Many Maintain Tables screens are similar. To start off with a completely new Maintain Tables screen that isn't based on an existing one is obviously more complicated. However, from Step 4 onwards, the same procedures would apply to such new screens as well.)

Step 1: Choosing a similar, existing Maintain Tables screen

TODO

Step 2: Copying existing screen definition file to new screen

TODO

Step 3: Modifying screen definition file to suit the new screen's data and layout

TODO

Step 4: Generating the screen's source code with help of the WinForms Generator

TODO

Step 5: Adding new source code files to corresponding C# Project

Step 5a: Adding the generated files

TODO

Step 5b: Creation and adding of the *.ManualCode.cs file

TODO

Step 5c: Compile C# Project

TODO

Step 6: Adding screen to openPETRA main menu structure

TODO

Step 7: Opening the new screen in openPETRA for the first time :-)

TODO

Step 8: Iterations: adjusting to needs, re-generate screen, re-open screen

TODO

Step 9: Commit new screen's files to your local Git repository

TODO

Step 10: Integration of new screen into official openPETRA Git repository

There are two options, depending on whether you have or haven't write access to the official openPETRA Git repository.

You can follow the instructions of 'Option B' only if you have write access to the official openPETRA Git repository. If you don't, then you have to follow the instructions of 'Option A'.

Step 10, Option A: Creating a Git Patch and sending the Patch to the openPETRA core development team

TODO

Step 10, Option B: Pushing new screen's files to the openPETRA Git repository

TODO