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 rather simple and similar to existing ones. 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

• Start openPETRA.
• Using the Navigation Panel, go to the Module (and perhaps Sub-Module) that contains the Area 'Setup' where a Task for a similar screen exists (in the Task List on the right hand side).
  • It is advisable to look for a similar screen in the Module where your new screen should end up as well - this makes it easier to copy the screen.
• Open the screen that you think is similar and check that it indeed is similar to the screen that you are about to do.
  • Check for
    • the overall appearance of the screen,
    • that there is a similar number of data fields in the columns of the grid and
    • that there is a similar number of data fields in the details section below the grid.
  • Should one or two columns in the grid or one or two data fields in the details section be different, this screen is still suitable for a 'similar screen' that we can start off with.

Step 2: Copying existing screen definition file to new screen

Overview

All Maintain Table screens are based on a 'screen definition file', which is passed to a Generator. The Generator generates the C# source code and Resources which form the actual screen in openPETRA.

By copying the screen definition file of the existing screen, we will get an exact copy of the layout and data of the existing screen - in a new file. This will be our starting point for the changes we need to make to change the data and layout into 'our' new Maintain Table screen.

Locating existing screen's screen definition file

• Recall what Module, Sub-Module and Area you chose, and which Task you chose from the Task List to bring up the existing, similar Maintain Table screen.
• Open the following file in a text editor (e.g. Notepad, Notepad++)

U:\csharp\openpetraorg\csharp\ICT\Petra\Definitions\UINavigation.yml

• This file contains a structure that is used for builing the Navigation structure which you see in the Main Menu's Navigation Panel of openPETRA.
• Scroll through the file until you find the Module, Sub-Module, Area and Task that describes the Task that you clicked to bring up the existing, similar Maintain Table screen (the hierarchy is created by indentation!).
  • The line that describes the exact Task contains the text 'ActionOpenScreen=', followed by text. That text, usually starting with 'TFrm...', is the Class Name of the existing, similar Form.
  • To find out the File Name of its 'screen definition file', leave out the 'TFrm' and take only the remainder of the text. Example: if the text is 'ActionOpenScreen=TFrmPartnerTypeSetup', the Class Name is 'TFrmPartnerTypeSetup' and the File Name is 'PartnerTypeSetup'.
  • append ".yaml" to get the full File Name including File Extension. Example: 'PartnerTypeSetup' becomes 'PartnerTypeSetup.yaml'.
    • openPETRA's Screen Definition Files are plain text files which are structured in the [YAML] syntax.

Determining full file path

• The line that describes the exact Task, or more likely the Elements who are one or two steps higher in the hierarchy (=one or two steps less indented), will contain the text 'Namespace='. It is followed by a text that ends in '.Setup', e.g. 'Ict.Petra.Client.MPartner.Gui.Setup'.
• This tells you the last part of the folder where the screen definition file can be found: replace the dots ('.') with backslashes ('\'), put tue word '\lib\' inbetween 'Client' and 'MPartner' and precede this with 'U:\csharp\openpetraorg\csharp\', and add the File Name to get the full file path: 'U:\csharp\openpetraorg\csharp\ICT\Petra\Client\lib\MPartner\gui\setup\PartnerTypeSetup.yaml'.

Copying the screen definitions file

• Make a copy of this file in the same directory.
  • Should your new Maintain Table screen need to go into a different namespace, choose the approriate directory (ending in 'gui\setup') and place the copied file there!
• Name the file according to what the screen will maintain
  • Example: if the screen will maintain Partner Types, name the file 'PartnerTypeSetup.yaml' (please use the singular, not the plural form).
  • The name of the file should end with 'Setup.yaml'.

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