HowTo port a screen from Old Petra

Old screen

1. Start Petra 2.3 (perhaps in a virtual machine).
2. Make a screenshot of the screen you are going to port to OpenPetra. Copy the screenshot into a word document or into a graphics processing program and save it.
3. If the screen contains a Table, scroll the Table to the right and make several screenshots in order to capture the headers of all columns and the format of the data of all the columns (e.g. bool, decimal, text, date).
4. Try to operate the screen and to perform the obvious actions that it offers (eg. add a record, edit a record, delete a record). Use the Petra User Guide for the Module in which the screen is located to get the instructions that a user is presented with for this screen. Try to get a 'feel' for how the screen operates, how it accepts and rejects data, the options it presents to the user and what - if anything - is special about that screen.
5. Also check the menus for any special menu items that are not normally present in screens like the one in question and note them down.
6. If the screen opens other screens (Forms or Dialogs) as a result of an action of the user make screenshots of those screens as well as you will need to port those too if they don't already exist in OpenPetra.
7. Finally, open Menu Help->About Petra. In the dialog that opens you can find the name of the 4GL program for the screen. Note this down as you will need this in order to open that 4GL file to read through the full screen logic (i.e. if values of Labels or TextBoxes are calculated, to check if the program has some extraordinary behaviour that isn't obvious from operating the screen, how the screen validates its values, or how the screen is set up or parametrised). You will also need to do this for any detail screen(s) and other screens that are opened from this screen and which don't already exist in OpenPetra.
8. In theory you could now close Petra 2.3 (and the virtual machine) and start to think about the development of the new screen. However, in practice you will want to keep them open to see how the user interaction with the screen works out in detail and how the screen's program code is reflected in the behaviour of the screen.

New Screen

• Compared to Petra we have vastly different capabilities for layout and screen design in OpenPetra!
  • We can have much larger screens!
    • In general we should aim for a screen to work well on a 1024x768 resolution (it really needs to work on a 800x600 resolution!), that is to make sure that the user is not forced to scroll through the screen on such resolutions for the normal operation of the screen.
    • In OpenPetra the screens should hardly ever be fixed in size (in Petra they were often fixed to 640x480!) and thus the user can make them larger, and we can and should make use of that for improving the layout of the screen.
  • OpenPetra screens can contain Tabs and UserControls.
  • Whereas in Petra there was often a combination of a 'Browse' and an 'Edit' screen, in OpenPetra we have reduced that to one screen for such purposes. Such an OpenPetra screen contains both the Table ('Browse') and the Details ('Edit') (in the Grid and Details Panels, respectively).

(Re-)Design decisions

1. Ask yourself the question how usable the Petra 2.3 screen was and if it can perhaps be done better in OpenPetra by using a different approach. The focus should be on usability and on reducing the 'clicks' and other operations such as keyboard strokes or scrolling that are needed to perform a certain functionality in that screen.
   1. Put yourself in the position of a new OpenPetra user that will open the new screen in question for the first time and ask yourself:
      1. is everything logically arranged;
      2. should some user interface elements be grouped into GroupBoxes for clarity;
      3. is there something that could be confusing or that will need explanation;
      4. are the Labels descriptive and not technical;
      5. are user interface elements enabled which should be initially disabled;
      6. are there buttons that aren't self-explanatory;
      7. are buttons positioned well;
      8. is the formatting of the data good and helpful;
      9. etc.
   2. Some screens in Petra 2.3 were done in a way that was technically easy to do, but this often resulted in a screen that was more confusing and 'technical' for new users than it needs to be ('the DB design bleeds through to the GUI'). Try to avoid that in OpenPetra!
   3. 'Mover Dialogs' that feature buttons for moving items from one list to another are perceived more complex by the average user - usability research has shown that. Avoid those in OpenPetra (in many cases a Grid with CheckBoxes in the first column can be substituted for such a functionality and that is easier to program, too).
   4. If you are in doubt about whether to stick to the Petra 2.3 screen layout or to create a new layout, or if you are not sure how it should be done differently, consult another experienced OpenPetra developer.
2. Create a YAML file for the new screen. There is a very good long description for this in How-To: Creating a Maintain Table screen.
   1. The YAML files reference Templates (located in [projectroot]\inc\template\src\Winforms) and you have to find out which is the right Template for the ported screen. Ask yourself...
      1. will the new screen be a Window, a Dialog, or will it be embedded in an other window (=UserControl)?
      2. does it need to contain a Grid?
         1. if so, will it need to contain an additional Details Panel?
      3. is the underlying DataTable part of a larger Typed DataSet or is it used on its own?
   2. Consult another experienced OpenPetra developer if you are unsure which Template to use!
   3. After the decision for the right template, find a screen where this template is already used and copy its YAML file and its *.ManualCode.cs file to the location in the file system where your new screen needs to be located. (The *.ManualCode.cs file is needed nearly always). Adopt the copied files to your purposes.
      1. Again, consult another experienced OpenPetra developer if you run into trouble with the new screen as some hurdles are easier to overcome that one might think - that is, if one already knows about them!