HowTo develop a new report

Example

This page uses the "Partner by City" as an example.

Report Definition

• this is for the sql queries and instructions how to calculate and render the report
• create new xml report file in XmlReports/Partner/partnerbycity.xml
  • please use the new template in XmlReports/template.xml for the report definition file
• the documentation of the xml file is here: XML Report Definition files

• if there is no subdirectory for the module yet in XmlReports/Settings, please create it (eg. Partner). The file XmlReports/Settings/Partner/Partner by City/standard.xml can be created more easy once the GUI is running.

GUI Definition

• this is for defining how a screen should look like that presents all parameters of the report to the user
• create new yaml file for report in csharp/ICT/Petra/Client/lib/MReporting/gui/MPartner/PartnerByCity.yaml
• there is no template or generator for such a yaml file. usually it helps to make a copy of a similar yaml file that is used for reports.
• documentation about the definition of winforms with yaml file is here: Documentation YAML for OpenPetra Forms

• • when you run nant generateWinform -D:file=MReporting/gui/MPartner/PartnerByCity.yaml, the files PartnerByCity.cs and PartnerByCity.Designer.cs will be regenerated and updated in the directory csharp/ICT/Petra/Client/lib/MReporting/gui/MPartner.
  • you will need to manually add those 2 files to the project csharp\ICT\Petra\Client\lib\MReporting\gui\MPartner\Ict.Petra.Client.MReporting.Gui.MPartner.csproj which is quite easy to do in the SharpDevelop IDE. Perhaps we can even add this to a task in NAnt sometime in the future.
  • for some customized behaviour, you might also want to manually create a code file called csharp\ICT\Petra\Client\lib\MReporting\gui\MPartner\PartnerByCity.ManualCode.yaml, and add it to the csproj file as well. Again, we might do this automatically in the future. Have a look at csharp\ICT\Petra\Client\lib\MReporting\gui\MPartner\PublicationStatisticalReport.ManualCode.cs for the contents of that file.

Navigation

• Recommended: New OpenPetra navigation (Outlook Style):
  • modify the file csharp\ICT\Petra\Definitions\UINavigation.yml
    • if you are using a customized version of OpenPetra, this will be Customizing\gui\UINavigation.yml

 Reports: {Icon=printer.ico, Namespace=Ict.Petra.Client.MReporting.Gui.MPartner}
     PartnerByCity: {ActionOpenScreen=TFrmPartnerByCity}

• Old Petra 2.x navigation:
  • create new entries in existing yaml file in csharp/ICT/Petra/Client/lib/MPartner/gui/PartnerMain.yaml
  • in section:

          mniReports: 
              Label: &Reports...
              mniReportPartnerByCity: {Label=&Partner By City Report (experiment), ActionOpenScreen=Ict.Petra.Client.MReporting.Gui.MPartner.TFrmPartnerByCity)

• • when you run nant generateWinform -D:file=MPartner/gui/PartnerMain.yaml, the files PartnerMain.cs and PartnerMain.Designer.cs will be regenerated and updated in the directory csharp/ICT/Petra/Client/lib/MPartner/gui

Store default settings

Once you are able to run your Report GUI, you can enter and select the default values and then save the settings with the name "standard", and this should create the file XmlReports/Settings/Partner/Partner by City/standard.xml

Committing new files to git

You will usually have to add these files to git:

XmlReports/Partner/partnerbycity.xml
XmlReports/Settings/Partner/Partner by City/standard.xml
csharp/ICT/Petra/Client/lib/MReporting/gui/MPartner/PartnerByCity.yaml
csharp/ICT/Petra/Client/lib/MReporting/gui/MPartner/PartnerByCity.cs
csharp/ICT/Petra/Client/lib/MReporting/gui/MPartner/PartnerByCity.Designer.cs
csharp/ICT/Petra/Client/lib/MReporting/gui/MPartner/PartnerByCity.ManualCode.cs

There will be modified files as well, but TortoiseGit will show those anyways:

csharp\ICT\Petra\Definitions\UINavigation.yml (or Customizing\gui\UINavigation.yml)
csharp/ICT/Petra/Client/lib/MReporting/gui/MPartner/Ict.Petra.Client.MReporting.Gui.MPartner.csproj

Files that the reports do depend on

• Most report yaml files refer to a base yaml file, eg. csharp\ICT\Petra\Client\lib\MReporting\gui\MPartner\PartnerReportingForm.yaml
  • this is useful to define general permissions, which are not implemented yet
  • also defines the way the user can select the columns

• on the report definition side (XML), the report depends on XmlReports\reports.dtd which is the schema DTD for the XML file, and on XmlReports\common.xml or other xml files to avoid similar basic functions or queries in several XML files.

NAnt commands related to reports

• nant generateGlue: this is only useful if you add new functions to the server, that are made public to the client. In relation to the reports, this could be needed if you add a function for example for the financial reports, that shows all available financial years.
• nant generateGTK: this was an experiment, to see if we can generate a GUI for GTK as an alternative to Windows.Forms. But in the end, Winforms are working quite alright with Mono on Linux, therefore generateGTK is probably deprecated.
• nant generateWinforms: this will generate all winforms files, that means it will go through the Petra/Client directories and regenerate the screens for each yaml file. This may take quite a long time.
• nant generateWinform: this will only generate one specific yaml file, and compile the project in that directory and attempt to start the Petra Client.
  • you need to specify the yaml file like this: nant generateWinform -D:file=MReporting/gui/MPartner/PartnerByCity.yaml
  • it is also possible to create all yaml files in a subdirectory, eg. nant generateWinform -D:file=MReporting/gui/MPartner. This will have problems compiling the correct csproj file though, I think.