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 several times, you will remember them pretty quickly. (A developer who has already done a few Maintain Table Screens will be able to do a new, simple Maintain Table Screen that is based on an existing Maintain Table Screen in about an hour or less.)

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

• Right-click on the C# Project you are working with and choose 'Build'.
  • The IDE will compile any dependent projects and finally the C# Project you are working with.
  • If no errors are shown, you can continue with the next step.
  • If errors are shown, try to solve them by going again over the list of things that need to be changed in the *.ManualCode.cs file (Step 5c) and by checking for any general C# syntax errors. If you still get errors after getting rid of any errors you were able to fix for yourself, seek help from other openPETRA developers by posting your problem in the Developer Area in the openPETRA Forum.

Step 6: Adding the new screen to the openPETRA main menu structure

• If you haven't got the following file still open, open it in a text editor (e.g. Notepad, Notepad++):

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

• Decide where your new screen should show up in the Navigation in the openPETRA Main Window:
  • We recommend that you start the openPETRA Client at that stage.
    • Have a look at the Module, Sub-Module, Setup Area and Tasks that you might have already in mind. Check what Tasks are already there and decide whether your new screen should be listed among the existing Tasks, or not. If not, keep on looking for a more suitable place in the menu structure, or, if you can't find one, decide on the name of a new Task Grouping in an existing 'Setup Area' that fits best.
    • Your new screen should usually be listed among Tasks of a fitting Setup Area. If you think it should not go in a 'Setup Area', it is best to ask in the Developer Area of the openPETRA Forum for guidance.
• Scroll through the UINavigation.yml file until you find the Module, Sub-Module, Area, Task Group where your new screen should be listed.
• Choose any existing Task's text line in that Task Group and copy the whole text line.
• Paste the copied text line in the place where you want your new screen to show up.
  • In case your screen should be displayed in a new Task Group, create a new Task Group by putting the name of the new Task Group in a separate line *before* the line of your new screen, followed by a colon (':'). Outdent (=the opposite of indent) the line for the new Task Group so that it starts in the same text column as other Task Groups do.
• Modify the pasted text line
  • Change the text before the colon (':') so it reflects what your Maintain Table screen is maintaining. Leave out any space characters and capitalise the first letter of every word.
    • Example: if your new Maintain Table screen is maintaining 'Location Types', change the text to 'LocationTypes'.
  • Change the text that follows 'Label=' to match how other Maintain Screens are showing up in the Task List.
    • Example: if your new Maintain Table screen is maintaining 'Location Types', change the text to 'Setup Location Types'.
  • Change the text that follows 'Description=' to match how other Maintain Screens are described in the Task List.
    • Example: if your new Maintain Table screen is maintaining 'Location Types', change the text to 'Maintain Location Types'.
  • Change the text that follows 'ActionOpenScreen' to match the Class Name of your new screen.
    • You can find out the Class Name by looking it up in the *.ManualCode.cs file: look for the line that starts with 'public partial class '. The text that follows that declaration is the Class Name of your new screen.
    • Example: if your new Maintain Table screen is maintaining 'Location Types', the Class Name is most likely 'TFrmLocationTypeSetup'.
• Close the openPETRA Client, if you have it open.

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

• Start the openPETRA Client.
• Go to the Module, Sub-Module and Setup Area to which you have added your new screen (in Step 6).
• Ensure that the Task for your new screen is listed, and that is in the Task Group that you want it in.
  • If you can't see your new screen listed, check back in the UINavigation.yaml file to see where you put the text line that defines the Task for your new screen, and move the text line of your new screen to a text line of the Setup Area and Task Group that you wanted to see it appearing in. Restart the openPETRA Client to see if the change made the difference you wanted.
  • If you still can't see your new screen listed where you want it to appear, seek help from other openPETRA developers in the Developer Forum in the openPETRA Forum.
• Click on the Task for your new screen.
  • Your new Maintain Table screen should open and display a list of entries.
    • If the screen opens: congratulations, you have created and added your first Maintain Table screen to openPETRA :-)
    • If the screen does not open: check the Status Bar of the Main Window of openPETRA for a message. That message should help you in finding the problem.
      • The most likely cause for a screen not opening is that the Class Name and/or the Namespace in the UINavigation.yaml file are not correctly specified.
        • Check the Class Name in the text line that defines your new screen and correct it if it is wrong. If you corrected it, save the UINavigation.yaml file and restart openPETRA. Check whether the screen opens after this change.
        • Check the Namespace.
          • The Namespace of a screen is specified by the word 'Namespace=', followed by text that denotes the exact Namespace in which the screen is located.
          • Ensure that the text that follows the word 'Namespace=' specifies the namespace of your screen: switch back to the SharpDevelop IDE and bring up the *.ManualCode.cs file. Search for the line that starts with 'namespace '. Check the text that follows and compare it with the text after the word 'Namespace='.
          • The word 'Namespace=' will most likely not appear in the text line that defines your new screen, but one or two steps higher in the hierarchy.
            • If it appears one or two steps higher in the hierarchy and it fits the namespace declaration of your screen's *.ManualCode.cs file, ensure that there is no 'Namespace=' defined in the text line that defines your new screen.
            • If it appears in the text line that defines your new screen, check that it is correct, and whether it is needed there at all - if the word 'Namespace=' appears one or two steps higher in the hierarchy and it fits the namespace declaration of your screen's *.ManualCode.cs file, then you should remove the 'Namespace=' declaration in the text line that defines your new screen because it is superfluous.
          • If you corrected the Namespace, save the UINavigation.yaml file and restart the openPETRA Client. Check whether the screen opens after this change.
    • If the screen does not open after your modifications (or the Class Name and the Namespace declarations in the UINavigation.yaml file seem to be right), seek help from other openPETRA developers in the Developer Forum in the openPETRA Forum.

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