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.

Don't get intimidated by fact that are quite a few steps involved - once you have done them a few times, you will remember them pretty quickly.

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 of frequently displayed 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.
    • 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 the Resource File (contains e.g. Icons) which form the actual screen in openPETRA.

openPETRA's Screen Definition Files are plain text files which are structured in the [YAML] syntax.

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:\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'.

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:\openpetraorg\csharp\', and add the File Name to get the full file path: 'U:\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 the WinForms Generator

• Open a Command Prompt (a.k.a. 'DOS Window').
• enter the following commands:

U:  <ENTER>
cd \openpetraorg  <ENTER>

• after that, verify that the 'nant' build system is working by entering

nant help  <ENTER>

• you should see a list of possible commands and their explanations on the screen
  • if you get an error message, then the setup of the development environment is not fully completed, or at least not working, on your computer. Refer to Setup_of_Development_Environment_for_Windows#NAnt for instructions to set nant up correctly.
• enter the following command

nant generateWinForm -D:file=MPartner/gui/setup/YourYamlFileSetup.yaml

- potentially replacing 'MPartner' with the name of another openPETRA Module, and replacing 'YourYamlFileSetup.yaml' with the actual name of your new yaml file.

• the WinForms Generator will launch and process your new yaml file.
  • if the Generator continues to build a C# project and then launches the openPETRA Client, your yaml file doesn't contain any 'bad' errors.
  • if the Generator stops and issues an error message: try to find out and fix what is wrong, according to the text of the error message.
  • in case the Generator stops with an Exception, check the overall structure of your yaml file for any potential errors, such as: missing or misplaced brackets ('[' and ']') or curly braces ('{' or '}'), wrong indentation, missing colons (':') or missing or superfluous commas (',') or space characters (' ').
  • fix what you think is wrong and run the Generator again, until the Generator continues to build a C# project.
  • if you are 'stuck', seek help from other developers in the Developer area in the openPETRA Forums.

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

Step 5a: Adding the generated files

The generated files now need to be added to the C# Project in which they belong so they can get compiled.

• Start the SharpDevelop IDE
• Run the Menu Command 'File' -> 'Open' -> 'Project/Solution...'
• Select the file

U:\openpetraorg\csharp\ICT\Client.sln

and choose 'Open'.

• SharpDevelop will open a group of C# Projects that contain all the client-side program code of openPETRA. (Such a group of Projects is called a 'Solution', hence the '.sln' file extension.)
• In the 'Projects' list, locate the C# Project that should contain the new Maintain Table screen.
  • The C# Project you need to choose will depend on where your new yaml file is in the folder structure of openPETRA.
    • Example: if your new yaml file is located in U:\openpetraorg\csharp\ICT\Petra\Client\lib\MPartner\gui\setup, then the corresponding C# Project file is called Ict.Petra.Client.MPartner.Gui.Setup
• Right-click on the correct C# Project in SharpDevelop and choose 'Add' -> 'Existing Item...'
• Locate the C# file that the Generator created and choose 'Open'.
  • The C# file is in the same folder as your new yaml file and is called the same, except that it's file extension is .cs, and not .yaml.
    • Example: if the yaml file of the new screen is called 'LocationTypeSetup.yaml', the file that you should choose will be called 'LocationTypeSetup.cs'. (Be sure not to select the file that ends in '.Designer.cs'!)
• Expand the C# Project by clicking on the '+' symbol in front of it.
  • You should now see a few nodes. One of that node is called like the C# file, with a '+' symbol in front of it.
• Expand that node by clicking on the '+' symbol.
  • You will see that additional files got added automatically - one that is called like your C# file, but with the file extension '.Designer.cs', and a file that is called like your C# file, but with the file extension '.resx'. Those file were created by the WinForms Generator and are necessary for the form (but you will never need to touch them!).

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

• Right-click on the node that represents your Maintain Table's C# file (this is the one you just expanded) and choose 'Add' -> 'Existing Item as Dependent Item...'.
• In the 'Add existing files' dialog you will make a copy of an existing file before adding it:
  • Locate a file that is called like the yaml file of the existing, similar screen that you started off with, except that its file extension is '.ManualCode.cs' instead of '.yaml'.
    • Example: if the yaml file of the existing, similar screen is called 'PartnerTypeSetup.yaml', the file that you should copy will be called 'PartnerTypeSetup.ManualCode.cs'.
  • Copy that file (e.g. by using the Context Menu entries 'Copy' and 'Paste') and rename the resulting file (e.g. by using the Context Menu entry 'Rename'):
    • The name of the file should be like the file name of your new yaml file, except that the file extension should be '.ManualCode.cs' instead of '.yaml'.
    • Example: if the new yaml file is called 'LocationTypeSetup.yaml', the new file name should be 'LocationTypeSetup.ManualCode.cs'.
• Choose 'OK' to add the new '*.ManualCode.cs' file as a 'dependant item' to your form.

Step 5d: 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